Environment
Reflection for the Web 2011 (All Editions)
Reflection for the Web 2008 (All Editions)
Situation
Resolution
Sample Templates
Beginning in Reflection for the Web 2008 R2, you can use JSP templates to embed dynamic Reflection sessions in custom web pages that you create. You can customize your web pages to include custom text, graphics, or JavaScript for the session.
Reflection for the Web includea an /rweb/templates folder with instructions on how to use templates (templates.txt). You can use the sample templates as a starting point for creating your own template.
Locate the templates folder:
/[MgmtServerInstall]/apache-tomcat/webapps/rweb/templates/
In Reflection for the Web 2008:
/ReflectionServer/jakarta-tomcat/webapps/rweb/templates/
The /rweb/templates/samples folder contains the following sample templates:
resizetemplate.jsp
scripttemplate.jsp
imagetemplate.jsp
customloginpage.jsp
Review the sample templates, along with the comments, to see how you can include different features in your own template.
For example
The following JSP code displays a simple custom page with an embedded Reflection for the Web session:
<%@ taglib uri="/WEB-INF/rweb.tld" prefix="rweb" %><html><head> <title><%=request.getAttribute("pagetitle")%></title></head><body> <rweb:applet userequest="true"/></body></html> |
Creating Your Own Template
When creating your custom JSP page, consider the following points:
- The page template you specify must have a .jsp extension and be stored in the /.../webapps/rweb/templates folder or in a subfolder.
- The page itself must have the following JSP directive at the top:
<%@ taglib uri="/WEB-INF/rweb.tld" prefix="rweb" %>This line is required to generate the session's applet tag.
- The page can contain any standard HTML formatting that you prefer for colors, fonts, JavaScript, images, or other formatting.
- At the point where you want the dynamic Reflection session to be embedded, include the following JSP tag:
<rweb:applet userequest="true"/>This tag inserts a Reflection applet tag as defined by the session record stored on the server. The tag is output as either the APPLET or OBJECT/EMBED element, based on the Applet tag option you selected on the General Settings page of the Administrative WebStation (Administrative WebStation > Tools > Settings > General tab). OBJECT/EMBED tag is the default option.
- The <rweb:applet> tag accepts all of the same attributes as the standard <applet> tag, and any attributes you specify in the <rweb:applet> tag override the values defined in the session record.
- You can also override or add more applet parameters to the dynamic session, by including this tag inside the <rweb:applet> tag:
<rweb:param name="param_name" value="param_value"/>For example, to embed a session that gets all of its attributes and parameters from the server's session record, but overrides the "hostURL" parameter, your custom page could include this element:
<rweb:applet userequest="true"> <rweb:param name="hostURL" value="telnet://host.example.com"/> </rweb:applet> |
- Note that the <rweb:applet> and the <rweb:param> elements use XML syntax and require a closing tag or the "/>" at the end of the element. If the syntax is incorrect, the JSP page fails to compile and generates a runtime error.
- Changes made to a template page apply the next time the JSP is recompiled, which occurs when the session that uses the template is relaunched.
- Backing up template files.
Uninstalling or upgrading Reflection for the Web may remove or overwrite the sample templates. If you use any of the samples as a starting template for your own page, copy and paste the template to a new file with a unique name, rather than using the sample as supplied.
Make a backup copy of all your template files, should you need them after upgrading.
Embedding a Dynamic Session in a Custom JSP Page
To embed a dynamic Reflection session in a custom template page:
- Launch the Administrative WebStation, and in Session Manager, create a new session by clicking Add. Select the Session type, enter a Session name, and click Continue.
- In the Appearance section, select the "Display session embedded in a web browser window" option to launch the session in a new browser window.
- Enter the name of your template in the "Page template (optional)" field.
If you leave this field empty, the Reflection session is embedded in a simple HTML page that has a heading with the session's name. Also, if the specified template is not present, the default embedded page is used.
To use one of the sample templates, specify the template name as "samples/<templatename>.jsp".
- Launch the session and configure it for your host connection; then save and exit the session.
- Launch your session from the links list page to verify that it displays and works as you expect.
You have created your custom session and can now make it available to your users.
Troubleshooting Tips
If your template does not load as expected, try these troubleshooting ideas:
- If the session does not appear to use the template page, the template may be in the wrong folder or have the wrong name. If the specified template cannot be found, the embedded session comes up in a default embedded page.
Check the location and the file name of the expected template.
- If there is a JSP syntax error when the specified template is loaded, the page will not appear, no default page is used, and a blank browser window opens.
To determine if there is a JSP error, review the trace.log file stored in the ReflectionData/log folder.
Creating a Custom Login Page
To create a custom login page, begin with the sample file, customloginpage.jsp, which you can modify. Then, edit your customized page to incorporate the elements that generate the Reflection applet tags.
The sample code includes these features:
- A banner with your company logo and buttons that direct the user to the corporate home page and the internal helpdesk.
- The embedded Reflection for the Web login/links list applet.
- Parameters for changing your background and foreground colors.
- The current date and time displayed at the bottom of the page.
- Source comments in the sample file that describes the JSP code in detail.
To customize a login page:
- Open the template samples folder, found in the following default locations.
- In Reflection for the Web 2014 or 2011: [MgmtServerInstall]\apache-tomcat\webapps\rweb\templates\samples\
- In Reflection for the Web 2008 R2: C:\Program Files (x86)\ReflectionServer\jakarta-tomcat\webapps\rweb\templates\samples\
- Copy the customloginpage.jsp file, and paste it into the templates folder (one level up).
Note: In Windows 7, the administrator needs permission to paste a file into the templates folder (because it is a subfolder under Program Files).
- In Reflection for the Web 2014 or 2011: [MgmtServerInstall]\apache-tomcat\webapps\rweb\templates\
- In Reflection for the Web 2008 R2: C:\Program Files (x86)\ReflectionServer\jakarta-tomcat\webapps\rweb\templates\
- Rename the customloginpage.jsp file (in the templates folder).
- In the Administrative WebStation, open the Settings page > General tab.
In the Custom login page field, enter the name of your renamed custom template .jsp file.
- Click Save Settings. Close the Administrative WebStation.
- Restart the browser and go to the Reflection for the Web login page.
You should see the custom login page. After you log in, you will see the same customizations in the links list page.
Note: If your custom login page fails to compile, you will not be able to access the Administrative WebStation to fix the problem. To resolve the issue, rename or remove the custom login .jsp page. By renaming or removing the custom page, Reflection for the Web cannot find it and will use the default login page.
- (Optional) You can now edit the renamed custom template .jsp file to display other customized content. For example, you can modify the links in the upper right corner of the sample page.
Note: In Windows 7, if you open the template file in Notepad to edit it, you may get an access denied error when you try to save it in that folder. As a workaround, copy the file to another location such as the desktop. Edit and save the file (using Notepad or another text editor), and then copy the file back to the templates folder.
- Be sure to make a backup copy of any files in the templates folder.
The files may be overwritten the next time you upgrade Reflection for the Web, and you would need to copy them to the correct location after the upgrade.
More Template Samples
Two additional template samples are presented in this section: Terminal and Printer JSP and Two Dynamic Sessions JSP. Review the code and the comments in the samples for potential use in your custom template.
Terminal and Printer JSP
The JSP code in this example shows how to embed a dynamic terminal session and a static printer session on the same page.
To use this template,
- Copy and paste the JSP content into a text file in the <rweb_context>/templates folder of the Reflection server.
- Rename the file with a .jsp extension.
- In the Administrative WebStation > Session Manager, configure an IBM 3270 terminal session as usual.
- In the Appearance section of the configuration page, select the "Display session embedded in a web browser window" option.
- In the "Page template (optional)" field, enter the name of the template.
The IBM 3270 terminal session will be dynamically generated and inserted on the page where the <rweb:applet userequest="true"/> tag appears.
The IBM 3270 printer session is defined statically on the template page, as shown in the following sample code.
Sample Code
<%-- The taglib directive is required to use the rweb:applet tag below .--%>
<%@ taglib uri="/WEB-INF/rweb.tld" prefix="rweb" %><html><head> <title>Terminal and Printer Session</title></head><body><h3>IBM 3270 Terminal Session</h3> |
<%-- The rweb:applet tag embeds the dynamic session on the page. The userequest="true" attribute says that all applet configuration information should come from the session record defined on the Reflection management server. Since each session record contains just a single Reflection session, only one of the applets (IBM 3270 terminal) can be generated dynamically from the server data. The other applet (IBM 3270 printer) is defined statically.
The single line below with userequest="true" is the simplest possible form of the rweb:applet tag. --%>
<rweb:applet userequest="true"/><p/><h3>IBM 3270 Printer Session</h3> |
<%-- There is only one Reflection session per session record, so unless multiple sessions of exactly the same type are desired, any additional sessions must either be defined statically or start with the dynamic session and override attributes and parameters (as is done in the next sample).
Here, an IBM 3270 printer session is defined completely using the rweb:applet tag. You can also do this using the standard applet tag, but the custom rweb:applet tag generates the actual applet tag as either the APPLET or OBJECT/EMBED elements, depending on the setting in the Administrative WebStation's General Settings tab. Note that the syntax of the rweb:applet tag is a more strict XML-like syntax that requires a closing "/>" on each line. Also, parameter lines must start with "rweb:param" rather than just "param". --%>
<rweb:applet code="com.wrq.rweb.Launcher" codebase="./ex" height="190" width="580" archive="Launcher.jar"> <rweb:param name="launcher.sessions" value="IBM3287"/> <rweb:param name="prefsName" value="ibm3270printer" /> <rweb:param name="hostURL" value="trixie" /> <rweb:param name="deviceName" value="TNEPRT56"/> <rweb:param name="cabbase" value="Launcher.cab"/></rweb:applet></body></html> |
Two Dynamic Sessions JSP
The JSP code in this example shows how to embed two dynamic terminal sessions, each to a different host.
To use this template:
- Copy and paste the JSP content into a text file in the <rweb_context>/templates folder of the Reflection server.
- Rename the file with a .jsp extension.
- In the Administrative WebStation > Session Manager, configure an IBM 3270 terminal session as usual.
- In the Appearance section of the configuration page, select the "Display session embedded in a web browser window" option.
- In the "Page template (optional)" field, enter the name of the template.
The IBM 3270 terminal session will be dynamically generated and inserted on the page where the <rweb:applet userequest="true"/> tags appear.
Sample Code
<%-- The taglib directive is required to use the rweb:applet tag below. --%>
<%@ taglib uri="/WEB-INF/rweb.tld" prefix="rweb" %><html><head> |
<%-- The name of the dynamic session is set in the HTTP request attribute called "pagetitle". That value is used here to title the HTML page. --%>
<title><%=request.getAttribute("pagetitle")%></title></head><body><h3>IBM 3270 Session to hosta.example.com</h3> |
<%-- The rweb:applet tag embeds the dynamic session on the page. The userequest="true" attribute says that all applet configuration information should come from the session record defined on the Reflection management server. Since each session record contains just a single Reflection session, both of the rweb:applet tags here create the same terminal session. However, the preconfigured session data can be overridden by adding standard applet attributes and parameters. If the rweb:applet tag contains any attribute or parameter overrides, the overrides are used instead of the data from the session record. Here, the preconfigured host is overridden in each session by specifying a different "hostURL" parameter. And, so that unique user preferences can be saved for each session, the "prefsName" parameter is overridden with a value that is different for each of the two sessions. All other attributes and parameters get their values from the management server's session record. --%>
<rweb:applet userequest="true"> <rweb:param name="prefsName" value="ibm3270embeddedA"/> <rweb:param name="hostURL" value="hosta.example.com"/></rweb:applet><p/><h3>IBM 3270 Session to hostb.example.com</h3><rweb:applet userequest="true"> <rweb:param name="prefsName" value="ibm3270embeddedB" /> <rweb:param name="hostURL" value="hostb.example.com" /></rweb:applet></body></html> |