Page tree
Skip to end of metadata
Go to start of metadata

EUI Portal Tutorial

The following pages contain a tutorial aimed at getting you started with creating a portal from scratch. It assumes familiarity with the Agiloft application and user interface. Some basic HTML knowledge is useful, but not absolutely necessary.

The portal you'll create in the tutorial is for illustrative purposes only. The HTML is very basic and designed for simplicity rather than representing advanced web development techniques. However, it is fully functional and should give you the practice you need to carry on with confidence.

Prerequisites

To successfully work through this tutorial, you will need access to a knowledgebase (KB) with the following setup:

  1. A user who is a member of the Admin group.
  2. A table with logical name contacts, usually labeled People, with a Default Contact View.

  3. A table with a logical name of case, usually labeled Support Cases.
  4. The EUI Templates table is activated and visible in the left pane.


From this point forward we will refer to your Agiloft server host as {host} and your knowledgebase as {kbName}. Take a look at the URL in your browser after logging in to your KB: the server host is in the first part of the URL.


Create a Simple Web Page

First, create a dummy user to act as the end user who will access the portal pages you create:

  • Login as admin and add a new user with a login of 'portalUser' and a password of 'test01.' You can enter any Name and Company you want.
  • Set the user to be a member of a group with permission to view ALL of the entries in the Contacts table, for example, the Support Staff group.

Next, you will create a very simple home page for the new user to access via the portal:

  1. Select the EUI Templates table.

    Note: If you do not see the EUI Templates table in the left pane, then permission access to the table has not been activated.  To turn on access to the table, click Setup > Access > Manage Groups and edit the Admin group. On the Table tab of the wizard, select EUI Templates in the table tree. Scroll down to select Yes on the options to allow access to the table and to show table on the toolbar.

  2. Create a new EUI template record with the following information:

    1. In the Name field: testContacts.htm.
    2. In the Description field: Test contacts page.
    3. In the Body field, enter the following:

      <html>
      <head><title>Test portal</title></head>
      <body>
      <h1>Test portal</h1>
      <div align="left">This is my new portal</div>
      <>
      </body>
      </html>
    4. Click Save when you are finished.
Test your work
  1. Open a new browser window and enter the following URL:
    {host}/gui2/eui2template/testContacts.htm?kb={kbName}&user=portalUser&passwd=test01

  2. You should see the following:

Congratulations! Even though the page doesn't look like much, you have accomplished the first step toward creating your custom End User Interface.

Make it a Bit More Useful

Now that you have a functioning web page, you can start to make it more useful by adding additional features, such as table views and links.

Next, add a view of the Contacts table to this page.

  1. While logged in as the admin user, navigate to the EUI Templates table.
  2. Edit the testContacts.htm template record that you created earlier.
  3. Edit the contents of the Body field by adding a new <div> and the #ew_table macro so that it matches the HTML below. Click Save when finished:

    <html>
    <head><title>Test portal</title></head>
    <body>
    <h1>Test portal</h1>
    <div align="left">This is my new portal</div>
    <br />
    <div align="left"><font
    size="+2">Contacts</font></div>
    #ew_table ("contacts" "Default Contact View" "" "" "" "contacts_frame" "")
    </body>
    </html>
    
Test the page again
  1. Open a new browser window and enter the same URL you used earlier:
    {host}/gui2/eui2template/testContacts.htm?kb={kbName}&user=portalUser&passwd=test01

  2. This time you should see something that looks like the following:

Try out the table. You can view and edit records, apply views, use saved searches—anything that the user’s group permissions in Agiloft allows. You have created a fully functional portal into the Contacts table.

How it Works

Before going any further, it is worth taking a step back and understanding how all this works. It will make what follows easier to understand. If you are experienced with HTML and are reading this guide for specific help with the Agiloft setup, you may want to refer to our EUI Tips and EUI Macro Reference.

What's in a URL?

A URL is an address. It specifies all the information needed to locate something on the internet. In this case, the URL tells your web browser how to locate the page you are constructing.

Take a look at the URL we used:
{host}/gui2/eui2template/testContacts.htm?kb={kbName}&user=portalUser&passwd=test01

  • The first part – {host}/gui2/eui2template/testContacts.htm – identifies the physical server machine on which the Agiloft software is installed, and specifies the name of the page template to retrieve from the EUI Templates table.
  • The last part–?kb={kbName}&user=portalUser&passwd=test01 – specifies which Agiloft knowledgebase the page template belongs to, and supplies the user’s login credentials to validate and authorize the page request.
  • Note: You may notice ;jsessionid=5E..... in place of the login credentials in the URL after logging in. This is normal. Once the credentials have been verified as correct, a user session is created on the server. Your web browser only needs to refer to the session by ID when requesting a page from Agiloft. This allows the software to retrieve your session, which contains all the details it needs.

