Context¶
On many Skuid pages, the end user is presented with onscreen data—for example, a table of records or a chart reflecting a collection of records visually—where they can click on a specific record or a portion of the chart to get more information. The click may open a modal or sliding panel, or navigate to a detail page. Clicking on an item on a chart can drill down into another chart that provides more information about the item.
But how does Skuid know what content to display in the popup, sliding pane, or new chart?
Context. Skuid passes a parameter—a specific value for the data that was clicked—from the record the end user selected into the follow-on components or charts, to ensure that the contextual data drives the subsequent display.
How Context Works¶
Actions and updates can occur on all rows within a model or on specific rows of data. The distinction is important, because the group of data being used by an action, component, or other element is known as context, in that it provides specificity to data operations. When working in Skuid, context will most often be a record (or set of records); context can occasionally be a field within a record. When data is used like this, it is “in context.”
Context ensures that actions requested by the end user logically occur on the data the end user is interacting with at the moment.
Context is used anywhere a user can take an action that opens or accesses another element or component. For example:
- With components, such as the Table, context is used so that when the user clicks a record on the table, that record shows up in the associated drawers, modals, or sliding panels).
- With buttons in the Button Set, which allows you to set model- or row-specific actions that are triggered by the button.
- With Chart and Geochart, to ensure that drill down and on-click actions access the correct data.
- With actions in the Action Framework and in merge syntax.
Note
Some components and actions do not need—or use—context. In these cases, the Context tab does not display on the property pane.
Using context with Table actions¶
Context can be an important part of an action or action sequence, especially with Table action buttons.
Row actions¶
When dealing with a row action on a table, context refers to the specific row where the user clicked the row action. The parameters of the record represented by the row are passed as part of the row action.
Note
Row merge variables are only available if you have a specific row in context.
Global actions¶
Global actions are not dependent on context and do not receive context data.
Note
Because global merge variables declare an explicit path to their data, they do not rely on context.
Mass actions¶
Mass actions allow an end user to select one—or more—rows and perform an action on them. Each selected row becomes context for the action.
Using context with drawers, modals, and sliding panels¶
When working within component accessories—such as modals and sliding panels —as well as with drawers on a table, you must set a context condition for each data component in the drawer, modals, or panel.
Let’s look at an example using drawers: Context conditions correlate a field on the table’s model to a field in the drawer’s model—meaning these fields must match. Once this match is made, Skuid can keep track of which record (i.e., the record selected in the table) is querying related data. Without context—or a consistent field to reference—Skuid cannot keep track of each individual drawer.
On a table that displays a list of accounts, a drawer might be used to show related contacts for individual accounts. Within the drawer, the Skuid Table or Form that lists contacts needs to know which account to look up contacts for, and thus needs a consistent field to correlate between the two models.
In this case, the context condition states that the Id field from the Account model must correspond to the AccountId field for the Contact model. This tells Skuid that the contact details displayed in the drawer must be related to the same account record that the end user clicked on in the original Table. This way, if a user has multiple drawers open, Skuid knows which record’s data goes in each drawer because Skuid has a context to reference when opening one or more drawers.
This works the same way for modals and sliding panels. Whichever component is contained within the drawer, modal or sliding panel—Table, Form, Button Set, or others—Skuid needs to know which record was selected to provide added information about it.
Using context with merge syntax¶
Context is especially important for merge syntax. Without it, the merge will have no idea which data object to pull data from. A merge’s context could be model records, fields within records, or JavaScript objects (with or without properties). Some merges may use field names, such as {{Name}}
. Without a context—a record or a JavaScript object to reference—this merge will fail because it has no idea where to pull data from.
Note
Global merge variables, such as {{$Model.OpenTasks.data.0.Id}} establish their context within the merge syntax itself, as they declare an explicit path to data.
For example, when including a template on a specific component with model or row context (such as text in a Header component with an associated model), use a merge syntax template like {{Name}}
to access the account name of the first record in the Header/Page Title’s model. The context passed into the merge determines which variables are available to you. Learn more about context in Merge Syntax.
Best Practices¶
- Be aware that, when you have a row action that creates a new row on the Table, context switches from the one with the row action to the new row. If the row action includes an action sequence after the creation of the new row, any follow-on actions that require context will take their context from the new row.
- When using a button to trigger a named action sequence, consider using inputs rather than context because it’s easier to track the inputs through the sequence, giving you more precision.
Properties¶
When context is needed, a Context tab is displayed on the properties pane.
Context tab [[]]¶
Field: The field in the new location—drawer, modals, sliding panel, Button Set, etc.—that needs to correlate to the Merge field.
Merge field: The field on the current component. This is the context field, the one selected by the end user (or by an action).
Note
The correct parameter is often the record’s Id, so this is the default for both properties. If necessary, select a different value by clicking Select Field.
Operator:
- =
- !=
In Charts and Geocharts [[]]¶
Charts and Geocharts use context with on-click and drilldown actions set in the Series tab.
Field: The field in the new chart that needs to correlate to the Merge field.
Merge field: The field on the current chart. This is the context field, the one selected by the end user (or by an action).
Note
The correct parameter is often the record’s Id, so this is the default for both properties. If necessary, select a different value by clicking Select Field.
Operator:
- in (default): The drilldown chart displays records where the context is “records that are in the element” clicked by the end user in the first chart.
- not in: The drilldown chart displays records where the context is “records that are not in the element” clicked by the user in the first chart.
Note
$Chart merge variables are useful for when working with drilldown and on-click actions.
Id or not Id?¶
Because the correct parameter is often the record Id, the context properties default to this. Why might you need to use a different parameter?
Imagine a pie chart displaying current sales opportunities. An on-click action launches a popup with a Table component showing the accounts associated with those opportunity records. If the record ID for the opportunity is passed in, the Table won’t know which accounts to display, because the ID is for opportunity records, not account records.
But if the context condition is changed so that the ID passed is not the id for the opportunity (usually “Id “) but the ID for the account (for example, “AccountId “), then this can be matched to` the record ID on the account object attached to the table.