Description

pjs.display() renders an HTML template in the browser and waits for the user to respond. It provides a way to build a screen entirely from HTML and EJS scripting, without a Rich Display File. Once displayed, the screen is submitted back to the server with the pui.submit() client-side API.

The template is populated with the strongly typed fields declared in the global scope of the module, or with the data object passed as the second parameter. When the user responds, any posted value whose name matches a global field is placed into that field, and posted values named *INxx set the corresponding indicator. The complete post data is also returned.

Because Profound.js applications are single-page applications, the template must not be a full HTML document. It must not include <html>, <title>, or <body> tags, and should contain only the body content to render. The browser page is not reloaded.

Syntax

pjs.display(htmlTemplateFile)
pjs.display(htmlTemplateFile, data)
pjs.display(htmlTemplateFile, data, ejsOptions)
pjs.display({ html: htmlString }, data)

Parameters

HTML template file (String or Object) - The path to the HTML template file, relative to the modules directory. If the path is not qualified, the pathlist is used to search for the file. Alternatively, an object with one of the following properties can be passed: file (the HTML template file) or html (a string containing the HTML template itself).
Data (Object, optional) - The data object to pass to the template. If omitted, all strongly typed fields declared in the global scope of the module are passed.
EJS options (Object, optional) - A JavaScript object of EJS options, as documented at ejs.co.

Return Value

Object - The user's response, as an object representing the browser's post data. Each property is a posted field name (from the name attribute of a form input, or a value passed to pui.submit()).

Examples

Example 1: Calculate the Square of a Number

A template with one input and two buttons. The Calculate button submits the screen; the Exit button submits it and also sets the exit indicator, which ends the loop in the module. The number input is returned into the global field of the same name.

Prerequisite: the template below saved as calculate_square.html in the modules directory.

calculate_square.html

<h1>Calculate Square of a Number</h1>

<br/>
<!-- The value typed here is returned into the "number" field -->
Enter a number: <input type="text" name="number" value="<%= number %>" />

<br/>
The square is: <%= square %>

<input type="button" value="Calculate" onclick="pui.submit()" />
<input type="button" value="Exit" onclick="pui.submit('exit')" />

Passing the global fields automatically

pjs.define("number", { type: "integer" });
pjs.define("square", { type: "integer" });
pjs.define("exit", { type: "boolean" });

while (!exit) {
  pjs.display("calculate_square.html");   // All global fields are passed to the template
  square = number * number;               // "number" now holds the value the user entered
}

Passing an explicit data object

pjs.define("number", { type: "integer" });
pjs.define("square", { type: "integer" });
pjs.define("exit", { type: "boolean" });

while (!exit) {
  pjs.display("calculate_square.html", { number: number, square: square });   // Only the listed values are passed
  square = number * number;
}

Example 2: Use the Returned Post Data

The return value contains everything the browser posted, which is useful for values that are not global fields. Here a select list named choice is read from the returned object.

Prerequisite: the template below saved as choose_report.html in the modules directory.

choose_report.html

<h1>Choose a Report</h1>

<select name="choice">
  <option value="sales">Sales by Region</option>
  <option value="inventory">Inventory on Hand</option>
</select>

<input type="button" value="Run" onclick="pui.submit()" />

Server-side module

var response = pjs.display("choose_report.html", {});   // Nothing needs to be passed to this template

console.log("The user chose: " + response.choice);     // "sales" or "inventory"

Example 3: Pass the HTML Directly

For a very small screen, the HTML can be supplied as a string instead of a file.

pjs.define("name", { type: "char", length: 30 });

pjs.display({
  html: 'Your name: <input type="text" name="name" value="<%= name %>" /> ' +
        '<input type="button" value="OK" onclick="pui.submit()" />'
});

console.log("Hello, " + name);

RPG Equivalent

EXFMT

pjs.display()