Your First Extension: Part 3c - The Dark Art of Property Synchronization

[david_stocker]

This is part of a tutorial series on creating extension components for Design Studio.

Before we actually start making use of the properties that we defined in the last session, we need to take a side trip into theory.  We'll do this in order to spare you hair pulling moments, later on, when you can't figure out why your properties are "working" sometimes, but not at other times.

Where the Properties Are

The fist thing to keep in mind is that component properties live in two or three places, depending on whether we are running in the designer, or whether the app is running and being accessed via a browser.  The three possible places are:

1. The Server: During design, this is the copy of the property that is shown in the properties sheet (if it is visible).  During runtime, this is the copy that the server maintains and the copy that scripts interact with.
2. Canvas/Client: This is the copy that lives in the client browser or design studio canvas and this is the copy that you'll be working with in your component.js file.
3. The Additional Properties Sheet: This is the copy that lives in the javascript file of the additional properties sheet.  The APS is only relevant during design time

When and how they are synchronized

There are two simple rules for how properties are synchronized:

1. If the change is happening on the server (in the properties sheet, or via BIAL script), then it is automatically propagated to all other copies.
2. If it happens elsewhere, there must be an explicit JavaScript function call to do this: firePropertiesChanged().Once this is called, the changed value is messaged to the server. (and propagated further, if relevant)

That's it!  Now let's take a look at what this means in practice.

Examples

As we're keeping two or three copies of all of our properties, we need a way to make sure that they are all synchronized.  How exactly this is done depends on where the value is changed.  In the following examples, let's presume that all copies  of some hypothetical property start with the value "A" and we'll change it to "B".

If the change happens on the properties sheet, during design time:

1. The designer changes the value to "B" in the properties sheet.
2. The changed value is messaged out to both the component in the canvas and the APS.  This happens automatically.

These property changes will be saved in the app.

If the change happens on the APS, during design time:

1. The designer changes the value to "B" in the APS.
2. The server update is not automatic and and firePropertiesChanged() must be called to copy it to the server.
3. The property update on the server cascades the change out to the canvas as well.

These property changes will be saved in the app.

If the change happens on the client, during run time:

1. The property value to is changed to "B" in the client.
2. When firePropertiesChanged() is called, the updated property value is copied to the server.

If the change happens on the server, during run time (it was set via BIAL script):

1. The property value to is changed to "A" on the server.
2. The changed property value is propagated to the client.

Mistakes and Pitfalls.  Things go bad when...

So far, we've covered the scenarios that are supposed to work.  There are also mistakes and pitfalls to watch out for.

If the change happens on the canvas, during design time:

1. The property value to is changed to "B" in the canvas.
2. Component.js also has a firePropertiesChanged() implementation, however, it only works at runtime.  Attempts to push a property update to the server copy will fail.

These property changes will not be saved in the app.

There is no "initial push" of property values from the server.  Only changed values are propagated.  This means that if I don't change a value from the default via the properties pane, no property value will be pushed to the client.  So if A is the default value in the properties pane and the designer never changes it, then it will be undefined in the client and APS.  The solution to this is to explicitly initialize every property in the APS and component.js.  Yes, it is tedious, but it will save you from wondering why the property is undefined in the client some times, but not others.

Forgetting to fire firePropertiesChanged() will also result in different property values being on the server and client.

As always, the completed extension (as of part 3) is available as a Github repository.

Next time, we'll put this theory into practice and start using our properties to define our gauge.