UI-Only Models and Fields

UI-Only—or “user interface-only”—fields are used for data values that react to user input or work with queried data. They work with data in run-time, but do not require the data to be saved. UI-Only fields work well as temporary variables that you can use to enhance your user experience:

  • Create custom formula fields that interact with your data in real-time on a screen-by-screen basis:
    • Display a field that shows the sum of all opportunity amounts within a table. If fields used to create this sum are affected by filters or conditions, the UI-only summary field will update to reflect these changes in real-time.
  • Create screen-level checkboxes that trigger the Action Framework and Conditional Rendering:
    • Show or hide components or component elements by setting a UI-only toggle.
  • Provide user-friendly fields that can automatically transform data for your use case:
    • Have a component that needs to react to or alter values input by the user? Use a UI-Only field to do just that.

As their name implies, UI-Only fields are not stored in any data source and will not persist across page loads.

Using UI-Only models and fields

The most intuitive way to use UI-Only fields is to create a UI-Only model. By doing this, you can sensibly organize any and all UI-Only fields, whether you use one model for all of your UI-Only fields or create separate models for different uses. You also avoid creating dummy models attached to your existing data sources.

To create a UI-Only model:

  1. Navigate to the Models tab of the App Elements Pane.
  2. Click the Add Model button.
  3. Set the Data Source Type to UI-only.
  4. Click Fields within your UI-Only model.
  5. Click Add Field.

You may take advantage of model actions when using UI-Only models; it’s also possible to add model conditions.

Warning

Model conditions on Ui-only fields require that the UI-only field has a value by default. If the UI-only field doesn’t have a value by default—for example, a UI-only field that is filled in by the user at runtime—the model condition will not work correctly.

Keep all of your UI-only fields in this UI-only in sensibly organized models; this gives you the convenience of UI-only fields without the hassle of creating dummy models.

You may also add UI-Only fields to any other model, regardless of data source type. To do so:

  1. Create a model or navigate to an existing one.
  2. Click Fields within the model.
  3. Click Add UI-Only Field.

Note

Models load in the order they are listed in the Models tab. This is very important for UI-only fields: having a field that references a model that hasn’t loaded yet will cause errors.

For example, if you place an Accounts model before your Contacts model, and then create a reference to the Contacts model inside of that Accounts model, Skuid will try to access data that hasn’t loaded yet. And that means errors on your page.

If you’re having issues with your UI-Only fields, make sure your models load in an appropriate order!

There are many different types to choose from

The field’s Display Type can be any of the following: Checkbox, Currency, Date, Datetime, Formula (see below), Percent, Picklist, Multi-select Picklist, Number, Reference, Text, Textarea, Url.

Remember, when you leave a page, the data captured in UI-Only fields is not attached to the record(s) on the page. If you want to create a field to store and track data, you should create a new custom field in Salesforce. UI-Only fields are for giving you more flexibility and pizazz on the UI side.

UI-only Formulas and Functions

If a UI-only field’s display type is set to Formula, then the field’s value will be determined by the statement listed within the Formula tab of the Properties pane. Within that tab you may use merge syntax, strings, numbers, and a variety of UI-only functions to create formulas.

Formula Return Type

A UI-only field’s formula return type determines how Skuid will store the result of the formula.

Available options include:

  • Checkbox

  • Currency

  • Date

  • Datetime

    Note

    Skuid stores all date and datetime fields in ISO 8601 format.

    When directly manipulating the value of a date or date time field in a Skuid model, the value must be formatted as follows:

    • Dates: yyyy-MM-dd
    • DateTimes: yyyy-MM-dd'T'HH:mm:ss[.SSS]'Z'
  • Percent

  • Number

  • Text

After evaluating a field’s formula, Skuid will also attempt to convert the result into the selected return type. For example, if the result of the formula is the text value "003" and the return type is Number, Skuid will convert that value into an actual number, 3, before storing it in the model.

It’s important to select the formula return type to be appropriate with the output of the function. For example, if you have a formula to format a date value into a non-ISO 8601 format format, you should select an output type of Text. Selecting Datetime will cause Skuid to attempt to convert that date string into an actual date value, and errors may occur.

