Create and Configure Models¶
Models are powerful tools that provide connections to external systems, allowing the builder to pull data into the page. However, models follow rules that govern how they can be connected to data objects or entities. It’s important to follow these rules when creating models:
- You can connect any individual model to only one object within any external system. (For example, a model can be connected to the Account object in Salesforce.)
- You can create one—or more—models for each page, and each model can connect to entirely different objects.
- A model can also connect to the same object as another model. That’s right: you can have multiple models on the same external system object—provided the models each have unique names.
Note
Why would you want to connect multiple models to the same object? Using model conditions, you can pre-filter what comes into each model.
- You may have one model on the Salesforce Account object that pulls in only certain information about the accounts, and displays the data in a table that is always on screen. This data will load immediately when the page displays, because the user always needs to see it.
- Another model may pull in specific internal account information (such as the account owner ID, last time modified, modified by whom, etc.). This model displays information in a “More about the Account” popup or modal. The records in this model don’t load with the page; instead, they only load when the user opens the popup to drill down into specific content. This streamlines the initial page load.
To prevent loading a single model with all the content that will ultimately be needed from that object—even though much of it is not needed immediately—it can be a best practice to create different copies of the model for each specific component or usage on the page.
Create a Model¶
Adding a model to a page involves twp steps:
- Create a model and name it.
- Connect the model to an external system. This makes it possible for the model to pull in content and display it in any associated components.
Create [[]]¶
You can create as many models as the application needs—even multiple models that point to the same external system.
Click
Models in the Elements pane.Click the
Add Model.Under Model ID, give the model a practical name, one that is distinctive enough to distinguish it from others on the page.
Note
This Model ID is not visible to end users.
Model name best practices¶
- Use alphanumeric characters:
SalesEntity4
- Do not include spaces between words; use an underscore to represent a space:
Opportunity_List_Data
- When possible, use a name that indicate the model’s function:
ContactDetail_Record
orAccountNameSource_forCustomfilter
- Creating more than one model from the same external connection? Be sure to label them accordingly:
Account1
,Account2
,Account3
Connect [[]]¶
A newly-created model is just an empty “container,” waiting to be filled. Turning that container into a powerful and effective model is a matter of pinpointing exactly what content the model can access by connecting it to an external system.
Note
UI-Only models do not require a connection to an external system.
Warning
To connect Skuid models to a specific instance of an external system, you must first set up a connection to that system. This is done from the Configure tab in the Skuid navigation bar, under Configure Data Sources. Do not attempt to connect a model until you have created a system connector to the desired data source or service.
There are a series of necessary choices to hone in on the exact content you want to pull into the model:
- Select the associated Skuid system connector that will connect the model to the system. (Skuid provides a variety of out-of-the box connectors for various data sources and other systems and services.)
- Once you select the connector, Skuid winnows the list external system connections associated with that connector. If you only have access to one connection, its name will pre-populate; if there is more than one instance of the system connector to choose from, Skuid will present all options in a dropdown list.
- Finally, use the dropdown next to Object or Entity to select the specific object within the system to pull the content from.
Note
UI-only models and fields work slightly differently than models built to connect to external systems such as data sources or services. See UI-Only Models and Fields to learn more.
Customize a Model¶
Customize the model to determine what part of the connected content to display and how the model behaves by using model properties, fields, conditions and actions. There are several ways to customize a model to gain even more control over the content pulled into a Skuid page.
- Model properties control essential model behaviors.
- Fields specify which content attributes are available in the model from the external system’s object.
- Model conditions limit or filter the specific records that are pulled into the model.
- Model actions trigger actions that run automatically when model-level events occurs.
Note
Depending upon the choices made, these options may impact page load times and performance.
Adjust the properties¶
Model properties—found in the properties pane—allow the builder more nuanced control over the model’s behaviors. The properties that are available vary, depending upon the external system connector being used. To learn about the specific properties available for a specific external connector, locate that topic in the Data section of Skuid’s documentation.
UI-Only models [[]]¶
UI-Only models are unique: they do not connect to any external system. A model using this type of system connector can store temporary values at runtime, but it does not save that data to any external system. UI-Only models are commonly used for variables that power interactive elements in the user interface or for other bits of logic within a page. See UI-Only Models and Fields to learn more.
Add model fields¶
Each model connected to an external system—and specifically, to a particular object in that external system. Most external connections include fields that are accessible to the model. By selecting which of those available fields to add to the model, you specify the data or content to be included and avoid including extraneous data or content that you don’t need.
There are several ways to add fields to a model.
Add fields using the model list [[]]¶
- In the Elements pane, click on the desired model.
- Below the model name, click Fields. Skuid opens a list of fields available for that model in the property pane.
- In the All Fields tab, check a field to add it to the model.
- Made a mistake? Uncheck any fields to remove them from the model.
- The fields selected are added to the model’s fields list in the order in which they are selected. They are also listed under the Selected Fields tab.
- In the All Fields tab, check a field to add it to the model.
Adding child relationship fields [[]]¶
Similar to related fields, you can add fields from child relationship objects by clicking the Child Relationships tab in the Properties pane. Child relationships refer to objects that are linked in a way that is often described as a parent-child relationship. Some values in the parent object draw their data from values in the child object.
To build a sample page using fields from a child object with a parent object, see Include Child Relationship Fields in a Parent Object.
Add components—then add fields to them [[]]¶
Certain data components, such as the Table, Form, or List components, are designed to contain and display model fields, making that content accessible to the end user. Because these components rely on model fields for their content, the component itself includes an Add fields button. Adding fields directly to a component also adds them to the model’s field list.
- Drag and drop a Table, Form, or List component into the page.
- In the Properties pane:
- Model: Select the desired model to link to the component from the drop-down list. (By default, the last model modified will be pre-selected.)
To add fields to component, either:
Click the Add fields button to open the Add fields dialog box, then:
To select a field already added to the model: Check a field from the Selected fields tab to add it to the component.
Note
Use the Search bar to find fields quickly.
To select a field that has not yet been added to a model: Check a field from the All fields tab to add it to the component. (The field will also be added to the model’s field list/)
- No check box next to a field? Click next to the field to add it to the model and make it selectable, then check the field to add it to the component.
Click Apply.
Or you can drag and drop fields into the component from the model’s fields listing by grabbing either:
- a field from the model’s field list (below the model’s name in the Elements pane, under Fields)
- a field from the model’s field’s list in the Properties pane.
Having trouble adding fields to a component?¶
A component can only accept fields from the model associated with it. When dragging a field into a component, if the component does not display an orange visual indicator for the area where you can drop the field, you may be trying to add a field to a component that is connected to a different model. Ensure that the component’s model matches the model you are pulling your fields from.
Reorder fields in a component¶
Just drag and drop to change the position of fields in a component.
View selected fields [[]]¶
To see a list of the fields currently included in the model, click the model from the Elements pane, then either:
- Below the model name, click Fields.
- In the Properties pane, click the Selected Fields tab.
You will see check boxes next to any Fields you added to your Model from the Fields list under the Models tab in the Page Composer. If you did not add any fields previous to clicking the model’s Field, then no check boxes will appear.
Check the boxes next to any Fields you want to add to your Component.
Add model conditions¶
A model condition is filters the content before it is loaded into the model. Without any conditions, a component attached to a model displays data for all the records in the object. Adding conditions lets you limit the data pulled into the page.
To add a model condition:
- In the Elements pane, click on the desired model.
- Below the model name, click Conditions.
- Click Add.
To learn more, see Model Conditions.
Add model actions¶
Skuid model actions let you to specify actions that will initiate when certain model-leve events occur on a given model.
To add a model action:
- In the Elements pane, click on the desired model.
- Below the model name, click Actions.
- Click Add.
To learn more, see Model Actions.
Working with Models¶
Change the order of models on the model list [[]]¶
Click, drag, and drop models to reposition them within the Elements pane.
Note
Model order matters: In a Skuid page, models load in the order they are listed in the models list with models at the top loading first. If you have models that are dependent on another model for data, the dependent models must load after their primary models.
Clone a model [[]]¶
Cloning makes an exact copy of the model (including properties, fields, conditions, and actions). This is useful when you have a model that you want to duplicate and revise, without affecting the original model.
- In the Elements pane, click Models to open the models list.
- Select the model you want to clone from the list and click Duplicate.
The clone appears at the bottom of the model list. Cloned models default to the name of the original model with a “1” appended. For clarity, remember to assign cloned models a unique name to help distinguish between it and the original model.
Delete a model [[]]¶
Warning
Deleting a model also deletes the components that are attached to that model.
To delete a model:
- Click Models in the Elements pane.
- In the list of models, click the model to delete.
- Click Remove. Because deleting a model removes any associated components attached to the model, Skuid confirms the deletion.
- Click OK. The model and associated components are removed from the page .
Best Practices¶
When creating models, consider both the data users need to access and the experience you want to offer those users.
Model order matters: Models load in the order they’re arranged in the models list: models at the top of the list load first. When a model is dependent on another for data, ensure that dependent model loads after the primary model. If necessary, re-order the models..
Set a Max # of records to a smaller number: Generally, users only really need to see around 10 records at a time; more records may present too much information to process, and in many cases they can load more records using pagination options.
Uncheck “Query on page load” to load models only when needed. Unchecking this property allows components and user action to determine when model data is loaded.This prevents all of the page’s models from loading at the same time during the initial page load, especially valuable for pages with numerous models.
Don’t specify Fields to order records by. If you need to use this feature, only specify indexed fields. (Ordering by a non-indexed field will make the page run slower.)
Note
Some databases support the creation of indexes for fields. To determine if the database you are using supports field indexing, see the database’s documentation.
Properties¶
Model properties¶
Warning
- Not all model properties listed below will be available for all data source types. If you do not see a property listed here in the Composer, it may not be available for your data source type.
Models for some data source types may have unique properties not documented here. These properties are detailed in the topics for those respective data source types.
General tab [[]]¶
Model ID: The unique name by which components refer to this model. Each model must have a unique name within one Skuid page. If other pages are included within that page—such as through the Page Include component or dependent pages—then the models in those pages must also have unique names.
Data source type: The data source type <data/> to use for this model, which narrows the selectable options in the Data Source property.
Data source: The data source <data/>—a connection to a system that has been configured by the Skuid builder—that the model uses to access records.
Model Object / Entity: The data object to pull data from. The label for this property can vary based on data source type, but they all mean the same thing:
- External Object Name
- Model Entity
- Salesforce Object Name
Model behavior: Some data sources allow the builder to select a specific type of model behavior:
- General: The default Skuid model.
- Aggregate: A model that collects, groups, and summarizes multiple data records into a single end result, such as a sum or a count.
- Read-only: (REST data sources) A model that can only query (and not update) data.
- Read/Write: (REST data sources) A model that can use multiple data source URLs for different data operations.
Query on page load: If unchecked, no data rows are loaded into the model when the page initially loads. Uncheck this box to use this model to create new records, or to load this model later via the Action Framework (for example, opening it in a drawer, popup, or tab).
Allow Page Render Before Query Completes: Controls whether Skuid must finish loading the metadata for the model before rendering the Skuid page. (Only available if Query on page load is checked.) By default, Skuid loads metadata for every model prior to rendering a page, even those without visible UI components. A model containing a picklist with hundreds or thousands of values could extend page load times, especially if there are many models on a page. Use this property to tailor which models have a higher priority, giving users access to the most meaningful data and UI elements first.
When unchecked, the model is considered synchronous—meaning it is given priority and its query must complete before the page renders.
When checked, the model is considered asynchronous, and the page will render even if its query is not yet finished.
Note
This model property is unavailable for server-side models.
Max # of records (limit): The maximum number of records that will be pulled in to this model when it is queried. The smaller this number is, the faster your page will load, but the less data available within the page.
Fields to order records by: Determines how the rows of records are sorted within the model. For basic models this sort statement is written as
FieldName SORT
, while for aggregate models it’s written asFUNCTION(FieldName) SORT
.Two sort commands are available:
- ASC: Ascending, meaning records of higher “value”—alphabetically or numerically—appear at the bottom of the record list. (If no sort command is specified, ASC is assumed.)
- DESC: Descending, meaning records of higher “value”—alphabetically or numerically—appear at the top of the record list.
So to sort a basic model’s rows by its amount field in descending value, use
Amount DESC
. Or to sort an aggregate model’s rows by an aggregation that sums the amount field in descending value, useSUM(Amount) DESC
.Multiple sort statements can be used in this property when separated by a comma. Sort statements are applied in the order they appear.
For example, to order a model’s rows alphabetically—ascending—by the Name field and then by their Number field descending, enter the following:
Name, Number__c DESC
(Note that the first sort statement works because ASC is assumed.)
Note
If used on a Salesforce data source model, this property is also compatible with the NULLS FIRST and NULLS LAST syntax.
Create default row if model has none: When checked, a new record will automatically be created if there are no records within the model on page load. Useful for “Create New Record” pages.
Advanced tab [[]]¶
Prevent users from leaving page if this Model has unsaved changes: When checked, a dialog box will appear to prevent users from leaving the page if there are unsaved changes in this model. If unchecked, users can leave freely but may potentially lose data changes within this model, so determine the best behavior for your use case.
Model label: If the model’s selected object does not have a singular label—such as Account—this property can be used to specify one. However, if a label is specified for the object within the data source this property has no effect. (Correlates with the {{Model.label}} merge variable for a model.)
Model plural label: If the model’s selected object does not have a plural label—such as Accounts—this property can be used to specify one. However, if a label is specified for the object within the data source this property has no effect. (Correlates with the {{Model.labelPlural}} merge variable for a model. Commonly appears at the bottom of paginated components—like Tables or Decks—and in Page Title components.)
Defer rendering: When checked, fields specified by the data source type or marked in the Fields to Defer property will load asynchronously—meaning all other fields in the model may load and display in any components as soon as they are loaded. Deferred fields display placeholder text while they load and do not prevent other fields from rendering. Useful for fields that may incur longer load times, such as image fields or other binary files.
Note
While some data source types allow for deferred fields to be specified, some will not. For data source types that do not, the Fields to Defer property will not appear.
Fields to defer: Available for some data source types, this property sets which fields should load asynchronously. Requires Defer Rendering to be checked.