Bear in mind, each session is only valid for a certain length of time after you stop using Agiloft. If you try to reuse a URL with a session ID in it at a later time, it probably won't work.  Remember to use the longer form of the URL as above.

Putting it all together

When you enter the URL into the web browser, a few things happen:

  1. The server looks up the page template in the database and retrieves it.
  2. The page template is passed through the Velocity template engine for macro expansion. In the example EUI Template above, #ew_table(...) is a macro that adds a table to a page. We will explain how that happens in more detail a little later on.
  3. Once all the macros have been expanded, the resulting HTML page is sent back to the web browser for display.

Note: The HTML on the page may contain other links (URLs) for page elements, e.g., images. In that case, the web browser will separately request all the links and assemble the results into the finished page.

A Closer Look

Let's take a closer look at the sample portal template to see how the theory works in practice.

  • Here is the page template testContacts.htm from earlier, with line numbers added for ease of reference:

    1. <html>
    2. <head><title>Test portal</title></head>
    3. <body>
    4. <h1>Test portal</h1>
    5. <div align="left">This is my new portal</div>
    6. <br />
    7. <div align="left"><font size="+2">Contacts</font></div>
    8. #ew_table ("contacts" "Default Contact View" "" "" "" "contacts_frame" "")
    9. </body>
    10. </html>
  • Line 8 is a Velocity macro. Once this template has been retrieved from the database, it is passed through the Velocity template engine for macro expansion as described earlier. Let's take a look at the HTML page returned once macro expansion has taken place:

    <html>
    <head><title>Test portal</title></head>
    <body>
    <h1>Test portal</h1>
    <div align="left">This is my new portal</div>
    <br />
    <div align="left"><font size="+2">Contacts</font></div>
    <iframe name="contacts_frame"
    width=100%
    height=100%
    border=0
    class=""src="/gui2/data/search.do;jsessionid=FC9AC66893B5D7DA29DE3D07998D74050247?q_id=63717&showToolBar=false&view=42744&"></iframe>
    </body>
    </html>
    

    You can see this by right-clicking in the browser window and choosing View Source in Internet Explorer or View Page Source in FireFox.

  • The macro #ew_table in line 8 of the page template has been replaced and expanded in the finished page with the <iframe> page element. The iframe has a name attribute with the value "contacts_frame" as specified in the macro. You can find out more about the iframe HTML element at https://www.w3schools.com/html/default.asp.
  • The <iframe> element creates an area on the page and obtains the content for the area by requesting it separately from the server as described above. The value of the src attribute (/gui2/data/search.do.....) gives the browser the location, or URL, of the requested content. The returned HTML is complex; it references CSS stylesheets and JavaScript functions. You can see what it looks like by right-clicking somewhere on the table and choosing View (Page) Source as before.

Useful Additions

What we've done works nicely, but a real portal will have multiple pages, working together to give users access to what they need.

Add Pages

In this section, our aim is to expand the portal you have created to include two pages the user can switch between: one to manage contacts and the other to manage tickets. You will also add the ability to use saved searches to filter the displayed records, a convenient link for the user to logout, and some status information to display the current user's login.

Add Records

First, you will add a new link to the page to allow the end user to add a new contact.

  1. Log in as an admin.
  2. Edit the testContacts.htm page template in the EUI Templates table. 
  3. Add lines 9-12, so the resulting code looks like:

    1. <html>
    2. <head><title>Test portal</title></head>
    3. <body>
    4. <h1>Test portal</h1>
    5. <div align="left">This is my new portal</div>
    6. <br />
    7. <div align="left">
    8. <font size="+2">Contacts</font>
    9. &nbsp;&nbsp;
    10. <a href="#ew_create_record("contacts" "/eui2template/testContacts.htm" "")">
    11. New Contact
    12. </a>
    13. </div>
    14. #ew_table ("contacts" "Default Contact
    15. View" "" "" "" "contacts_frame" "")
    16. </body>
    17. </html>

    This new code creates a New Contact link on the portal. The URL of the link is supplied by the velocity macro #ew_create_record.

  4. Take a look at the parameters for the macro. The first parameter, “contacts”, specifies the name of the table where the new record should be created. The required name of the table can be found in Setup > Tables by selecting the desired table and clicking Edit. On the General tab of the table wizard, look for the name displayed under Logical Table Name.

  5. The second parameter tells Agiloft where to redirect the user when they are finished adding the new record and selects Save or Cancel. In other words, it provides a URL indicating that the system should re-display the contacts page once the user is finished with the record.

  6. Save the changes and re-test the portal interface. Try adding a new contact using the interface, then check how the contacts page displays after saving.

Add Saved Searches

