UI Automation

Ben Tiedt — Thu, 20 Jun 2019 20:13:47 GMT

Current Revision posted to Developer Training by Ben Tiedt on 06/20/2019 20:13:47

When developing custom extensions using [[Plugins|plugins]], it is often beneficial to install UI components as part of the installation of the extension making use of the [[api-documentation:IInstallablePlugin Plugin Type|IInstallallablePlugin]] interface and the UI automation API.

[toc]

What is the UI Automation API

The UI automation API is set of APIs made available to [[Plugins|plugins]] via the [[api-documentation:In-Process API Documentation|in-process API]] to enable the automated adjustment of UI components. Specifically, it includes the following services and constants:

Services

[[api-documentation:ContentFragments In-Process API Service|ContentFragments]]

Enable/disable widgets, identify widgets to other UI automation APIs, translate widgets, and automate widget upgrading (see [[Managing Widget Source and Distribution]]).

[[api-documentation:FactoryDefaultScriptedContentFragmentProviderFiles In-Process API Service|FactoryDefaultScriptedContentFragmentProviderFiles]]

Add/update, delete, and detect factory default widget provider source files and attachments to install files associated to a factory default widget provider ([[api-documentation:IScriptedContentFragmentFactoryDefaultProvider Plugin Type|IScriptedContentFragmentFactoryDefaultProvider]] plugin). For the recommended approach to deploy factory default widgets, see [[Managing Widget Source and Distribution]].

[[api-documentation:ThemeFiles In-Process API Service|ThemeFiles]]

Add/update and detect embedded theme files.

[[api-documentation:ThemeFooterContentFragments In-Process API Service|ThemeFooterContentFragments]]

List, insert, replace, and delete widgets within theme footers.

[[api-documentation:ThemeFooters In-Process API Service|ThemeFooters]]

Add, edit, delete, and detect theme footers.

[[api-documentation:ThemeHeaderContentFragments In-Process API Service|ThemeHeaderContentFragments]]

List, insert, replace, and delete widgets within theme headers.

[[api-documentation:ThemeHeaders In-Process API Service|ThemeHeaders]]

Add, edit, delete, and detect theme headers.

[[api-documentation:ThemePageContentFragments In-Process API Service|ThemePageContentFragments]]

List, insert, replace, and delete widgets within theme pages.

[[api-documentation:ThemePages In-Process API Service|ThemePages]]

Add, edit, delete, and detect theme pages.

[[api-documentation:Themes In-Process API Service|Themes]]

List themes for a specific theme type.

Constants

The following APIs provide constants for use with UI automation services:

[[api-documentation:ContentFragmentWrappingFormats In-Process API Service|ContentFragmentWrappingFormats]]

Constants for platform-defined widget wrapping formats for use with content-fragment-related services.

[[api-documentation:LayoutRegions In-Process API Service|LayoutRegions]]

Constants for platform-defined layout regions for use with widget placement in content-fragment-related services.

[[api-documentation:ThemeableApplicationIds In-Process API Service|ThemeableApplicationIds]]

Constant for identifying the site application identifier.

[[api-documentation:ThemeProperties In-Process API Service|ThemeProperties]]

Constants for theme properties used to interact with the ThemeFiles service.

[[api-documentation:ThemeTypes In-Process API Service|ThemeTypes]]

Constants for the platform-defined theme types to be used with other UI automation APIs.

Using the UI Automation API

There are a few common situations where you'd use the UI automation API:

