Documentation des Web Services de Geoconcept Web  -  Le Kit de développement des widgets

Le fichier XML est un fichier de description du widget. Il est parsé par le moteur de widget pour en extraire les informations qui lui seront utiles et les renvoyer au client sous forme JSON. Ce fichier doit respecter les mêmes règles pour tous les widgets :

<widget id="geocoder"
        category="navigation"
        position="1"
    icon="images/geocoder.png"
    js="view/GeocoderWidget.js"
    module="geoconcept-widget-geocoder"
    display="true"
        groups="Standard"
        lang="resources/widgets">
</widget>

Il est possible d’ajouter des propriétés pour configurer le widget dans le Composer dans le fichier XML. En fonction de ce qui est renseigné, les propriétés sont automatiquement générées dans la fenêtre de configuration des widgets du Composer.

Le label de la propriété affichée est structuré ainsi, "widget." + id du widget + "." + id de la propriété. La valeur à ajouter dans le fichier properties est par exemple "widget.geocoder.mode=Mode d’affichage".

Le champ params permet de déterminer une valeur par défaut à la propriété :

<widget id="geocoder"
                category="navigation"
                position="1"
                icon="resources/images/Geocode_32.png"
                js="navigation/GeocoderWidget.js"
                module="geoconcept-widget-geocoder"
                display="true"
                groups="Standard"
                lang="resources/widgets">
        <properties>
                <property id="mode" type="radiobutton-2">
                        <params value="0"/>
                </property>
        </properties>
</widget>

Voici la liste des propriétés disponibles pour les widgets :

<property id="checkboxProperty" type="checkbox">
        <params value="true"/>
</property>

<property id="textProperty" type="text">
        <params value="default text"/>
</property>

<property id="sliderProperty" type="slider">
        <params min="1" max="12" value="6"/>
</property>

<property id="colorpickerProperty" type="colorpicker">
        <params value="#ffffff"/>
</property>

<property id="comboboxProperty" type="combobox">
        <params value="comboboxValueName"/>
</property>

<property id="datagridProperty" type="datagrid">
        <params value="datagridValueName"/>
</property>

<property id="radiobuttonProperty" type="radiobutton-2">
        <params value="0"/>
</property>

<property id="checkbox2Property" type="checkbox-2">
        <params value="0"/>
</property>