Operators

The following operators are supported within UI-only formulas:

  • + Add
  • - Subtract
  • * Multiply
  • / Divide
  • = Equals
  • != Does not equal
  • > Greater than
  • >= Greater than or equal to
  • < Less than
  • <= Less than or equal to
  • && And
  • || Or

Equality operators are always interpreted strictly, meaning they compare both type and value.

For example, the formula 1 = "1" will return false, because "1" is a string type, even though the value could be interpreted as one.

Note

Even if these equality operators are formatted non-strictly—= and !==—Skuid nonetheless interprets them strictly. Both = and == are interpreted as follows:

1 = "1" returns false 1 == "1" also returns false

Warning

In previous Skuid releases, equality operators could be used non-strictly as == for equal and !== for does not equal. As of the Brooklyn Q2 Point Release, this functionality is no longer supported.

Conditional Operation

  • IF: Returns one of two values based on a whether an equation or equations are true or false:

    IF( equations, value1, value2 )

    • equations: The equation or equations to evaluate. Equations can be evaluated using the operators listed above and can be chained with the && and || operators.
    • value1: The value returned if the equation is true.
    • value2: The value returned if the equation is false.
  • ISBLANK: Returns true or false based on whether its parameter is blank. This function will return true if its parameter is an empty string, null, or undefined. For example:

    • ISBLANK('') = true
    • ISBLANK(null) = true
    • ISBLANK(undefined) = true

    Some false examples.

    • ISBLANK('test') = false
    • ISBLANK(true) = false
    • ISBLANK(9) = false

    Note that if the string contains a typically falsey value, that is not considered blank.

    • ISBLANK("0") = false
    • ISBLANK("false") = false
  • NOT: Returns the opposite boolean value of its parameter, which must be a boolean value or an expression that evaluates to a boolean value. For expressions returning true, this formula will return false, and vice versa.

    • NOT(true) = false
    • NOT(false) = true
    • NOT(2+2==4) = false
    • NOT(2+2==7) = true
    • NOT(ISBLANK('')) = false
    • NOT(ISBLANK('Not an empty string')) = true

Note

While expressions within this function will evaluate before this function executes, if those expressions return non-boolean values, like strings or null values, then this function will return true.

Number Manipulation

  • ABS: Returns the absolute value of a number (42 and -42 both return 42).
  • CEIL: If a number is not whole - it will be rounded up to the next integer.
  • FLOOR: If a number is not whole - it will be rounded down to the next integer.
  • ROUND: If a number is not whole - it will be rounded up or down to the next integer depending on which is nearer.

