Difference between revisions of "Pages"

Revision as of 05:29, 19 December 2017

> Customization > Developer Resources > Pages

Pages can be used to create highly customized user interface elements as well as completely independent tabs.

1 About Pages

A Page is a standard JSP page (JavaServer Page) that can contain HTML and Java code.

Pages gives you a way to customize the user's interactions with the platform. They can be:

accessed directly via their URL
used in a Dashboard
used to display or enter data in lieu of a standard object Form
display a message in a dialog
used in a Site

Pages that contain platform header files generally communicate with the platform through a Java controller class that does data retrieval and storage. For details, see Working with Pages and Classes. Pages without headers operate as standard HTML pages that provide information, add styling, and give the user links to other pages.

1.1 About Header Files

All JSP pages have access to the platform's Tag Library, and all can be displayed in a Web Tab or Dashboard, or accessed by their URL. (When displayed as part of the platform UI, the page is displayed in an iFrame--a sandbox, of sorts, the isolates the page from the rest of the platform UI.) In addition, JSP pages can use the Java APIs to access and update platform data (or use a Controller Class for that purpose).

When the platform's header files are included in a page:

The platform's standard CSS and JavaScript files are included.
The page has access to the platform's JavaScript Functions.
The page has access to the platform's jQuery library.
The functions and libraries can be used to create a sophisticated interface for data retrieval and storage.

If the header files are not included, the page becomes a "vanilla" HTML page:

CSS styling defined in the page is honored (with headers included, CSS styles defined in the page are ignored)
Links to other pages work (with headers included, they fail).
The page can be displayed in a dialog, using the showDialog function.
The page can be used in a Site.
A jQuery library (or other library) can be referenced, but it must first be uploaded as a Static Resource.

1.2 Designing Pages

Use HTML and CSS to create the look you want, and use a variety of dynamic display-and-interaction technologies to create the feel you want:

Use Java APIs to access and interact with the platform.
Use features from the jQuery library (JavaScript components, stylesheets, themes, effects, etc).
Add your own JavaScript code for forms and other options.
Use AJAX and REST to communicate with the platform in JavaScript code.
Upload other JavaScript libraries and CSS files as Static Resources and reference them in your JSP pages.

1.3 Using APIs

In general, the Java APIs and REST APIs provide equivalent functionality. But there are some differences, as well. So while the Java APIs are generally more convenient to use in a JSP page, you may also want to review the functionality listed in the REST API CheatSheet.

The following Java API classes are implicitly imported into JSP Pages:

Other considerations:

You cannot make a database connection. (Use the Java Record Handling APIs, instead.)
The maximum number of loop iterations, along with other restrictions, is determined by the configuration of the platform Governors.)

2 Working with Pages

Pages can be Added, Edited or Deleted.

Users that have the Customize Objects permission can add, edit or delete pages.

2.1 Add a Page

To add a page:

Click the [New Page] button, and complete the following information:
Title

Enter the filename for the page.

A Page that includes platform headers compiles to a Java class, so the page name must be a valid Java class name. And it must end with a .jsp extension.

The same naming rules apply to a page that does not include platform headers, even though it becomes a vanilla HTML page--because headers can always be added later.

Include Header Files

Checkbox
Enter the code for the page in the text area:
- Typically, you'll use Java APIs and JSTL tags to access data (described later), and then insert the data into the page using <%=fieldName%>
- If there is any doubt at all about the integrity of your data (particularly when data comes from external users via Web Forms), be sure to encode the data before displaying it
Learn more: HowTo:Protect Your Users by Ensuring that Data Never Executes as Code
Click [Save]

2.2 Edit a Page

To edit a page:

Click > Customization > Developer Resources > Pages
Click the name of the page to edit
Click the [Edit] button
Edit the code in the text area
Click [Save]

2.3 Delete a Page

To delete a page:

Click > Customization > Developer Resources > Pages
Click the name of the page to delete
Click the [Delete] button

2.4 Managing Pages in Eclipse

Use the Eclipse Plug-In to add, edit, and delete pages.

3 Using Pages

3.1 Display a Page as a Web Tab

To make a Page available as a web tab:

Click > Customization > Developer Resources > Web Tabs
Click the [New Web Tab] button:
- Enter a Name
- For the Web Tab Type, select Page
- Choose the page you created
Choose which roles can see the tab
Click [Save]
Refresh your browser to see the new tab

Learn more: Displaying a Web Tab

3.2 Display a Page from a Form Action

Click > Customization > Objects.
Click an object
Click the Actions tab
Click the [Add Action] button
Enter a title
For Type, select Invoke Custom Page
Select a page you have defined
Click [Save]

