The Widget Studio editing interface is presented whenever a widget is being edited or created via Widget Studio. The following document describes using the Editing Interface without diving into Widget API specifics.
Saving, branching, deleting, reverting
Saving a widget
Simply select Save in the sidebar. Alternatively the keyboard shortcut of CTRL-S also saves. If the widget is being created via the Widget Studio or is a custom widget being edited via the Widget Studio, changes overwrite the existing widget. If the widget is a Factory Default, the original is retained and changes are saved in a custom version. The custom version is deployed on the site, but can be reverted to the Factory Default.
Branching a widget to a theme-specific version
After a widget is saved at least once (it is not being created for the first time), the widget can be saved as a theme-specific version. By default, a given Studio Widget functions identically in any theme. A theme-specific Widget is only used when that theme is selected. A theme-specific widget defines its own complete set of content, configuration, attachments, and resources and can potentially vary significantly in implementation from its base.
To create a theme-specific version, select the arrow next to the Save button and select Save for Theme. Widget Studio will prompt for which theme to save against.
When a one or more theme-specific versions exist for a widget, those versions are listed below the Widget's name. Selecting the theme version defines what version is being viewed and edited within the Widget Studio.
Branching a widget to a separate widget
To save a copy of a widget as a new, separate, widget that does not overwrite the original, select the arrow next to the Save button and select Save As. Widget Studio will prompt for a new name for the new widget. The new widget will be created with a copy of the source widget's content, configuration, attachments, and resources and will not affect existing usages of the source widget.
Deleting or Reverting a widget
Deleting and Reverting works identically as in the Managing Widgets screen.
A widget which was imported or created via the Widget Studio can be deleted, but not reverted. A Factory Default widget can be neither deleted nor reverted. However, a customized version of a factory default (a factory default which has been "saved" against through Widget Studio) can be reverted back to its original Factory Default state. The type of widget being viewed determines whether a Delete or Revert button is presented.
Exporting a widget
A widget can be exported into a single file by selecting Export Widget. A widget's export contains all of the widget's script, configuration, attachments, and resources. Widget exports can be re-imported to any Evolution 6 installation via the Managing Widgets section of Widget Studio.
Defining a widget
A widget's name is the only field required when defining a widget. Both 'Name' and 'Description' support resource tokens to allow for localized names. So, if a widget is titled "Hello World", "Hello World" can optionally be defined as a resource named title_hello_world and the 'Name' field for the widget can contain ${resource:title_hello_world}
Defining main content script
The first tab of the Widget Studio contains all of the Widget's main Widget Script. The widget content is defined Using Velocity templated markup. Along with all velocity templates, the entire Platform API is available to widget content script via Script Extensions as documented in the API Documentation link in the sidebar of the Widget Studio.
Defining available widget configuration
Widget Configuration is defined using dynamic configuration XML in the 'Configuration Content' field of the 'Configuration' tab.
Defining available contexts
Without defined available contexts, a widget can be placed in any region on any page, header, or footer. With specified contexts, a widget can only be placed in certain regions dependent on the context. For example, a widget that only works when there is a current Blog Post in context would want to specify the 'Blog Post' context. Multiple available contexts can be defined.
Defining widget headers
'Show Header by Default' defines whether the header of a widget is shown by default. The selected wrapping format when placing a widget can override this choice.
'Header Script' optionally declares velocity script which, when evaluated, generates the content displayed in a widget's header. When not provided, a widget's header will be equivalent to its title.
A common pattern for Header Script when a widget's title is configurable is to use the following configuration...
<property id="Title" resourceName="Property_Title" dataType="String" defaultValue="${resource:Widget_Title}" controlType="Telligent.Evolution.Controls.ContentFragmentTokenStringControl, Telligent.Evolution.Controls" />
...and the following Header Script...
$core_v2_widget.ApplyTokens($core_v2_widget.GetStringValue('Title', '${resource:Widget_Title}'))
This allows for the widget configuration to expose editing of the title while still supporting resource tokens.
Defining caching attributes
Is Cacheable defines whether a widget's output should be cached by the site. This should be enabled whenever possible, which includes when a widget is not Accessing-user-specific, or is user-specific but can be cached per user.
Vary Cache by User defines whether a cached widget should use the same output for every accessing user or a separate cached copy for each. A widget whose content is specific to the accessing user should vary cache by the user.
Defining a widget's CSS class
To allow for easier styling of a widget from a theme, a widget can define its own unique CSS class which is applied to its wrapping div element. CSS selectors can then be targeted to specific descendants of the class as follows
.content-fragment.social-share h2 { /* H2 styling specific to the 'Social Share' widget */ }
Defining and editing attachments
Any file type can be "attached" to a widget, including images, JavaScript, stylesheets, web fonts, and more. To attach files, select Upload File(s) from the sidebar. Files will not be attached until the next widget save.
Uploaded attachments that are known editable text formats including CSS, JavaScript, HTML, XML, and VM (velocity) are displalyed on their own independent tabs within the editing interface and can be further edited directly within Widget Studio.
All other attachments are listed on the "Attachments" tab with previews when available.
Attachments can be referenced from widget script via a URL generated from
$core_v2_widget.GetFileUrl('attachmentname.extension')
Often, velocity script attachments are intended to be evaluated as Ajax endpoints. In such cases, GetExecutedFileUrl should be used:
$core_v2_widget.GetExecutedFileUrl('script.vm')
More documentation is available on using custom Ajax endpoints
In addition to uploading in-browser editable attachments, new editable attachments can be added directly within Widget Studio by selecting Add File, which opens a new Studio tab identical to other editable attachment tabs.
Defining resources
Studio Widgets can define all of their own resources for localization purposes. The Resources tab allows for defining resources for each currently-enabled Language pack. Resources can be exported and imported independently of widgets when Managing Widgets.
A defined resource can be referenced via widget script as:
$core_v2_language.GetResource("resource_name")
Accessing API Documentation
The Platform API, as exposed via Widget Script Extensions, is automatically documented within the Widget Studio. This documentation is available by selecting API Documentation.
API Documentation shows as much data as it can about all currently-enabled extensions, including any third-party installed and enabled extensions. Only enabled extensions are displayed.
Customizing the editing interface
In supporting browsers, the Widget Studio editing interface allows supports syntax highlighting and auto-indentation. By selecting Editor Settings in the sidebar, the following options can be configured:
- Theme: Syntax highlighting color scheme
- Show Gutter: defines whether line numbers are shown
- Highlight Line: defines whether the current line is displayed
- Show invisibles: defines whether non-visible characters such as tabs and line breaks are rendered