Global Merge Variables / Functions¶
Global Merge variables are available in ANY Merge context, and all start with $, e.g. {{$Param.accountId}}, {{$Api.Session_Id}}. The following is a complete list of global variables available for use in Skuid.
When configuring Skuid data sources and authentication providers, additional merge variables are added to the Merge API that allow you to access information about the data source’s authentication configuration and current state.
There are a number of places in data source and authentication provider configuration that process Skuid’s Merge API, which we’ll give examples of here as well.
Index of all global merge variables / functions¶
Global Variables
- $Api: for accessing the running user’s Session Id, User Id, and Partner/Enterprise Server Urls. Corresponds to Visualforce $Api.
- $Component: returns information about a specified component.
- $Label: retrieves the translation of a Custom Label requested by the running Skuid Page. Corresponds to Visualforce $Label or Apex System.Label
- $Model: access to JavaScript representation of a specific Skuid Model by Name.
- $Network: returns information about the state of the network connection.
- $Page: returns information for the current Skuid page.
- $Param: for accessing URL Parameter values for the current page. Corresponds to Visualforce $CurrentPage.parameters
- $Platform: access information about the platform of the current Skuid page.
- $Site: access to information about the Force.com site that the current Skuid Page is running on. Corresponds to a subset of Visualforce $Site.
- $User: data about the the running user. Corresponds to Visualforce $User and Apex UserInfo.
Global Functions
- urlEncode / encodeUrl: for URL-encoding merge data so that it can be safely added to a URL. Equivalent of JavaScript’s encodeURIComponent function. Example: /apex/skuid__UI?page=LeadsWithCompanyName&companyname={{#urlEncode}}{{companyName}}{{/urlEncode}}
- urlDecode / decodeUrl: for decoding URL-encoded merge data. Equivalent of JavaScript’s decodeURIComponent function. Example: {{#urlDecode}}{{$Param.companyname}}{{/urlDecode}}
$Api¶
Intended to correspond fairly one-to-one with the Visualforce $Api global variable. Exposes the following properties:
- $Api.Session_Id: The Visualforce Session Id of the running user.
Note
This is NOT the same as the Session Id returned by native Salesforce pages, on domains such as na*.salesforce.com. Generally this is irrelevant for Api integrations, but it can be a problem when trying to run / access Salesforce Reports from an external system. Available in JavaScript via sforce.connection.sessionId.
- $Api.User_Id: The 18-digit Id of the running user. Available in JavaScript via skuid.utils.userInfo.userId.
- $Api.Organization_Id: The 18-digit Id of the current Salesforce organization / instance. Available in JavaScript via skuid.utils.userInfo.organizationId.
- $Api.Partner_Server_Url: The Url that is needed for 3rd-party integrations to call-in to the current Salesforce instance via the Salesforce Partner API, for the latest API version of Salesforce supported by Skuid. Example:
https://c.na11.visual.force.com/services/Soap/u/29.0/00DG0000000XHQa
. Available in JavaScript via sforce.connection.partnerServerUrl. - $Api.Enterprise_Server_Url: The Url that is needed for 3rd-party integrations to call-in to the current Salesforce instance via the Salesforce Enterprise API, for the latest API version of Salesforce supported by Skuid. Example:
https://c.na11.visual.force.com/services/Soap/c/29.0/00DG0000000XHQa
. Available in JavaScript via sforce.connection.enterpriseServerUrl. - $Api.Partner_Server_Urls: A map containing all Partner Server Urls for past API versions of Salesforce starting with API v3, keyed by the integer version of the Api. Example: using $Api.Partner_Server_Urls.29 would return the same thing as $Api.Partner_Server_Url above, whereas $Api.Partner_Server_Urls.3 would return something like
https://skuid.na11.visual.force.com/services/Soap/u/3.0/00DG0000000XHQa%22
. Available in JavaScript via sforce.connection.partnerServerUrls. - $Api.Enterprise_Server_Urls: A map containing all Partner Server Urls for past API versions of Salesforce starting with API v3, keyed by the integer version of the Api. Example: using $Api.Partner_Server_Urls.29 would return the same thing as $Api.Partner_Server_Url above, whereas $Api.Partner_Server_Urls.3 would return something like
https://skuid.na11.visual.force.com/services/Soap/c/3.0/00DG0000000XHQa
. Available in JavaScript via sforce.connection.enterpriseServerUrls.
$Component¶
$Component merge variables return certain properties of a component. This allows for that particular component, other components, or action lists to display that information, configure display logic conditions, or branch into different logic based on that information.
These global merge variables are written in the following syntax:
{{$Component.<component ID>.<merge variable>}}
The component ID can either be the Skuid-generated unique ID or a custom unique ID—a property often set in a component’s Advanced tab.
For example, to access the search value of a Search component with the unique ID of globalSearch
, enter:
{{$Component.globalSearch.searchValue}}
Alternatively, a Skuid-generated ID will look similar to:
{{$Component.sk-222E-42382.searchValue}}
Note
Component merge variables do not dynamically update. That is, if a component’s values change, the merge variables will not be updated to match automatically.
These component values are only checked whenever the merge variable is called—and that is typically when a component first renders. Be wary of using these variables in static components that render on page load.
Button component¶
label
Returns the label of the specified Button.
For example, use the following merge variable to check the label of a Button with the unique ID “buttonId”:
{{$Component.buttonId.label}}
If the Button’s label were “Activate” this merge variable would return:
Activate
Search component¶
searchValue
Returns the current value the end user has entered within the specified Search component.
Often used in conjunction with Enter/Return Keystroke actions, as well as Go To URL actions, to pass a search value from one page to another.
For example, use the following merge variable to check the value entered within a Search component with the unique ID “searchId”:
{{$Component.searchId.searchValue}}
If the end user had entered “Skuid” within the Search component, this merge variable would return:
Skuid
Table component¶
model
Returns the model that the specified Table component is connected to.
For example, use the following merge variable to check the model of a Table component with the unique ID “tableId”:
{{$Component.tableId.model}}
If the Table were connected to a model with the ID “Accounts” this merge variable would return:
Accounts
Wizard component¶
currentStep
Returns a number that correlates to the current step.
For example, use the following merge variable to display the current step number of a Wizard component with the unique ID “wizardId”:
{{$Component.wizardId.currentStep}}
If the end user were on the third step in that Wizard, this merge variable would return:
3
currentStepLabel
Returns the value of the Step label property of the current step displaying within the specified Wizard component.
Often used with Navigation or Button Set components to render the name of a current step in a complex form.
For example, use the following merge variable to display the label of a Wizard component with the unique ID “wizardId”:
{{$Component.wizardId.currentStepLabel}}
If the end user were on a step in the Wizard with a step label of “Enter your billing info”, this merge variable would return:
Enter your billing info
currentStepId
Returns the value of the Step ID property of the current step displaying within the specified Wizard component.
Often used with the display logic and the Branch action for action lists that need to respond to a particular Wizard flow.
For example, use the following merge variable to display the step ID of a Wizard component with the unique ID “wizardId”:
{{$Component.wizardId.currentStepId}}
If the end user were on a step in the Wizard with the ID of “unique-step-id”, this merge variable would return:
unique-step-id
By using a branch formula, with if-true actions, you could configure a set of actions that only occur when the specified Wizard component has unique-step-id
active:
{{$Component.wizardId.currentStepId}} === "unique-step-id"
$Label¶
Used to retrieve the translated value of a custom label . Skuid internally requests various custom labels, e.g. “save”, “cancel”, “delete”, so that Skuid’s UI can be translated into any language by end users (Skuid ships with translations into Spanish and French of all end-user-facing components).
To use any custom label in a Skuid page, the label must be specified within the Label tab of that page. After doing so, request a label using the $Label merge variable.
For example, a custom label named “label_name” would be referenced with $Label.label_name.
Warning
In most cases, custom labels must not be marked as a protected component. Doing so will disallow the label from being referenced in a different namespace—including Skuid. If you are seeing issues with including your labels, try unmarking this property.
Note
Labels must be requested by their API Name, case-insensitive. However, whatever syntax you use to request a label will determine how it is accessible via JavaScript and via the $Label merge variable. For instance, suppose you have a Custom Label with API Name “Hello_World”.
When requesting a Label from a Skuid Page, you can enter “HeLLo_WoRld”, “hello_world”, “HELLO_WORLD” — all of these will retrieve the correct Custom Label. But you will only be able to request a Label by the Name you used, e.g. if you requested Label “hello_world”, then ONLY $Label.hello_world will work; $Label.HELLO_WORLD will not work.
This can be very useful for internationalizing parts of your Skuid Page, e.g. the labels of Tabs, Sections in a Field Editor, Buttons, or text in Templates, Page Titles, or even Filter Labels.
For more information, see the label localization topic.
$Model¶
A direct reference to the JavaScript representation of a Model, by Model Name. Use this to access data in particular Model rows, metadata for the Model, metadata for a Model’s fields, or particular settings for a Model, e.g. the number of records retrieved in the Model:
For instance, let’s say you have an “OpenTasks” Model, configured like this:
- Fields: Subject, Status, Priority, WhoId, Who.Name, WhatId, What.Name, Secondary_Owner__c
- Conditions: (1) Status = “New”, (2) OwnerId = (userinfo) User Id
- Limit: 100
You could then use $Model.OpenTasks to get a reference to the JavaScript API for this Model. For a full reference into what this returns, we recommend that you go into your browser’s JavaScript Console and do skuid.model.getModel(‘OpenTasks’) and check out what is returned — all of this data is available via $Model.OpenTasks! Just remember that in Skuid Merge Syntax / MustacheJS, object property navigation is via the . operator (period), not via brackets. We often find ourselves doing $Model.MyModel.data[0], which is valid JavaScript but NOT valid curly bracket (“mustache”) merge syntax — here you would need to use $Model.MyModel.data.0 instead.
Here are some examples of information that you could retrieve, in specific categories:
Accessing data in the Model
$Model.OpenTasks.data.length – e.g. 18, the number of records actually in the Model’s data array, which contains all records retrieved by the Model’s underlying SOQL query
This value is returned as an integer. So for a model with one row, the following formula will be true:
{{$Model.NewModel.data.length}} = 1
Warning
In previous versions of Skuid, this value was a string. If your formulas or snippets use this merge variable ensure it is interpreted as an integer.
For example:
{{$Model.NewModel.data.length}} = “1”
The above formula will return false.
$Model.OpenTasks.data.0.Status – e.g. New, the value of the Status field for the 1st record in the OpenTasks Model.
$Model.OpenTasks.data.0.Id – e.g. 00T000000000a7bAAA, the 18-digit Id of the 1st record in the OpenTasks Model
$Model.OpenTasks.data.0.Id15 – e.g. 00T000000000a7b, the 15-digit Id of the 1st record in the OpenTasks Model. Often necessary for passing data into standard Salesforce page layouts.
Accessing Model Conditions
- $Model.OpenTasks.conditions.0.value – e.g. ‘New’, the current value of the 1st Condition in the Model
- $Model.OpenTasks.conditions.0.inactive – will be false if the Condition is currently active, true if it is inactive
- $Model.OpenTasks.conditions.1.field – e.g. ‘OwnerId’, the field for the 2nd Condition in the Model
- $Model.OpenTasks.conditions.1.name – if the Condition is Filterable On/Off, then this will return the Condition’s unique name
Metadata for the Model’s SObject
- $Model.OpenTasks.accessible – e.g. true, whether or not the running user has Read permission on the Task object
- $Model.OpenTasks.createable – e.g. true, whether or not the running user has Create permission on the Task object
- $Model.OpenTasks.updateable – e.g. true, whether or not the running user has Edit permission on the Task object
- $Model.OpenTasks.deleteable – e.g. false, whether or not the running user has Delete permission on the Task object
- $Model.OpenTasks.label – e.g. Task, the translated Label of the Model’s SObject
- $Model.OpenTasks.labelPlural – e.g. Tasks, the translated plural Label of the Model’s SObject
Metadata for Fields requested in the Model
- $Model.OpenTasks.fieldsMap.WhoId.label – e.g. Contact/Lead Id, the Label of the WhoId field on the Task object
- $Model.OpenTasks.fieldsMap.Secondary_Owner__c.inlineHelpText – e.g. A backup owner to takeover if the primary Owner fails to complete this task, the Inline Help Text defined for the particular field
- $Model.OpenTasks.fieldsMap.Status.picklistEntries.2.label – e.g. Completed, the Label of the 2nd picklist entry defined for the Status field on the Task object
Model properties / settings
- $Model.OpenTasks.recordsLimit – e.g. 100, the number of records requested by the Model
- $Model.OpenTasks.soql – e.g. select Subject, Status, Priority, WhoId, Who.Name, WhatId, What.Name, Secondary_Owner__c from Task where Status = ‘New’ and OwnerId = ‘005000000000AChAAB’ limit 100, the actual SOQL run by the Model’s query
$Network¶
- $Network.Connected - e.g. true, whether or not the page is connected to the network.
- $Network.Disconnected - e.g. false, whether or not the page is disconnected from the network.
$Page¶
Returns information about the Skuid page the user is viewing.
- $Page.Id: The unique Id Skuid generates and assigns to the page when created.
- $Page.Name: The name assigned to the page by the user upon creation.
$Param¶
A keyed map of all URL query string parameters for the current page, as well as any query string parameters if the page is being displayed within a Page Include component. A window into the Skuid JavaScript object skuid.page.params.
Syntax:
$Param.<parameterName>
For instance, if your page URL looks like this:
https://skuid.na11.visual.force.com/apex/skuid__ui?page=AccountDetail&id=001G000000qI8REIA0
Then you would be able to do the following:
- $Param.page –> “AccountDetail”
- $Param.id –> “001G000000qI8REIA0”
Note
If a Page Include component has a parameter that is also within the URL, the Page Include’s query string parameter will always win out. Ensure that all page parameters are uniquely named.
$Platform¶
Provides information about which form of Skuid—Skuid NLX, Skuid SFX (Classic or Lightning)—the current Skuid Page is running on, if applicable. Can be used for platform-specific features, such as changing a URL-based template field to reflect the platform the user is currently running.
- $Platform.Name –> The name of the current Skuid page’s platform:
- skuid-platform: The Skuid page exists on Skuid NLX.
$Session¶
Used to access the value of a session variable for the current running user: {{$Session.variable.VariableName}}
For example, with a session variable named department:
{{$Session.variable.Department}}
For more information on session variables and how to configure them, see the session variables section in the single sign-on topic.
$Site¶
Provides information about the Force.com Site that the current Skuid Page is running on, if applicable. Provides a very limited subset of the variables exposed via Visualforce’s $Site global variable.
- $Site.CurrentSiteUrl –> e.g. “https://skuidmunity-developer-edition.na15.force.com/partners/”, the base URL for your Force.com site or Salesforce community.
- $Site.Prefix –> e.g. “/partners”, if “partners” is your Force.com site or Salesforce community’s prefix, or “” if there is no Prefix.
Note
Looking for the Skuid JavaScript API equivalent of these values?
$User¶
Provides information about the running user viewing the page. A direct window into the Skuid JavaScript object skuid.utils.userInfo, which contains most of the properties available in System.UserInfo in Apex, or the $User Global Variable in Visualforce. These properties are camel-cased, so they generally start with a lower-case, then, if they are multi-word, the successive words are upper-case, e.g. $User.userName, $User.email, $User.defaultCurrency
- $User.userId –> the 18-digit User Id of the running User. Same as $Api.User_Id.
- $User.sessionId –> the Session Id of the running User. Same as $Api.Session_Id.
- $User.organizationId –> the 18-digit Id of the current Salesforce Organization. Same as $Api.Organization_Id.
- $User.organizationName –> the Company Name of the current Salesforce Organization, e.g. “Acme Recruiting Inc.”
- $User.profileId –> the 18-digit Id of the running User’s Profile, e.g. “00eG0000000143nuLIAQ”.
- $User.userRoleId –> the 18-digit Id of the running User’s Role, or null if the User has no role, e.g. “00EG000000th3bMAA”.
- $User.firstName –> the First Name of the running User, e.g. “Tanya”
- $User.lastName –> the Last Name of the running User, e.g. “Johnson”
- $User.name –> the Full Name of the running User, e.g. “Tanya Johnson”
- $User.email –> the email address of the running User, e.g. “tanya.johnson.3743@gmail.com”
- $User.userName –> the User Name of the running User, e.g. “tjohnson@acme.com”
- $User.federationId –> the universal, cross-system identifier of the running User used for identity provider connection and connecting to external systems. Federation Id format varies, but it is most often represented as an alphanumeric key.
- $User.locale –> the User’s specified Locale’s key, e.g. “en_US”, “zh_CN”, “fr_FR”
- $User.language –> the User’s specified Language’s key, e.g. “en_US”
- $User.defaultCurrency –> the Default Currency for the running User, e.g. “USD”, “GBP”.
- $User.callCenterId –> the running User’s associated Call Center record, if configured.
- $User.userType –> e.g. “Standard”
- $User.isAuthenticated –> boolean. True if the running User is an authenticated, named user, false if in an unauthenticated context, e.g. if the running user is a Site Guest User.
Location¶
Location merge variables that point to the user’s current location. Used with the Refresh user location action.
Note
If these merge variables are used within a component, the component must be re-rendered after the Refresh user location action has occurred before the text will display. Consider using the Toggle Component action.
- $User.location.countryCode: The two-letter country code.
- $User.location.countryName: The full name of the country.
- $User.location.postalCode: The postal code.
- $User.location.administrativeArea: General region information, such as a state within the United States.
- $User.location.subAdministrativeArea: More specific region information, such as the county within a state in the United States.
- $User.location.locality: The city name.
- $User.location.thoroughfare: The name of the street.
- $User.location.subThoroughfare: Street-level information, typically an address number.