16
Customizing the JasperReports Server User Interface 1 CUSTOMIZING THE JASPERREPORTS SERVER USER INTERFACE After upgrading the JasperReports Server from earlier versions to 4.0 you need to migrate server customizations. This document describes how to make common changes to the web interface: How do you customize branding? How do you add a menu item to the web interface? How do you incorporate server styles into custom content? How do you display a menu item conditionally? How do you hide the main navigation? The figures in this document depict the server running on Tomcat in Windows 7 using the Firefox browser. HOW DO YOU CUSTOMIZE BRANDING? In addition to using your organization’s colors, you can replace or hide brand-related interface elements. This section provides these examples: Branding on the Browser Tab and Title Bar Company Logo on All Pages Copyright and About Link Graphic and Login Form on the Login Page Welcome Heading and Contact Jaspersoft Button Figure 1 calls out some of the elements you customize as you work through procedures in this document. Figure 1 JasperReports Server Login Page Logo Copyright About link Welcome heading Favicon and company name Contact button Main graphic

Customizing Server

Embed Size (px)

Citation preview

Page 1: Customizing Server

Customizing the JasperReports Server User Interface

CUSTOMIZING THE JASPERREPORTS SERVER USER INTERFACE

After upgrading the JasperReports Server from earlier versions to 4.0 you need to migrate server customizations. This document describes how to make common changes to the web interface:

How do you customize branding?

How do you add a menu item to the web interface?

How do you incorporate server styles into custom content?

How do you display a menu item conditionally?

How do you hide the main navigation?

The figures in this document depict the server running on Tomcat in Windows 7 using the Firefox browser.

HOW DO YOU CUSTOMIZE BRANDING?In addition to using your organization’s colors, you can replace or hide brand-related interface elements. This section provides these examples:

Branding on the Browser Tab and Title Bar

Company Logo on All Pages

Copyright and About Link

Graphic and Login Form on the Login Page

Welcome Heading and Contact Jaspersoft Button

Figure 1 calls out some of the elements you customize as you work through procedures in this document.

Figure 1 JasperReports Server Login Page

Logo

Copyright

About link

Welcome heading

Favicon and company name

Contact button

Main graphic

1

Page 2: Customizing Server

JasperReports Server User Guide

In addition to these branding changes, the following procedures give the Login page a custom look by repositioning elements, changing the main graphic, and using a different color. After performing these procedures, the Login page looks quite different:

Branding on the Browser Tab and Title BarThe branding on the browser tab and title bar includes:

The company name on the browser tab

The favicon – When the user bookmarks or adds the URL of the server to the favorites list, browsers append the favicon to all the locations where favicons can appear. This varies from browser to browser.

The company name on the browser title bar

The following procedure describes how to change the branding on the browser tab and title bar in the source code.

To change the company name and icon on the browser tab:

1. Open this file for editing in your IDE (Interactive Development Environment) or a text editor:

<js-src>\jasperserver\jasperserver-war\src\main\webapp\WEB-INF\decorators\decorator.jsp

2. To change the company name on the browser title bar, make the following change to the HTML TITLE tag:

Figure 2 Custom Login Page

<js-src> is the location where you unpacked JasperReports Server source code archive files.

<html>

<head>

<!-- Change Jaspersoft to ABC Corp -->

<title>ABC Corp: <decorator:title /></title> ...

<decorator:head />

</head>

2

Page 3: Customizing Server

Customizing the JasperReports Server User Interface

3. Rename your icon to favicon.ico.

4. Copy the icon to this location:

<js-src>/jasperserver/jasperserver-war/src/main/webapp

5. Build the source code. For more information, see “Build the Source Code” on page 8.

6. Log into the server.

The Login page manifests the changes to the browser tab and title bar.

Company Logo on All Pages

To change the logo on all server pages, including the Login page:

1. On the file system of the server, navigate to the \themes directory in the server installation files:

<js-src>\apache-tomcat\webapps\jasperserver-pro\themes

2. Expand the default\images directory and locate the logo image, logo.png.

3. Look at the properties of logo.png to determine its dimensions: 141 x 28 pixels.

4. Size your logo to match the dimensions of the original logo, and give it the same name: logo.png.

5. Log into the server as superuser.

6. Click View > Repository.

7. In the Folders panel, right-click root/Themes, and select Add Folder.

8. Name the new folder customizations.

9. Right-click the customizations folder, and select Add Folder. Name the new folder images.

10. Add your logo to the images folder:

a. Right-click the images folder and select Add Resource > File > Image.

