skuid.builder.core

This is the core API for interacting with the Skuid Page Composer, particularly for creating custom component Builders.


Good news, everyone!

We are currently writing more material for our Javascript API. All of the objects and functions you see below are part of Skuid’s public API, even if they aren’t fully documented yet. Feel free to experiment while we write about them—and check back later for updates.


Classes

Builder

Think of Builders as components that build components, or more correctly, build the XML representation of components. When a user interacts with a component in the Page Composer, they are actually interacting with a Builder component.

The primary responsibility for a Builder is to provide an interactive UI layer over a component’s XML definition. Rather than working with a raw XML text document, the Builder enables non-developers and developers alike to change settings, enable features and add child components by clicking and dragging:

  • The Builder declares the user-friendly name and description seen within the Components tab of the App Elements pane.
  • The Builder contains functions used to render an HTML preview of the associated component. Builders typically are not true WYSIWYG previews — that is, what you see in the composer might not be exactly what you see at runtime — rather, they are optimized for component customization. For example, the preview generated by the Table Builder renders the fields, actions and filters that will be visible at runtime, but in such a way as to make working with them easier for the developer.
  • The Builder defines what will be displayed in the properties pane. The properties pane may include properties that do not have, or are not easily rendered as, a UI element. For example, the Table Builder exposes a Model property, a setting that does not easily lend itself to a UI preview.

Constructor

class new skuid.builder.core.Builder(parameters)
Arguments:
  • parameters (object) –

    A dictionary object with the following properties:

    new skuid.builder.core.Builder.skuid.builder.core.Builder.id

    A unique name that identifies the component type. To ensure that the builder is correctly associated with the component in the Page Composer, the XML tag name should exactly match the id (case-sensitive).

    new skuid.builder.core.Builder.skuid.builder.core.Builder.name

    A user-friendly name of the component, which will be displayed within Skuid’s component list in the Page Composer Toolbar.

    new skuid.builder.core.Builder.skuid.builder.core.Builder.icon

    The icon that will be displayed beside the component name within the component list.

    new skuid.builder.core.Builder.skuid.builder.core.Builder.description

    The description displayed in the component properties panel when the component is selected within the component list.

    new skuid.builder.core.Builder.skuid.builder.core.Builder.hideFromComponentsList

    Set to true to prevent the component from being listed in the composer

    new skuid.builder.core.Builder.skuid.builder.core.Builder.componentRenderer

    A function that will be called when the builder is rendered or re-rendered.

    new skuid.builder.core.Builder.skuid.builder.core.Builder.propertiesRenderer()

    Written as

    1
    propertiesRenderer: function (propertiesObj,component).
    

    A function that determines options and properties that are displayed within the component properties panel. It accepts two objects as its parameters:

    Arguments:
    • propertiesObj (object) –

      Contains the data for the component’s properties panel

      new skuid.builder.core.Builder.skuid.builder.core.Builder.skuid.builder.core.Builder.propertiesRenderer.propertiesObject.setTitle(title)
      Arguments:
      • title (string) – A string that will be used as the title of the component’s properties panel
    • component – A skuid.builder.Component representing the specific component the user is working with.
    new skuid.builder.core.Builder.skuid.builder.core.Builder.defaultStateGenerator:

    Written as

    1
    defaultStateGenerator : function() {}
    

    A function that returns the xml template to use when a component is dropped on the page. Commonly used with skuid.utils.makeXMLDoc()

Nested Namespaces

skuid.builder.core.coreProps

Functions

skuid.builder.core.componentFactory()

Create a component from the given XML.

skuid.builder.core.getActionsCategory()

Used in a Builder’s renderProperties function to add an Action properties tab.

Arguments:
  • parameters (object) –

    A dictionary object with the following properties:

    skuid.builder.core.parameters.label

    Optional. Defaults to “Actions”. The user-friendly title of the tab as well as the label of the root-level tree node. When ambiguous, use the label to clarify the type of action - such as “On Error Actions” or “Before Load Actions”.

    parameters.linkedComponent

    Optional, but encouraged. Sets the Builder Component that should keep focus while the user interacts with the Actions properties. If this property is not set, then the Build component may lose focus which can lead to a confusing user experience.

    parameters.customNodeId

    Optional. Defaults to “actions”. The name of the XML node. For consistency, the default is recommended for most scenarios.

    parameters.icon

    Optional. Defaults to “sk-icon-component-pack”. The name of an icon to use when rendering the root-level tree node.

    parameters.props

    Optional. Array of properties to display for the root-level Action tree node, usually an array containing a single “helptext” property explaining when or how the actions are used. For example:

    1
    2
    3
    4
    props : [{
      type : 'helptext',
      html : 'Actions to run whenever a user adds a Post or Comment to the Feed.<br/><br/>For instance, if a user uses the Feed to Log a Call, you may want to re-query a Skuid Model that is showing Completed Tasks.'
    }]
    
    parameters.useModelName

    Optional. The name of the model to use as “context” for the actions.

skuid.builder.core.getBuilder()
skuid.builder.core.getComponentFromState()
skuid.builder.core.getFirstModel()

Retrieves first model listed in model panel.

Return:Model properties (as listed in model pane)
Return:Fields
Return:Conditions
Return:Actions
skuid.builder.core.getHotkeysCategory()
skuid.builder.core.getLastSelectedModelComponent()

Returns GUID and other stuff from the last clicked model in the model panel

skuid.builder.core.getMetadataForField()
skuid.builder.core.getModelFromModelName()
skuid.builder.core.getRenderingCategory()
skuid.builder.core.getStateProperty()
skuid.builder.core.handleModelIdChange()
skuid.builder.core.handleModelRemove()
skuid.builder.core.registerBuilder(new builder)

Registers a Component Builder with the Page Composer. Registering a Builder adds it to the Component List and enables the Page Composer to recognize XML elements associated with the Builder.

Arguments:
  • skuid.builder.core.Builder (builder) – The Builder to add to a list of Builders available for use on the Page Composer
skuid.builder.core.registerComponent()
skuid.builder.core.save()
skuid.builder.core.updateStateProperty()