Next we'll add the saved search selection drop-down.

  1. Edit the testContacts.htm template again so that it looks like the following:

    <html>
    <head><title>Test portal</title></head>
    <body>
    <h1>Test portal</h1>
    <div align=”left”>This is my new portal</div>
    <br />
    <div align=”left”>
    <font size=”+2”>Contacts</font>
    <a href=”#ew_create_record(“contacts” “/eui2template/testContacts.htm” “”)”>New Contact</a>
    </div>
    <div align=”right”>#ew_searches_list(“contacts” “contacts_frame” “contacts_select” “” “”)</div>
    #ew_table(“contacts” “Default Contact View” “” “” “”  “contacts_frame” “”)
    </body>
    </html>
  2. The #ew_searches_list macro adds all the HTML and JavaScript needed to add a drop-down list of available saved searches and attach it to the displayed table. Permanently displayed searches are dynamically based on the user’s group permissions. When the user selects a saved search, the table re-displays with the filtered results of the chosen search.

  3. Take a look at the parameters of the #ew_searches_list macro:

    1. The first parameter specifies the name of the table associated with the saved searches list you want to display.
    2. The second parameter tells Agiloft the name of the iframe element where the search results will be displayed. In this example, we've specified the name of the iframe created earlier by the #ew_table macro, “contact_frame”. As a result, the Contacts table refreshes with the saved search results when an entry in the saved search drop-down is selected.
    3. The third parameter gives a name for the HTML <select> element that is created by this macro. Setting a name can be useful if you want to refer to the element later, perhaps to change its attributes, but for the purposes of this tutorial we will leave it blank.
    4. The fourth, fifth, and sixth parameters let you apply a CSS class to the <select> list, indicate request parameters that should be passed to the table when the search is displayed, and specify which default search to use.

      Note: The parameters for each macro are described in Macros Reference.

  4. Save changes and re-test your portal. Locate the new drop down list on the right hand side of the screen. Try choosing a saved search and observe that the Contacts table refreshes with the search results.

Make an Included Template

Now you are almost ready to add a Tickets page to the portal, but first we will make an included template to contain the content that is common to both pages.

  1. Create a new record in the EUI Templates table. Name it "testHeader.htm", and type or copy-and-paste the following into the Body field:

    <html>
    <head><title>Test portal</title>
    </head>
    <body>
    <h1>Test portal</h1>
    <div align="left">This is my new portal</div>
    <div align="right">
    You are logged in as <b>#ew_user()</b>.
    <a href="#ew_logout('http://www.agiloft.com')">Click to logout</a>
    </div>
    <br />
    

    Notice the two velocity macros, #ew_user and #ew_logout, used in the code. These expand to the login of the current user, and a logout link, respectively. The macro #ew_logout takes a URL parameter: this is the URL the user is redirected to after they have logged out.

  2. Save the new testHeader.htm template, then open the testContacts.htm template for editing.

  3. We are going to remove some of the code from the testContacts.htm template. We obtain the content by including our new header template instead.
    Here are the first few lines of the testContacts.htm template, with line numbers added for convenience:

    1. <html>
    2. <head><title>Test portal</title></head>
    3. <body>
    4. <h1>Test portal</h1>
    5. <div align=”left”>This is my new portal</div>
    6. <br />
    7. <div align=”left”>
    8. <font size=”+2”>Contacts</font>
    ...
  4. Delete lines 1-6 and replace them with the #ew_include macro. The revised template looks like this:

    1. #ew_include("testHeader.htm")
    2. <div align="left">
    3. <font size="+2">Contacts</font>
    ...
  5. Save the changes and test out the testContacts.htm portal.

We're nearly there. Next you will quickly create a Tickets page, and add a few navigation links to the included header template.

  1. Create a new EUI template. Name it testTickets.htm, and type or copy-and-paste the following into the Body field:

    #ew_include("testHeader.htm")
    <div align="left">
    <font size="+2">Tickets</font>
    &nbsp;&nbsp;
    <a href="#ew_create_record("case" "/eui2template/testTickets.htm" "")">
    New Ticket
    </a>
    </div>
    <div align="right">#ew_searches("case" "tickets_frame" "case_select" "")
    </div>
    #ew_table ("case" "Staff default" "" "" "" "tickets_frame" "")
    </body>
    </html>

    This is really just a straight copy of the testContacts.htm template with a few changes to reference tickets rather than contacts. It assumes that you have a table in your KB with a logical name of case.

  2. Save the new template, and test it to make sure it works. You can do this by viewing the testContacts.htm page in your browser, and then editing the URL, substituting testContacts.htm with testTickets.htm.
    Your resulting URL will be in the form:
    {host}/gui2/eui2template/gui2/testTickets.htm?kb={kbName}&user=portalUser&passwd=test01
  3. The final step is to add links to the header template that allow the user to navigate between the tickets and contacts pages. Open the testHeader.htm template for editing, and add the two lines highlighted in blue so that it looks like the following:

    <html>
    <head><title>Test portal</title></head>
    <body>
    <h1>Test portal</h1>
    <div align="left">This is my new portal</div>
    <div align="right">
    You are logged in as <b>#ew_user()</b>.
    <a href="#ew_logout('http://www.agiloft.com')">Click to logout</a>
    </div>
    <a href="#ew_forward("testContacts.htm")">Contacts</a>
    <a href="#ew_forward("testTickets.htm")">Tickets</a>
    <br />

    Notice the #ew_forward macro. This macro expands into a URL to forward the user to the template named by the parameter.

  4. Save the changes to the template and test out the portal. You should now have two pages, with links labeled Contacts and Tickets. The user can now switch between the two pages and can view, search and add new contacts and tickets. There is also text displaying the user’s login name, and a link to logout.

