Merge pull request #4894 from camptocamp/metadata-docs

Add visible documentation about metadata and functionnalities

contribs/gmf/src/backgroundlayerselector/component.js

@@ -59,10 +59,14 @@ function gmfBackgroundlayerselectorTemplateUrl($element, $attrs, gmfBackgroundla
  *        gmf-backgroundlayerselector-select="onBackgroundSelected()">
  *      </gmf-backgroundlayerselector>
  *
- * Used UI metadata:
+ * Used metadata:
  *
  *  * thumbnail: The URL used for the icon.
  *
+ * Used functionnalities:
+ *
+ *  * default_basemap: Base maps to use by default.
+ *
  * @htmlAttribute {import("ol/Map.js").default=} gmf-backgroundlayerselector-map The map.
  * @htmlAttribute {string} gmf-backgroundlayer-opacity-options The opacity slider options.
  * @htmlAttribute {Function} gmf-backgroundlayerselector-select Function called

contribs/gmf/src/controllers/AbstractAppController.js

@@ -36,6 +36,7 @@ import {ThemeEventType} from 'gmf/theme/Manager.js';
 
 /**
  * A part of the application config.
+ *
  * @typedef {Object} Config
  * @property {number} srid
  * @property {import("ol/style/Style.js").default} [positionFeatureStyle]
@@ -55,6 +56,12 @@ import {ThemeEventType} from 'gmf/theme/Manager.js';
  * This file includes `goog.require` for base components/directives used
  * by the HTML page and the controller to provide the configuration.
  *
+ * Used functionnalities:
+ *
+ *  * open_panel: When set, contains the name of the panel to open upon loading an application.
+ *      Note: although this is a list, only one can be defined.
+ *
+ *
  * @param {Config} config A part of the application config.
  * @param {import('ol/Map.js').default} map The map.
  * @param {angular.IScope} $scope Scope.

contribs/gmf/src/datasource/Manager.js

@@ -44,19 +44,22 @@ import olSourceTileWMS from 'ol/source/TileWMS.js';
 
 
 /**
- * @hidden
+ * The GeoMapFish DataSources Manager is responsible of listenening to the
+ * c2cgeoportal's themes to create instances of `ngeo.datasource.DataSource`
+ * objects with the layer definitions found and push them in the
+ * `DataSources` collection. The Manager must be initialized
+ * with the app's map using the setDatasourcseMap() method.
+ *
+ * When changing theme, these data sources are cleared then re-created.
+ *
+ * Used metadata:
+ *
+ *  * identifierAttributeField: The field used in the 'display query window' as feature title.
+ *      For WMS layers.
  */
 export class DatasourceManager {
 
   /**
-   * The GeoMapFish DataSources Manager is responsible of listenening to the
-   * c2cgeoportal's themes to create instances of `ngeo.datasource.DataSource`
-   * objects with the layer definitions found and push them in the
-   * `DataSources` collection. The Manager must be initialized
-   * with the app's map using the setDatasourcseMap() method.
-   *
-   * When changing theme, these data sources are cleared then re-created.
-   *
    * @param {angular.IQService} $q Angular q service
    * @param {!angular.IScope} $rootScope Angular rootScope.
    * @param {angular.ITimeoutService} $timeout Angular timeout service.

contribs/gmf/src/disclaimer/component.js

@@ -38,9 +38,11 @@ function forEachDisclaimer(layer, func) {
 
 
 /**
- * @constructor
- * @private
- * @hidden
+ * Used metadata:
+ *
+ *  * disclaimer: The disclaimer text for this element.
+ *      For WMS and WMTS layers, layer groups and themes.
+ *
  * @param {!JQuery} $element Element.
  * @param {!angular.ISCEService} $sce Angular sce service.
  * @param {!angular.ITimeoutService} $timeout Angular timeout service.
@@ -53,7 +55,7 @@ function forEachDisclaimer(layer, func) {
  * @ngdoc controller
  * @ngname GmfDisclaimerController
  */
-function Controller(
+function DisclamerController(
   $element, $sce, $timeout, gettextCatalog, ngeoDisclaimer, ngeoEventHelper, ngeoLayerHelper
 ) {
 
@@ -147,7 +149,7 @@ function Controller(
 /**
  * Initialise the controller.
  */
-Controller.prototype.$onInit = function() {
+DisclamerController.prototype.$onInit = function() {
   this.layerVisibility = this.layerVisibility !== undefined ? this.layerVisibility : true;
 
   this.dataLayerGroup_ = this.ngeoLayerHelper_.getGroupFromMap(this.map, DATALAYERGROUP_NAME);
@@ -158,7 +160,7 @@ Controller.prototype.$onInit = function() {
  * @param {import("ol/Collection.js").CollectionEvent} evt Event.
  * @private
  */
-Controller.prototype.handleLayersAdd_ = function(evt) {
+DisclamerController.prototype.handleLayersAdd_ = function(evt) {
   this.timeout_(() => {
     const layer = evt.element;
     console.assert(layer instanceof olLayerBase);
@@ -171,7 +173,7 @@ Controller.prototype.handleLayersAdd_ = function(evt) {
  * @param {import("ol/Collection.js").CollectionEvent} evt Event.
  * @private
  */
-Controller.prototype.handleLayersRemove_ = function(evt) {
+DisclamerController.prototype.handleLayersRemove_ = function(evt) {
   const layer = evt.element;
   console.assert(layer instanceof olLayerBase);
   this.unregisterLayer_(layer);
@@ -182,7 +184,7 @@ Controller.prototype.handleLayersRemove_ = function(evt) {
  * @param {import("ol/layer/Base.js").default} layer Layer.
  * @private
  */
-Controller.prototype.registerLayer_ = function(layer) {
+DisclamerController.prototype.registerLayer_ = function(layer) {
 
   const layerUid = olUtilGetUid(layer);
 
@@ -250,7 +252,7 @@ Controller.prototype.registerLayer_ = function(layer) {
  * @param {import("ol/layer/Base.js").default} layer Layer.
  * @private
  */
-Controller.prototype.unregisterLayer_ = function(layer) {
+DisclamerController.prototype.unregisterLayer_ = function(layer) {
 
   const layerUid = olUtilGetUid(layer);
 
@@ -273,7 +275,7 @@ Controller.prototype.unregisterLayer_ = function(layer) {
 };
 
 
-Controller.prototype.$onDestroy = function() {
+DisclamerController.prototype.$onDestroy = function() {
   this.unregisterLayer_(this.dataLayerGroup_);
 };
 
@@ -282,7 +284,7 @@ Controller.prototype.$onDestroy = function() {
  * @param {string} msg Disclaimer message.
  * @private
  */
-Controller.prototype.showDisclaimerMessage_ = function(msg) {
+DisclamerController.prototype.showDisclaimerMessage_ = function(msg) {
   msg = this.gettextCatalog_.getString(msg);
   if (this.external) {
     if (this.msgs_.indexOf(msg) < 0) {
@@ -305,7 +307,7 @@ Controller.prototype.showDisclaimerMessage_ = function(msg) {
  * @param {string} msg Disclaimer message.
  * @private
  */
-Controller.prototype.closeDisclaimerMessage_ = function(msg) {
+DisclamerController.prototype.closeDisclaimerMessage_ = function(msg) {
   msg = this.gettextCatalog_.getString(msg);
   if (this.external) {
     this.visibility = false;
@@ -374,7 +376,7 @@ Controller.prototype.closeDisclaimerMessage_ = function(msg) {
  * @ngname gmfDisclaimer
  */
 const disclaimerComponent = {
-  controller: Controller,
+  controller: DisclamerController,
   bindings: {
     'layerVisibility': '<?gmfDisclaimerLayerVisibility',
     'popup': '<?gmfDisclaimerPopup',

contribs/gmf/src/editing/Snapping.js

@@ -20,6 +20,7 @@ import olInteractionSnap from 'ol/interaction/Snap.js';
  * which allows the snapping to occur on other places where vector
  * features are drawn or modified.
  *
+ *
  * @constructor
  * @param {angular.IHttpService} $http Angular $http service.
  * @param {angular.IQService} $q The Angular $q service.

contribs/gmf/src/editing/editFeatureComponent.js

@@ -123,6 +123,16 @@ module.run(/* @ngInject */ ($templateCache) => {
  * In order to create a new feature, you use the "Draw" button and digitize
  * the feature on the map.
  *
+ * If no layers are editable the component will be hidden.
+ *
+ * Used metadata:
+ *
+ *  * enumeratedAttributes: List of attribute names which have enumerated attribute
+ *      values (for filters purpose). For WMS layers.
+ *  * snappingConfig: The snapping configuration for the leaf. If set, the leaf's layer is considered to be
+ *      "snappable", even if the config itself is empty.
+ *      Example of value: {'tolerance': 50, 'edge': false} For WMS layers.
+ *
  * Example:
  *
  *     <gmf-editfeature

contribs/gmf/src/filters/filterselectorComponent.js

@@ -73,10 +73,21 @@ function gmfFilterselectorTemplateUrl($attrs, gmfFilterselectorTemplateUrl) {
 
 
 /**
- * @private
- * @hidden
+ * FilterSelector Controller
+ *
+ * Used metadata:
+ *
+ *  * directedFilterAttributes: List of attribute names which should have rules
+ *      already ready when using the filter tools. For WMS layers.
+ *
+ * Used functionnalities:
+ *
+ *  * preset_layer_filter: Name of the layer (data source) that should be toggled in the filter tool upon
+ *      loading an application.
+ *      Note: although this is a list, only one can be defined.
+ *  * filterable_layers: A list of layer names that can be filtered, if empty the component will be hidden.
  */
-class Controller {
+class FilterSelectorController {
 
   /**
    * @param {!angular.IScope} $scope Angular scope.
@@ -709,13 +720,15 @@ class Controller {
  * @property {Array.<import('ngeo/rule/Rule.js').default>} customRules
  * @property {Array.<import('ngeo/rule/Rule.js').default>} directedRules
  */
+
+
 module.component('gmfFilterselector', {
   bindings: {
     active: '=',
     map: '<',
     toolGroup: '<'
   },
-  controller: Controller,
+  controller: FilterSelectorController,
   templateUrl: gmfFilterselectorTemplateUrl
 });
 

contribs/gmf/src/layertree/TreeManager.js

@@ -29,6 +29,7 @@ import * as olEvents from 'ol/events.js';
  *
  * This service's theme is a GmfTheme with only children and a name.
  * Thought to be the tree source of the gmf layertree directive.
+ *
  * @constructor
  * @param {angular.ITimeoutService} $timeout Angular timeout service.
  * @param {angular.auto.IInjectorService} $injector Angular injector service.

contribs/gmf/src/layertree/component.js

@@ -129,14 +129,30 @@ function gmfLayertreeTemplate($element, $attrs, gmfLayertreeTemplate) {
  * metadata URLs in a new window. By default, and in the default template,
  * links will be opened in a popup (The window.openIframePopup function must be available !)
  *
- * Used UI metadata:
+ * Used metadata:
  *
  *  * isChecked: if 'false' the layer visibility will be set to false.
  *  * iconUrl: layer icon full URL.
  *  * legendRule: WMS rule used to get a layer icon.
  *  * isLegendExpanded: if 'true' the legend is expanded by default.
  *  * metadataUrl: Display a popup with the content of the given URL if
  *    possible also open a new window.
+ *  * exclusiveGroup: Whether the group contain children that have to be mutually
+ *      exclusive, meaning that only one child may be ON at any time.
+ *  * legend: Display the legend of this layers. For WMS and WMTS layers.
+ *  * legendImage: The URL to the image used as a legend in the layer tree. For WMS and WMTS layers.
+ *  * maxResolution: The max resolution where the layer is visible. For WMS layers.
+ *      On WMTS layers it will have effect on the node in the layertree but not on the layertree directly.
+ *  * minResolution: The min resolution where the layer is visible. For WMS layers.
+ *      On WMTS layers it will have effect on the node in the layertree but not on the layer directly.
+ *  * ogcServer: The corresponding OGC server for a WMTS layer. For WMTS layers.
+ *  * opacity: Layer opacity. 1.0 means fuly visible, 0 means invisible, For WMS and WMTS layers.
+ *  * timeAttribute: The name of the time attribute. For WMS(-T) layers.
+ *  * wmsLayers: A corresponding WMS layer for a WMTS layers. Used to query the WMTS layers and to print it.
+ *      (See also printLayers and queryLayers metadata for more granularity). For WMTS Layers.
+ *  * printLayers: A WMS layer that will be used instead of the WMTS layers in the print.
+ *  * queryLayers: The WMS layers used as references to query the WMTS layers. For WMTS layers.
+ *  * isExpanded: Whether the layer group is expanded by default. For layer groups (only).
  *
  * @htmlAttribute {import("ol/Map.js").default} gmf-layertree-map The map.
  * @htmlAttribute {Object<string, string>|undefined} gmf-layertree-dimensions Global dimensions object.

contribs/gmf/src/permalink/Permalink.js

@@ -245,6 +245,10 @@ const ParamPrefix = {
  * gmfThemeManager, defaultTheme, gmfTreeManager, ngeoWfsPermalink,
  * ngeoAutoProjection and ngeoFeatures.
  *
+ * Used functionnalities:
+ *
+ *  * default_theme: Theme to use by default.
+ *
  * @constructor
  * @param {!angular.IQService} $q The Angular $q service.
  * @param {angular.ITimeoutService} $timeout Angular timeout service.
@@ -259,7 +263,6 @@ const ParamPrefix = {
  * @ngInject
  * @ngdoc service
  * @ngname gmfPermalink
- * @hidden
  */
 export function PermalinkService(
   $q, $timeout, $rootScope, $injector, ngeoDebounce, gettextCatalog, ngeoEventHelper, ngeoStateManager,

contribs/gmf/src/print/component.js

@@ -194,6 +194,12 @@ function gmfPrintTemplateUrl($element, $attrs, gmfPrintTemplateUrl) {
  * Note: The 'print' and 'cancel' functions can also be called via globals
  * events 'gmfStartPrint' and 'gmfCancelPrint'.
  *
+ * Used metadata:
+ *
+ *  * hiDPILegendImages: The URLs to the hi DPI images used as a legend in the layer tree. For WMS and
+ *      WMTS layers.
+ *  * printNativeAngle: Whether the print should rotate the symbols. For layer groups (only).
+ *
  * @htmlAttribute {import("ol/Map.js").default} gmf-print-map The map.
  * @htmlAttribute {boolean} gmf-print-active A boolean that informs if the
  *     panel is open or not.
@@ -246,7 +252,7 @@ module.component('gmfPrint', printComponent);
  * @private
  * @hidden
  */
-class Controller {
+class PrintController {
 
   /**
    * @param {JQuery} $element Element.
@@ -268,7 +274,6 @@ class Controller {
    * @param {angular.IFilterService} $filter Angular $filter service.
    * @param {PrintState} gmfPrintState GMF print state.
    * @param {import("gmf/theme/Themes.js").ThemesService} gmfThemes The gmf Themes service.
-   * @private
    * @ngInject
    * @ngdoc controller
    * @ngname GmfPrintController
@@ -1418,7 +1423,7 @@ class Controller {
   }
 }
 
-module.controller('GmfPrintController', Controller);
+module.controller('GmfPrintController', PrintController);
 
 
 export default module;

contribs/gmf/src/themes.js

@@ -185,22 +185,16 @@
  *      values (for filters purpose). For WMS layers.
  * @property {boolean} [exclusiveGroup=false] Whether the group contain children that have to be mutually
  *      exclusive, meaning that only one child may be ON at any time.
- * @property {boolean} [geometry_validation=false] Whether geometries must be validated by PostgreSQL on
- *      edition. For WMS layers.
  * @property {string} [iconUrl] The URL of the icon to display in the layer tree. For WMS and WMTS layers.
- * @property {string} identifierAttributeField The field used in the 'display query window' as feature title.
- *      For WMS layers.
+ * @property {string} [identifierAttributeField] The field used in the 'display query window' as feature
+ *      title. For WMS layers.
  * @property {boolean} [isChecked=false] Is the layer checked by default. For WMS and WMTS layers.
  * @property {boolean} [isExpanded=false] Whether the layer group is expanded by default. For layer groups
  *      (only).
  * @property {boolean} [printNativeAngle=true] Whether the print should rotate the symbols. For layer groups
  *      (only).
  * @property {boolean} [isLegendExpanded=false] Whether the legend is expanded by default. For WMS and
  *      WMTS layers.
- * @property {string} [lastUpdateDateColumn] 'Date' column that will be automatically updated after editing
- *      an element. For WMS layers.
- * @property {string} [lastUpdateUserColumn] 'User' column that will be automatically updated after editing
- *      an element. For WMS layers.
  * @property {boolean} [legend=false] Display the legend of this layers. For WMS and WMTS layers.
  * @property {string} [legendImage] The URL to the image used as a legend in the layer tree. For WMS and
  *      WMTS layers.

src/layertree/component.js

@@ -118,7 +118,7 @@ module.run(/* @ngInject */ ($templateCache) => {
  * @ngdoc directive
  * @ngname ngeoLayertree
  */
-function layertreeComponent(ngeoLayertreeTemplateUrl) {
+function gmfLayertreeComponent(ngeoLayertreeTemplateUrl) {
   return {
     restrict: 'A',
     scope: true,
@@ -128,7 +128,7 @@ function layertreeComponent(ngeoLayertreeTemplateUrl) {
 }
 
 
-module.directive('ngeoLayertree', layertreeComponent);
+module.directive('ngeoLayertree', gmfLayertreeComponent);
 
 
 export default module;