Introduction

 

Client Components are a feature of the Client Builder that allows you to build your own custom Widgets. All the Client Components which are saved into a Namespace will appear on the Client Builder’s Widget palette alongside the builtin Widgets. Components can contain more than just Widgets; they can also carry other Client Builder objects inside them to support the Component’s purpose:

• Pages
• Data Streams
• Localizations
• JavaScript Assets
• CSS Assets

This document explains Client Components from two different perspectives:

• The “Author” of a Component, who needs to know how Components are created, edited, configured and saved.
• The “Consumer” of a Component, who needs to know how a Component can be used inside a Client. This means both how they are configured when being edited within the Client Builder and how they can be controlled at runtime.

A common purpose for Components is to use them to build a “wrapper” around 3rd-party JavaScript libraries or plugins, allowing you to extend the builtin Widget set. Components can also be used to capture and generalize common UI patterns you use inside your Clients, and make them available to be reused and leverage in other Clients.

The Client Component Tutorial walks you through the process of creating a Component.

A note on names: Keep in mind when reading this document that the name of a Component is not the same thing as the name of a Widget that embodies an instance of the Component inside a Client. For example, an Author might build a generic Component called “MyGauge”. The Consumer of this Component might drop 3 instances of “MyGauge” into their Client. Each instance of the Component is a separate Widget, and the Consumer can give each a separate name (e.g. “EngineTemp”, “OilPressure” and “ExhaustTemp”). The name of the Component and the name of a Widget which instantiates it are not the same thing.

Creating a Component

Components are saved into a special kind of Client that contains only the parts the Component needs to operate. All these special Clients in a Namespace will result in a palette entry when using the Client Builder, which allows you to drop them into a consumer’s Client.

A Component author can create a Component Client in 2 different ways.

Create an empty Component from scratch

The “Add / Clients” dialog contains a “New Component” button. You will be asked to supply a name for the Component and a special Component Client will be created. This Component will initially be empty, ready for the author to start adding Widgets.

Create a Component from an existing Layout Widget

An author can also create a Component by using an existing Layout Widget as a starting point. It will often happen that while developing a Client you will realize that some fragment of the Client would make a useful Component. Since a Component is just a single complex Widget, you simply select the Layout Widget which contains fragment you want to capture. (If the functionality you want is not already contained within a single Layout you must create one and move all the Widgets inside.)

Here’s a simple example that contains a GridLayout with some Widgets and code to add 2 numbers and display the result.

After selecting a Layout Widget you will see a “Create Component” button appear in the toolbar at the top of the Client Builder pane.

Clicking that button will ask you for a name for the Component and create the special Client which will contain it.

Clicking “OK” will save the new Component and open a Client Builder to edit it. (Notice that now the Client Builder just contains your “wrapper Widget” within a “Single” layout.)

Important – Client Components often depend on other assets than just the Widgets inside them. When you create a Client Component in this way it is impossible to know which assets from the original Client are required by the new Component and which are not. Unfortunately this means that the Client Builder must copy all the assets into the new Client Component, and then it becomes the responsibility of the Author to clean up, deleting any of the assets which the Client Component does not actually require.

After the new Client Component is created you should review the assets which were added and delete any which you don’t need. Here are the assets you should check:

• Pages
• DataStreams
• Global Localization Symbols
• CSS Assets
• JavaScript Assets
• Offline Assets
• Document Assets

Editing a Component

The author edits a Component using the Client Builder, which runs in a special mode when editing a Component instead of a Client. There are variety of changes to the behavior that we will cover as we go.

A simple Component appears as if there is only a single “Start” page in the “Single” Layout Type. The outermost Widget is the “wrapper” that contains all the parts of the Component. If you created this Component from scratch this wrapper will be a VerticalLayout by default. If you prefer a different type of Layout you can use the context menu to convert it to a different type (GridLayout, HorizontalLayout, etc.) When the consumer drops your Component into a Client it is only this outer “wrapper” Widget which will be directly accessible when editing. (The “Start” Page itself is just a shell that is left behind when you drop the Component into a Client.)

A more complex Component may want to open or popup additional Pages; simply add them to the Component as needed and they will be carried along with the Component into the consumer’s Client.

A Component is rather like a Class; it contains internal state and methods which allow the consumer to operate on it; it is up to the author to decide what to reveal. Unless the author exposes a more elaborate interface all the consumer would be able to do is to click on the Widgets inside the Component at runtime. The author creates a Component’s interface by specifying a “Configuration”.

When editing a Component you can open its “Component Properties Dialog”; this is similar to the “Client Properties Dialog” for a regular Client.