Learn more: Custom Form Actions

3.3 Display a Page by Visiting a URL

If you have written your page in a way that does not require a controller to display it, you can directly invoke it using:

https://www.longjump.com/networking/pages/MyJSP.jsp

If your page depends on a controller to display it, you can use this type of URL:

https://www.longjump.com/networking/controller/com/platform/{namespace}/{package}/MyService?action=doSomething

where com.platform.{namespace}.{package}.MyService is a class that implements the Controller interface and action is a parameter that you can use in the controller.

For more about controllers, see see Working with Pages and Classes.

3.4 Making an Application Help Page

An application help page is simply a JSP page without the platform's header files. Such pages can include CSS, and can link to other pages.

Learn more:

About Header Files
Application Help Tab (example)

4 Advanced Techniques

4.1 Share Common Libraries

The standard technique for including common libraries is to create a JSP that references them, for example, common.JSP, and then include that page in every other page:

<%@ include file="/pages/common.JSP"%> </syntaxhighlight> A new library can then be added to every page, simply by adding it to common.JSP.

4.2 Access Implicit JSTL Objects

The implicit objects built into JSP pages give you a great deal of power, with negligible additional work. To access them, include this line near the top of your JSP page:

<%@ taglib uri="/c" prefix="c" %> </syntaxhighlight>

That tag references the JSTL core library. (Since that library is built into the platform, the typically long URI is replaced by "/c".)

The JSTL Expression Language provides a nice way to access those objects. For example, to access a named parameter sent to the page in an HTTP request, you can use this syntax.

${param.someParameterName} </syntaxhighlight>

Using the implicit objects, you can store and retrieve data for a request, a page, a session, or an application. For example, see the JSTL pageContext properties.

In addition to the pageContext properties, you can access these implicit objects:

cookie - Client data, accessed by cookie name
header - Request header value, accessed by name
headerValues - List of header values
initParam - Initialization parameter, accessed by name
param - Request parameter, accessed by name
paramValues - List of parameter values
pageScope - Page attribute, accessed by name.
requestScope - Request attribute, accessed by name.
sessionScope - Session attribute, accessed by name.
applicationScope - Application attribute, accessed by name.

Learn More:

4.3 Read the HttpServlet Request Stream

You can access the servlet input stream from the request object in the JSP page.
Here's sample code that uses it to build a string:

<%

  StringBuilder sb = new StringBuilder();

  // Read the input stream
  java.io.InputStream is = request.getInputStream();
  String line = null;

  // Convert to String
  java.io.BufferedReader br = 
     new java.io.BufferedReader(new java.io.InputStreamReader(is));
  while ((line = br.readLine()) != null) {
     sb.append(line);
  }

%> </syntaxhighlight>

4.4 Access CSS Files and JavaScript Libraries

In a page, you can access files uploaded as static resources.

Learn more: Static Resources#Accessing Static Resources in a JSP Page

5 Encode Data Before Displaying It!

A Cross-Site Scripting (XSS) attack is one in which a script is entered into the data stream. Then, when the data is displayed, the script executes. This guide explains how an XSS attack works, and shows you how to guard against it.

In general, the idea is to encode incoming data, so that it is displayed when accessed, rather than executing. That encoding is done automatically when data is entered into a Form that is running in the platform. But when you create an external Web Form, you need to do it yourself.

5.1 Executing a Script Stored as "Data"

To see how XSS works, you'll create an object with a data field and put a tiny script into that field. Then, when you display the data, you'll see that the script executes in the browser.

Here's the process:

Create a TestObject with one textfield, TestData.
Create a record in that object.
In the field, store the following data: <script>alert("You have been hacked!");</script>
That code is a script that opens a dialog and displays a simple message--but it could conceivably do much more, like opening a cookie on the user's system and sending its information elsewhere.
Now create a JSP Page, TestPage.jsp to display the data in that field. For example:
<syntaxhighlight lang="java" enclose="div">

 <title>Test Page</title>

</head> <body> Here is the data from the first and only record: <%

 // Get all records that have testfield data.
 Result results = Functions.searchRecords("TestObject", "testfield", "testfield != BLANK");
 String data = null;

 // Get the data from the first record. 
 ParametersIterator iterator = results.getIterator();
 while(iterator.hasNext())
 {
    Parameters recordParams = iterator.next();
    data = recordParams.get("testfield");
    break;
 }

%> <%=data%>. </body> </html> </syntaxhighlight>

Next, visit that page, at https://{yourDomain}/networking/pages/TestPage.jsp
When you go there, you encounter the dialog box generated by the script that was stored as "data".

