Macro and Conditional Logic EUI Tutorial
Macros are short, reusable pieces of code that represent a longer set of instructions for the software or browser to perform. Macros allow developers to save time and simplify their code. In the Agiloft EUI context, macros are shorthand instructions for linking in pages, requesting data from Agiloft, or creating table views in the EUI. Agiloftuses the Velocity Template Language, a Java-based template engine, to expand macros - also known as Velocimacros. For more information, see the Velocity User Guide.
Macros may require one or more additional parameters.
#ew_forward($templateName) is a macro that creates a link to another template page in the EUI and requires the $templateName parameter. In practice, the macro might look like
More generally, macros come in the form
#macro_name($param1, $param2, $param3, ...). When used in practice, each parameter is enclosed in double quotation marks.
Let's look at the
#ew_image macro used in the following ways:
$imageName parameter is the relative file path to the image from within the KB. It is the same information provided by the src attribute in a linked image tag
This topic will give you some practical examples to help you navigate the macro scripting language, add visibility conditions, and create new pages in the EUI.
Adding Images and Customizing the Logos
One of the first changes many customers want to make is to add their own logo to the EUI. Based on the wireframe above, this is an element in the header.htm file.
- Upload the new logo via the Icons tab of the Look and Feel wizard. This will make it available in the /gif directory where it can be called by the
header.htmin the EUI Templates table.
In the Body field, locate the line that reads:
To link a new logo, simply replace the reference to
#ew_imagemacro with the new file name.
- Change the alt attribute value from "Agiloft" to the new logo name.
- Change the width and height properties to match the new logo dimensions, or leave out the dimensions to display it at its full size.
Click Save when you are finished, and the new logo will be visible when you log into the EUI.
The Velocity engine expands the relative file path
/gif/logo-name.pnginto a fully formed URL. The expanded URL becomes the value of the src image and links in the image.
Adding Table and Record Functions
More complex functions in the EUI are done in much the same way as the logo example above: by using the specialized macros to add tables, records, and forms. For more information on the available macros, see EUI Macro Reference. The main difference is that while
#ew_image requires a single parameter
$imageName, the more complex macros require several parameters.
In the default EUI setup, each of the basic page types corresponds to an Agiloft macro that links in the table, record, or form, and can apply search filters or set additional parameters.
Table views use the
#ew_tablemacro, which creates an iframe and displays an Agiloft table inside it. For example, the My Support Cases or All Documents pages.
Record editing pages use the
#ew_edit_recordmacro. For example, the My Profile page.
Submission forms use the
#ew_create_recordmacro. For example, Create a Support Case.
The Velocity Template Language has a prebuilt #if directive. Used within the body of an EUI template, #if helps to apply conditional visibility to various HTML elements.
#if (condition A is true)
This will display the text 'Welcome!' only if the condition is true; otherwise
To set up more complex conditions you can use the full range of If/ElseIf/Else logic. You can also use relational and logical operators within an #if condition.
This will evaluate if both conditions A and B are true.
#if ([conditionA] || [conditionB])
This will evaluate if condition A or condition B is true (or both).
Conditional User Customization
A Velocity method is defined in Java and can be used to check conditions or arrive at decisions. The following methods can be used to check user group or team membership and perform functions if the specified group/team names are found:
You can also use operators to combine conditions. For example:
#if ($ew.User.isInGroup("Internal Customer") || $ewUser.isInGroup("Customer"))
The code below will display a welcome message only to users in the Guest group:
Suppose you wanted to display a different logo to users in a particular group or team. With a few simple statements in the EUI Template header.htm you can achieve this goal.
In the header.htm record, locate the line related to the logo which you edited earlier in this topic:
Replace this with the following lines of code and save the record:
The new code does the following:
Log in with different test users to confirm that only contract creators can see the initial Agiloft logo.