Custom Component

This is a simple custom component

A Custom Component is a component where you can make a custom UI.

The Custom Component has the following views:

• Display - This shows the HTML element, which the user populates in the other views below.

• Input Code - This is the formula for the table. The value returned from this function will be the data displayed in the user defined display. For example, if the user makes this display a simple text area, this would typically be the text placed in the text area.

• Input Private - This is the private space associated with the input code above.

• HTML - This is HTML that is placed in the HTML element on its creation. Note that IDs on the elements here should be unique for the entire page.

• CSS - This is CSS that is appended to the page. This can be used to style the element. Note that style classes should be unique for the entire page.

• uiGenerator() - This is a function the user codes which should return a UI generator object. That is an object that contains methods shown here to give functionality to the display for this component.

• Notes - These are notes the user can add for the component.

Reference the Custom Components page for a reference of what is in the UI Generator object we use to define our user interface.

Example Workspace

This is a simple example of a custom control.

Click here to open the Example Workspace.

This workspace contains three tables:

• initialValue - This is a plain data table containing some random text to be used by our test component.

• testComponent - This is an example custom component, described below.

• sentData - This is a plain data table that will receive data from our test component.

The custom component, testComponent, has a text area and a button. The text area is initially populated with data from the table intialValue. The button, when pressed, will copy the data from the text area to the table sentData.

Programming the Test Component

The following screen shots show the code added to the custom component, testComponent.

This is the HTML for our component. It includes a text area and a button.

This is the CSS to style our HTML. For simplicity we are just making the text area fixed in size. (Note that is we want to react to size changes of the component, we could have defined an onResize method.)

The main code for the example is the UI Generator. This is just an object that has some callback functions in it. It is convenient to define this as a class and then return an instance of it, as we did below.

In the onload method, we loaded the text area and the button from the HTML. We also add a click handler to the button. This takes the data in the text area and sends it to the sentData table using the messenger, which we can obtain from the admin object passed in.

An important point here is that we can NOT access other table from this code. This is not code in our model. This is just UI code. We can however get data from our model by defining the setData function.

The setData function receives the output of the "formula", or the function we defined in the input code view for this component. The input code DOES have access to the model. We show that code below.

There is one other notable item here in the constructor. We added a call to __customControlDebugHook(). This doesn't have any action. It references a function in our static code, in the source file called "debugHook.js". We put it there so we can set a breakpoint in our debugger to debug our code. This is optional.

Below is the input code. This is equivalent to the formula in a data table. It is a function that returns a value that will be passed into our UI generator code with the setData function. This code does have access to our model, as we see here, and it is the only way to pass data from our model to our UI.

In this case we just return the value in initialValueTable. In our model we will use this to set the value in our test area. For one thing, it sets the initial value of the table.

The input code will execute any time we update the tables it depends on. In this case that means if we change the value in the initialValue table, it will overwrite the data in the text area. (That may not be the behavior we want. But this is just an illustration of how the component works. It can be coded differently.)

Here is our result for the Display view. We have the simple for as we described.

Destroy On Hide Option

When we create a custom component, or when we edit the properties of the component, there is an option Destroy on Hide. The default value is false.

If we set this to true, any time we hide the component display we will destroy it. It will be reconstructed when we show it again. This is done in most of the native components to save resources. However it may take a little extra care in defining the component. If the value is set to false, which is the default, than the display is only created once and then saved, so there is no need to worry about saving state between the when the display is destroyed and recreated.

If you do want to tear down the display created when it is not shown, this flag can be set to true. It is typically not needed however.