The Upload a File From Your Local Computer page appears.

b. Browse to your logo.

c. In the Name field, enter logo.png.

d. In the Resource ID field, enter logo.png.

Only root themes apply to the login page and only as superuser can you create this folder.

Figure 3 Adding a Folder to the Themes Folder

3

Page 4: Customizing Server

JasperReports Server User Guide

e. Click Submit.

The logo.png file appears in the Themes > customizations > images folder in the repository.

The logo is now available in the server. It appears in the server web interface after you perform the procedure in “Activate the New Theme,” on page 6.

Copyright and About LinkThe default theme defines styles for the copyright and About link, which appear at the bottom of the server web interface.

Figure 4 Uploading an Image to the Repository

Figure 5 The Logo Image Added to the Repository

4

Page 5: Customizing Server

Customizing the JasperReports Server User Interface

A quick inspection of the themes.css file, which includes styles for typography, colors, and global page elements, reveals the names of the styles:

In this procedure you override the default style to hide the copyright and About link from all server pages. For more information about themes, see the JasperReports Server Administrator Guide.

To hide the copyright and About link on all server pages, including the Login page:

1. On the file system of the server, navigate to the \themes directory in the server installation files. By default, this directory is in the following source code location:

<js-src>\apache-tomcat\webapps\jasperserver-pro\themes

2. Copy overrides_custom.css to a different location on your hard drive and open it in a CSS editor.

3. Add the following line to the file:

4. Perform the next procedure that adds the CSS file to the repository in steps 5-9.

Graphic and Login Form on the Login PageThe pageSpecific.css in the Themes directory of the repository defines the following styles:

loginForm – positions the form 740 px to the left

loginPage and loginCopy – floats the rest of the Login page to the right

This procedure shows you how to override the styles in pageSpecific.css to:

Move the login form to the left side of the Login page.

Move the main graphic to the right side of the Login page.

Replace the main graphic with a custom graphic.

This procedure assumes that you performed steps 1-2 of Copyright and About Link (above) to place overrides_custom.css on your hard drive.

To move the login form and graphic to opposite sides of the Login page:

1. Add the following lines to the end of the overrides_custom.css file to position the login form at the left margin:

#about,

#copyright {

font-size:9px;/* 11 x 0.818 = 9 */

line-height:0.909em;

}

#about,#copyright{display:none;}

#loginPage #loginForm {

position: absolute;

left: 0px;

top: 0;

}

5

Page 6: Customizing Server

JasperReports Server User Guide

2. Add the following lines to the end of the overrides_custom.css file to float the other content on the page to the right, clearing the form by 10px.

3. Log into the server as superuser.

4. Click View > Repository.

5. In the Folders panel, right-click the customizations folder in root/Themes, and select Add Resource > File > CSS.

The Upload a File From Your Local Computer page appears.

6. In the Path to File field, browse to the overrides_custom.css file that you modified.

7. In the Name field, enter overrides_custom.css.

8. In the Resource ID field, enter overrides_custom.css.

9. Click Submit.

Overrides_custom.css is added to the customizations folder in Themes.

Activate the New Theme

To activate the customizations theme:

1. Log into the server as superuser.

2. Click View > Repository.

3. In the Folders panel, right-click the customizations folder in Themes, and select Set as Active Theme.

4. To see the Login page, click log out.

Welcome Heading and Contact Jaspersoft ButtonThis procedure shows you how to:

Change the text of the Welcome heading from Welcome to Jaspersoft to Welcome to ABC.

#loginPage #copy {

float: right;

clear: right;

width:700px;

margin-right: 10px;

}

For more information about the float or clear properties, go to http://www.w3.org, and search for the property by name.

Figure 6 The overrides_custom.css File in the customizations Folder

6

Page 7: Customizing Server

Customizing the JasperReports Server User Interface

Change the Contact Jaspersoft button on the Login page.

To customize the text of the Welcome heading on the Login page:

1. Navigate to the following directory:

<js-src>\jasperserver\jasperserver-war\src\main\webapp\WEB-INF\bundles\

2. Open this file for editing in your IDE or a text editor:

jasperserver_messages.properties

3. Search for Welcome Login Page.

4. Change the LOGIN_WELCOME_OS property from Welcome to Jaspersoft to Welcome to ABC.

5. Save and close the properties file.

To customize the Contact Jaspersoft button URL and label:

This procedure changes the URL and label of the Contact Jaspersoft button shown in Figure 1 on page 1.

1. Open this file for editing in your IDE or a text editor:

<js-src>\jasperserver\jasperserver-war\src\main\webapp\scripts\components.loginBox.js

2. Change the URL of the CONTACT_SALES_URL in the loginBox variable definition from the jaspersoft.com address to another address, for example, http://www.abc.com:

3. Open the following file for editing in your IDE or a text editor:

<js-src>\jasperserver\jasperserver-war\src\main\webapp\WEB-INF\bundles\jasperserver_messages.properties

4. Search for the BUTTON_CONTACT_SALES property and change the definition from Contact Jaspersoft to Contact ABC.

Figure 7 Welcome Login Page Properties

This change to the Welcome heading affects the login page only when running the server in the US English locale. To change it for other locales, edit the corresponding properties file. For example, to change the heading for the French locale, edit the jasperserver_messages_fr.properties in <js-src>\jasperserver-pro\jasperserver-war\src\main\webapp\WEB-INF\bundles. For information about changing the default login page from US English to another locale, see the JasperReports Server Administrator Guide.

var loginBox = {

LOGIN_BOX_TEMPLATE_DOM_ID: "login",

.

.

.

CONTACT_SALES_URL: "http://www.abc.com", /* Change this URL */

_dom: null,

7

Page 8: Customizing Server

JasperReports Server User Guide

5. Build the source code. For more information, see “Build the Source Code” on page 8.

6. Point your browser to your web interface; for example, go to http://localhost:8080/jasperserver-pro.

The relabeled button appears on the Login page.

Build the Source CodeThe documentation assumes you have set up the server development environment using Tomcat and that you can recompile and run JasperReports Server from its source code. For more information, see the JasperReports Server Source Build Guide.

To build the source code:

1. Stop Tomcat.

2. Check that no applications, including Windows Explorer, are accessing the server files or directories.

Right-click Program Files > Accessories > Command Prompt and select Run as administrator.

3. Navigate to the buildomatic directory in the source distribution:

cd <js-src>/jasperserver/buildomatic

4. Enter the following commands, checking for the BUILD SUCESSFUL message upon completion of each one:

js-ant build-ce

js-ant build-pro

js-ant deploy-webapp-pro

5. Restart Tomcat.

HOW DO YOU ADD A MENU ITEM TO THE WEB INTERFACE?This procedure shows you how to customize the web interface to add a menu item to the Create menu.

To add a menu item to the navigation model:

1. Edit this file:

<js-src>\jasperserver\common\shared-config\actionModel-navigation.xml

BUTTON_CONTACT_SALES=Contact ABC

.

.

.

This change to the name of the Contact button affects the login page only when running the server in the US English locale. To change it for other locales, edit the corresponding properties file, as described in the note in “To customize the text of the Welcome heading on the Login page:” on page 7.

If you do not run Command Prompt as administrator, the build can fail during the deployment phase due to permissions problems when adding and deleting files.

Figure 8 Create Menu on the Main Navigation Bar

8

Page 9: Customizing Server

Customizing the JasperReports Server User Interface

2. Below the context element main_create_mutton add an option element with ABC action arguments:

3. Edit the resource bundle file, which stores localized strings that users see in the web interface:

a. Open pro_nav_messages.properties in the following directory:

<js-src>\jasperserver-pro\jasperserver-war\src\main\webapp\WEB-INF\bundles

b. Locate the group of properties for the menu you want to modify.

For example, to modify the Create menu, locate the group of properties that begins with the following line:

NAV_005_CREATE=Create

c. Below this line define a new property using the labelKey as the property name and using ABC Watchlist as the value:

NAV_123_ABC=ABC Watchlist

4. At this point, you can build the source code as described in “Build the Source Code” on page 8, log into the server, and check that the new menu item, ABC Watchlist, appears on the Create menu.

Alternatively, you can perform the next procedure, and then build the source code.

<context name="main_create_mutton" test="isProVersion">

<selectAction labelKey="NAV_005_CREATE">

<option labelKey="NAV_051_ADHOC_REPORT" action="primaryNavModule.navigationOption" actionArgs="designer"/>

<option labelKey="NAV_050_DASHBOARD" action="primaryNavModule.navigationOption" actionArgs="dashboard"/>

<!--------------- Add the following ABC option element: -------------------->

<option labelKey="NAV_123_ABC" action="primaryNavModule.navigationOption" actionArgs="abc"/>

. . .

</context>

To add a menu item to the View menu, add the option element to the main_view_mutton context element.

To add a menu item to the Manage menu, add the option element to the main_manage_mutton element.

This menu item appears on the Create menu only when running the server in the US English locale. To change it for other locales, edit the corresponding properties file. For example, to change the menu for the French locale, edit pro_nav_messages_fr.properties.

Figure 9 Custom Menu Item

9

Page 10: Customizing Server

JasperReports Server User Guide

HOW DO YOU INCORPORATE SERVER STYLES INTO CUSTOM CONTENT?If you simply create custom content and place it in the web application directory, the new menu item will link to it. The design of your content, however, will not match the design of the JasperReports Server. Most likely, your custom content will look poorly integrated design-wise unless you use the Spring Web Flow framework as described in this section.

In a few steps, you can incorporate the look and feel of the JasperReports Server into your custom content by integrating into the Spring Web Flow framework the custom content linked to a new menu item.

To incorporate the look and feel of the server UI into custom content:

1. Create an XML file with the flow container element and view-state element, as shown in the following example:

2. Name the XML file abcFlow.xml, and save it in the following location:

<js-src>/jasperserver/jasperserver-war/src/main/webapp/WEB-INF/flows

3. Decide which server-defined styles you want to apply to your custom content:

a. Login to the server as an administrator.

b. Click View > Samples.

c. In the Index to Sample Galleries panel, scroll down to Standard Layouts:

<?xml version="1.0" encoding="UTF-8"?>

<flow xmlns="http://www.springframework.org/schema/webflow" xmlns:ns0="http://www.w3.org/2001/XMLSchema-instance"

ns0:schemaLocation="http://www.springframework.org/schema/webflow http://www.springframework.org/schema/webflow/spring-webflow-2.0.xsd"

start-state="startHere">

<view-state id="startHere" view="abc">

</view-state>

</flow>

To decorate your JSP content linked to the custom menu item, you must integrate it into the Spring Web Flow framework through this XML file.

Figure 10 Standard Layouts in Sample Galleries

10

Page 11: Customizing Server

Customizing the JasperReports Server User Interface

d. Click One Column.

Decide to use the One Column, Primary layout shown Figure 11.

e. Click View > Samples again, and in Index to Sample Galleries, select Typography.

f. In the Swatches panel, scroll down to Text Accents. The CSS warning class defines the red text style.

You decide to use the Warning style to highlight the date and time in your JSP content. You feel confident about how to accent the text using the Warning style, but want more information about how to use the column layout style. You can obtain more information from the CSS files in the repository.

4. Click View > Repository. In the Folders panel, scroll down to Themes, right-click default, and select Download Theme.

Figure 11 Sample of the Primary, One Column Style

Figure 12 CSS Warning Text Accent

Figure 13 Download the Default Theme

11

Page 12: Customizing Server

JasperReports Server User Guide

A file named default.zip appears on your hard drive.

5. Open pages.css in the default.zip file, read the comments to understand how to use the column layout styles, and then search for one column.

6. Create the JSP file to link content to the new menu item, as shown in the following example:

7. Save the JSP file in this location:

<js-src>\jasperserver-pro\jasperserver-war\src\main\webapp\jsp

8. Open actionModel.primaryNavigation.js in this directory:

<js-src>\jasperserver\jasperserver-war\src\main\webapp\scripts\

9. Locate the home navigation path and insert the URL for abc.jsp:

10. Open JSCommonController.java in this directory:

<js-src>\jasperserver\jasperserver-war-jar\src\main\java\com\jaspersoft\jasperserver\war\control

/* ONE COLUMN */

.oneColumn>.primary.column,

.body.oneColumn>.primary.column,

.row.oneColumn>.primary.column {

right:0;

left:0;

display:block;

}

You can set the CSS class of the body element to one column primary in your JSP file to capture the look and feel of the one column layout.

<!DOCTYPE html>

<html>

<head><title>ABC Watchlist</title>

<link href="favicon.ico" rel="shortcut icon">

</head>

<body class="oneColumn primary column">

<h1>ABC Regional Reports</h1>

<%@ page import="java.util.*" %>

<h2 class="warning">Time on server: <%= new Date() %></h2>

<%@ taglib prefix="tags" tagdir="/WEB-INF/tags" %>

<h2>Region 1 Commission</h2>

<tags:displayReports>

<jsp:attribute name="unchanged">

Sales Rep: ${name}<br/>

Commission Q1: ${origCommission}

Commission Q2: ${newCommission}

</jsp:attribute>

. . .

</body>

</html>

home: {url : “home.html”}

abc : {url : "flow.html", params : "_flowId=abcFlow"}

12

Page 13: Customizing Server

Customizing the JasperReports Server User Interface

11. Add this method to JSCommonController.java after the homePage method:

12. Modify the servlet definition file:

a. Open this servlet definition file for editing:

<js-src>/jasperserver-war/src/main/webapp/WEB-INF/jasperserver-servlet.xml

b. Locate this line:

<prop key=”/home.html”>loginController</prop>

c. Directly below it, add the following line:

<prop key=”/abc.jsp”>jsCommContr</prop>

d. Locate this line:

<prop key>=”/home.html”>homePage</prop>

e. Directly below it, add this line:

<prop key>=”/abc.jsp”>abc</prop>

13. Build the source code as described in “Build the Source Code” on page 8.

14. Login to the server, and click Create > ABC Watchlist.

The abc.jsp page, which you created in step 6, appears.

Your custom content looks like a standard JasperReports Server page and incorporates the primary, one-column style that you specified.

public ModelAndView abc(HttpServletRequest req, HttpServletResponse res)throws ServletException {return new ModelAndView("abc");}

Figure 14 Custom JSP page

13

Page 14: Customizing Server

JasperReports Server User Guide

HOW DO YOU DISPLAY A MENU ITEM CONDITIONALLY?In this procedure, you customize the web interface to dynamically display a menu item based on a business rule, for example, the role of the user. You add logic to display a new menu item only to administrators. When end-users log in, the menu item does not appear.

To customize the web interface based on a condition:

1. Open the following file for editing:

<js-src>\jasperserver\common\shared-config\actionModel-navigation.xml

2. Wrap the abc action arguments that you created in “How do you add a menu item to the web interface?” on page 8 in the condition element, as shown in the following snippet:

If the role of the person logged in is ROLE_ADMINISTRATOR, the ABC Example menu item appears on the Create menu; otherwise, it does not appear.

3. Build the source code as described in “Build the Source Code” on page 8.

4. Log into the server as an administrator, and click Create on any server page.

The custom menu item appears on the Create menu.

5. Log into the server as joeuser, and click Create on any server page.

The custom menu item does not appear on the Create menu:

HOW DO YOU HIDE THE MAIN NAVIGATION?You can hide the main navigation from the web interface to prepare the server to use custom navigation. You can hide the main navigation by overriding the default theme with a custom theme, as described in the following procedure.

<condition test="checkAuthenticationRoles" testArgs="ROLE_ADMINISTRATOR">

<option labelKey="NAV_123_ABC" action="primaryNavModule.navigationOption"actionArgs="abc"/>

</condition>

Figure 15 The Create Menu as Seen by an Administrator

Figure 16 The Create Menu as Seen by Joe User

14

Page 15: Customizing Server

Customizing the JasperReports Server User Interface

To hide the main navigation:

1. On the file system of the server, navigate to the \themes directory in the server installation files. By default, this directory is in <js-install>\apache-tomcat\webapps\jasperserver-pro\themes.

2. Copy overrides_custom.css to a location on your hard drive and open it in a text editor, such as Notepad.

3. Add the following line to the end of the file:

4. Log into the server as an administrator, such as superuser.

5. Click View > Repository.

6. In the Folders panel, select the customizations folder in the root\Themes folder.

If you did not create this folder earlier, do it now. For more information, see “Company Logo on All Pages” on page 3.

7. Right-click the customizations folder, and select Add Resource > File > CSS.

The Upload a File From Your Local Computer page appears.

8. In the Path to File field, browse to the overrides_custom.css file that you modified.

9. In the Name field, enter overrides_custom.css.

10. In the Resource ID field, enter overrides_custom.css.

11. Click Submit.

Overrides_custom.css is added to the customizations folder in Themes.

12. In the Folders panel, right-click the customizations folder in Themes, and select Set as Active Theme.

The main navigation is hidden. Log Out is the only visible function.

In this state the web interface is seriously limited until you define your own custom navigation.

13. To restore the navigation, reset the default theme:

a. Log out of the server and log in again.

The Getting Started page appears:

<js-install> is the root directory where JasperReports Server is installed. For manual installations, it is the directory where you unpack the WAR file distribution.

#mainNavigation{display:none;}

Figure 17

15

Page 16: Customizing Server

JasperReports Server User Guide

b. Scroll down to Manage Server on the Getting Started page.

c. Click the Manage Server button.

d. On the Manage Home page, click the Repository button.

e. In the Folders panel, locate Themes, right-click the default folder, and select Set as Active Theme.

The main navigation appears.

Figure 18 Main Navigation Hidden in the Web Interface

Figure 19 Repository Button on the Manage Home Page

16