Webclient: event for filtering selection lists

[jri]

A plugin must be able to control the selection lists offered by the standard renderers e.g. the text renderer (combobox) and checkbox renderer.

Solution:
The standard renderers offers a new extension point by the means of an event.

[Jörg Richter]

Webclient: new "option_topics" event (#345).

A plugin can control the options being offered by a combobox (Text Renderer) or checkbox list (Checkbox Renderer). It does so by providing an "option_topics" listener.

Example:

dm4c.add_listener("option_topics", function(object, topic_type_uri, assoc_def) {
    if (object.type_uri == "dm4.example.notes_collection") {
        var person = object.get_topic_by_type("dm4.contacts.person")
        return dm4c.restc.get_topic_related_topics(person.id, {
            ...
            others_topic_type_uri: "dm4.notes.note"
        }, true).items  // sort=true
    }
})

This example assumes there is an "dm4.example.notes_collection" association type with a "dm4.notes.note" child type. The listener reacts when a "dm4.example.notes_collection" association is selected. The listener assumes there is exactly one Person topic involved in that association and then returns all Note topics which are related to that person. This set of Note topics forms the availble options rendered by the combobox resp. checkbox list.

To an "option_topics" listener 3 arguments are passed:

• object: the selected topic or association
• topic_type_uri: the type the returned option topics are supposed to be
• assoc_def: the association definition that lead to the field being rendered

The 2nd and 3rd arguments are meant to let the plugin tell the fields apart in case there are more than one combobox or checkbox list appearing in the detail panel. (Not used in the example.)

Return value of an "option_topics" listener: an array of topics or undefined.

Note: if more than one option_topics listeners feel responsible (that is, they return a non-undefined value)
a "competing plugins" exception is raised.

Furthermore in Webclient:

• The client-side Association model class provides a get_topic_by_type(topic_type_uri) convenience method.

See ticket 345.

• Changeset: 3556cc7c6d04746c442a5653abb46bcdfb3616a5
• URL: ​https://github.com/jri/deepamehta/commit/3556cc7c6d04746c442a5653abb46bcdfb3616a5

[Malte]

Thanks for implementing support for this surely useful feature.

But out of this commit message I have troubles to understand:

a) where exactly this listener should be written down, so that its properly picked up and
b) when exactly this listener is going to be called

i would assume:

a) in the generic plugin.js-file and
b) when the edit-form is rendered in the page-panel

i am asking since i am unable to register this listener on dm4-snapshot of today.

thankful for any further hints.

[jri]

Replying to Malte:

a) where exactly this listener should be written down, so that its properly picked up

Typically, yes, in your plugin.js main file.
Virtually in any file that is loaded by the DM Webclient.

b) when exactly this listener is going to be called

The "option_topics" event is fired each time a checkbox list widget or a combobox widget is rendered in the page panel (when it is in Edit mode). So, the event might be fired multiple times per page rendering. Use the passed "topic_type_uri" and "assoc_def" arguments to determine which widget has fired.
Actually the event is fired by the Checkbox (multi) renderer and the (simple) TextRenderer? (see Webclient's /script/renderers).
The option_topics event allows a plugin to provide the set of options displayed in a checkbox list or combobox. Each option is a topic. Hence the name "option_topics".

i am asking since i am unable to register this listener on dm4-snapshot of today.

What is your problem exactly? How looks your code like?

[Malte]

Thanks, now I understand the behaviour better.

The "option_topics" event is fired each time a checkbox list widget or a
combobox widget is rendered in the page panel (when it is in Edit mode

And the problem seems clearer to me, since i never had a "Checkbox Renderer" explicitly declared in the model of my applications, it makes sense to me that my listener is never called.

But now i am curious what made the change happen, since (as described here ​http://redmine.eduzen.tu-berlin.de/issues/228 ) the Checkbox Renderer was already working (magically) for users, and now there is a multi-composite (add/remove) form-module at its place, as described behind the link.

[Malte]

It turns out that locally, my application plugins where not available/installed (after a cleared out pom) and that caused (out of some reason) the default renderer to be used (instead of the customly set "dm4.webclient.checkbox_renderer").

With all my plugins available, I can now write a filter-function showing just a subset for users to multiple-select from.

Thanks for your support.