Text Manipulation and Analysis

  • JOIN_TEXT: Combines text strings with a separator between them—while skipping empty parameters. It accepts three or more parameters:

    JOIN_TEXT( separator, string1, string2, ..., stringN )

    • separator: The text that appears between strings. Must be encased in quotation marks. This function guarantees that the separator appears once—and only once—between the parameters, should that separator also happen to be within a parameter. This prevents duplication.
    • string1: The first text string, appearing before the separator. This can be a hardcoded string or a merge variable. If this is an empty value, then the parameter will be skipped.
    • string2 - stringN: Any additional string parameters will appear after the first separator, with additional separators between each parameter. This can be a hardcoded string or a merge variable. If this is an empty value, then the parameter will be skipped.

    See the following examples:

    • Combining hardcoded strings and merge variables:

      JOIN_TEXT("+", "A hardcoded string",{{AFieldFromAModel}})

      Result: A hardcoded string + That field's text value

    • The separator is not duplicated:

      JOIN_TEXT("/", "http://example.skuidsite.com/", "/do-not-duplicate-the-slashes-please/")

      Result: https://example.skuidsite.com/do-not-duplicate-the-slashes-please/

    • Empty parameters are skipped:

      JOIN_TEXT("/", "", "start", "", "middle/", "", "/end/", "")

      Result: start/middle/end/

    Note

    As its name implies, this function will only work with text strings. If a hardcoded parameter is not encased in quotes, or if a parameter is a merge variable for a number-based field, Skuid will return errors.

    Warning

    JOIN_TEXT allows for multiple string parameters and more intuitive separator behavior, and as such it replaces the now deprecated COMBINE_STRINGS function.

    If you have used the COMBINE_STRINGS function in the past, be aware that

    1. JOIN_TEXT will handle separators differently.
    2. The order of parameters in JOIN_TEXT is different.

    Compare the following:

    • JOIN_TEXT(null, "/test", "/") returns /test/

      COMBINE_STRINGS(null, "/test", "/") returns test

    • JOIN_TEXT("/", null, "/test") returns /test

      COMBINE_STRINGS("/", null, "/test") returns /

  • CONTAINS: Accepts two parameters and returns true if the second parameter is contained anywhere within the first. If not, the formula will return nothing.

    • CONTAINS("A string of text", "text") = true
    • CONTAINS("A string of text", "123") will return nothing.

    Note

    This function is case sensitive.

  • CONTAINS_ANY: Determines if a string contains any of a list of provided parameters. Case sensitive.

    CONTAINS_ANY( stringToExamine, stringToLookFor1, stringToLookFor2, ... )

    Each parameter can be a merge variable or a hardcoded string, but any strings must be encased in quotes.

    Some examples:

    • CONTAINS_ANY({{InputField}}, "Foo", "bar", "BAZ")

      If InputField is “Yummy Food”, the above function would be true

      If InputField is “barbeque” the above function would be true

      If InputField is “ice cream baz” the above function would be false

    • CONTAINS_ANY({{InputField}}, {{InputField}}) = true

  • CONTAINS_ALL: Determines if a string contains all of the provided parameters. Case sensitive.

    CONTAINS_ALL( stringToExamine, stringToLookFor1, stringToLookFor2, ...)

    Each parameter can be a merge variable or a hardcoded string, but any strings must be encased in quotes.

    Some examples:

    • CONTAINS_ALL({{InputField}}, "Foo", "bar", "fruity drinks")

      If InputField is “Food, barbeque, and fruity drinks”, the above function would be true

      If InputField is “Food and barbeque”, the above function would be false

      If InputField is “Foo bar fruity drinks”, the above function would be true

  • CASE: Returns different results based on whether the parameter meets the specified criteria instead of using complicated chains of IF functions. An optional default value can be added as a final parameter for use if none of the provided case-result pairs match.

    CASE(testValue, case1, result1, case2, result2, ..., default)

    Each parameter can be a merge variable or a hardcoded string, but any strings must be encased in quotes.

    Note

    Case functions can be entered as a single line, but the examples below are multi-line for ease of reading.

    Some examples:

    • To return a numeric indicator corresponding to textual values for an Opportunity “Stage” picklist, CASE would look like this:

       1
       2
       3
       4
       5
       6
       7
       8
       9
      10
      CASE(
      {{StageName}},
      "Prospecting", 10,
      "Qualification", 20,
      "Needs Analysis", 30,
      "Proposal", 50,
      "Proof of Concept", 75,
      "In Review", 80,
      "Closed Won", 100,
      "Closed Lost", 0)
      
    • A CASE function with a default value would contain several pairs of cases and results, along with an extra parameter. Such a function would look like this:

      1
      2
      3
      4
      5
      CASE(
        {{Input}},
        "Foo", "Bar",
        "Hello", "World",
        "Unknown")
      
    • A CASE function without a default value would look like this:

      1
      2
      3
      4
      CASE(
        {{StageName}},
        "Prospecting", 10,
        "Closed Lost", 0)
      
  • ENDS_WITH: Accepts two parameters and returns true if the second parameter is at the end of the first. If not, the formula will return nothing.

  • LEFT: Returns a specified number of characters starting from the left of the first parameter. Requires a string and the number of characters to return.

    • LEFT("A string of text","4") = A st
  • LEN: Returns the length—or number of characters—of a string.

  • LOWER: Returns the value of the parameter with all letters as lowercase.

  • RIGHT: Returns a specified number of characters starting from the right of the first parameter. Requires a string and the number of characters to return.

    • RIGHT("A string of text","4") = text
  • STARTS_WITH: Accepts two parameters and returns true if the second parameter is at the beginning of the first. If not, the formula will return nothing.

  • UPPER: Returns the value of the parameter with all letters as uppercase.

  • VALUE: Accepts a string and turns it into a number. This function can process + and - signs, numerals, decimal points, and exponents, but will ignore other characters—and any numbers that come after them.

    • VALUE("42") = 42
    • VALUE("0.42E+2") = 42
    • VALUE("2A03") = 2

    If the parameter for the formula starts with a letter, the formula will return nothing.

    • VALUE("Text123") will not return a value.

