Adding Html Block Components

The Widget Library is an extensible library of components, that can be extended with new components. Users can add widget library components, of different types, directly in the builder. One of the types of components is a component generated by a block of custom HTML code, what we refer to as a HTML Block component, or simply HTML component.

This may often be an HTML wrapper code for other third-party components.

The following describes the steps required to add a new HTML component to the widget library. This is an overview of the steps required, with details in the sections below.

1. Create a file with the HTML code that generates the component.
2. Add Javascript to the HTML block file to allow setting properties for the new component
3. Create a HTML file with the form elements to configure any needed component properties
4. Add the component to the widget library

The HTML Block File

Create a new file with the HTML code for the new component. The following is a sample HTML block with two labels.

<div > <h5 id="firstelementjustadded" >Sample HTML Component</h5>

<span id="sometextgoeshere">We'll fill this in with Javascript</span> </div>

This file is then added to the widget library as described below.

Add Javascript Support to Configure Component

With HTML alone, it will not be possible for component users to configure the component in their applications using builder property forms. Such support can be easily added with a little Javascript in your HTML file. Two variabales are initalized before the embedded script is evaluated, and should be used to ensure the component works properly.

• htmlcontainer: This is variable for the container the component is in, which is useful to ensure you get the correct container when there are more than one such component on a page.
• htmlelement: This variable represents the element instance, and it's properties are used to store and configure the properties of the component.

In the following example, we change the properties of the HTML component example above. We use the properties of the htmlelement variable, and modify the component elements as needed. We use separate techniques for each of the two elements in the component, to illustrate how to access the component. In the first case, we need to set the id of the element the first time to access the correct child element in subsequent calls. In the second case we use the simpler document.getElementById method.

The simpler document.getElementById method can be used when there is only one such component on a pge. If more than one component of this type is used on a page, this method will often result in only one of the components getting updated, and often not the intended one. To see this add two of these components on a page, and only one of the labels will work properly. To avoid this kind of problem if you want to allow multiple components of the same type on a page, use the htmlcontaner to navigate to the corrent component element on a page.

<script type="text/javascript">
    if (htmlelement) {
       // Initialize list of element properties for the quick properties form
       if (!htmlelement.quickProperties) { // Quick properties need to be specified as an array
           htmlelement.quickProperties = new Array( "message", "color1", "color2"  );
       }
       
        // Initialize property values in forms as needed
        if (!htmlelement.message) htmlelement.message = 'Hello HTML World';
        if (!htmlelement.color1) htmlelement.color1 = 'red';
        if (!htmlelement.color2) htmlelement.color2 = 'yellow';
       
        
        var sp = document.getElementById('firstelementjustadded');
        if (typeof sp != 'undefined') {
            sp.id = 'firstelement'+htmlelement.id;
        } else sp = document.getElementById('firstelement'+htmlelement.id);
        
        sp.style.background = htmlelement.color1;
        
        
        var dv = document.getElementById('sometextgoeshere');
        var txt = document.createTextNode(htmlelement.message);
        dv.innerHTML = "";
        dv.style.background = htmlelement.color2;
        dv.appendChild(txt);
       
    }
    
</script>

Add the Javascript to the top of the file. Only the first script is executed, and it is executed after loading the HTML.

The HTML file for Configuration

In order to enable configuration of component properties, a HTML form should be provided for each component added to the library. The HTML is not really an HTML form, but has the fields typically fornd in a form. These fields display and allow configuration of component properties.

Each property should use the same id value patterns for the input fields, so that the properties can be displayed and picked up when modified. The following is an example of such a property form HTML. Your specific HTML can vary considerably, with the id names constraint being the only real requirement, i.e. set the input field id to quickprop_<property name&gt:

        <table class="chartform">
    <tbody>
      <tr>
        <td style="vertical-align: top;" align="right">Message:</td>
        <td style="vertical-align: top;"><input id="quickprop_message" name="message" type="text" size="30"></td>
      </tr>
      <tr>
        <td style="vertical-align: top;" align="right">First Color:</td>
        <td style="vertical-align: top;"><input id="quickprop_color1" name=""color1" value="green" type="text" size="30"></td>
      </tr>
      <tr>
        <td style="vertical-align: top;" align="right">Second Color:</td>
        <td style="vertical-align: top;"><input id="quickprop_color2" name=""color2" value="green" type="text" size="30"></td>
      </tr>
    </tbody>
         </table>

As shown above, each field has an id derived from the property value.

Adding To the Widget Library

Use the Extend Library link in the Widget Library to add the new Javascript component to the library. A property form will come up, and fill in the details for the component as described below.

• Widget Name The name of the widget shown in the widget library tree.
• Widget Source File The source file of the widget, in this case a Javascript file. Use a relative path, relative to the Ajax Builder root directory. (Note: This needs to be changed soon to be relative only if it is not a full url, or does not begin with /.)
• Widget Properties HTML File The properties HTML file described above. Use a relative path, relative to the Ajax Builder root directory. (Note: This needs to be changed soon to be relative only if it is not a full url, or does not begin with /.)
• Widget Type The type of the widget, either a Javascript widget, a HTML block, or a URL to be loaded in a iframe (this last option is not currently supported). In this case select HTML.
• Widget Width The width of the widget.
• Widget Height The height of the widget.
• Tree Parent The parent.
• Widget Package The widget package, which wil be used to put the component functions in a package. Currently ignored.
• Widget Icon The icon to be used in the widget library tree.
• Widget Description A short description of the widget, to be offered as help text on the widget library tree. Currently ignored.

Once all these properties are provided, click Add to add the component to the widget library tree.