Creating a Custom Portal

Create the Portal
  1. Click Database in the top navigation bar and select Portals.
  2. Click New Portal when creating a portal (or clicking the "edit" button for an existing portal), the following settings can be configured:
    • Status - If the portal is Active, it can be visited at a URL formed from "/portal/" followed by the portal key.
    • Folder - If you have a number of portals, you may want to organize them into folders for your own reference.
    • Key - A simple name used in the public URL for the portal. For example, you might have a portal with a name of "My Awesome Portal" with a key of "awesome." The URL would then be: https://apply.slateuniversity.edu/portal/awesome
    • Name - A descriptive name you can give your portal for your own reference (it won't be seen by the public).
    • Default View – The view that defines the portal layout when the portal is initially loaded. When creating a new portal, there will be no available views to select, as these have not yet been created. The default view can be set later as soon as at least one view is created.
    • Security - The method you want to use to authenticate who can enter your portal. This will allow you to control access to the portal, and also allow you to identify a portal user so that you can show them content that is specific to them (e.g., an alumni interviewer would see their own interview assignments).
    • Secure Link – Portal access can be provided via login or a secure link. The secure link will look something like: https://apply.slateuniversity.edu/portal/alumni?key= be930235-707b-4405-b0ca-04cf64aceec7

      A local export can be added via the Query Exports/Filters tool to generate the individualized link for each record, like so:
      (select [value] from [config] where ([key] = 'https' )) + '/portal/alumni?key=' + dbo.toGuidString(d.[id])

      This can be used, for example, as a merge field in email communications.

      Secure links are only available for portals with person or dataset security. If any personally-identifiable information will be displayed on the portal, we recommend requiring a login and discourage from using the "Secure Link" setting.
    • Use SSO – This setting is used for dataset portals, which can leverage an institutional SSO for authentication.
      • Restrict Access - Add filters to indicate who should have access to your portal. For example, in a User portal, you can restrict to certain roles or permissions. In an Application portal, you might restrict based on round or decision.
      • Authorization Fail Custom Message - This message will appear if the filters prevent access.
      • Inactive Message - This message will appear if the portal is set to an inactive state.
      • Description  - A longer description of the portal for your own reference.
      • XML Configuration - Allows you to define custom variables that will be available in portal methods as well as in views to store information that is needed throughout the portal. For example, if the queries should reference certain rounds, or the portal should link to a certain form, you might want to define that in a variable here so that you can update it in one central location. You can add a variable in XML by adding something like
        var id="review_form">84bf4da7-ce29-4151-ac47-2edad7b84691</var>
        where the enclosed value is the GUID of a form. In the portal editor, you can then reference that variable in SQL as @review_form.

Most datasets will use the key of d.[id]. However, if your dataset uses a different key, you would use the key specific to your dataset.

Portal Methods

Each portal method can run one or more Slate queries to look up or update Slate data. Each portal method should correspond to a given "page" of the portal.

Each method can have an action attribute that determines when it will run (no action means it will run for the default portal page; otherwise it will run for URLs of the form "?cmd=action" ).

A portal method is also meant to represent a page or endpoint for the portal -- for example, in the portal method you indicate whether the page should include your branding.

  • Status - Portal methods that are set to "inactive" will not run even if they would otherwise be called.
  • Name - A descriptive name of the method for your own reference.
  • Type - A GET method is designed to be given request parameters and look up and return information. Most portal methods will be GET requests; for example, to get information about the current user, to get a list of applicants to display, etc.

    A POST method is designed to receive passed-in data and perform an update. For example, an interviewer is assigned a particular applicant and that connection is saved to the database.
  • Output Type - For GET portal methods, the data that has been returned from the query can be treated in several ways.
    • Default Branding - The associated view creates an HTML web page, which would be displayed using your institution's default Slate branding.
    • Framework + No Branding - Use the associated view to create an HTML web page, which should be displayed as is (no added branding) but with the built-in Slate framework code included. This should be used if you want your portal to have a different branding than your default Slate branding (and the portal branding should then be included in the view).
    • AJAX Popup/No Branding - Use the associated view to create an HTML web page which should be displayed as is. This is typically used when the portal method is creating the contents of a pop-up or is just meant to render a section of a page which will be inserted by an AJAX call (i.e., where the page doesn't get reloaded but JavaScript replaces part of the page contents dynamically).
    • JSON - Output the results in JSON (JavaScript Object Notation) format, useful for AJAX calls that are then using the data to do an update themselves.
    • JSONP - Output the results in JSONP format, a version of JSON in which the results are formatted in a way that allows the calling code to avoid cross-domain security restrictions. This would be used if you were creating a portal in order to support some sort of integration with an outside system.
    • XML - Output the results in XML format. The results from the portal method will be returned as an XML element with the name specified under Node below, with each column as an XML attribute.
    • Raw - Output the results with no formatting or markup. This could be useful for troubleshooting or for a situation where you're doing your formatting within the SQL.
    • Excel Spreadsheet - Output the result as an Excel spreadsheet which will be queued for download in the web browser. The Excel spreadsheet will automatically inherit the portal key as its filename. However, you can specify the filename by appending a query string parameter to the download link. This filename can use merge fields so the name may be dynamic as needed.

      /portal/key?cmd=method-action&filename={{merge-field}}_spreadsheet.xlsx
    • Redirect - Typically used in situations in which a logged-in person will need to be redirected to a particular page.

      Redirect example: You have a custom portal intended for applicants in which a specific view has been set up for admitted students only. Once an applicant has been admitted, they have to be redirected to the admitted students page, bypassing the page for all applicants. A redirect method could be set up which is linked to a portal query that can identify the applicants that have the correct decision code. The query would use filters to conditionally return a URL; if a URL is returned, the applicant would be redirected.
  • Page Title - Display a custom page title for the method.
  • Action - For the initial "home" page of the portal no action should be entered. For other pages, popups, or updates, the value entered under "action" will determine when the method should be called.
    • If the URL that loaded the current page or pop-up includes "cmd=doThis" , and the action value for this portal method is "doThis" , then this portal method will be called.
    • For a POST method, the portal will look for a cmd parameter that is part of the submitted form.
  • Post Action - For POST portal methods, the post action is a snippet of Javascript that will be run after the action completes. For example, you could run a Javascript function to refresh part of the page, or you could show an alert message. If you don't include a post action, the default action is:
top.location.reload(true);

which will refresh the page.

  • View – Select the view associated with this method.
Portal Queries

The core of the functionality for a portal method is a query (or queries) that will run when the method is called. Queries will either get the data from your database and display it according to how the portal view is set up, or update data back in the database.

Queries can be reused across methods within a portal, and each portal method can also be linked with multiple queries.

Add a New Query

Configure queries using various bases to dynamically display data on the dashboard.

  1. Give the query a Name, for your own reference. Give your portal queries names that are easily understandable and distinguishable from one another.
  2. Select a Base. If the query is only querying for data of a given type (e.g., applicants), selecting the corresponding population allows you to set up your query using the standard Slate query interface.

POST methods currently require a Custom SQL query base.

The data returned by the query will be available as merge fields that can be used in Liquid markup with your views.

The export parts should be edited to use lowercase names that do not include spaces or punctuation other than underscores or dashes. (For example, change "First Name" to 'first' or 'first_name').

Parameters

If you need to pass data into a portal method query, you will create parameters. This might be data that you are using to refine the data you are retrieving (for example, retrieve applicant data for a particular applicant by passing in the applicant ID) or might be data sent in through a POST to be saved.

  1. Click Edit Parameters.
  2. Add XML tags, once for each parameter, following the format below:
    <param id="person" type="uniqueidentifier" />
    <param id="term" type="string" />
  3. In the query, you would typically need to add a custom SQL filter so that the parameter value can be included in the query, which will then be used to refine the data being pulled in. The custom SQL filter might contain a snippet of SQL such as
    p.[id] = @person

Queries that perform updates (i.e., with POST methods) must currently be set up with the Custom SQL query base. Note that this is a SQL script and does not need to be a single query, so you are able to define SQL variables, populate them, run a query, and/or perform an update within a single portal method query.

Output Nodes

The node controls how the data in the query is delivered to a view. Typically, when a query delivers data for a list of objects each with their own attributes, the output node is used to designate the name given to this "container" of objects.

In the view editor, the node can then be referenced in Liquid markup for data inside an object - that is, with Liquid looping where each object needs to be iterated over.

The node will only be needed when looping through a list of results. If the query is returning a single set of data (e.g., information about the currently logged-in person), then the node should be blank.

Common uses for the output node include: displaying checklist data (node name: checklist), displaying a list of alumni interviewers within a table that generates one row per interviewer (node name: interviewers).

Linking Queries to Methods

In each portal method, a list of queries linked to that method is displayed. Click "Edit Linked Queries" to specify which portal queries should be associated with the method.

Portal Views

A view controls how the content of the portal is displayed. A view may consist of static HTML content (which could contain merge fields that display data from a portal query), a form, a report, or (for applicant status pages) content widgets such as checklist sections, decision sections, etc.

Each view represents a single "page" of the portal. There is typically one "Default" view with additional views linked to portal methods that render other pages, popups, or sections of pages that will be loaded on the fly.

Create a New View
  • Status – The portal can use a view when it is set to Active.
  • Name – The name will be visible when editing the portal, so it is recommended that the name makes it clear which section the view represents.
  • Layout – The page can be set up with the Layout Editor (selected by default) to build a customized view using a drag-and-drop methodology, or it can be set up by using one of a collection of pre-defined layouts.

Using the Layout Editor

  1. In the Views section, select the New View link. The Edit View popup appears.

  2. Confirm that the Status is automatically be set to Active. There is no need to change the value.
  3. Enter an appropriate name for the view in the Name field.
  4. Select Use Layout Editor.
  5. Click Save. The layout editor appears.

  6. Click New Row on the right side of the page. The Select Row Layout popup appears.

  7. Select the desired layout for the row. The new row appears on the layout.
  8. From the parts shown on the right side of the page, drag the desired view parts into the row. The Edit Part popup appears.

  9. Add additional rows and parts as needed.
  10. When finished adding all rows and parts click the portal name link in the breadcrumb on the top of the page to return to the portal summary page.

Using a Standard Layout

  1. In the Views section, select the New View link. The Edit View popup appears.
  2. Clear the Use Layout Editor option. A drop-down list appears.
  3. Select the desired page layout.
  4. Click Save. The view layout appears.
  5. Add content to the view by dragging the desired view parts from the palette on the right.

Removing View Parts

  1. From the layout page, select View As List.
  2. Select the intended part from the View Parts list. The Edit Part popup appears.
  3. Click Delete. A confirmation popup appears.

  4. Click OK.
  5. Click Edit View to return to the layout editor.
Modify an Existing View
  1. Select the desired view to modify.

    If the view was created with the fixed (legacy) portal process, it can be converted to use the dynamic layout editor.

  2. Click Edit. The Edit View popup appears.

  3. Select Convert To Use Layout Editor. A confirmation opens to inform you that Slate will attempt to reconstruct the view as closely as possible, and also to suggest testing this conversion prior to using it in your production environment.
  4. Click OK.
  5. Click Save.
  6. Refer to the procedures described in the Creating a New View section above for information on editing the view with the layout editor. 
Converting All Views to Use the Layout Editor

If a portal was created using the legacy portal process, all views within the portal can be converted to use the dynamic layout editor.

Note: This option is only available when copying a portal. This prevents auto-conversion of items that might result in a change in the portal appearance.

  1. On the Portal page, select the desired portal.
  2. Under View Layout, click the Copy this portal to switch to the dynamic Layout Editor link. The Copy Portal popup appears.
  3. Enter the desired values in the popup fields, and make sure that Convert Views to Dynamic Layout Editor is selected.
  4. Click Copy. The portal summary page for the new (copied) portal appears.

All views in the portal now use the dynamic layout editor.

Important

Keep in mind that Slate attempts to convert the views as accurately as possible, but the conversion process may result in changes to the portal display (portals with  fixed-layout views are rendered using HTML tables, but dynamic-layout views are rendered using a CSS grid). Confirm the appearance of the portal in the test environment prior to converting in the production environment.

View Parts

Events

Inserts event landing pages into the portal, in list, map, or calendar format.

Form

It is possible to embed a Slate form in a portal page. Click “Form” from the palette on the right hand side, and drag and drop to the area in which you would like the form to be displayed for users.

  • By default, submitting an embedded form will not reload the entire portal page. To reload the portal upon submission, check the "Reload portal" box when embedding a form. If you are using filters to control what is visible on the portal and the form submission will change that data, reloading will show the updated view.
  • If the form is not the same scope as the security method for the portal, the form should not be embedded using the widget palette (for example, an application-scoped interview report form should not be embedded in an alumni volunteers dataset portal page). Depending on the use case, the form could be hyperlinked to, or the form embed code could be used instead. Don't hesitate to contact the Service Desk to help evaluate your use case.

Report

Slate reports can be embedded in a portal page. More information can be found in this article.

Social Media

Allows embedding a Facebook page or Twitter feed.

Static Content

Static content blocks can be used to display content, including data derived from a portal query.

Static content can be edited using the HTML WYSIWYG editor. On the editor, the Source button also gives access to the source code for viewing and editing. Liquid looping, JavaScript, or custom CSS can be edited in the Source view.

Merge fields can be added in static content to display, for example, information about the person logged in to the portal, or the constituents or records that “belong” to the logged-in user, e.g., athletic recruits in a particular coach’s sport or events happening within a volunteer’s area.

Table

Presents the results of a query as a dynamic table within the portal, automatically adding paging. Refer to the Display Data Tables in a Portal article for more information.

Weather

Allows embeding a weather forecast into the portal.

Was this article helpful?
1 out of 5 found this helpful