Working with the Default EUI Templates
This topic provides instructions on how to control which tables are displayed on the End User Interface home page and menu bar, add new tables to these sections, and some code samples to set up these areas in the templates.
The end user interface is controlled by records in the EUI Templates table. These records contain the HTML for the pages that are displayed and control the functionality and appearance of the EUI. For more information on getting started with the EUI, please review Unit 19 of the online Administrator Training at unit-19-eui.pdf.
The EUI uses macros and methods which are interpreted by the Apache Velocity template engine. For more information on the macros and methods used in an Agiloft EUI, please refer to the Macros Reference section of the EUI Tips and Reference Guide at http://www.agiloft.com/documentation/eui-reference-guide.pdf.
Home Page Layouts
Near the top of the translation.properties file are three variables that define the home page template files. The variable
global.home.file defines which of two predefined home pages to use: the default value of
In addition to these default home pages, the code automatically substitutes a third home page if the user who logs in only has access to one table, since the other home page layouts are not optimized for displaying a single table. This third home page is defined by the variable
global.home.one.table.file and by default it is set to the
The home page code defines which tables are shown to which users, the ordering of tables, and other formatting. Of course, you may create your own version of a home page if you don’t wish to use our predefined versions.
While some page components are static, such as the Logout link, other links and headings are controlled by a combination of user permissions and variables defined in translations.properties.
These conditions include the values of the
show.[table] variable, as well as the user’s specific permissions, returned by the
Making Changes or Substituting a New Home Page
To make changes to the style or layout of your end user interface home page, copy and edit one of the default home page records, or create a new template record. Then, update the
global.home.one.table variables in
translation.properties to point to your new page.
Changing the Order of Tables in the Home Page
There is a block of code for each table included in the home page; the order of these sections determines the order in which tables are displayed to users.
Therefore, to change the order of the tables, you can cut and paste one table’s section above or below another one. Just be careful to include all of the section related to that table: each section should start with an #if and end with an #end - watch out for nested if-end conditions.
Specifically, each block of table code begins with:
Please review the Home Page Table Block example code from the home.htm template, the default home page, to see how the permission-based conditions are used.
We recommend first making a copy of the template text before making significant changes.
Default Template Layouts
The default home page layouts are:
home.htm template provides a dynamic two-column display; the system dynamically calculates the layout to list the available tables in order from left-to-right and top-down.
Available links to create or view items appear under each table heading, as pictured here.
The alternative home page
home-1column.htm arranges each table on its own row with the links in a second column to the right:
home-1table.htm—Default one-table layout
home-1table.htm template uses a similar layout to the
home-1column.htm template, above. The primary differences are larger icons and text in
home-1table.htm, and an additional block of text added to fill space on the home page.
Navigation Menu Structure
The navigation menu and its contents are defined in the
menu.htm EUI template. Please refer to the Code Samples section for an example of that template’s text for the section controlling the New menu. You can see that it uses permission controls very similar to those used in the home page.
The menu template is used to count the number of tables available to a user and if the table count in the menu results in a total value of 1, then the home page defined as the single table home page is displayed to the user.
Changing which Menu Items a User Sees
Just as in the home page, the menu items are controlled by a combination of the show.[table] variable and user permissions, so if you want to hide the item from all users, the easy way is to update the translation.properties file to change the
show.[table] to no. If it should be shown to only users with specific permissions, then the approach is to update the relevant #if condition to use the appropriate permissions.
Adding a New Table to the EUI
If you want to add a table to the EUI that is not included in the default setup, you must update the EUI templates to provide this access.
For this example, we’ll suppose you have a custom table called Invoices and you would like to add functions to the EUI such as “Create an Invoice” and “My Invoices,” a link to view invoices for end users.
Below are the basic recommended steps for adding a new table:
- Create new template pages that will be launched from the home page. We recommend copying a similar EUI template record and then changing the page-specific information such as the logical table name, macro parameters, and text variables. For instance, to create a page to display the Invoices table, copy the
my_supportcases.htmlpage into a new template called my_invoices.html; to create a “Create an Invoice” page, copy the new_supportcase.html template.
- Edit the new template pages to update the logical table name, change the default view, add any default saved searches, and so on.
- If the page you copy from includes a search block, you will need to create a corresponding subsidiary search page for the new table, Invoices.
- Change the variables within the $ewText.get macro. Note down the variables you create and the text strings they represent. These variables and values must be added to translation.properties in the following step.
- In the translation.properties file (and its variants for multilingual KBs):
- Add the line show.invoices=yes
This will let you turn the Invoices table on or off quickly and allows you to use that variable in the new section of table code. For instance, in home.htm or menu.htm where you previously had
#if ($ewText.get("show.support.cases")=="yes", replace
- Add any text variables created for the subsidiary pages in the previous step.
Create new text variables for the home page and menu: the table title, create link, view links, menu tabs, etc. Use the set of variable codes from an existing table and create new variables using a similar syntax. Since we are copying from Support Cases in this example, copy the text variables (in the left column) and create new variables for the Invoices table in a similar syntax (shown in the right-hand column).
Support Case Text
home.sc.my.link=View My Support Cases
home.sc.new.link=Create a Support Case
home.invoice.my.link=View My Invoices
home.invoice.new.link=Create an Invoice
menu.view.sc.my=My Support Cases
- Add the line show.invoices=yes
- Edit the default home page(s) you are using.
- Copy an existing table’s complete section of code, e.g. the Support Case section, and paste it to create a new section of the home page template. Paste the section into the appropriate position so the tables are ordered as you prefer.
- Modify the copied block of code by replacing variables and parameters with new values associated with the table you want to display (Invoices). For example:
i. Update the
#ew_forwardmacro to point to the new template pages created in the previous step.
ii. Update the
$ewText.getstatements to use the variables created in the previous step.
iii. Update the logical table name (i.e., case) wherever it appeared.
- To add links from the menu, add new sections to the menu.htm template in the appropriate places (e.g., under the New and View sections). Copy an existing block of code and change the table name, text variables, and criteria as needed.
- Of course, you must set group permissions to give users the appropriate access to the Invoices table and its records.
This section provides you with some examples of code that can be deployed in the templates.
Home Page Table Block
Below is an example section of code for a single table, the Support Cases table, as defined in the default home.htm template. Comments are in blue, and visibility controls are highlighted in yellow.
Add the Table to Global Search
The following code sample will add the new table to the global search area for the EUI. In this example the Invoice table will be added to the global search.
home-multiple-search.htm, add the following:
In multiple-search-result.html add the following:
This section contains samples to add items in the navigation menu.
Below is the section of menu.htm that creates the New menu drop-down in the EUI.
Below is the section of menu.htm that creates the View menu drop-down in the EUI.
- Home Page Layouts
- Default Template Layouts
- Navigation Menu Structure
- Adding a New Table to the EUI
- Code Samples