• <Helps for GetStart>
  • CSPro User's Guide
    • The CSPro System
    • Data Dictionary Module
    • The CSPro Language
    • Data Entry Module
    • Batch Editing Applications
    • Tabulation Applications
    • CSPro Statements and Functions
    • Templated Reporting System
    • HTML and JavaScript Integration
      • HTML in CSPro
      • HTML Dialog Boxes
      • JavaScript Interface
      • JSON Format
    • Appendix
  • <Helps for CSEntry>
  • <Helps for CSBatch>
  • <Helps for CSTab>
  • <Helps for DataViewer>
  • <Helps for TextView>
  • <Helps for TblView>
  • <Helps for TRSWin>
  • <Helps for CSDeploy>
  • <Helps for CSPack>
  • <Helps for CSFreq>
  • <Helps for CSSort>
  • <Helps for CSExport>
  • <Helps for CSReFmt>
  • <Helps for CSDiff>
  • <Helps for CSConcat>
  • <Helps for TRSSetup>
  • <Helps for ParadataViewer>
  • <Helps for ParadataConcat>
  • <Helps for CSIndex>
  • <Helps for Excel2CSPro>
  • <Helps for CSWeb>

HTML in CSPro

Overview
While CSPro is not a web-based application, HTML is used in CSPro in a variety of ways:
  1. When displaying question text.
  2. When displaying logic-based reports written in HTML.
  3. When displaying content using the view or htmldialog functions.
  4. When displaying some dialogs for logic functions, as well as other aspects of the CSPro user interface (UI).
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.
Local Web Server and HTML Directory References
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" />
JavaScript Libraries Included With CSPro
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>
See also: JavaScript Interface