## Defining Data Binding Within A Component Rather than having to define lots of methods within a Component, each of which controls the state of DOM elements within your WebComponent, *Golgi* provides a further, declarative approach which allows you to define the specific data binding used in the Component's state map. First, you can specify the state map that the Component should use with the *addStateMap()* method. You'd usually define this in the Component's *onBeforeState()* lifecycle method, eg: onBeforeState() { this.addStateMap('article'); } If you did this, and then, at some later point, assigned an object to this state property, eg: this.golgi_state.article = { author: 'Rob', title: 'My Great Article', description: 'An amazing piece of work!', image: 'https://static.productionready.io/images/smiley-cyrus.jpg' }; ... you can declaratively specify how and where to bind those three properties (author, title and description) within the Component's HTML assignment by using the special keyword *golgi:bind={{property_name}}*, eg: let html = `
golgi:bind=title
Author
Description
golgi:bind=description## Rendering Multiple Copies of a Component Mapped to a State Array Suppose you want to render error messages returned from a back-end system, and the layout/presentation of each error message is defined in a *Golgi Component*. Alternatively, imaging the back-end returns an array of results, each element in the array being an object whose key/value pairs represent columns in a table row that you want to display. The layout/presentation of each row might be defined in a *Golgi Component*. Essentially, therefore, in both example scenarios, for each member of the data array, you want to do two things: - render an instance of a *Golgi Component* that will display the array member - map the data in the array member's key/value pairs to fields defined in the *Golgi Component* using the *golgi:bind* keyword. *Golgi* makes this very simple, and you can see examples of its use in the *RealWorld Conduit UI* example that is included in this repository. Within any Component, you have access to the *Golgi*-provided method: *this.renderComponentMap()* It has the following arguments: - *componentName*: the name of the *Golgi Component* to be rendered for each data array member - *targetElement*: the DOM element to which each instance of the Component is to be appended - *context*: the *Golgi* Content object (accessible as *this.context* within all Components) - *dataArray*: the array containing the data you want to map to each Component Instance - *stateMapPropertyName*: the name of the *this.golgi_state* property to be used for data binding. - *callback*: an optional callback function that is invoked after each Component is rendered and after databinding has occurred. The callback function has two arguments: - *component*: the instance of the Component that has been rendered and populated - *dataArrayRow*: the data array member that has been used to populate the instance of the Component You'll see numerous examples of this method in use [within this example Component](./examples/conduit/components/conduit/conduit-root.js).
---- # Automatically Detecting DOM Changes in *Golgi Components*
## Detecting Changes the Hard Way Deep within your application you might have a *Golgi Component* that displays some text that you might want to change programmatically. Of course, to make the actual text change you can use the data binding provinded by [*Golgi's* StateMap mechanism](#state-management-and-data-binding-in-golgi). Suppose, however, that whenever the text changes, you want to invoke a method within the Component, causes other things to happen. Some HTML tags, for example *input*, allow you to add a *change* EventListener, so for these, within the Component's HTML definition you could do something like this: and you could then define a method within the Component: doSomething() { // do something because this.myInput.value has changed } However, if the HTML tag was a simple *div* tag, this wouldn't work. You could, instead, define a MutationObserver for the *div* tag and trap any events associated with any Mutation *childList* types. You don't need to do this, however, since *Golgi* already automates much of the MutationObserver logic for you within your Components. Golgi provides three ways of applying the MutationObserver: - you can observe and handle changes to attributes for any element within a Golgi Component; - you can observe and handle changes to the text content of any element within a Golgi Component; - for any other scenario, you can define your own mutationOberver handler in a more generic way.
## Observing and Handling an Attribute Value Change This can be done using the special attribute value: golgi:observer={handlerMethodName} eg: golgi:observer=setVisibility Note that Golgi permits an attribute to have multiple special Golgi directives as values. This is needed because you'll often want to observe and handle an attribute whose value is bound to a state-mapped object's property. Separate multiple Golgi directives with a semi-colon and optional space(s), eg: The handler method is simply defined within the containing Component, eg: handleMyAttr(newValue, oldValue) { // do something } A Golgi Observer attribute-change handler method takes two arguments: - the new value of the attribute being observed - the old/previous value of the attribute being observed Note that *this* within the handler method refers to the Component. Note also that you can define as many attribute observers as you wish within a Component.
## Observing and Handling an element's Text Content Change This can be done using the special text value: golgi:observer={handlerMethodName} eg: golgi:observer=setVisibility Note that Golgi permits an element's text content to have multiple special Golgi directives as values. This is needed because you'll often want to observe and handle an element's text content whose value is bound to a state-mapped object's property. Separate multiple Golgi directives with a semi-colon and optional space(s), eg:
golgi:bind=myText; golgi:observer=handleMyText
The handler method is simply defined within the containing Component, eg:
handleMyText(value, targetTag, originalTag) {
// do something
}
A Golgi Observer text-change handler method takes three arguments:
- the new value of the element's text content that is being observed
- the actual element whose text has changed. If you've used a *golgi:bind* directive to maintain the value, you should be aware that in order to unambiguously maintain text content, even if there are other nested sub-elements, Golgi actually adds a *span* tag to your original element, ie for the example above what Golgi actually renders is:
the value of myText
So in this case, the *targetTag* argument is the *span* tag
- the original element whose text is being observed. This will always be the one specified in the Component's HTML. For the above example this will be the *div* tag.
Note that *this* within the handler method refers to the Component.
Note also that you can define as many textcontent observers as you wish within a Component.
## Activating a Generic MutationObserver within a *Golgi Component*
If you need to observe and handle something other than a tag's attribute or text changes, you can make use of the more generic MutationObserver integration provided by Golgi. This is rather more involved that the attribute-specific and textcontent-specific functionality previously described. For that reason, it's best to use the attribute-specific and textcontent-specific MutationObserver functionality provided by Golgi.
To activate a generic MutationOBserver, invoke *this.observerStart()* in one of the Component's lifeCycle event handers such as *onBeforeState*, eg:
onBeforeState() {
this.observerStart();
}
*observerStart()* will detect all the standard mutation types, ie what *Golgi* actually runs for you (for each HTML tag within your component) is:
golgi.observer.observe(target, {
attributes: true,
attributeOldValue: true,
characterData: true,
characterDataOldValue: true,
childList: true,
subtree: true
});
When *this.observerStart()* is invoked, any DOM changes within any of the Component's HTML tags will trigger the Component's *observerCallback()* method (if it is defined). This callback is triggered for each and every DOM change. What you do in this callback method is up to you, eg:
observerCallback(mutation) {
// do something as a result of this specific mutation object
}
The *mutation* argument for the *observerCallback()* is a standard MutationObserver object representing a specific mutation, so it has all the standard properties you'd expect, eg:
mutation.type: the type of mutation
mutation.target: the DOM element that has mutated
### Simple Example Using the Generic MutationObserver
To detect changes to the text within a *div* tag in your Component:
- define the *div* tag within the Component's HTML definition, eg:
golgi:bind=theText
- start the Mutation Observer and also define the state map for data binding within the component:
onBeforeState() {
this.observerStart();
this.addStateMap('myExample');
}
- define the *observerCallback()* method:
observerCallback(mutation) {
// any text change will trigger a childList mutation...
if (mutation.type === 'childList') {
// When using Golgi's data binding, the mutation will have
// actually occurred on a span tag that is added to the div
// as a child tag
// So we can determine that the mutation has occurred to
// the myText div as follows:
if (mutation.target.parentNode === this.myText) {
this.doSomething();
}
}
}
- define the *doSomething()* method:
doSomething() {
console.log('The text was changed to ' + this.myText.textContent);
}
- now the *div*'s text can be changed from anywhere within your application logic by simply setting the state map object:
this.golgi_state.myExample = {
theText: 'A new value for the div'
}
and as a result, the *doSomething()* method will also fire within the Component.