Referential Data Access

  • MODEL_LOOKUP: A function that returns the value of a field within another model, similar to a VLookup Excel function. Commonly used for including one model’s data or functionality—such as an aggregation on an aggregate model—within a component already assigned to a different model.

    For the examples below, Model 1 refers to the model being looked up, while Model 2 refers to the model with this function.

    To use MODEL_LOOKUP, you’ll need at least two—but usually four—parameters:

    MODEL_LOOKUP("Model1Id","FieldIDfromModel1","KeyFieldfromModel1",{{KeyFieldfromModel2}})

    The first two parameters indicate which data you wish to display from Model 1.

    1. (Required) The Id of the model you are looking up. Noted in the example below as Model1Id.
    2. (Required) The field containing the value you want to display. Noted in the example below as FieldIDfromModel1.

    The third and fourth parameters provide context and tell Skuid how to match that data to the current row:

    1. A field ID or alias in Model 1 from parameter 1 that matches key field from Model 2. Noted in the example below as KeyFieldfromModel1.
    2. The field from Model 2 which correlates to the key field specified in the previous parameter—inserted via merge syntax. Noted in the example below as KeyFieldfromFieldfromModel2.

    Note

    Parameters 3 and 4 are optional, but excluding them will only return the first row of the model being looked up.

    Warning

    Models will load in the order that they are listed within the App Composer’s Models tab.

    This function will not work properly unless the model it references (Model 1) is loaded before the model containing this function (Model 2).

Date / Time Format and Manipulation

  • AMPM: Returns text ‘am’ or ‘pm’ from a DateTime field.

  • DAY_NAME_SHORT: Returns an abbreviated name of the day from a Date or DateTime Field as an internationalized label.

  • DAY_NAME: Returns the full Name of the day from a Date or DateTime field as an internationalized label.

  • DAY_OF_WEEK_UTC: Returns a Number corresponding with the day of the week from a Date or DateTime field. This day is calculated according to UTC (Universal Coordinated Time) rather than local time.

  • DAY_OF_WEEK: Returns a Number corresponding with the day of the week from a Date or DateTime field - in local time

  • DAY: Returns a Number corresponding with the day in a month from a dDate or DateTime field.

  • FORMAT_DATE: Returns a string with the date formatted according to the Format string specified.

    The format string follows jQuery’s $.datepicker.formatDate(), whose format characters are based on Java’s SimpleDateFormat.

    For more technical information, see the skuid.time topic.

  • FORMAT_TIME: Returns a string with time portions of a DateTime field according to the Format string specified.

    The format string follows jQuery’s $.datepicker.formatDate(), whose format characters are based on Java’s SimpleDateFormat.

    For more technical information, see the skuid.time topic.

  • HOUR_UTC: Returns the hour portion of a DateTime field with no time zone adjustment.

  • HOUR: Returns the hour portion of a DateTime field adjusted for the time zone of the system.

  • MILLISECOND: Returns the millisecond portion of a DateTime field if there is one. (Note Salesforce Dates do not contain Milliseconds. This function is only relevant for particular external data sources.)

  • MINUTE_UTC: Returns the minute portion of a DateTime field with no time zone adjustment.

  • MINUTE: Returns the minute portion of a DateTime field adjusted for the time zone of the system.

  • MONTH_NAME_SHORT: Returns an abbreviated name of the month from a Date or DateTime field as an internationalized label.

  • MONTH_NAME: Returns the full name of the month from a Date or DateTime field as an internationalized label.

  • MONTH_UTC: Returns the number for the month from a Date or DateTime field - without any time zone adjustments.

  • MONTH: Returns the number for the month from a Date or DateTime field - adjusted for the time zone of the system.

  • NOW: Returns the current time.

  • SECOND_UTC: Returns the second portion of a DateTime field with no time zone adjustment.

  • SECOND: Returns the second portion of a DateTime field adjusted for the time zone of the system.

  • TODAY: Returns the current date.

  • YEAR_UTC: Returns the number for the year from a Date or DateTime field - without any time zone adjustments.

  • YEAR: Returns the number for the year from a Date or DateTime field - adjusted for the time zone of the system.

