[Commits] r2680 - sandbox/mapgears/geoext.ux/ux/WFSTFeatureEditing/lib/GeoExt.ux/widgets
commits at geoext.org
commits at geoext.org
Thu May 12 20:07:30 CEST 2011
Author: adube
Date: 2011-05-12 20:07:30 +0200 (Thu, 12 May 2011)
New Revision: 2680
Modified:
sandbox/mapgears/geoext.ux/ux/WFSTFeatureEditing/lib/GeoExt.ux/widgets/WFSTFeatureEditingManager.js
sandbox/mapgears/geoext.ux/ux/WFSTFeatureEditing/lib/GeoExt.ux/widgets/WFSTFeatureEditingStatusBar.js
Log:
WFSTFeatureEditing - api documentation
Modified: sandbox/mapgears/geoext.ux/ux/WFSTFeatureEditing/lib/GeoExt.ux/widgets/WFSTFeatureEditingManager.js
===================================================================
--- sandbox/mapgears/geoext.ux/ux/WFSTFeatureEditing/lib/GeoExt.ux/widgets/WFSTFeatureEditingManager.js 2011-05-12 14:58:03 UTC (rev 2679)
+++ sandbox/mapgears/geoext.ux/ux/WFSTFeatureEditing/lib/GeoExt.ux/widgets/WFSTFeatureEditingManager.js 2011-05-12 18:07:30 UTC (rev 2680)
@@ -1,5 +1,26 @@
+/**
+ * Copyright (c) 2008-2011 The Open Source Geospatial Foundation
+ *
+ * Published under the BSD license.
+ * See http://svn.geoext.org/core/trunk/geoext/license.txt for the full text
+ * of the license.
+ */
+
Ext.namespace("GeoExt.ux");
+/*
+ * @requires GeoExt.ux/FeatureEditorGrid.js
+ * @requires gxp/grid/FeatureGrid.js
+ */
+
+/** api: (define)
+ * module = GeoExt.ux
+ * class = WFSTFeatureEditingManager
+ */
+
+/** api: constructor
+ * .. class:: WFSTFeatureEditingManager
+ */
GeoExt.ux.WFSTFeatureEditingManager = Ext.extend(Ext.util.Observable, {
/* CONSTANT */
@@ -13,105 +34,233 @@
"commitfail"
],
+ /** private: property[DEFAULT_CAPABILITIES_PARAMS]
+ * ``Object`` Hash of default parameters used for WFS GetCapabilities
+ * requests.
+ */
DEFAULT_CAPABILITIES_PARAMS: {
'SERVICE': "WFS",
'REQUEST': "GetCapabilities",
'VERSION': "1.0.0"
},
+ /** private: property[DEFAULT_DESCRIBE_FEATURETYPE_PARAMS]
+ * ``Object`` Hash of default parameters used for WFS DescribeFeatureType
+ * requests.
+ */
DEFAULT_DESCRIBE_FEATURETYPE_PARAMS: {
'SERVICE': "WFS",
'REQUEST': "DescribeFeatureType",
'VERSION': "1.0.0"
},
+ /** private: property[DEFAULT_PROTOCOL_OPTIONS]
+ * ``Object`` Hash of options to use when creating a new
+ * :class:`GeoExt.data.WFSCapabilitiesStore` object as the
+ * "protocolOptions" property default values.
+ */
DEFAULT_PROTOCOL_OPTIONS: {
featureNS: "http://localhost"
},
+ /** private: property[DEFAULT_LAYER_OPTIONS]
+ * ``Object`` Hash of options to use when creating a new
+ * :class:`GeoExt.data.WFSCapabilitiesStore` object as the
+ * "layerOptions" property default values. Used when
+ * this.useFilter is set to false.
+ */
DEFAULT_LAYER_OPTIONS: {
visibility: false,
displayInLayerSwitcher: false,
strategies: ["BBOX", "Save"]
},
+ /** private: property[DEFAULT_LAYER_OPTIONS_USE_FILTER]
+ * ``Object`` Hash of options to use when creating a new
+ * :class:`GeoExt.data.WFSCapabilitiesStore` object as the
+ * "layerOptions" property default values. Used when
+ * this.useFilter is set to true.
+ */
DEFAULT_LAYER_OPTIONS_USE_FILTER: {
visibility: false,
displayInLayerSwitcher: false,
strategies: ["Fixed", "Save"]
},
+ /** private: property[DEFAULT_ACTION_GROUP]
+ * ``String`` Default group value to use when creating
+ * :class:`GeoExt.Action` objects.
+ */
DEFAULT_ACTION_GROUP: "wfstFeatureEditing",
/* i18n */
+ /** api: config[drawMenuButtonText] ``String`` i18n */
drawMenuButtonText: "Draw",
+ /** api: config[drawMenuButtonTooltipText] ``String`` i18n */
drawMenuButtonTooltipText: "Add Tool: Select a layer from the list then " +
"digitalize a new feature by clicking on the map.",
+ /** api: config[editMenuButtonText] ``String`` i18n */
editMenuButtonText: "Edit",
+ /** api: config[editMenuButtonTooltipText] ``String`` i18n */
editMenuButtonTooltipText: "Edit Tool: Select a layer from the list then " +
"click on a feature on the map to edit it.",
+ /** api: config[featureGridContainerTitleText] ``String`` i18n */
featureGridContainerTitleText: "Features",
+ /** api: config[featureEditorGridContainerTitleText] ``String`` i18n */
featureEditorGridContainerTitleText: "Editing feature",
+ /** api: config[returnToSelectionText] ``String`` i18n */
returnToSelectionText: "Return to selection",
+ /** api: config[commitSuccessText] ``String`` i18n */
commitSuccessText: "Changes successfully saved",
+ /** api: config[commitFailText] ``String`` i18n */
commitFailText: "An error occured. The changes were not saved",
/* API */
+ /** api: property[toolbar]
+ * :class:`Ext.Toolbar` The toolbar where the two main
+ * :class:`Ext.Button` objects (draw and edit) are
+ * added. Mandatory.
+ */
toolbar: null,
+ /** api: config[url]
+ * ``String`` The url to the WFS service. Mandatory.
+ */
url: null,
+ /** api: config[map]
+ * :class:`OpenLayers.Map` A reference to the map object. Mandatory.
+ */
map: null,
+ /** api: config[mainPanelContainer]
+ * :class:`Ext.Panel` The main panel created by this widget is added to the
+ * mainPanelContainer. Mandatory.
+ */
mainPanelContainer: null,
+ /** api: config[capabilitiesParams]
+ * ``Object`` Hash of parameters for WFS GetCapabilities requests in
+ * addition or replacement to the ones in
+ * this.DEFAULT_CAPABILITIES_PARAMS.
+ */
capabilitiesParams: null,
+ /** api: config[describeFeatureTypeParams]
+ * ``Object`` Hash of parameters for WFS DescribeFeatureType requests in
+ * addition or replacement to the ones in
+ * this.DEFAULT_DESCRIBE_FEATURETYPE_PARAMS.
+ */
describeFeatureTypeParams: null,
+ /** api: config[protocolOptions]
+ * ``Object`` Hash of options to use when creating a new
+ * :class:`GeoExt.data.WFSCapabilitiesStore` object as the
+ * "protocolOptions" property values in addition or replacement
+ * to the ones in this.DEFAULT_PROTOCOL_OPTIONS.
+ */
protocolOptions: null,
+ /** api: config[layerOptions]
+ * ``Object`` Hash of options to use when creating a new
+ * :class:`GeoExt.data.WFSCapabilitiesStore` object as the
+ * "layerOptions" property values in addition or replacement
+ * to the ones in this.DEFAULT_LAYER_OPTIONS.
+ */
layerOptions: null,
+ /** api: config[geomProperty]
+ * ``String`` The name of the geometry property. Defaults to "the_geom".
+ */
geomProperty: "the_geom",
+ /** api: config[actionGroup]
+ * ``String`` "group" property value when creating new
+ * :class:`GeoExt.Action` objects. Defaults to
+ * this.DEFAULT_ACTION_GROUP.
+ */
actionGroup: null,
+ /** api: config[useFilter]
+ * ``Boolean`` Whether the "edit" tools should use a filter to get the
+ * vector features or not (all visible). Defaults to true.
+ */
useFilter: true,
+ /** api: config[ignoredAttributes]
+ * ``Object`` Hash of attributes we don't want the grids to display.
+ */
ignoredAttributes: {name:["the_geom", "id", "gid", "fid"]},
/* PRIVATE*/
+ /** private: property[mainPanel]
+ * :class:`Ext.Panel` The main panel of the widget.
+ */
mainPanel: null,
+ /** private: property[featureGridContainer]
+ * :class:`Ext.TabPanel` The panel used as a container for the
+ * :class:`gxp.grid.FeatureGrid`
+ */
featureGridContainer: null,
+ /** private: property[featureEditorGridContainer]
+ * :class:`Ext.Panel` The panel used as a container for the
+ * :class:`GeoExt.ux.FeatureEditorGrid`
+ */
featureEditorGridContainer: null,
- statusBar: null,
-
+ /** private: property[queries]
+ * ``Integer`` A query response counter.
+ */
queries: null,
+ /** private: property[layers]
+ * ``Array`` of :class:`OpenLayers.Layer.Vector` object that were created
+ * by the :class:`GeoExt.data.WFSCapabilitiesStore`. Each one
+ * is automatically added to the map.
+ */
layers: null,
+
+ /** api: property[toolbar]
+ * :class:`Ext.Toolbar` The toolbar where the two main
+ * :class:`Ext.Button` objects (draw and edit) are
+ * added. Mandatory.
+ */
+
+ /** private: property[drawMenuButton]
+ * :class:`Ext.Button` Button containing a :class:`Ext.menu.Menu` of
+ * layer names. When one is selected, it activates its
+ * :class:`OpenLayers.Control.DrawFeature`, thus
+ * enabling the addition of a new feature.
+ */
drawMenuButton: null,
+ /** private: property[editMenuButton]
+ * :class:`Ext.Button` Button containing a :class:`Ext.menu.Menu` of
+ * layer names. When one is selected, it activates its
+ * :class:`OpenLayers.Control.SelectFeature`, thus
+ * enabling the selection of an existing feature for
+ * edition. When this.useFilter is set to true, it
+ * activates the
+ * :class:`OpenLayers.Control.UserFilter` first.
+ */
editMenuButton: null,
/** private: method[constructor]
- * Private constructor override.
*/
constructor: function(config) {
Ext.apply(this, config);
@@ -123,6 +272,12 @@
this.url && this.createToolsFromURL(this.url);
},
+ /** private: method[initMainTools]
+ * Called by the constructor. Creates all static components that are not
+ * directly related to the WFS service (buttons, menus, statusbar,
+ * containers, etc.) Also add the main panel to the main panel
+ * container.
+ */
initMainTools: function() {
// === Draw and Edit toolbar buttons and Menus ===
this.drawMenuButton = new Ext.Button({
@@ -175,6 +330,12 @@
this.mainPanelContainer && this.mainPanelContainer.add(this.mainPanel);
},
+ /** private: method[initMainTools]
+ * Called by the constructor. Creates all dynamic components that are
+ * directly related to the WFS service (store, layers, controls, etc.)
+ * Everything is created asynchronously, except the
+ * :class:`GeoExt.data.WFSCapabilitiesStore` object.
+ */
createToolsFromURL: function(url) {
var wfsCapURL = Ext.urlAppend(url, Ext.urlEncode(Ext.applyIf(
this.capabilitiesParams || {}, this.DEFAULT_CAPABILITIES_PARAMS
@@ -203,6 +364,22 @@
wfsCapStore.load();
},
+ /** private: method[onWFSCapabilitiesStoreLoad]
+ * Callback method triggered on "load" of the
+ * :class:`GeoExt.data.WFSCapabilitiesStore` object. At this point,
+ * :class:`OpenLayers.Layer.Vector` object with their according
+ * :class:`OpenLayers.Protocol.WFS` protocols were created.
+ *
+ * For each created layer :
+ * - its "wfstFeatureEditing" hash property set, which is used to
+ * reference everything created by this widget that is related to
+ * the layer so that it can access any of its widget directly from
+ * itself.
+ * - it is added to the :class:`OpenLayers.Map`
+ * - a WFSDescribeFeatureType is triggered
+ * - try to get a WMS layer sibling in order to refresh it when
+ * transactions are made to the vector one.
+ */
onWFSCapabilitiesStoreLoad: function(store, records, options) {
var layers = [];
Ext.each(records, function(record, index) {
@@ -247,6 +424,17 @@
}, this);
},
+ /** private: method[onDescribeFeatureTypeSuccess]
+ * Callback method triggered when a WFS DescribeFeatureType request is
+ * is completed. The scope has a reference to the layer. Used for :
+ * - detection the geometry type from the geometry property to create
+ * the appropriate :class:`OpenLayers.Handler` for the
+ * :class:`OpenLayers.Control.DrawFeature`.
+ * - creation a field for each property (currently without any form of
+ * type detection).
+ *
+ * When all requests were received, trigger the createEditingTools method.
+ */
onDescribeFeatureTypeSuccess: function(response) {
var format = new OpenLayers.Format.WFSDescribeFeatureType();
format.setNamespace("xsd", "http://www.w3.org/2001/XMLSchema");
@@ -303,10 +491,20 @@
}
},
- onDescribeFeatureTypeFailure: function(response) {
- //todo
- },
+ /** private: method[onDescribeFeatureTypeFailure]
+ * Callback method triggered when a WFS DescribeFeatureType request has
+ * failed.
+ */
+ onDescribeFeatureTypeFailure: function(response) {},
+ /** private: method[createEditingTools]
+ * Calls the createEditingToolsForLayer method for each layer, then
+ *
+ * When all requests were received, trigger the createEditingTools method,
+ * redo the layout of the toolbar (because items added after it was
+ * rendered don't appear unless doing so) and reset query related
+ * elements.
+ */
createEditingTools: function() {
Ext.each(this.layers, function(layer, index) {
this.createEditingToolsForLayer(layer);
@@ -315,6 +513,22 @@
this.resetAll();
},
+ /** private: method[createEditingToolsForLayer]
+ * :param layer :class:`OpenLayers.Layer.Vector` The vector layer.
+ *
+ * Creates all editing tools and event listeners for this layer :
+ * - draw control and action (added to the draw menu)
+ * - select feature control for select purpose
+ * - select feature control for highlight on mouse hover purpose
+ * - select feature action (added to the draw menu)
+ * - feature grid, used to contain all features (or all filtered
+ * features if this.useFilter is set to true)
+ * - feature editor grid, used to edit the currently selected feature
+ * attributes
+ *
+ * If this.useFilter is set to true :
+ * - user filter control for "GetFeature" purpose
+ */
createEditingToolsForLayer: function(layer) {
// ======================
@@ -531,11 +745,23 @@
layer.wfstFeatureEditing.featureGrid = featureGrid
},
+ /** private: method[resetAll]
+ * Reset all query related elements. Doesn't destroy anything.
+ */
resetAll: function() {
+ // todo: if we want to support more than one WFS service, we could have
+ // an other property to keep all layers created by this widget and
+ // keep this one for "current service only".
this.layers = [];
this.queries = 0;
},
+ /** private: method[getWMSLayerSibling]
+ * :param layer :class:`OpenLayers.Layer.Vector` A vector layer.
+ * :return: :class:`OpenLayers.Layer.WMS`
+ *
+ * Using a vector layer, try to find a WMS one having the same name
+ */
getWMSLayerSibling: function(layer) {
var wmsLayerSibling;
Ext.each(this.map.getLayersByName(layer.name), function(layerSibling) {
@@ -547,6 +773,17 @@
return wmsLayerSibling;
},
+ /** private: method[getNewFeatureEditorGrid]
+ * :param feature :class:`OpenLayers.Feature.Vector` A vectore feature.
+ * :param layer :class:`OpenLayers.Layer.Vector` A vector layer.
+ * :return: :class:`GeoExt.ux.FeatureEditorGrid`
+ *
+ * Using a vector layer and a vector feature, create and return a new
+ * :class:`GeoExt.ux.FeatureEditorGrid` object with 'done', 'cancel'
+ * and store 'load' event listeners to respectively "save" or "cancel"
+ * changes made to a feature and focus on the first attribute cell
+ * upon edition starting.
+ */
getNewFeatureEditorGrid: function(feature, layer) {
var featureEditorGrid = new GeoExt.ux.FeatureEditorGrid({
nameField: "name",
@@ -578,6 +815,13 @@
return featureEditorGrid;
},
+ /** private: method[getNewAttributeStore]
+ * :param feature :class:`OpenLayers.Feature.Vector` A vectore feature.
+ * :return: :class:`GeoExt.data.AttributeStore`
+ *
+ * Using a vector feature and the DescribeFeatureType parameters, create
+ * and return a new :class:`GeoExt.data.AttributeStore` object.
+ */
getNewAttributeStore: function(feature) {
var params = Ext.applyIf(Ext.applyIf(
this.describeFeatureTypeParams || {},
@@ -592,6 +836,18 @@
});
},
+ /** private: method[getNewFeatureGrid]
+ * :param layer :class:`OpenLayers.Layer.Vector` A vector layer.
+ * :return: :class:`gxp.grid.FeatureGrid`
+ *
+ * Using a vector layer, create and return a new
+ * :class:`gxp.grid.FeatureGrid` object used to have complete list of
+ * the vector features currently visible on the map (from the vector
+ * layer).
+ *
+ * Also, if this.useFilter is set to true, some listeners are added as
+ * well for various purposes.
+ */
getNewFeatureGrid: function(layer) {
var store = this.getNewFeatureStore(layer);
var featureGrid = new gxp.grid.FeatureGrid({
@@ -601,6 +857,7 @@
layer: layer,
store: store,
cls: "geoextux-wfstfeatureediting-featuregrid",
+ // todo: create a public property for this
ignoreFields: ["the_geom"],
bbar: this.useFilter ? this.getNewFeatureGridToolbar(layer) : null,
sm: new GeoExt.grid.FeatureSelectionModel({
@@ -647,6 +904,15 @@
return featureGrid;
},
+ /** private: method[getNewFeatureGridToolbar]
+ * :param layer :class:`OpenLayers.Layer.Vector` A vector layer.
+ * :return: :class:`Ext.Toolbar`
+ *
+ * Using a vector layer, create and return a new
+ * :class:`Ext.Toolbar` object containing a button that, on click,
+ * returns to the selection mode. Only used when this.useFilter is
+ * set to true.
+ */
getNewFeatureGridToolbar: function(layer) {
return new Ext.Toolbar({
"items": ["->", new Ext.Action({
@@ -659,6 +925,12 @@
});
},
+ /** private: method[returnToSelection]
+ * :param layer :class:`OpenLayers.Layer.Vector` A vector layer.
+ *
+ * Only used when this.useFilter is set to true. Returns to the selection
+ * using the filter mode.
+ */
returnToSelection: function(layer) {
layer.wfstFeatureEditing.selectControl.unselectAll();
layer.wfstFeatureEditing.highlightControl.deactivate();
@@ -666,6 +938,13 @@
this.toggleMainPanelContainer(false);
},
+ /** private: method[returnToSelection]
+ * :param layer :class:`OpenLayers.Layer.Vector` A vector layer.
+ * :return: :class:`GeoExt.data.FeatureStore`
+ *
+ * Using a vector layer, create a new :class:`GeoExt.data.FeatureStore`
+ * object with its features as records.
+ */
getNewFeatureStore: function(layer) {
return new GeoExt.data.FeatureStore({
fields: layer.wfstFeatureEditing.fields,
@@ -675,6 +954,12 @@
});
},
+ /** private: method[cancelEditing]
+ * :param layer :class:`OpenLayers.Layer.Vector` A vector layer.
+ *
+ * Discard all changes from the feature of the editor grid store, close
+ * the editor grid and destroy the feature if it had an 'insert' state.
+ */
cancelEditing: function(layer) {
if (layer.wfstFeatureEditing.editorGrid) {
var feature = layer.wfstFeatureEditing.editorGrid.store.feature;
@@ -687,6 +972,14 @@
}
},
+ /** private: method[cancelEditing]
+ * :param layer :class:`OpenLayers.Layer.Vector` A vector layer.
+ * :param options ``Object`` A hash of options
+ *
+ * Destroy all elements from editor grid container, unselect all features
+ * and check if we should return to selection (only used when
+ * this.useFilter is set to true).
+ */
closeEditing: function(layer, options) {
options = options || {};
// avoid reentrance
@@ -704,6 +997,12 @@
}
},
+ /** private: method[commitFeature]
+ * :param feature :class:`OpenLayers.Feature.Vector` A vector feature
+ *
+ * Calls the :class:`OpenLayers.Strategy.Save` object 'save' method with
+ * current feature.
+ */
commitFeature: function(feature) {
if (feature.state != null) {
this.fireEvent('commitstart');
@@ -711,6 +1010,16 @@
}
},
+ /** private: method[onCommitSuccess]
+ * :param e ``Object`` Request response
+ *
+ * Callback method when a "success" event is triggered by the
+ * :class:`OpenLayers.Strategy.Save` linked to a layer :
+ * - fires a "commitsuccess" event
+ * - redraw the WMS layer sibling (if any)
+ * - cancel editing (just to return to selection, doesn't actually
+ * "cancels" anything).
+ */
onCommitSuccess: function(e) {
this.manager.fireEvent('commitsuccess', e);
var wfstFE = this.layer.wfstFeatureEditing;
@@ -738,10 +1047,24 @@
}
},
+ /** private: method[onCommitFail]
+ * :param e ``Object`` Request response
+ *
+ * Callback method when a "fail" event is triggered by the
+ * :class:`OpenLayers.Strategy.Save` linked to a layer. Fires a
+ * "commitfail" event.
+ */
onCommitFail: function(e) {
this.manager.fireEvent('commitfail', e);
},
+ /** private: method[toggleMainPanelContainer]
+ * :param display ``Boolean`` Whether to display the panel or not
+ *
+ * Utility method to display the main panel by detecting the type of its
+ * container. If it's a window, it's shown/hidden. If it's a panel
+ * with accordion layout, it's expanded/collapsed.
+ */
toggleMainPanelContainer: function(display) {
var ct = this.mainPanel.ownerCt;
if (ct instanceof Ext.Window) {
Modified: sandbox/mapgears/geoext.ux/ux/WFSTFeatureEditing/lib/GeoExt.ux/widgets/WFSTFeatureEditingStatusBar.js
===================================================================
--- sandbox/mapgears/geoext.ux/ux/WFSTFeatureEditing/lib/GeoExt.ux/widgets/WFSTFeatureEditingStatusBar.js 2011-05-12 14:58:03 UTC (rev 2679)
+++ sandbox/mapgears/geoext.ux/ux/WFSTFeatureEditing/lib/GeoExt.ux/widgets/WFSTFeatureEditingStatusBar.js 2011-05-12 18:07:30 UTC (rev 2680)
@@ -1,5 +1,21 @@
+/**
+ * Copyright (c) 2008-2011 The Open Source Geospatial Foundation
+ *
+ * Published under the BSD license.
+ * See http://svn.geoext.org/core/trunk/geoext/license.txt for the full text
+ * of the license.
+ */
+
Ext.namespace("GeoExt.ux");
+/*
+ * @requires Ext.ux/StatusBar.js
+ */
+
+/** api: (define)
+ * module = GeoExt.ux
+ * class = WFSTFeatureEditingStatusBar
+ */
if (Ext.ux.StatusBar) {
/** api: constructor
More information about the Commits
mailing list