HTML in CSPro

Overview

Although CSPro is not a web-based application, HTML is used in CSPro in a variety of ways:

When displaying question text.
When displaying templated reports written in HTML.
When displaying content using functions like view or actions like UI.showDialog.
When displaying some dialogs for logic functions, as well as other aspects of the CSPro user interface.

HTML files or web pages are displayed in an embedded window using a Chromium-based web browser:

Windows: Edge WebView2
Android: WebView

In this web browser, it is possible to:

Use the Action Invoker, called using JavaScript, to interact with various CSPro features.
Use JavaScript libraries included with CSPro, such as Bootstrap and jQuery.

In most instances where CSPro processes HTML, it is possible to instead use Markdown if you prefer a simpler, more lightweight syntax. Markdown will be automatically converted to HTML for displaying.

Local Web Server and HTML Directory References

When a CSPro application runs, a local web server is launched that can serve content stored on the local file system. 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 8.1\html\

The pathname and other path-related functions can return the name of this directory using the Html argument.

The local web server treats the html directory as the root of the server. 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 (e.g., shown using view): 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:

If you want to access any of the files in HTML that you write, you should not reference the file using an absolute path (using a file URL) because the web view 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 templated report:

<img src="file:///C:/Program Files (x86)/CSPro 8.1/html/images/pff-icon.png" />


<img src="~~Path.getRelativePath(Path.getDirectoryName(filename($)),
"C:/Program Files (x86)/CSPro 8.1/html/images/pff-icon.png")~~" />

Fortunately, because the local web server treats the html directory as the root of the server, the above example can instead be coded as: