Portal Pop-ups
  • 23 Jan 2025
  • 11 minute read
  • Dark
    Light
  • PDF

Portal Pop-ups

  • Dark
    Light
  • PDF

Article summary

Pop-ups in portals can provide end-users with additional information about an individual item, or they can allow end-users to view and update information using a form. Typically, pop-ups are leveraged by clicking on an individual result within a list or table of records. Creating a pop-up involves the following steps:

  1. Creating a query (for pop-ups that only display information) or a form (for pop-ups that allow information to be updated).

  2. Creating a pop-up view.

  3. Creating a pop-up method.

  4. Updating the main view to link to the new pop-up.

Create the Query (Display Only)

If your pop-up only needs to display information, you’ll need a query that determines the information to display and a view to format the output of the query.

  1. Create a new query. The base of your query should match the object being clicked on for the popup. For example, if your popup is displaying information about a student record, choose the Person base.

  2. Click Edit Parameters to open the parameter popup. Each parameter has an ID, which will be used in your query, and a type, which defines the type of data being passed in. The id attribute must computer-friendly, meaning it only uses letters and underscores. Since we’re passing a GUID, the type attribute will be uniqueidentifier. Use the following syntax to create your parameter: <param id="id_of_parameter" type="type_of_parameter" />.

    Important!

    Do not use id or identity as your parameter ID, or your query will not work as expected. The record parameter ID should only be used for specific purposes in Reader portals.

  3. Click Save to save your parameter.

  4. Click Filter and search for the GUID filter. Make sure you’re choosing the filter from the base of your query, under Direct Filters. In this example, we would choose the filter in the Person section.

  5. On the following screen, enter the at symbol (@) followed by the parameter ID. In this example, the parameter ID is person.

Create the Form (Updating Information)

If your pop-up needs to allow the end-user to update information in the database, you’ll need to create a form. Pay special attention to the settings in the Edit Properties:

  • Scope: The scope of the form should match the record being updated, even if the form is only updating a single related item.

  • Multiple: In general, it’s safest to check this box for portal pop-up forms, since the same form is used across multiple instances of the same pop-up.

  • Unsafe (Person-scoped forms): Consider the use case for this pop-up to determine whether to check this box. Person-scoped record data (like name or birthdate) and related data (like sports or addresses) will be prevented from saving if the student has an active application and this box is unchecked.

  • Security (Person- and Dataset-scoped forms): Checking one of the two options here is required if you want to use merge fields on your form. If you don’t need merge fields, this setting is not required since the person query string parameter will prefill existing data regardless.

  • Save for Later: Do not check this box.

There are two main types of forms for pop-ups: updating record information, and updating related information.

Updating Record Information

This type of pop-up form will only contain fields with the same scope as the record. For example, if your popup allows students to update their directory information; or, if your portal displays a list of students to staff members and allows updates to their information.

Updating Related Information

This type of pop-up form will represent a single row in a related table, like Sport or an entity row. It requires specific form fields and additional configuration when being added to the main view because Slate does not support application-style widgets in portals. The following requirements must be met:

  • The scope of the form must be the same as the record, not the related item.

  • The GUID of the related item must be mapped in a read-only form field.

  • Any form field mapping must be provided to the form via query string parameters. This means it’s not advisable to map a lot of fields on the form - limit the mappings to only the needed elements.

For example, let’s say a Person-scoped portal is displaying a list of Sports. The form might look something like this:

The “Sport GUID” form field maps to “Sport - GUID Matching Only” and is marked as “Read only”. The “Rating” form field maps to “Sport - Rating”.

Create the View

If your pop-up is only displaying information, your pop-up view only needs one Static Content block. Since the query associated with the pop-up method will only return one row, we can use the export merge fields as-is without using Liquid Looping:

Portal Pop-Up View

If your pop-up allows information to be updated, your view must be created as follows:

  1. Create a new in the portal and give it a descriptive name.

  2. Add a New Row and choose the first option (single column).

  3. Add a Form element with the following settings:

    • Name: A descriptive name, often the same as your form’s name.

    • Status: Active

    • CSS Class Name: This setting allows you to apply CSS styles and isn’t required.

    • Form: Choose the form you built.

    • Submission Behavior: Since pop-up forms change information, you generally want to check this box so your table view reloads and displays the updated information.

    • Popup: Check this box.

    • Query String Parameters: Checking this box is required so that the form can display the existing information.

Add the Pop-up Method

A pop-up will have its own method associated with the view you created. If your popup is only displaying information, you’ll also associate the query.

  1. Create a new method with the following settings:

    • Status: Active

    • Name: A descriptive name. For example, “Pop-up: Person Detail”.

    • Type: GET

    • Action: A computer-friendly name for the method. It must only use letters and underscores and be a maximum of 32 characters. For example, “detail”.

    • View: Select the pop-up view you created.

    • Output Type: AJAX Popup/No Branding
      Portal Pop-Up Method

  2. If your pop-up is only displaying information, click Edit Linked Queries, select the pop-up query you created, and click Save. (A query is not required for form pop-ups.)

Update the Main View

The main portal view will need to be updated to link to this new popup. This is done in the source code, typically in a list or table of records. For the popup to work, the <a> element must have the following attributes:

  • data-href: Set to the method action and include relevant query string parameters. Use a relative path.

  • onclick: Set to return FW.Lazy.Popup(this);.

  • href: Set to #.

This can be easier to see in practice. Here is an example using configurations described throughout this article:

<table class="table"><tbody>
{% for student in students %}
<tr>
<td>
<a data-href="?cmd=detail&amp;person={{student.guid}}"
onclick="return FW.Lazy.Popup(this);" href="#">{{student.name}}</a>
<td>
</tr>
{% endfor %}
</tbody></table>

In this example, the main view of the portal has a “students” element, which may be a query node or a dictionary subquery export. The code creates a table and uses Liquid looping to create the rows of the table. Each row has a cell with an <a> element that has the described attributes:

  • The data-href attribute is a relative path - that is, it starts with a question mark since we’re already in the context of the portal URL. The cmd query string parameter should match the action from the method. The remaining parameters should match either the parameter(s) in the query (for pop-ups that only display information) or form fields (for form pop-ups). In this example, the person parameter provides the pop-up with the {{student.guid}} merge field. It could match a “person” parameter in the associated query, or it could be the special “person” query string parameter that prefills forms.

  • The onclick attribute contains JavaScript that is run when the <a> element is clicked. In this case, we use the Slate JavaScript function FW.Lazy.Popup(). This function looks for the value in the data-href attribute and generates a popup using the URL provided there.

  • Finally, the href attribute is set to #, since we don’t actually want this link to navigate to another page - the JavaScript defined in onclick takes over instead.

Requirements for Form Pop-Ups

Form pop-ups require the person query string parameter so that Slate can match to the existing record in the database. If your pop-up only updates record information, the person query string parameter fills in the record information, so no additional steps are required.

However, pop-ups for updating related information require the person query string parameter and also every form field. This is because these types of forms do not fill in related data from the database and must be filled in manually through query string parameters to ensure the data is not deleted when the form is submitted. There are some special considerations for these query string parameters:

  • Other than person, all other field mappings must have the form_ prefix added to the query string parameter.

  • Prompt-driven fields require the lower-case GUID of the prompt itself in the query string parameter. When updating the query for your main portal view, make sure to set the Export Value to “GUID” and the Format Type to “String (Lower Case)”.

Let’s look at a specific example to illustrate this. This portal has a scope of Person and displays a list of their Sports. There is a Person Information query associated with the main view that looks like this:

The “sports” subquery export is a Dictionary. It grabs all of the student’s sports by joining to “Sports”, then includes all the necessary exports: the “sport” and “rating” exports that will be displayed in the table, the required Sport GUID export (“guid”) for the form, and any other form fields we want the end-user to update on the form.

Using the example from the “Creating a Form” section earlier in the article, the only other form field mapping we have is to Rating. Since Rating is a prompt-driven field, we need a separate “rating_guid” export to get the lower-case GUID of the rating prompt:

The table in the main view has the following markup:

<table class="table"><tbody>
  <tr>
    <th>Sport</th>
    <th>Rating</th>
  </tr>
  {% for sport in sports %}
  <tr>
    <td><a data-href="?cmd=update_sport&amp;person={{guid}}&amp;form_sys:sport:id={{sport.guid}}&amp;form_sys:sport:rating={{sport.rating_guid}}"
onclick="return FW.Lazy.Popup(this);" href="#">{{sport.sport}}</a></td>
    <td>{{sport.rating}}</td>
  </tr>
  {% endfor %}
</tbody></table>

We create a table with “Sport” and “Rating” headers. We use Liquid Markup to loop through the “sports” dictionary subquery export. Each row has a cell with the sport’s rating, and a cell with the sport’s name linked to our pop-up including the necessary query string parameters.

Display Information on a Form Pop-up

There may be situations where you want the end-user to update certain information but only be able to view other information. If your form pop-up represents record information, this is straightfoward and aligns with best practices elsewhere in Slate: you can simply use form merge fields. (Remember that Person- and Dataset-scoped forms require one of the Security settings to be checked in order to use merge fields.)

If your form pop-up represents a row of related information, merge fields cannot be used. Even though the person query string parameter identifies the right record, it doesn’t identify the individual related object. In this situation, a form must be combined with a query as follows:

  1. Create a query with a base of the related object.

  2. Add a parameter with a computer-friendly id and a type of “uniqueidentifier”.

  3. Add the GUID direct filter and add your parameter to the filter.

  4. Add exports for the data points you’d like to show. Make sure to use computer-friendly names.

  5. Associate the query with your pop-up method by using Edit Linked Queries.

  6. In the main view, add the new query string parameter and pass it the GUID of the related object. It’s a good idea to put this new parameter next to the existing form_ parameter, so if any updates are required in the future, it’s clear that both parameters must be updated.

  7. In the pop-up view, edit the Form part and uncheck the Popup setting.

  8. Add a Static Content part before the Form part. Add the HTML for the pop-up header and choose the header text you’d like the pop-up to display:

    <div class="header">
    Header Text Goes Here
    </div>
  9. In the same Static Content part, add the merge fields for the data you’d like to display.

The portal pop-up now displays the information from the merge fields, while still allowing updates via the existing form fields.

Additional Design Elements

You may want to add some other design elements to your pop-up view that provide additional functionality. This section contains a few common designs used in portal pop-ups.

Close/Cancel Button

By default, the pop-up can be closed by clicking the "x" that appears in the header. However, code can be added in the pop-up view to also display a button at the bottom of the pop-up window:

Portal Pop-Up


<div class="action">
<button onclick="FW.Dialog.Unload();" type="button">Close</button>
</div>

By including this code, clicking the button will close the pop-up. The text between the tags can be changed from "Close" to "Cancel", "Return", or any other verbiage.

Header Text

You can add text to the grey bar that appears at the top of the pop-up. This grey bar also contains the "x" to close the pop-up, as well as "Prev" and "Next" links where applicable.

Header in Pop-Up

To do this, add a <div> element with a class of “header” at the very top of the pop-up view. You can hard-code this text or use any merge fields available in the pop-up.

<div class="header">
Header Text Goes Here
</div>

Source Code for Header

Setting a Fixed Height

If a pop-up contains a fair amount of content, a scroll bar may be necessary for the user to view all the information. Setting the height of the pop-up will create a scroll bar.

Scrollbar in Pop-Up

<div class="header">
Header Text Goes Here
</div>
<div class="content" style="height:500px;">
All of the pop-up content goes here.
</div>

The div with a class of "content" has been given a style, setting the height of 500px. If there is data in the pop-up that will not fit within 500px, a scrollbar will appear.

Source Code Setting Height


Was this article helpful?