Pages

Designer > 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. A Page compiles to a Java class, so the page name must be a valid Java class name. And it must end with a .jsp extension.

Pages gives you a way to fully customize the user's interactions with the platform. They can be accessed directly via their URL, or they can be used to define custom Dashboards, Lookup pages, or to display or enter data in Forms. They can also be used in Sidebars and Sites.

In most cases, a Page communicates with the platform through a controller class. For details, see Working with Pages and Classes.

1.1 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.2 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:

• Result
• Parameters
• ParametersIterator
• HttpConnection

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

If Versioning has been enabled, then a page must be checked out (Checkout) before it can be edited, and it should be checked in (Commit) after Editing.

2.1 Add a Page

To add a page:

1. Click Designer > Pages

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

   Title

   Enter the filename for the page.

   Note: The *.jsp extension is required

   Include Header Files

   Checkbox (see below)

3. 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

4. Click [Save]

About Header Files

When the platform's HTML headers are included in a page:

• When displayed, the page appears as a tab in the platform GUI.
• You have access to the jQuery library in the page.
• You have access to the platform's JavaScript Functions.

If the headers are not included:

• The page can be displayed in a dialog, using the showDialog function.
• The page is a candidate for use as a Print Template.

2.2 Edit a Page

Before editing a page, the page must be checked out. To edit a page:

1. Click Designer > Pages
2. Click the name of the page to edit
3. Click the [Edit] button
4. Edit the code in the text area
5. Click [Save]

2.3 Checkout a Page

Before editing a page, the page must be checked out.

Learn more: Version Control

To checkout a page:

1. Click Designer > Pages
2. Click the name of the page to edit
3. Click the [Checkout] button

The following actions can be taken on a page that is checked out:

• Edit
• Delete
• Commit

The following information is displayed when a page is checked out:

Page Information

Title

Display with Tab Header

If yes, the page is shown in a tab of its own)

Version Information

Version

Locked

Last Commit By

Last Commit Date

Last Checkout By

Last Checkout Date

2.4 Commit a Page

After editing a page, the changes should be committed to the working copy. To commit a page:

1. After editing a page, click [Save]
2. Click [Commit]

   The Item Type and Name cannot be modified

   Add Comments about the changes

   The following Commit Details are displayed:

   Item Type

   Page

   Item Name

   pagename.jsp

   Comment

   Description of the changes to the page

3. Click [Save]

2.5 Delete a Page

To delete a page:

1. Click Designer > Pages
2. Click the name of the page to delete
3. Click the [Delete] button

2.6 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:

1. Click Designer > Web Tabs
2. Click the [New Web Tab] button:
   • Enter a Name
   • For the Web Tab Type, select Page
   • Choose the page you created
3. Choose the appropriate Data Access Permissions
4. Click [Save]

Learn more: Displaying a Web Tab

3.2 Display a Page by Clicking an Action Button

1. Click Designer > Objects.
2. Click an object
3. Click the Actions tab
4. Click the [Add Action] button
5. Enter a title
6. For Type, select Invoke Custom Page
7. Select a page you have defined
8. Click [Save]

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.

4 Advanced Techniques

4.1 Use Static Resources in Pages

You can upload image files, stylesheets, JavaScript files, and other files as Static Resources, and then use special JavaScript tags to reference them in your Pages.

4.2 Make an Image into an Active Link

An image file can be uploaded as a Document, and then made Publicly Available so it can be referenced. (When it is made public, the platform generates a URL you can use to access the document content--in this case, the image--so it can be displayed in a Page.) You can then use that image in the body of a link, in addition to or in place of text.

You insert an image into the page using the <img> tag. To make it a link, you place the <img> tag in an HTML anchor (<a>) tag, as shown here (with newlines added for readability):

<a href="...">
    <img src="https://{domain}/networking/RepositoryPublicDocDownload
         ?id={image_id}&cid={company_id}
         &encode=image/png" width="160" height="48" border="0">
</a>

Learn more:

• Link to a Document
• For examples of the kind of link targets you might use, see the sample code for the JavaScript showTabInIframe function.

4.3 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"%>

A new library can then be added to every page, simply by adding it to common.JSP.

4.4 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" %>

That tag references 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}

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:

• JSP Standard Tag Library
• JSTL Expression Language
• Implicit Objects]

5 Presentation Pages for Record Data

In a Presentation Page, these record-parameters can be referenced, using the Implicit JSTL Object, param:

<%@ taglib uri="/c" prefix="c" %>
${param.objectId}         <!-- The object ID -->
${param.objectName}       <!-- The object name -->
${param.id}               <!-- The Record ID -->

Then:

• Use that information with the appropriate REST or Java APIs to get additional record data.
• Use jQuery controls or standard JavaScript forms to display the data to the user.
• Send the user's data to classes defined in the platform, or modify object records directly using either REST APIs or explicit Java API calls.

6 Print Templates Using Pages

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

Examples

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

Using print templates in pages is a two-step process:

1. Create a Page that includes the desired print formatting
2. Create a Print Template using a Page as the template type

