Note
All code samples below refer to the skuid
object.
In the v2 API, this object is not directly accessible when working within a browser console—or when referring to another Skuid page runtime.
If you are experiencing issues, use the skuid.runtime API to target the appropriate page context.
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 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¶
Functions¶
-
skuid.builder.core.
createModel
(initialState, options)¶ Creates a new Model and adds it to the Composer’s XML state. If the Models tab is visible within the Composer, its UI is also updated to include the new Model. Useful for custom components that must generate their own Models.
Optionally, the Model can be focused and selected in the Composer.
Arguments: - initialState (XML) – (Optional) The initial model state to use instead of the default, generic model state.
- options (Object) –
(Optional) Additional configuration properties for the newly created Model:
-
skuid.builder.core.options.
select
¶ Defaults to false. If true, the newly-created Model component will be selected and focused on immediately upon creation.
-
Returns: The Builder component for the Model
Return type: Component
-
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.
-
- parameters (object) –
-
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
()¶