| 1 | # Externs
|
| 2 |
|
| 3 | This directory contains externs files, which tell the Closure compiler about symbols and properties that it should not rename.
|
| 4 |
|
| 5 | ## oli.js and olx.js
|
| 6 |
|
| 7 | These two files are special externs that belong to OpenLayers, and this document explains their purpose and how they are used.
|
| 8 |
|
| 9 | ### Prevent class properties from being renamed
|
| 10 |
|
| 11 | For events, we make properties available to the application. Methods can be made available by just marking them with the `@api` annotation directly where they are defined; properties should also be added to `oli.js`:
|
| 12 |
|
| 13 | ```js
|
| 14 | /**
|
| 15 | * @interface
|
| 16 | */
|
| 17 | oli.MapBrowserEvent = function() {};
|
| 18 |
|
| 19 | /**
|
| 20 | * @type {ol.Coordinate}
|
| 21 | */
|
| 22 | oli.MapBrowserEvent.prototype.coordinate;
|
| 23 | ```
|
| 24 | In the source file (`src/ol/MapBrowserEvent.js`), the class needs to implement this interface:
|
| 25 | ```js
|
| 26 | /**
|
| 27 | * ...
|
| 28 | * @constructor
|
| 29 | * @implements {oli.MapBrowserEvent}
|
| 30 | */
|
| 31 | ol.MapBrowserEvent = function(type, map, originalEvent, opt_frameState) {
|
| 32 |
|
| 33 | // ...
|
| 34 |
|
| 35 | /**
|
| 36 | * @type {ol.Coordinate}
|
| 37 | * @api
|
| 38 | */
|
| 39 | this.coordinate = map.getEventCoordinate(this.originalEvent);
|
| 40 |
|
| 41 | // ...
|
| 42 |
|
| 43 | };
|
| 44 | ```
|
| 45 |
|
| 46 | ### Override methods in custom classes
|
| 47 |
|
| 48 | For custom subclasses in applications, which can be created using `ol.inherits`, the API may want to make certain methods available to override. In addition to marking such methods as `@api`, they should also be added to an interface in `oli.js`:
|
| 49 | ```js
|
| 50 | /**
|
| 51 | * @interface
|
| 52 | */
|
| 53 | oli.control.Control = function() {};
|
| 54 |
|
| 55 | /**
|
| 56 | * @param {ol.Map} map Map.
|
| 57 | * @return {undefined} Undefined.
|
| 58 | */
|
| 59 | oli.control.Control.prototype.setMap = function(map) {};
|
| 60 |
|
| 61 | ```
|
| 62 | This interface must be implemented by the class in the source file (`src/ol/control/control.js`):
|
| 63 | ```js
|
| 64 | /**
|
| 65 | * ...
|
| 66 | * @constructor
|
| 67 | * @implements {oli.control.Control}
|
| 68 | */
|
| 69 | ol.control.Control = function(options) {
|
| 70 | // ...
|
| 71 | };
|
| 72 |
|
| 73 | // ...
|
| 74 |
|
| 75 | /**
|
| 76 | * Application subclasses may override this.
|
| 77 | * @param {ol.Map} map Map.
|
| 78 | * @api
|
| 79 | */
|
| 80 | ol.control.Control.prototype.setMap = function(map) {
|
| 81 | // ...
|
| 82 | };
|
| 83 | ```
|
| 84 | See Custom controls example for an example of how this can be used.
|
| 85 |
|
| 86 | ### Export object literals
|
| 87 |
|
| 88 | Object literals cannot be exported like classes. To make sure that their properties do not get renamed, they go in `olx.js`:
|
| 89 | ```js
|
| 90 | /**
|
| 91 | * @typedef {{element: (Element|undefined),
|
| 92 | * target: (Element|string|undefined)}}
|
| 93 | * @api
|
| 94 | */
|
| 95 | olx.control.ControlOptions;
|
| 96 |
|
| 97 | /**
|
| 98 | * The element is the control's container element. This only needs to be
|
| 99 | * specified if you're developing a custom control.
|
| 100 | * @type {Element|undefined}
|
| 101 | */
|
| 102 | olx.control.ControlOptions.prototype.element;
|
| 103 |
|
| 104 | /**
|
| 105 | * Specify a target if you want the control to be rendered outside of the map's
|
| 106 | * viewport.
|
| 107 | * @type {Element|string|undefined}
|
| 108 | */
|
| 109 | olx.control.ControlOptions.prototype.target;
|
| 110 | ```
|
| 111 | In the source code, the name used for the typedef is used as type whenever this object literal is expected:
|
| 112 | ```js
|
| 113 | /**
|
| 114 | * ...
|
| 115 | * @param {olx.control.ControlOptions} options Control options.
|
| 116 | */
|
| 117 | ol.control.Control = function(options) {
|
| 118 | // ...
|
| 119 | };
|
| 120 | ```
|