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

Prepopulating Records in the EUI

This section explains how to pass parameters using the  Agiloft macros in the EUI and how this can be used to make hotlinks that will populate records. This will require web development and JavaScript expertise.

The main usage of this feature would be to provide users with different links to create various types of tickets. For example, you could use a different link for critical tickets or for submitting to another department. This could also be used with a question tree to track user responses and to submit a ticket at the end based on those responses.

Passing Data Between Pages

To add a query string created by #ew_forward to a URL, add a question mark after the macro, followed by the parameter names and values.

example.location.href="#ew_forward("mytemplate")?param1=value1&...&paramN=valueN";

'#ew_forward("case")?summary=I\'m locked out&priority=Critical&assigned_team=Admin team'

To pre-fill fields in the form created by #ew_create_record, add an ampersand (&) after the macro followed by the parameter names and values.

example.location.href="#ew_create_record("mytemplate")&param1=value1&...&paramN=valueN";

#ew_create_record("case", "/eui2template/main.php", "parent")&summary=I\'m locked out&priority=Critical&assigned+team=Admin Team
  • In most cases the individual parameters values do not need quotes and may have spaces. However, older browsers may not interpret the spaces correctly. To include single or double quotes they must be preceded by a backslash (\).
  • When populating fields use the name of the field, not the label.
  • There appears to be no difference in the format of the values based on field data type. Text, number, choice and linked fields all function the same in testing.

Grabbing Passed Data

The next step is to take the query parameters that were passed with #ew_forward and include them in the #ew_create_record on the new page. This can be done with either JavaScript or standard Velocity macros.

This is a standard block that holds the new record form:

<td class="main-block" id="main_frame">
<iframe src='#ew_create_record("case" "/eui2template/main.php" "parent")&summary=fail' name="content_frame" id="frameres" width="100%" height="100%" frameborder="0"></iframe>
</td>

In this example, the new #ew_create_record macro is in the SRC attribute for the iframe, and the frame itself is in a table cell with the ID of main_frame. This is the standard setup, which may vary.

Since the macro is expanded before the page is actually loaded, in order to add in the extra parameters passed to the page we either have to use other macros or replace the entire iframe with JavaScript. If you are pre-populating only fixed values or data from other macros (such as the user login), the JavaScript will not be needed.

Using JavaScript

In this example, we'll use JavaScript to redraw the entire iframe containing the #ew_create_record macro.

  1. Comment out the existing iframe in the HTML: <!--- commented part here --->
    This will cause nothing to be displayed on the page. If users do not have JavaScript enabled, you may want to add text outside of the commented area but still within the table cell, such as "You must have JavaScript enabled to submit a new record." If the JavaScript is working, it will overwrite that text.

  2. Next, in the head section of the page, add the following:

    <script language="javascript"> 
    function fillForm()
    {
    var frameTag='<iframe src=\'#ew_create_record("case" "/eui2template/main.php" "parent")&' + window.location.search.substring(1) + '\' name="content_frame" id="frameres" width="100%" height="100%" frameborder="0"></iframe>'
    document.getElementById("main_frame").innerHTML=frameTag
    }
    </script>

     

    1. This example is for the Support Case table (logical table name is "case"). Change the #ew_create_record macro part as appropriate for your configuration.
    2. The portion &' + window.location.search.substring(1) is where the query parameters that have been passed to the page are added. In this setup example we will be grabbing all of the parameters exactly as they are passed.
    3. If the table cell – or whatever HTML element contains the iframe – has a different ID, you will need to adapt the getElementByID("main_frame") portion.
  3. Add a call to the fillForm() function to the onload event in the body tag of the page.
    1. The standard configuration looks like:  <body onload="menuChange();" id="main_table_top">. Change this to <body onload="fillForm();menuChange();" id="main_table_top">.
    2. This should be all that is needed for the basic setup. The #ew_forward URLs can be used, as above, to pass parameters to populate the forms.
  4. If you wish to not grab all of the parameters, a second JavaScript function can be added to parse the query string and grab only the requested parts:

    function qs(search_for)
    {
    var query = window.location.search.substring(1); 
    var parms = query.split('&');
    for (var i=0; i<parms.length; i++) 
    { var pos = parms[i].indexOf('=');
    if (pos > 0 && search_for == parms[i].substring(0,pos)) {
    return parms[i].substring(pos+1);;
    }
    }
    return "";
    }
  5. Referencing this function, the fillForm() function can be changed to say:

    function fillForm()
    {
    var frameTag='<iframe src=\'#ew_create_record("case" "/eui2template/main.php" "parent")&summary=' + qs("summary") + '&priority=' + qs("priority") + '\' name="content_frame" id="frameres" width="100%" height="100%" frameborder="0"></iframe>'
    document.getElementById("main_frame").innerHTML=frameTag
    }
    

    Here, we have replaced the &' + window.location.search.substring(1) portion from the earlier example with &summary=' + qs("summary") + '&priority=' + qs("priority"). This will check to see if a parameter has been passed with the given name and return the value, or return blank if the parameter is not found. This could be useful if the parameters are being passed with incorrect names, or if you only want to use selected parts of the query string.

Using Standard Velocity Macros

Instead of using JavaScript to replace the entire iframe, Velocity macros can be used to grab the parameters and fill them in immediately.

You can retrieve desired parameters from the URL by using $request.getParameter("parameter"). The parameter must be named in this case. From the example of #ew_forward above, given a parameter name of 'brand' with a value of 'cs', you could pass #ew_forward("newsupport_case.htm")?brand=cs.

Once the value of a parameter has been retrieved, it can be placed into a new variable by using: #set($new_var =...). For example:

#set($brand = $request.getParameter("brand"))

This retrieves the value of the "brand" parameter and assigns it to the new variable $brand. This new variable can now be referenced anywhere in the page, including ew_macros. For example, <h1>Your brand is $brand </h1>. This approach requires assigning each parameter to a separate variable. There is likely a Velocity macro for pulling in the entire parameter string if more than one parameter is expected but the parameters do not need to be handled separately.

 

  • If one of these variables is mixed with standard text when being declared, the name of the variable should be surrounded by brackets. For example: ${brand}_otherText.
  • If the variable is being used in an ew_macro which normally encloses the values in quotes, then the variable should also be included within the quotes. For example: #ew_include("{brand}_header.htm").

By using these parameters in the existing #ew_macros it greatly extends the ability to customize the behavior of the macros based on the page or link the user has come from.

Example: 

#ew_create_record("case" "/eui2template/${brand}_main.php" "parent")

This macro lets the user create a support case and then forwards them to a different home page based on the brand parameter. This can be used to create differently branded home pages - the links from the initial home page set the brand parameter, which is then used in #ew_include and other macros in the pages.