Although it is possible to enter the script using the platform interface, as we have done here, the most likely scenario for XSS is in the form of data that originates from an external source, submitted to the system in a Web Form. For example, the script could be part of a comment on a blog post. Anyone who displays the comments then unknowingly executes the script.

Such problems are prevented by encoding user data, before it is displayed. You can do that using either Java APIs or JavaScript APIs, discussed in the sections that follow.

Warning: It is never a good idea to "double encode" data. You can store data in encoded form, or display it that way. You never want to do both. (Since encoding the data takes additional space, it is typically desirable to do the encoding when the data is displayed.) Similarly, make sure that the data runs through only one encoding process before it is displayed.

5.2 Using Java APIs to Encode Displayed Data

Protecting users in such scenarios is a matter of ensuring that such "data" is always displayed, rather than executed. To do that, you encode the data, so the browser sees <script>, for example, rather than <script>. (When it sees <script> it goes into execution mode. But it when it sees <script>, it substitutes the left- and right-angle brackets, and then simply displays the resulting string.

The methods you need to encode displayed data are available in the com.platform.api.XSSEncoder class:

encodeForHTML - Encode data for display in an HTML page
encodeForHTMLAttribute - Encode data for display in an HTMLAttribute
encodeForJavaScript - Encode data before inserting it into JavaScript code

Here's the JSP page, rewritten to encode the data. When you run it now, you no longer see the dialog box. Instead, you see the code that would have generated it, had it been allowed to run.

 <title>Test Page</title>

</head> <body> Here is the data from the first and only record: <%

 // Get all records that have testfield data.
 Result results = Functions.searchRecords("TestObject", "testfield", "testfield != BLANK");
 String data = null;

 // Get the data from the first record. 
 ParametersIterator iterator = results.getIterator();
 while(iterator.hasNext())
 {
    Parameters recordParams = iterator.next();
    data = recordParams.get("testfield");

    // **** ADD THIS LINE ****
    data = com.platform.api.XSSEncoder.encodeForHTML(data);
    // ***********************

    break;
 }

%> <%=data%>. </body> </html> </syntaxhighlight>

5.3 Using JavaScript APIs to Encode Displayed Data

In JavaScript, use the jQuery Encoder APIs:

encodeForHTML - Encode data for display in an HTML page
encodeForHTMLAttribute - Encode data for display in an HTMLAttribute
encodeForJavascript - Encode data before inserting it into JavaScript code
encodeForURL - Encode data for use in a URL

Considerations

When the JSP/Html Page is set to include headers, the jQuery Encoder APIs are automatically included in the page.
When the JSP/Html page does not include platform headers, load the jQuery-encoder library as a Static Resource, and use it in your page

6 Document Templates Using Pages

Print templates in pages can be used to print records in any object. See Document Templates for an overview of Document Templates in the user interface.

Examples

Create an Expense Report to be used in expense management application
Print an Employee Benefit Form

Using Document Templates in pages is a two-step process:

Create a Page that includes the desired print formatting
Create a Document Template using a Page as the template type

6.1 Create a Page

Click > Customization > Developer Resources > Pages
Click the [New Page] button
Click the [Edit] Button
Enter a Title (filename) for the Document Template; Include .jsp as the file extension
Uncheck the Display with Tab Header checkbox
Add appropriate code, as shown in the next section.
Click [Save]

6.2 Get Object and Record ID from the Request Object

When a JSP Page is launched from a context that is associated with a particular object record, the request object available in the JSP page contains the identifiers needed to obtain additional information from the record, using either the REST record Resource or the Java record handling APIs.

To get all of the parameters available in the request object, and their values:

<%

 String[] params = request.getParameterValues();
 for (int i=0; i<params.length; i++)
 {
   String paramName = params[i];
   String paramValue = request.getParameter( paramName );
 }

%> </syntaxhighlight>

To obtain a record identifier from a request object sent by the platform:

With the object ID and record ID, use the getRecord API to retrieve the record.

<%

 String object_id = request.getParameter("object_id");
 String record_id = request.getParameter("record_id");

%> </syntaxhighlight>

Note: Although the object_id is alphanumeric, it can be used in any API that requires an object name.

To obtain a record identifier from a request object sent by a Custom Action button:

This code gets the record IDs and uses the searchRecords API to retrieve the records:

<%

 // Get the object ID and the comma separated list of record IDs
 String object_id = request.getParameter("object_id");
 String selectedRecords = request.getParameter("selectedRecords");

 // Break the comma-separated list into record IDs. 
 // Join them with "OR" operands for use when searching for the records
 String filterCriteria = "";
 if (selectedRecords != null)
 {
   StringTokenizer st = new StringTokenizer(selectedRecords,",");
   while (st.hasMoreTokens())
   {
     if ( !"".equals(filterCriteria.trim()))
     {
        // Criteria string isn't empty, and we're adding another expression
        // Prefix the new expression with a boolean OR operator
        filterCriteria += " OR "
     }
     filterCriteria += "record_id = "+ st.nextToken();
   }
 }

 // Use the filter criteria to fetch the selected records
 // Here, we ask for the record_id and name fields
 Result results;
 results = Functions.searchRecords(object_id , "record_id,name", filterCriteria);
 int resultCode = results.getCode();
 if (resultCode < 0)
 {
    // Error occurred
 }
 else if (resultCode == 0)
 {
   // No records found. (This situation should never occur.)
 }
 else
 {
   // Records retrieved successfully
   // Process them here
   ParametersIterator iterator = results.getIterator();
   while(iterator.hasNext())
   {
     Parameters params = iterator.next();
     String recordID = params.get("record_id");
     String recordName = params.get("name");
     // Take additional action according to your business logic
   }
 }

%> </syntaxhighlight>

6.3 Create a Document Template

This Document Template uses Page as the type of template, instead of HTML

Click > Customization > Objects > {object}
Add a new Document Template, select Page type and select the .jsp Document Template file

7 Page and Controller Examples

7.1 Example: Add a Contact using a Page and a Class

This example describes how to add a Contact using a Page and Class.

7.1.1 Create the Class

Create a class, following the instructions at Adding a Class
Copy and paste the following code into the class, and name it AddContact

import java.util.*; import com.platform.api.*;

public class AddContact implements Controller {

 public ControllerResponse execute(HashMap params) throws Exception
 {
     String action = (String)params.get("action");

     if(action == null || action.equals(""))
     {
         Logger.info("Action - null?", "AddContact");            
         action = "Add";
     }
     if(action.equals("Add"))
     {
          Logger.info("Action - not null?" + action, "AddContact");
          return addContact(params);
     }
     else
     {
                             
     }
     return null;
 }

 private ControllerResponse addContact(HashMap params) 
   throws Exception
 {
     ControllerResponse cr = new ControllerResponse();
     Result result = null;
                               
     try
     {
       Parameters addOptions = Functions.getParametersInstance();
       addOptions.add("object_id", "Contacts");
       String addFirstName = (String)params.get("addFirstName");
                   
       String addLastName = (String)params.get("addLastName");
                           
       if(addLastName != null && !addLastName.equals("") 
             && addFirstName != null && !addFirstName.equals(""))
       {
           addOptions.add("first_name", addFirstName);
                     
           addOptions.add("last_name", addLastName);
       }
       else
       {
          addOptions.add("first_name", "CPfirst"+new Date());
          addOptions.add("last_name", "CPLast" + new Date());
          addOptions.add("account_id", "1593373443");
       } 
       result = Functions.addRecord("Contacts", addOptions);
       Logger.info("Message:" + result.getMessage(), "AddContact");
       cr.setData(result);
       cr.setTargetPage("AddContact.jsp");
     }
     catch(Exception e)
     {
        cr.setTargetPage("AddContact.jsp");
        cr.setMessage(e.getMessage());
               
        Logger.info("Message:", "AddContact");          
     }
     return cr;
 }

} </syntaxhighlight>

7.1.2 Create the Page

Create a page, following the instructions at Adding a Page
Copy and paste the following code into the page, and name it AddContact.jsp

<body>

</body> </html> </syntaxhighlight> Now the page is ready to be invoked from browser or web tab.

7.2 Example: Submit Data that Includes a File Attachment

This example uploads a file selected by a user.

7.2.1 Create the Class

Create a class, following the instructions at Adding a Class
Copy and paste the following code into the class (minus the footnotes), and name it SampleController

package com.platform.{yourNamespace}.{yourPackage}; --[1]

import java.util.*; import com.platform.beans.*; import com.platform.api.*;

public class SampleController implements Controller {

  public ControllerResponse execute(HashMap parameters) throws Exception 
  { 
     // Create a new Comment record using the incoming parameters,
     // including the attached_file field.
     ControllerResponse response = new ControllerResponse(); 
     addRecord("Comments",parameters);                                         --[2]

     // Or extract the parameter into a PlatformFileBean for use elsewhere
     Parameters params = Functions.getParametersInstance(); 
        /* ... add additional parameters, as required... */
     PlatformFileBean fileBean = (PlatformFileBean)parameters.getPlatformFileBean("attached_file");  --[3]
     params.add("someFieldName", fileBean); 
     addRecord("SomeOtherObject",parameters); 
    
     // Set the target page and return
     response.setTargetPage("target.jsp"); 
     return response; 
  }

} </syntaxhighlight>

Notes

Fill in your organization's namespace and the package in which you are creating the class
The record is added to a fictitious Comments object, in this example.
The name of the incoming field is "attached_file", in the form you'll create next.
Learn more: PlatformFileBean javadocs

7.2.2 Create the Page

Create a page, following the instructions at Adding a Page
Copy and paste the following code into the page (minus the footnotes).
Fill in your organization's namespace and the package in which you created the class.

<%@taglib prefix="lj" uri="/LJTagLib"%> --[1] <html> <head></head> <body> <form name="mainForm"

  enctype="multipart/form-data"                                                      --[2]
  action="/networking/multipartController/com/platform/{ns}/{pkg}/SampleController"  --[3]
  method="POST">

  <lj:file name="attached_file" id="attached_file" size="15" value=""/>              --[4]
     
     
  <input type="submit" name="action" value="upload" />

</form> </body> </html> </syntaxhighlight>

Notes

Include the platform's Tag Library
Specify the encoding type as a multi-part form
Specify the platform's multipartController handler for the class.
Fill in your organization's namespace and the package in which you created the class.
Use the Tag Library's file tag to allow the user to browse for a file, and to submit the resulting selection as multi-part data.

8 Lookup Examples

8.1 Search based on Lastname

This example performs a search action in a lookup window based on "Lastname" as the Record Locator:

Add a Page:

Add a Page
Use this file name: AccountPopup.jsp
Use this code sample: AccountPopup.jsp

Add a AccountPopup.java Class:

Add a Class
Use this file name: AccountPopup.java
Use this code sample: AccountPopup.java

Add a AccountPopupController.java Class:

Add a Class
Use this file name: AccountPopupController.java
Use this code sample: AccountPopupController.java

8.2 Search based on multiple fields

This example performs a search action in a lookup window using Multiple Fields in the Record Locator:

Prerequisite: In the Directory object, define the Record Locator fields to include "First name" and "Last name".

Add a Page

From the Directory object, Add a Page
Use this file name: DirectoryPopup.jsp
Use this code sample: DirectoryPopup.jsp

Add a DirectoryPopup.java Class

From the Directory object, Add a Class
Use this file name: DirectoryPopup.java
Use this code sample: DirectoryPopup.java

Add a DirectoryPopupController.java Class

From the Directory object, Add a Class
Use this file name: DirectoryPopupController.java
Use this code sample: DirectoryPopupController.java

8.3 Multiple Fields in the Record Locator

If the Record Locator is a combination of fields, then it must be created by concatenating the field names.

For example, the record locator for the Employee object is a combination of First name, Last name. Then the record locator value is formed as: [First name value][space][-][space][Last name value]

<LABEL for="addFirstName"> First Name: </LABEL> <INPUT type="text" id="addFirstName" name="addFirstName" value="CPFirst">
<LABEL for="addLastName"> Last Name: </LABEL> <INPUT type="text" id="addLastName" name="addLastName" value="CPLast">
<INPUT type="submit" value="Add"> <INPUT type="reset">

   </form>

First name	Last Name	Record Locator Value
John	Smith	John - Smith
Peter		Peter -
	Jones	- Jones

9 Global Pages

ISVs can create custom pages at the global level for distribution to Tenants. This feature gives Service Providers the ability to design and build pages once, then make the custom work available to multiple tenants, as the default Dashboard for Tenants, or added as Web Tabs.

Global Page access

Global Page access is defined by {namespace}, as shown in this URL:

https://{{domain}}/networking/isv/{namespace}/{globalpage.jsp}

where:

{yourDomain} is the Service Domain of the Service Provider

{namespace} is the namespace of the Service Provider, defined in Company Information

{globalpage.jsp} is the the name of the Page

9.1 Create a Global Page

Click > Customization > Developer Resources > Pages
Click the [New Page] button, and complete the following information:
Title

Enter a title for the page, for example: pagename.jsp

'.jsp' extension is required

Display with Tab Header

Checkbox

Uncheck the Display with Tab Header option
Enter the code in the text area
Click [Save]

9.2 Using Global Pages

To select a Global Page as the Dashboard for tenants, see: Application Container URL

To use a Global Page as a Web Tab:

Create a New Web Tab
Choose URL as the Web Tab Type
Paste the Global Page URI into the edit area:
https://{{domain}}.com/networking/isv/{namespace}/{globalpage.jsp}

Remember to substitute actual values for the {arguments}