A custom application or custom functionality defines new pages (see [[Page Definition and URL Routing]]) and wants to include theme-specific variants of the new pages to simplify installation. For this, use the [[api-documentation:ThemeHeaders In-Process API Service|ThemeHeaders]], [[api-documentation:ThemePages In-Process API Service|ThemePages]], and [[api-documentation:ThemeFooters In-Process API Service|ThemeFooters]] APIs.
A set of custom functionality implemented as a set of custom widgets (via an [[api-documentation:IScriptedContentFragmentFactoryDefaultProvider Plugin Type|IScriptedContentFragmentFactoryDefaultProvider]]) needs to install the source widget files as part of the plugin representing the custom functionality. For this, see [[Managing Widget Source and Distribution]].
A custom application with custom widgets needs to install one or more custom widgets on existing pages. For this, use the ThemeHeaderContentFragments, [[api-documentation:ThemePageContentFragments In-Process API Service|ThemePageContentFragments]], and [[api-documentation:ThemeFooterContentFragments In-Process API Service|ThemeFooterContentFragments]] APIs.
A CSS file should be programmatically installed in the theme, either for general customization (perhaps as part of an automated deployment process) or as part of a custom application. For this, see the [[api-documentation:ThemeFiles In-Process API Service|ThemeFiles]] API and the example, Installing a CSS File, below.

Sample: Installing a CSS File

In this sample, a hard-coded CSS file will be installed in the site theme. This is a common scenario when deploying widgets through an [[api-documentation:IScriptedContentFragmentFactoryDefaultProvider Plugin Type|IScriptedContentFragmentFactoryDefaultProvider]] (see [[Managing Widget Source and Distribution]]) when the widgets share a common CSS or LESS file.

To integrate with the platform via code and access the [[api-documentation:In-Process API Documentation|In-Process API]], the example will implement the [[api-documentation:IPlugin Plugin Type|IPlugin interface]] in a public class named InstallCssFile. To ensure that the CSS file is only installed when it needs to be (when the plugin is first enabled or when a new version is installed), the InstallCssFile class also implements the [[api-documentation:IInstallablePlugin Plugin Type|IInstallablePlugin interface]]. To implement the class, the project will need to reference the Telligent.Evolution.Api and Telligent.Evolution.Components DLLs.

The full source is at the bottom of this page, but the key usage of the UI Automation API occurs in the Install() and Uninstall() methods:

public void Install(Version lastInstalledVersion)
{
    foreach (var theme in Themes.List(ThemeTypes.Site))
    {
        ThemeFiles.AddUpdateFactoryDefault(
            theme, 
            ThemeProperties.StyleSheetFiles, 
            _fileName, 
            _fileStream, 
            (int)_fileStream.Length, 
            new CssThemeFileOptions
            {
                ApplyToModals = true,
                ApplyToNonModals = true
            });

        ThemeFiles.AddUpdate(
            theme, 
            ThemeableApplicationIds.Site, 
            ThemeProperties.StyleSheetFiles, 
            _fileName, 
            _fileStream, 
            (int)_fileStream.Length, 
            new CssThemeFileOptions
            {
                ApplyToModals = true,
                ApplyToNonModals = true
            }
            );
    }
}

In Install(), the plugin loops on each available site theme (using the [[api-documentation:ThemeTypes In-Process API Service|ThemeTypes]] and [[api-documentation:Themes In-Process API Service|Themes]] APIs). For each theme, it installs a factory default version of the CSS file and the same file into the current contextual version of the site theme (using the [[api-documentation:ThemeTypes In-Process API Service|ThemeFiles]], [[api-documentation:ThemeProperties In-Process API Service|ThemeProperties]], and [[api-documentation:ThemeableApplicationIds In-Process API Service|ThemeableApplicationIds]] APIs). When installing CSS files into the ThemeProperties.StyleSheetFiles theme property, CSS options can be defined using [[api-documentation:CssThemeFileOptions In-Process API Supplementary Type|CssThemeFileOptions]]. In this example, the plugin identifies that the file should be rendered on modal and non-modal pages of the theme.

public void Uninstall()
{
    foreach (var theme in Themes.List(ThemeTypes.Site))
    {
        ThemeFiles.RemoveFactoryDefault(theme, ThemeProperties.StyleSheetFiles, _fileName);
        ThemeFiles.Remove(theme, ThemeableApplicationIds.Site, ThemeProperties.StyleSheetFiles, _fileName);
    }
}

When uninstalling, the Uninstall() method is called and the plugin again loops on the available themes and removes the installed CSS file from the factory default and contextual implementation of each theme.

The full source of this sample is below:

community.telligent.com/.../InstallCssFile_2E00_cs