Custom Formula Functions

Note

If you are a developer and would like to learn more about creating custom formula functions using JavaScript, see the skuid.formula API documentation.

To use a custom formula function within the App Composer:

  1. Ensure it is available to a page within either an in-line resource or a static resource.

  2. Input the namespace—followed by two underscores—and name of the formula function in the formula field like so:

    nameSpace__formulaName(arg1, ... argN)

Using UI-only fields in components, conditions, merges etc.

image1

Example #1: “Show More Details” Checkbox

image2

For this example, we’ll make a “Show Details” checkbox and connect it to conditional rendering so that when the box is checked, it will show more data on the page.

  1. Field Id is used as the field api name for merges etc.
  2. The Label is what is shown to the end user.
  3. You can also choose to add Inline Help Text if necessary.
  4. Choose the Display Type (see above for options). Let’s make this one a checkbox.
  5. Choose whether or not this field is read-only and enter the default value.

Pro Tip: You can also use the actions framework to activate/deactivate this field and trigger the rendering/hiding of this area.

Now you can reference this field in rendering conditions.

image3

In this example, we want the Show Details checkbox to show the Extra Details column of our field editor when it’s checked.

  1. Click on the Column/area you want to conditionally render.
  2. Click Rendering and add a new Render Condition.
  3. Your UI-Only field will be available to select!
  4. Enter the value for when you want this area to render (in this case checked or unchecked).

Example #2: Amount Formula Field.

image4

For our second example, we’ll add an “Amount” UI-Only field on the line items model. This is like the standard amount field, but with the advantage that it will calculate in real time as the sales price and quantity are updated.

Enter the formula. ~~~

image5

  1. Click Formula.
  2. Use these buttons to insert model fields, operators, and function. Don’t forget you can use the merge syntax {{$Model.MODELNAME.data.0.FIELDNAME}}
  3. For this example calculating total amount, our formula will be {{UnitPrice}}*{{Quantity}}

Example #3: Percent Saved Formula Field

image6

I also want to be able to see the percent that is saved for each list-item.

The formula is (({{ListPrice}}-{{UnitPrice}})/{{ListPrice}})*100

image7

You can also use table column summaries to sum, average, etc. UI-Only fields.

image8

Click Save & Preview.

Success! Working UI-Only Fields!

image9

  1. Click Show Details to show the Extra Details Column.
  2. Enter the Quantity and Sales Price to view the Amount in Real Time.
  3. Save a new line-items to view the % Saved.

Troubleshooting

My UI-only field is displaying the wrong date or datetime.

This may be caused by issues with the end user’s browser parsing the date field in an unexpected way. Skuid highly recommends date or datetime fields utilize ISO 8601 format.

If you are displaying dates in a different format (perhaps through use of the FORMAT_DATE), then set the formula return type to text instead:

  1. Within the Models tab of the App Elements pane, click the model containing the UI-only field.
  2. Click the UI-only field.
  3. Within the Properties pane, set Formula Return Type to Text.

Depending on your use case, you may also consider three curly brackets for any merge variables referencing these fields. Using three curly brackets will display the raw string without attempting to transform the date/time based on the end user’s locale.