Chacune de ces propriétés peut ensuite être utilisées dans le widget en utilisant la méthode getPropertyValue (voir l'API des widgets).

Un ensemble de catégories sont définies dans un fichier de configuration du projet EasyGeowebCategories.xml. Chaque widget est dépendant d’une de ces catégories. Pour ce faire le widget doit être placé dans un répertoire comportant le nom d’une catégorie. Exemple: notre widget geocode est placé dans navigation/Distance.js, ainsi il appartient à la catégorie navigation. Le widget distance est placé dans measure/Distance.js donc il appartient à la catégorie measure.

Il est possible d’ajouter de nouvelles catégories dans EasyGeowebCategories.xml. Pour cela il suffit d’ajouter une balise entry. key permet de définir le positionnement dans l’affichage de l’accordéon.

<properties>
        <entry key="0">layout</entry>
        <entry key="1">general</entry>
        <entry key="2">navigation</entry>
        <entry key="3">view</entry>
        <entry key="4">measure</entry>
        <entry key="5">annotation</entry>
        <entry key="6">data</entry>
        <entry key="7">modification</entry>
</properties>

Le nom de la catégorie permet de gérer son internationalisation. Par exemple, pour une nouvelle catégorie nommée graphic, il faudra ajouter la clé suivante dans easy.properties

accordion.category.graphic = graphique

Le fichier JavaScript est le fichier source du widget. Celui-ci sera chargé par la combo pour être injecté dans le client. Voici le squelette d’un fichier source :

YUI.add("module-name", function(Y) {

        function WidgetClassName(config) {
        WidgetClassName.superclass.constructor.apply(this, arguments);
        }

        WidgetClassName.NAME = "WidgetClassName";

        Y.extend(WidgetClassName, Y.GCUI.WidgetBase,  {
            initializer: function(config) {
            },

            destructor: function() {
            },

            getWidget: function() {
                // return html description widget
            },

            configureAction: function() {
                WidgetClassName.superclass.configureAction.apply(this);

                // some actions
            }

        });
        Y.namespace("GCUI");
        Y.GCUI.WidgetClassName = WidgetClassName;

}, "1.0.0", {requires: ["project-widgetbase"] });

La fonction getWidget() sera appelée dans un premier temps par le WidgetManager (client) pour afficher le widget. Ainsi cette méthode renvoie la représentation du widget. Elle peut contenir tout ce que le développeur désire afficher. La seule contrainte est de rester dans une balise HTML <div></div>. En effet le widget ne sera affiché que s’il est contenu dans cette balise.

WidgetBase permet d’afficher des TreeView, des listbox, des combobox etc.

La fonction configureAction() sera appelée par le WidgetManager pour configurer le widget une fois celui-ci inséré dans le DOM. WidgetBase propose un série de fonction de base formant l'API des widgets. Ainsi tous les widgets ont accès à la carte, au détail du projet mais aussi à un panel que l’on peut utiliser pour y afficher diverses informations.

Tous les widgets héritant de WidgetBase possèdent des propriétés par défaut : Affichage de l'étiquette, label de l'étiquette et affichage d’un séparateur d'étiquette.

Cette partie la section intitulée « Widgets par l’exemple » ainsi que le tutorial présente des cas concrets d’utilisation des méthodes du WidgetBase.

WidgetButton fonctionne de la même façon que WidgetBase, il suffit d’hériter de cette classe et de mettre le « requires project-widgetbutton ».

Il existe 3 types de boutons à définir dans initializer() :

Voici le squelette d’un WidgetButton

YUI.add("geoconcept-widget-button", function(Y) {

        function SchemaButton(config) {
                SchemaButton.superclass.constructor.apply(this, arguments);
        }

        SchemaButton.NAME = "schemaButton";

        Y.extend(SchemaButton, Y.GCUI.WidgetButton,  {
                initializer: function(config) {
                        SchemaButton.superclass.initializer.apply(this);
                        this.setType(Y.GCUI.WidgetButton.TYPE_TOOL);
                },

                destructor: function() {
                        SchemaButton.superclass.destructor.apply(this);
                },

                configureAction: function() {
                        SchemaButton.superclass.configureAction.apply(this);
                },

                // Button type action
                trigger:function() {
                        SchemaButton.superclass.trigger.apply();
                        // some actions
            },

                // Toggle and tool type action
                activate:function() {
                        SchemaButton.superclass.activate.apply();
                        // some actions
            },

            // Toggle and tool type action
            deactivate:function() {
                SchemaButton.superclass.deactivate.apply();
            }

        });
        Y.namespace("GCUI");
        Y.GCUI.SchemaButton = SchemaButton;

}, "1.0.0", {requires: ["project-widgetbutton"] });

Tous les widgets héritant de WidgetButton possèdent des propriétés par défaut : Affichage de l'étiquette, label de l'étiquette et widget par défaut s’il s’agit d’un bouton de type toggle ou tool.

L’ensemble des méthodes de WidgetBase sont réutilisables dans WidgetButton.

Ce widget permet de déplacer la carte. Il est de type bouton donc héritera de la classe WidgetButton.

YUI.add("geoconcept-widget-hand", function(Y) {

        /* Hand class constructor */
        function Hand(config) {
                Hand.superclass.constructor.apply(this, arguments);
        }

        /*
         * Required NAME static field, to identify the Widget class and
         * used as an event prefix, to generate class names etc. (set to the
         * class name in camel case).
         */
        Hand.NAME = "hand";

        Y.extend(Hand, Y.GCUI.WidgetButton,  {
                initializer: function(config) {
                        Hand.superclass.initializer.apply(this);
                        this.setType(Y.GCUI.WidgetButton.TYPE_TOOL);
                },

                destructor: function() {
                        Hand.superclass.destructor.apply(this);
                },

                configureAction: function() {
                        Hand.superclass.configureAction.apply(this);
                },

                activate:function() {
                        Hand.superclass.activate.apply();
                        var map = this.getMap();

                        DynMapSetMouseMode(map,DynMapMoveSelectionMode());
            },

            deactivate:function() {
                Hand.superclass.deactivate.apply();
            }

        });
        Y.namespace("GCUI");
        Y.GCUI.Hand = Hand;

}, "1.0.0", {requires: ["project-widgetbutton"] });

Ce widget reprend l’exemple standard décrit plus haut. La méthode activate() permet au widget d’appeler la méthode de l’API Javascript pour activer le mode de déplacement de la carte.

Voici son fichier de description XML :

<widget id="hand"
                icon="resources/images/hand.png"
                js="navigation/Hand.js"
                module="geoconcept-widget-hand"
                display="true"
                lang="resources/widgets">
</widget>

Le nom du module correspond à celui définit dans le fichier source. De plus on peut remarquer que le widget se trouvera dans la catégorie position de l’accordion.

Ce widget permet de mesurer des surfaces.

YUI.add("geoconcept-widget-measure-area", function(Y) {

        [...]

        Y.extend(MeasureArea, Y.GCUI.MeasureBase,  {

                [...]

            /**
             * Manage widget action
             */
                activate:function() {
                        MeasureArea.superclass.activate.apply(this,[this.getCallbacks()]);
                        this.createPanelMeasure();
                        this.showPanel();
                },

                deactivate:function() {
                        MeasureArea.superclass.deactivate.apply(this);
                },

                /**
                 * Manage default panel
                 */
                // Create panel for area information
                createPanelMeasure:function() {
                var panelNode = this.createPanel(this._("widget.measureArea.popup.title"));
                        var id = this.getPanelId();

                var areaInfo = Y.Node.create("<div id='" + id + "' class='areaMeasure'></div>");
                areaInfo.append("<div class='areaSegmentTitle'>" + this._("widget.measureArea.segment.measure") + "</div>");
                areaInfo.append("<div id='" + MeasureArea.ID_PANEL_SEGMENT_MEASURE + id + "' class='areaSegmentValue'>0.000 " + this._("widget.measureArea.segment.kilometer") + "<sup>2</sup></div>");

                        panelNode.appendChild(areaInfo);
            }
        });
        Y.namespace("GCUI");
        Y.GCUI.MeasureArea = MeasureArea;

}, "1.0.0", {requires: ["geoconcept-widget-measure-base"] });

Ce widget étend Y.GCUI.MeasureBase utilisant le Control OpenLayers de mesure, OpenLayers.Control.Measure Ce widget utilise le panel pour afficher son résultat.

Le widget layers n’est pas un bouton mais affiche un TreeView sur un div donné.

YUI.add("geoconcept-widget-layers", function(Y) {

        [...]

        Y.extend(Layers, Y.GCUI.LayersBase, {

                [...]

                configureAction : function() {
                        Layers.superclass.configureAction.apply(this);

                        if (!this.isExistingLayers) {
                                var yuiNode = Y.one("#"+this.getId());
                                if (!this.isPortal()) {
                                        yuiNode.setContent(this.getWrapper());
                }
                                var map = this.getMap();
                                var wLayers = this;
                                var options = {
                                        div : document.getElementById(this.getId())
                                };
                                var ls = new GCUI.Control.LayerSwitcher(options);
                                map.addControl(ls);

                                var json = this.initJson();
                                ls.initFromJson(json);

                                yuiNode.addClass("addedWidget");

                                if (this.isPortal()) {
                        var layers = map.layers;
                                        for (var i = 0; i < layers.length; i++) {
                                                var layer = layers[i];
                                                layer.events.on({
                                    "visibilitychanged" : wLayers.layerChangeVisibility,
                                    scope : wLayers
                                });
                                        }
                                        this.showLegends(layers);
                }
                        }
                },

                [...]

        });
        Y.namespace("GCUI");
        Y.GCUI.Layers = Layers;

}, "1.0.0", {requires : ["geoconcept-widget-layers-base"] });

Ce widget étend Y.GCUI.LayersBase qui étend lui même Y.GCUI.WidgetBase. Le TreeView est généré par GCUI.Control.LayerSwitcher. Il affiche la liste des couches à afficher dans un JSON.

Ce widget a la particularité d’utiliser des propriétés, ces propriétés sont définies dans son fichier de description XML :

<widget id="contact"
                icon="resources/images/contact.png"
                js="general/Contact.js"
                module="geoconcept-widget-contact"
                display="true"
                lang="resources/widgets">
        <properties>
                <property id="mailContact" type="text"/>
        </properties>
</widget>

Depuis le client il sera donc possible de déterminer l’adresse mail dans un champ texte.

Le fichier source prend en compte ces propriétés qui lui sont injectées en JSON par le client. En effet, le moteur de widgets va lire le fichier XML du widget, injecter le JSON correspondant au client qui créera une instance du widget et le client se chargera d’instancier le widget avec le descriptif JSON. Ce descriptif JSON est setté à l’instance. A chaque changement d’une des valeurs des propriétés, le JSON est mis à jour. Lors de la sauvegarde du builder, le fichier JSON de chaque instance est récupéré pour être ensuite sauvegardé par le builder. (cf partie client)

Voici le code source du widget :

YUI.add("geoconcept-widget-contact", function(Y) {

        [...]

        Contact.MAIL_CONTACT_PROPERTY = "mailContact"

        [...]

        Y.extend(Contact, Y.GCUI.WidgetButton,  {

                [...]

                configureAction: function() {
                        Contact.superclass.configureAction.apply(this);
                        var defaultMail = this.getPropertyValue(Contact.MAIL_CONTACT_PROPERTY);
                        if (defaultMail == undefined || defaultMail == "") {
                                this.updatePropertyValue(Contact.MAIL_CONTACT_PROPERTY, this.getParameters().contact);
                        }
                },

                trigger: function() {
                        window.location = "mailto:" + this.getPropertyValue(Contact.MAIL_CONTACT_PROPERTY);
                }

        });
        Y.namespace("GCUI");
        Y.GCUI.Contact = Contact;

}, "1.0.0", {requires: ["project-widgetbutton"] });

La partie importante ici est la gestion des properties. En parsant le fichier XML, le moteur de widgets va appeler la addProperties() lors de la sélection de l’instance dans l’outil de conception si le widget possède des propriétés. updatePropertyValue() est utilisée ici pour mettre à jour la valeur de la propriété dans le JSON. Il sera ensuite sauvegardé dans la description du projet puis stocké dans la base de données.