Developer
How-To Articles

Dynamic Setup UI Creation

Problem:

You want to have your user interface in the Klip's setup window reflect what is contained in a data source, and keep the information up to date.

Solution:

In this example, we'll dynamically configure the contents of a combobox. The main idea is that we will make two requests during the onRefresh handler, and that each request will use different onCreate and onUpdate handlers to manipulate the data. Please note that this example assumes that the configuration data source and the regular data source share similar tag naming in their XML (different stylesheets could be used for each data source by using Engines.Data.stylesheet).

First of all, we'll create a "Setup" tab with a combobox on it:


function onLoad()
{
    // Build the Setup window UI
    Setup.addTab("Setup");

    Setup[0].addText("Select which icon colour to use:");
    gCombo = Setup[0].addComboBox();
}

gCombo is a global variable in the Klip.The key to the solution is in the onRefresh function. An onRefresh function is not limited to only one HTTP request, nor is it limited to only one call to Engines.Data.process(), as we'll see below:


function onRefresh()
{
    // Use special onCreate and onUpdate handlers for the configuration items
    Engines.Data.onCreate = configCreate;
    Engines.Data.onUpdate = configUpdate;
    
    // Clear the arrays that will contain the configuration options
    gColours = new Array();
    gImages = new Array();

    var req = Engines.HTTP.newRequest("http://www.myserver.com/feeds/myfeed.xml");

    if(req.send())
    {
        if(req.response.data.length > 0)
        {
            // Process the configuration data
            Engines.Data.process(req.response.data);
        }
    }
    
    // Build the combobox out of the configuration data
    buildCombo();
    
    // Use different onCreate and onUpdate handlers for the regular items
    Engines.Data.onCreate = myCreate;
    Engines.Data.onUpdate = myUpdate;

    return Engines.Data.process(Prefs.contentsource);
}

In the above code, gColours and gImages are global variables that we'll use to store the configuration data. Once the first request is made to the feed which contains the configuration data, the onCreate and onUpdate handlers are switched, and then the regular data source of the Klip is processed.The configureCreate and configureUpdate functions are shown below:


function configCreate(newItem)
{
    var colour = newItem.getData("status");
    var image = newItem.getData("description");
    
    gColours.push(colour);
    gImages.push(image);

    // Return false to make sure the item isn't created in the Klip
    return false;
}

function configUpdate(oldItem, properties)
{
    return configCreate(properties);
}

The above functions read the data from the configuration feed as each item is processed, and save the data in the two arrays. Note that false is returned from this function, preventing the configuration items from appearing in the Klip.

Once the configuration data has been read, the onRefresh function calls buildCombo():


function buildCombo()
{
    // Reconstruct the combobox based on the new data feed.
    gCombo.clear();

    var i = 0;
    for(i = 0; i < gColours.length; i++)
    {
        gCombo.addItem(gColours[i]);
    }
}

The above function clears the current contents of the combobox, and then adds new items to it based on the data read from the configuration feed. The gColours and gImages arrays now contain a mapping of combobox setting to value, and the order of these arrays matches the order of the data in the combobox. This is important for later on in the Klip when the user chooses an item from the combobox - gCombo.selected can be used as the index into the gImages array to find the data related to what the user selected:


gImages[gCombo.selected]

To leave a comment, you must sign in or register (it's free).


Comment Type:
Title:
Comment:

Dynamic Setup UI Creation

Problem:

Solution:

Leave a Comment