6.1 Create a Page

1. Click Designer > Pages
2. Click the [New Page] button
3. Click the [Edit] Button
4. Enter a Title (filename) for the print template; Include .jsp as the file extension
5. Uncheck the Display with Tab Header checkbox
6. Add appropriate code, as shown in the next section.
7. 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 );
  }
%>

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");
%>

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:

A Custom Action button can be applied to one record, or it can be applied to several records at one time if the user took advantage of the More Actions feature in the record list view.

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
    }
  }
%>

6.3 Create a Print Template

This print template uses Page as the type of template, instead of HTML

1. Click Designer > Objects > {object}
2. Add a new Print Template, select Page type and select the .jsp print 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

1. Create a class, following the instructions at Adding a Class
2. 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(""))
      {
          Functions.debug("Action - null?");            
          action = "Add";
      }
      if(action.equals("Add"))
      {
           Functions.debug("Action - not null?" + action);
           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", "CONTACT");
        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("CONTACT", addOptions);
        Functions.debug("Message:" + result.getMessage());
        cr.setData(result);
        cr.setTargetPage("AddContact.jsp");
      }
      catch(Exception e)
      {
         cr.setTargetPage("AddContact.jsp");
         cr.setMessage(e.getMessage());
                
         Functions.debug("Message:");          
      }
      return cr;
  }
}

7.1.2 Create the Page

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

<body>

<form  name = "mainForm" action="/networking/controller/com/platform/demo/samples/AddContact" method="POST">
<table width="100%" border="10" cellspacing="0" cellpadding="0">
  <tr>
    <td><table width="50%" border="0" cellspacing="0" cellpadding="2">
      <tr>
        <LABEL for="addFirstName">    First Name: </LABEL>
              <INPUT type="text" id="addFirstName" name="addFirstName" value="CPFirst"><BR>
        <LABEL for="addLastName">   Last Name: </LABEL>
              <INPUT type="text" id="addLastName" name="addLastName" value="CPLast"><BR>
    
        <INPUT type="submit" value="Add"> <INPUT type="reset">        
      </tr>
    </table>
    </form>
    </td>
  </tr>
 
</body>
</html>

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

1. Create a class, following the instructions at Adding a Class
2. 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 = params.getPlatformFileBean("attached_file");  --[3]
      params.add("someFieldName", fileBean); 
      addRecord("SomeOtherObject",parameters); 
     
      // Set the target page and return
      response.setTargetPage("target.jsp"); 
      return response; 
   } 
}

Notes

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

7.2.2 Create the Page

1. Create a page, following the instructions at Adding a Page
2. Copy and paste the following code into the page (minus the footnotes).
3. 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]
      
   <!-- other form fields -->
      
   <input type="submit" name="action" value="upload" /> 
</form>
</body> 
</html>

Notes

1. Include the platform's Tag Library
2. Specify the encoding type as a multi-part form
3. Specify the platform's multipartController handler for the class.
   Fill in your organization's namespace and the package in which you created the class.
4. 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 Pages for Lookup Fields

Lookup fields can be based on a Page, to display a customized Lookup Window. These pages are launched in the usual way, by clicking the lookup icon in a record.

When a Lookup Window search is successful, these parameters are used to identify and return Lookup Fields in Pages:

Paramter Name	Description
object_id	Object Type Identifier
keyword	String value, entered by the user in the lookup field. If the user types ABC in the lookup field, then the keyword is ABC.
target_field	Used to store the Record Id
target_name_field	Used to store the contents of the field (text string format, contents of the field)

The Lookup Field is rendered using two HTML elements:

• target_field
• target_name_field

See the .jsp sample code files for more information.

Considerations

• Lookup Record Selection Criteria is not supported.
• Auto-Completion for Lookup Fields is not supported.

8.1 Lookup Examples

8.1.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:

1. From the Account object, Add a Page
2. Use this file name: AccountPopup.jsp
3. Use this code sample: AccountPopup.jsp

Add a AccountPopup.java Class:

1. From the Account object, Add a Class
2. Use this file name: AccountPopup.java
3. Use this code sample: AccountPopup.java

Add a AccountPopupController.java Class:

1. From the Account object, Add a Class
2. Use this file name: AccountPopupController.java
3. Use this code sample: AccountPopupController.java

8.1.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

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

Add a DirectoryPopup.java Class

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

Add a DirectoryPopupController.java Class

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

8.2 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]

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

9 Global Pages

ISVs and MSPs 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 Home Page for Tenants, or added as Web Tabs.

Global Page access

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

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

where:

{domain} 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

Considerations

• Usage is hierarchical, meaning that:

• ISVs can create Global Pages, which can be used by MSPs and Tenants of that ISV
• MSPs can create Global Pages, which can be used by Tenants of that MSP

9.1 Create a Global Page

1. Click Designer > Pages
2. 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

3. Enter the code in the text area
4. Click [Save]

9.2 Using Global Pages

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

• To use a Global Page as a Web Tab:

1. Create a New Web Tab
2. Choose URL as the Web Tab Type
3. 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}