Add Style

For our last exercise in this tutorial we demonstrate the use of the #ew_url macro to link in a .css stylesheet. You can see http://www.w3schools.com to find out more about stylesheets.

  1. Create a new template and name it testStyles.css. Type or copy-and-paste the following into the Body field, and don't forget to click Save when done:

    body {font-family: arial;}
    a:link {color: blue}
    a:visited{color: blue}
    a:hover {color: teal}

    This simple stylesheet will change the font on your page to Arial. It also sets the color of links to blue, or to teal when you move the mouse over the link.

  2. Now open the testHeader.htm template for editing, and add lines 11 and 12, so that it looks like the following:

    1. <html>
    2. <head><title>Test portal</title></head>
    3. <link rel="stylesheet" type="text/css" href="#ew_url("eui2template/testStyles.css")"/>
    4. <body>
    5. <h1>Test portal</h1>
    6. <div align="left">This is my new portal</div>
    7. <div align="right">
    8. You are logged in as <b>#ew_user()</b>.
    9. <a href="#ew_logout('http://www.Agiloft.com')">Click to logout</a>
    10. </div>
    11. <a href="#ew_forward("testContacts.htm")">Contacts</a>
    12. <a href="#ew_forward("testTickets.htm")">Tickets</a>
    13. <br />
  3. Click Save, then login to see the changes to your portal's appearance.

Why did we use the #ew_url macro?

The ‘testStyles.css’ stylesheet that you created is stored as a record inside the EUI Templates table. When the browser receives the portal page HTML, it follows the URL in the <href> attribute of the <link> element to request the contents of the stylesheet.

The #ew_url macro turns the relative URL, passed as the parameter, into a valid Agiloft URL complete with user session information. Just like a URL for a page template, it must contain all the information needed to prove the request is coming from a valid Agiloft user, such as the jsessionid described earlier.

Here is an example of what the HTML looks like after macro expansion has been performed:

<link rel="stylesheet" type="text/css" href="/gui2/eui2template/testStyles.css;jsessionid=83BB5B689B95B0A352942DAEAB0247"/>

Wrap Up

That's it! You now have the basic knowledge you need to carry on and create a useful interface for your users.

We've covered:

  • How to create portal page templates in the EUI Templates table, and how to access them through a browser.
  • What's contained in the URLs that your browser uses to access page templates.
  • Use of the #ew_table#ew_searches_list and #ew_create_record macros to add record management functionality
  • Use of the #ew_user and #ew_logout macros to display login information and provide a logout link
  • Use of the #ew_forward macro to provide links that forward the user to different page templates
  • Use of the #ew_include macro to pull common content into multiple pages
  • Use of the #ew_url macro to create a valid Agiloft URL including user session and authentication information

A good way to learn more is to look through the default EUI template pages that are included with the default knowledgebase. With the knowledge you've gained already you should be able to understand how the templates work.

Because templates use the Velocity engine for Agiloft macros, any other Velocity constructions are also available for your use. Please see Velocity’s documentation for details here: http://velocity.apache.org/engine/releases/velocity-1.4/user-guide.html.

Notes:

1. If no login details are included in the URL when a user accesses Agiloft, the system will try to login with user=eui2, password=qwerty. If you would like to take advantage of this automatic login, ensure that a user created with those login credentials exists, and is granted the appropriate permissions

2. If users belong to different groups, and their end-user interfaces allow them access to different areas of your Agiloft application, you will need to either create a separate portal interface for each group or use conditional #if macros to determine what they see. All users logging into one particular EUI template will see the same HTML, regardless of the permissions granted to their individual groups. When users begin to interact with the Agiloft application through the portal controls, such as attempting to add a new record, detailed group and user permissions will come into play. The user’s group permissions may restrict or permit access to tables, fields, and records.









  • No labels