So I just got back home to Ithaca a couple days ago and have been working hard on CourseTopia.  I finally had a chance this morning to get back to the State Model.  I’ve written the final two example files for the state model, the uiComponent and the action.

Again, this post is part of the State Model Development series.

The example source files for this part can be found here: uiComponent.js and action.js.

These two parts of the State Model, I feel, might not be as well developed as the other ones, so they will likely change more drastically when I do the practice run.  I plan on creating a sample application today or tomorrow to test the State Model, and we’ll see what needs changed during/after production.

I’ll start by discussing the action paradigm.

An action will generally be anything that can occur.  In the example source file, there’s barely any code to it at all.  It’s really just a holder for a couple different functions.

There are three difference callbacks for an action:

commit(params) – This function takes an object as parameters, and performs the initial setup of the action.  Generally, it would be possible for this to be the only callback set, as the uiComponents created through commit could handle automatically updating to reflect data changes after a response has been made.

onSuccess(params) – However, if there is some part of an action you’d like to perform after a call has been made successfully, this could be managed by the onSuccess function.  This will be called after a response has been received for the action and no errors occurred.

onError(params) – This function will receive a set of parameters and an array of error objects.  This should be set up for any action that might receive an error from the server, and should be able to effectively handle any errors.

That really covers actions.  I think there will likely be some major changes in the next revision, after the test-run.

The uiComponent paradigm is only marginally more complicated.

uiComponents objects are instantiated on document ready.  They actually refer to types of components than individual components.  For instance, you might create a uiComponent for Label, but not Label Id #543.  After you have instantiated the various types of uiComponents, you can then make calls to uiComponent.create(…) to make specific components.

There are up to four parameters passed into the uiComponent constructor, in record form:

dataManager : This is simply a reference to the data manager to be used.

initialize(id, params) : This callback function is called to create a component, with a given id and parameters.  The id refers to an internal identifier for the component, but for consistency, you might want to make the top-level element of the component have the same id.

The initialize(…) function should take advantage of uiComponent.data(name, field) for getting data, because this automatically adds to the list of dependencies, and throws an exception if data is not set, which can be used to automatically call not_ready.

Also, to insert an element into the DOM, you can also take advantage of the uiComponent.append function(element, target), which will append the element to the target.  If the ID of the element already exists, that object will be replaced.  This can be used to make writing an update method unnecessary, for code simplicity or rapid prototyping.

onUpdate(id, params) : This callback function is used to update the component to reflect some data change.  If it is not set, initialize will be called.  This should take advantage of a knowledge of the component, using document.getElementById(…)’s and setting values rather than recreating DOM elements.

notReady (id, params) : This callback function is called AFTER either update or initialize, if any piece of data was not yet defined.  This can be used to place some kind of a not-ready or loading notification in a component.

This is really about it.  Public uiComponent methods are .create(id, params) which calls initialize, and optionally also notReady, and .update(id, params) which calls the onUpdate(..) and optionally also notReady.

At this point, it should all be a little blurry, but I think we’ll all have a better understanding after a couple of practice runs.

related post