View source for Pages

<noinclude><!--Fails when transcluded into category page-->__NUMBEREDHEADINGS__</noinclude>
'''[[File:GearIcon.png]] > Customization > Developer Resources > Pages'''

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

==About Pages==
A Page is a standard [http://www.java-tips.org/java-ee-tips/javaserver-pages/an-example-of-a-simple-jsp-page.html 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.

====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 [[JavaScript Functions#showDialog|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]].

===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 API]]s to access and interact with the platform.
:* Use features from the [http://jquery.com/ 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.

===Using APIs===
{{:Common:Using APIs}}

==Working with Pages==
Pages can be Added, Edited or Deleted. 

{{permissionRef|Customize Objects|add, edit or delete pages}}

=== 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 <tt>.jsp</tt> 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 [[#About Header Files|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 <tt><%=''fieldName''%></tt>
#* 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]'''

=== Edit a Page ===
To edit a page:
# Click '''[[File:GearIcon.png]] > 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]'''

=== Delete a Page ===
To delete a page:
# Click '''[[File:GearIcon.png]] > Customization > Developer Resources > Pages'''
# Click the name of the page to delete
# Click the '''[Delete]''' button

=== Managing Pages in Eclipse ===
Use the [[Eclipse Plug-In]] to add, edit, and delete pages.

== Using Pages ==

=== Display a Page as a Web Tab ===
To make a Page available as a web tab:
#Click '''[[File:GearIcon.png]] > 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:'' [[Web Tabs#Displaying a Web Tab|Displaying a Web Tab]]

=== Display a Page from a Form Action ===
# Click [[File:GearIcon.png]] > 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]]

=== 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:
:{|
<pre>https://www.longjump.com/networking/pages/MyJSP.jsp</pre>
|}
If your page depends on a controller to display it, you can use this type of URL:
:{|
<pre>https://www.longjump.com/networking/controller/com/platform/{namespace}/{package}/MyService?action=doSomething</pre>
|} 
where <tt>com.platform.{namespace}.{package}.MyService</tt> is a class that implements the <tt>Controller</tt> interface and <tt>action</tt> is a parameter that you can use in the controller.

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

=== 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:''
:* [[Pages#About Header Files|About Header Files]]
:* [[Application Help Tab]] (example)

== Advanced Techniques ==

===Share Common Libraries===
The standard technique for including common libraries is to create a JSP that references them, for example, <tt>common.JSP</tt>, and then include that page in every other page:
:<syntaxhighlight lang="java" enclose="div">
<%@ include file="/pages/common.JSP"%>
</syntaxhighlight>
A new library can then be added to every page, simply by adding it to <tt>common.JSP</tt>.

===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:
:<syntaxhighlight lang="java" enclose="div">
<%@ 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.
:<syntaxhighlight lang="java" enclose="div">
${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:'' 
:* [https://jstl.java.net/ JSP Standard Tag Library]
:* [http://www.roseindia.net/jstl/jstl-el.shtml JSTL Expression Language]
:* [http://www.informit.com/articles/article.aspx?p=30946&seqNum=7 Implicit Objects]

===Read the HttpServlet Request Stream===
You can access the servlet input stream from the <tt>request</tt> object in the JSP page.<br>Here's sample code that uses it to build a string:
:<syntaxhighlight lang="java" enclose="div">
<%
   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>

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

== Encode Data Before Displaying It! ==
{{:HowTo:Protect Your Users by Ensuring that Data Never Executes as Code|Ensure Data is Never Executed}}

==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|Create a Page]] that includes the desired print formatting
#[[#Create a Document Template|Create a Document Template]] using a Page as the template type

===Create a Page===
#Click '''[[File:GearIcon.png]] > 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]'''

===Get Object and Record ID from the Request Object===
{{:Get Object and Record ID from the Request Object}}

===Create a Document Template===
This Document Template uses Page as the type of template, instead of HTML
#Click '''[[File:GearIcon.png]] > Customization > Objects > {object}'''
#Add a new Document Template, select Page type and select the <tt>.jsp</tt> Document Template file

==Page and Controller Examples==

===Example: Add a Contact using a Page and a Class===
This example describes how to add a Contact using a Page and Class.

====Create the Class====
#Create a class, following the instructions at [[Classes#Adding_a_Class|Adding a Class]]
#Copy and paste the following code into the class, and name it <tt>AddContact</tt>
::<syntaxhighlight lang="java" enclose="div">
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>

====Create the Page====
#Create a page, following the instructions at [[#Adding a Page|Adding a Page]]
#Copy and paste the following code into the page, and name it <tt>AddContact.jsp</tt>
::<syntaxhighlight lang="java" enclose="div">
<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>
</syntaxhighlight>

Now the page is ready to be invoked from browser or web tab.

===Example: Submit Data that Includes a File Attachment===
This example uploads a file selected by a user.

====Create the Class====
#Create a class, following the instructions at [[Classes#Adding_a_Class|Adding a Class]]
#Copy and paste the following code into the class (minus the footnotes), and name it <tt>SampleController</tt>
::<syntaxhighlight lang="java" enclose="div">
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 
   { 
      ControllerResponse response = new ControllerResponse(); 

      // Or extract the parameter into a PlatformFileBean for use elsewhere
      Parameters params = Functions.getParametersInstance(); 
         /* ... add additional parameters, as required... */
      PlatformFileBean fileBean = (PlatformFileBean)parameters.get("attached_file");  --[2]
      params.add("someFieldName", fileBean); 
      Functions.addRecord("SomeOtherObject",params); 
     
      // 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 name of the incoming field is "attached_file", in the form you'll create next.<br>''Learn more:'' [{{DOCHOST}}/javadocs/com/platform/beans/PlatformFileBean.html PlatformFileBean javadocs]

====Create the Page====
#Create a page, following the instructions at [[#Adding a Page|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.
::<syntaxhighlight lang="java" enclose="div">
<%@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> 
</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.<br>Fill in your organization's namespace and the package in which you created the class.
:# Use the Tag Library's [[Tag Library#File Tag|file]] tag to allow the user to browse for a file, and to submit the resulting selection as multi-part data.

==Lookup Examples==

===Search based on Lastname===

This example performs a search action in a lookup window based on "Lastname" as the [[Record_Locator#Search_Fields|Record Locator]]:

Add a Page:
#[[#Pages#Adding_a_Page|Add a Page]]
#Use this file name: <tt>AccountPopup.jsp</tt>
#Use this code sample: [[AccountPopup.jsp]]

Add a <tt>AccountPopup.java</tt> Class:
#[[Classes#Adding_a_Class|Add a Class]]
#Use this file name: <tt>AccountPopup.java</tt>
#Use this code sample: [[AccountPopup.java]]

Add a <tt>AccountPopupController.java</tt> Class:
#[[Classes#Adding_a_Class|Add a Class]]
#Use this file name: <tt>AccountPopupController.java</tt>
#Use this code sample: [[AccountPopupController.java]]

===Search based on multiple fields===
This example performs a search action in a lookup window using [[#Multiple Fields in the Record Locator|Multiple Fields in the Record Locator]]:

'''Prerequisite:''' In the Directory object, define the [[Record_Locator#Search_Fields|Record Locator]] fields to include "First name" and "Last name".

;Add a Page:
#From the Directory object, [[#Pages#Adding_a_Page|Add a Page]]
#Use this file name: <tt>DirectoryPopup.jsp</tt>
#Use this code sample: [[DirectoryPopup.jsp]]

;Add a <tt>DirectoryPopup.java</tt> Class:
#From the Directory object, [[Classes#Adding_a_Class|Add a Class]]
#Use this file name: <tt>DirectoryPopup.java</tt>
#Use this code sample: [[DirectoryPopup.java]]

;Add a <tt>DirectoryPopupController.java</tt> Class:
#From the Directory object, [[Classes#Adding_a_Class|Add a Class]]
#Use this file name: <tt>DirectoryPopupController.java</tt>
#Use this code sample: [[DirectoryPopupController.java]]

===Multiple Fields in the Record Locator===

If the [[Record_Locator#Search_Fields|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: <tt>[First name value][space][-][space][Last name value]</tt>

:{| border="1" cellpadding="5" cellspacing="0"
|-
|First name||Last Name||Record Locator Value
|-
|John|| Smith||John - Smith
|-
|Peter|| ||Peter -
|-
| ||Jones || - Jones
|}

==Global Pages==

[[ISV]]s can create custom pages at the global level for distribution to [[Tenants]]. This feature gives [[Service Provider]]s 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:
:<tt><nowiki>https://{{domain}}/networking/isv/{namespace}/{globalpage.jsp}</nowiki></tt>
: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]]

===Create a Global Page===
# Click '''[[File:GearIcon.png]] > Customization > Developer Resources > Pages'''
# Click the [New Page] button, and complete the following information:
#;Title:Enter a title for the page, for example: <tt>pagename.jsp</tt>
#:<tt>'.jsp'</tt> extension is required
#;Display with Tab Header:Checkbox
#:Uncheck the ''Display with Tab Header'' option
# Enter the code in the text area
# Click '''[Save]'''

===Using Global Pages===
*To select a Global Page as the [[Dashboard]] for tenants, see: [[Service_Provider_Settings#Application_Container_URL|Application Container URL]]

*To use a Global Page as a [[Web Tab]]:
#Create a [[Web_Tabs#Create_a_Web_Tab|New Web Tab]]
#Choose URL as the ''Web Tab Type''
#Paste the Global Page URI into the edit area: 
#::<tt><nowiki>https://{{domain}}.com/networking/isv/{namespace}/{globalpage.jsp}</nowiki></tt>
#::Remember to substitute actual values for the <tt><nowiki>{arguments}</nowiki></tt>
<noinclude>

[[Category:Logic| 2]]
[[Category:Pages]]
</noinclude>