While CSPro is not a web-based application, HTML is used in CSPro in a variety of ways:
HTML files or websites are displayed in an embedded window using a Chromium-based web browser (
Edge WebView2 on Windows;
WebView on Android). In this web browser, it is possible to use the
JavaScript interface to interact with various CSPro features.
When a CSPro application runs, a local web server is launched that serves content stored on the local file system. On Windows, this server uses localhost as the host and chooses a dynamic port, checking for one that is not in use.
Relative paths that are not based off the root are evaluated from the location of the displayed HTML content:
- Question Text: Relative to the data entry application (.ent) or .pen file.
- Reports: Relative to the location of the report (or, when running a .pen file, where it would have existed relative to the data entry application).
- HTML Files (shown using view or htmldialog): Relative to the location of the file.
For example, these references in question text would refer to files in the application directory and in a relative directory located one level above the application directory:
<img src="image-in-application-directory.jpg" />
<img src="../shared/image-in-relative-directory.jpg" />
HTML, JavaScript, CSS, and other files that CSPro uses for its operations are located in a html directory. On Windows, these files are typically found here:
C:\Program Files (x86)\CSPro 7.7\html\
The
pathname and other path-related functions can return the name of this directory using the
Html argument.
If you want to access any of the files in that directory in HTML that you write, you should not reference the file using an absolute path (using a file URL) because the web browser that displays the HTML may not be able to access local files. Instead, you should use the
path.getRelativePath function to construct a relative path from the location of your HTML content. For example, if trying to use the PFF icon from a
report:
<!-- will not work when displayed in CSPro: -->
<img src="file:///C:\Program Files (x86)\CSPro 7.7\html\images\pff-icon.png" />
<!-- correct format: -->
<img src="~~path.getRelativePath(path.getDirectoryName(filename($)),
"C:\Program Files (x86)\CSPro 7.7\html\images\pff-icon.png")~~" /> Fortunately, the local web server treats the html directory as the root of the server. The above example can instead be coded as:
<img src="/images/pff-icon.png" />
Some popular JavaScript libaries are included in the html directory:
- Bootstrap: "Quickly design and customize responsive mobile-first sites with Bootstrap, the world’s most popular front-end open source toolkit, featuring Sass variables and mixins, responsive grid system, extensive prebuilt components, and powerful JavaScript plugins."
- jQuery: "jQuery is a fast, small, and feature-rich JavaScript library. It makes things like HTML document traversal and manipulation, event handling, animation, and Ajax much simpler with an easy-to-use API that works across a multitude of browsers".
- Leaflet (Windows only): "Leaflet is the leading open-source JavaScript library for mobile-friendly interactive maps."
- mustache.js: "Mustache is a logic-less template syntax. It works by expanding tags in a template using values provided in a hash or object."
To use these libraries, use the following code:
<!-- Bootstrap -->
<link rel="stylesheet" href="/external/bootstrap/bootstrap.min.css" />
<link rel="stylesheet" href="/external/bootstrap/bootstrap-icons.css" />
<script src="/external/bootstrap/bootstrap.bundle.min.js"></script>
<!-- jQuery -->
<script src="/external/jquery/jquery.min.js"></script>
<!-- Leaflet (Windows only) -->
<link rel="stylesheet" href="/external/leaflet/leaflet.css" />
<script src="/external/leaflet/leaflet.js"></script>
<!-- Mustache -->
<script src="/external/mustache/mustache.min.js"></script>