Becasue typedefs sometimes use namespaces that are actually
constructors, we need to process typedefs after symbols to avoid
duplicate entries for such namespace types.
When ol.Overlay has set positioning is set to right or bottom, no offset is applied. I added the missing calculations.
I made 2 fiddles showing the bahaviour before and after.
The divs in hte fiddles are named after their positioning (anchor point)! Not the actual position!
Before: http://jsfiddle.net/simon_seyock/ob7ggtx6/
As you can see, on div named "bottom-right" no offset at all is applied. On "bottom-center" it is only applied horizontally and on "center-right" only vertically.
After: http://jsfiddle.net/simon_seyock/sL2f3nL9/2/
All offsets are applied correctly, you could draw a straight line through the anchor points of every div.
This change adds all information that is needed to generate the externs
file to build/info.json, so tasks/generate-externs.js no longer needs
to spawn JSDoc.
This reworks the changes in #2442 so we always include the version info, regardless of whether the module is run as main or not. This also addresses a few lint related issues.
Most of our uses of source extent were cargo cult programming. The source extent was seldom and inconsistently used. Instead, layers can now be configured with an extent, and layer renderers limit rendering (and data requests) to the layer extent.
For vector sources, the `getExtent` method returns the extent of currently loaded features (this was the case before and after this change). For tile based sources, we will likely want to allow easy construction of tile grids based on an extent (this is not possible before or after this change, but could be added later).
Tile grids cannot currently be constructed with an extent (though we should perhaps provide a function that allows this - see 68815dca10 for an example).
This has two nice consequences that can be seen in the wms-image.js and mapbuide-untiled.js examples:
* no images are requested when you browse outside of the layer extent
* when the layer extent is within the viewport extent, cached images are used since the intersecting extent is the same for multiple viewport extents
The ol-all.json and ol.json build configurations differ only in their use of the manage_closure_dependencies Compiler option. I don't think there is value in running both (there are plenty of other compiler options that we don't exercise in this same way).
Instead of running everything through the Compiler just to remove whitespace, we provide a build that is a simple concatenation of all scripts in dependency order. This build (ol-debug.js) should never be used in production (the same applies to the old ol-whitespace.js build). Instead, the intention is that it be used to aid in debugging during development.
If a `src` config is not provided, by default, all of the library sources are included. There is some special handling in the build task to make sure all library sources are included regardless of the path to the build config. When someone includes a `src` config, path patterns are assumed to be relative to the current working directory (unless overriden with the `cwd` config). So, when you use the `src` config, your config is no longer portable.
This allows other packages to depend on the ol3 package and get the build tools (devDependencies are not installed when they are transitive dependencies). The justification here is that the ol3 package becomes useful to other packages when you are able to run the build.js task. For this task to run all of its dependencies must be available.
Because we don't know if a new or modified file includes changes to the class hierarchy, we regenerate info for all sources any time any one has changed. An alternative would be to generate info first for the new or modified file and then (potentially) regenerate info for more source files in the class hierarchy, but this makes the generate-info.js task far more complicated.
[forking](https://github.com/openlayers/ol3/fork_select) the ol3 repository.
### Travis CI
The Travis CI hook is enabled on the Github repository. This means every pull request
is run through a full test suite to ensure it compiles and passes the tests. Failing
pull requests will not be merged.
Although not mandatory, it is also recommended to set up Travis CI for your ol3 fork.
For that go to your ol3 fork's Service Hooks page and set up the Travis hook.
Then every time you push to your fork, the test suite will be run. This means
errors can be caught before creating a pull request. For those making
small or occasional contributions, this may be enough to check that your contributions
are ok; in this case, you do not need to install the build tools on your local environment
as described below.
### Development dependencies
The minimum requirements are:
* Git
* [Node.js](http://nodejs.org/)
* Python 2.6 or 2.7 with a couple of extra modules (see below)
* Java 7 (JRE and JDK)
The executables `git`, `java`, `jar`, and `python` should be in your `PATH`.
You can check your configuration by running:
$ ./build.py checkdeps
To install the Node.js dependencies run
$ npm install
To install the extra Python modules, run:
$ sudo pip install -r requirements.txt
or
$ cat requirements.txt | sudo xargs easy_install
depending on your OS and Python installation.
## Working with the build tool
As an ol3 developer you will need to use the `build.py` Python script. This is
the script to use to run the linter, the compiler, the tests, etc. Windows users
can use `build.cmd` which is a thin wrapper around `build.py`.
The `build.py` script is equivalent to a Makefile. It is actually based on
[pake](https://github.com/twpayne/pake/), which is a simple implementation of
`make` in Python.
The usage of the script is:
$ ./build.py <target>
where `<target>` is the name of the build target you want to execute. For
example:
$ ./build.py test
The main build targets are `serve`, `lint`, `build`, `test`, and `check`. The
latter is a meta-target that basically runs `lint`, `build`, and `test`.
The `serve` target starts a node-based web server, which we will refer to as the *dev server*. You'll need to start that server for running the examples and the tests in a browser. More information on that further down.
Other targets include `apidoc` and `ci`. The latter is the target used on Travis CI. See ol3's [Travis configuration file](https://github.com/openlayers/ol3/blob/master/.travis.yml).
## Running the `check` target
The `check` target is to be run before pushing code to GitHub and opening pull
requests. Branches that don't pass `check` won't pass the integration tests,
and have therefore no chance of being merged into `master`.
To run the `check` target:
$ ./build.py check
If you want to run the full suite of integration tests, see "Running the integration
tests" below.
## Running examples
To run the examples you first need to start the dev server:
$ ./build.py serve
Then, just point your browser <http://localhost:3000/examples> in your browser. For example <http://localhost:3000/examples/side-by-side.html>.
Run examples against the `ol.js` standalone build:
The examples can also be run against the `ol.js` standalone lib, just like the examples
[hosted](http://openlayers.github.com/ol3/master/examples/) on GitHub. Start by
executing the `host-examples` build target:
$ ./build.py host-examples
After running `host-examples` you can now open the examples index page in the browser, for example: <http://localhost/~elemoine/ol3/build/hosted/master/examples/>. (This assumes that the `hosted` directory is a web directory, served by Apache for example.)
Append `?mode=raw` to make the example work in full debug mode. In raw mode the OpenLayers and Closure Library scripts are loaded individually by the Closure Library's `base.js` script (which the example page loads and executes before any other script).
## Running tests
To run the tests in a browser start the dev server (`./build.py serve`) and open <http://localhost:3000/test/index.html> in the browser.
To run the tests on the console (headless testing with PhantomJS) use the `test` target:
$ ./build.py test
See also the test-specific [README](../blob/master/test/README.md).
## Running the integration tests
When you submit a pull request the [Travis continuous integration
server](https://travis-ci.org/) will run a full suite of tests, including
building all versions of the library and checking that all of the examples
work. You will receive an email with the results, and the status will be
displayed in the pull request.
To run the full suite of integration tests use the `ci` target:
$ ./build.py ci
Running the full suite of integration tests currently takes 5-10 minutes.
This makes sure that your commit won't break the build. It also runs JSDoc3 to
make sure that there are no invalid API doc directives.
## Adding examples
Adding functionality often implies adding one or several examples. This
section provides explanations related to adding examples.
The examples are located in the `examples` directory. Adding a new example
implies creating two files in this directory, an `.html` file and a `.js` file.
See `examples/simple.html` and `examples/simple.js` for instance.
The `.html` file needs to include a script tag with
`loader.js?id=<example_name>` as its `src`. For example, if the two files for
the example are `myexample.js` and `myexample.html` then the script tag's `src`
should be set to `myexample`.
You can use `simple.js` and `simple.html` as templates for new examples.
### Use of the `goog` namespace in examples
Short story: the ol3 examples should not use the `goog` namespace, except
for `goog.require`.
Longer story: we want that the ol3 examples work in multiple modes, with the
standalone lib (which has implications of the symbols and properties we
export), and compiled together with the ol3 library.
Compiling the examples together with the library makes it mandatory to declare dependencies with `goog.require` statements.
## Pull request guidelines
Your pull request must:
* Follow OpenLayers 3's coding style.
* Pass the integration tests run automatically by the Travis Continuous
Integration system.
* Address a single issue or add a single item of functionality.
* Contain a clean history of small, incremental, logically separate commits,
with no merge commits.
* Use clear commit messages.
* Be possible to merge automatically.
### The `check` build target
It is strongly recommended that you run
$ ./build.py check
before every commit. This will catch many problems quickly, and it is much
faster than waiting for the Travis CI integration tests to run.
The `check` build target runs a number of quick tests on your code. These
Linter](https://developers.google.com/closure/utilities/) in strict mode. You
can run the linter locally on your machine before committing using the `lint`
target to `build.py`:
$ ./build.py lint
In addition to fixing problems identified by the linter, please also follow the
style of the existing OpenLayers 3 code, which includes:
* Always wrap the body of `for`, `if`, and `while` statements in braces.
* Class methods should be in alphabetical order.
*`var` declarations should not span multiple lines. If you cannot fit all
the declarations in a single line, then start a new `var` declaration on a
new line. Within a single line, variables should be declared in
alphabetical order.
* Do not use assignments inside expressions.
### Pass the integration tests run automatically by the Travis CI system
The integration tests contain a number of automated checks to ensure that the
code follows the OpenLayers 3 style and does not break tests or examples. You
can run the integration tests locally using the `ci` target:
$ ./build.py ci
### Address a single issue or add a single item of functionality
Please submit separate pull requests for separate issues. This allows each to
be reviewed on its own merits.
### Contain a clean history of small, incremental, logically separate commits, with no merge commits
The commit history explains to the reviewer the series of modifications to the
code that you have made and breaks the overall contribution into a series of
easily-understandable chunks. Any individual commit should not add more than
one new class or one new function. Do not submit commits that change thousands
of lines or that contain more than one distinct logical change. Trivial
commits, e.g. to fix lint errors, should be merged into the commit that
introduced the error. See the [Atomic Commit Convention on Wikipedia](http://en.wikipedia.org/wiki/Atomic_commit#Atomic_Commit_Convention) for more detail.
`git apply --patch` and `git rebase` can help you create a clean commit
[](http://travis-ci.org/#!/openlayers/ol3)
Welcome to [OpenLayers 3](http://ol3js.org/)!
Welcome to [OpenLayers 3](http://openlayers.org/)!
Check out the [hosted examples](http://ol3js.org/en/master/examples/), the [workshop](http://ol3js.org/ol3-workshop/) or poke around the evolving [API docs](http://ol3js.org/en/master/apidoc/).
Check out the [hosted examples](http://openlayers.org/en/master/examples/), the [workshop](http://openlayers.org/ol3-workshop/) or poke around the evolving [API docs](http://openlayers.org/en/master/apidoc/).
Please don't ask questions in the github issue tracker but use [the mailing list](https://groups.google.com/forum/#!forum/ol3-dev) instead.
<tr><td><p>All coordinates and extents need to be provided in view projection (default: [EPSG:3857](ol.proj.EPSG3857.html)). To transform, use [ol.proj.transform()](ol.proj.html#transform) and [ol.extent.applyTransform()](ol.extent.html#applyTransform).</p>
<tr><td><p>All coordinates and extents need to be provided in view projection (default: EPSG:3857). To transform, use [ol.proj.transform()](ol.proj.html#transform) and [ol.proj.transformExtent()](ol.proj.html#transformExtent).</p>
[ol.proj](ol.proj.html)</td>
<td><p>[Objects](ol.Object.html) can be kept in sync using the [bindTo()](ol.Object.html#bindTo) method.</p>
<p>A [DOM Input](ol.dom.Input.html) class is available to bind Object properties to HTML Input elements.</p></td>
The first part is to include the JavaScript library. For the purpose of this tutorial, here we simply point to the ol3js.org website to get the whole library. In a production environment, we would build a custom version of the library including only the module needed for our application.
The first part is to include the JavaScript library. For the purpose of this tutorial, here we simply point to the openlayers.org website to get the whole library. In a production environment, we would build a custom version of the library including only the module needed for our application.
@@ -16,7 +16,7 @@ It is also designed such that major new features, such as displaying 3D maps, or
OL3 is based on Google's Closure Tools. It makes heavy use of parts of the [__Closure Library__](https://developers.google.com/closure/library/). Using this to handle basics like DOM or event handling means the developers can concentrate on mapping functionality, and be sure that the underlying software is well-tested and cross-browser. Closure Library is specially designed to be optimized by the [__Closure Compiler__](https://developers.google.com/closure/compiler/). The 'advanced' optimizations that this provides offers a level of compression that far exceeds anything else available. OL3 has been designed to make full use of this.
## Public API
Using the advanced optimizations of the Closure Compiler means that properties and methods are renamed – `longMeaningfulName` might become `xB` – and so are effectively unusable in applications using the library. To be usable, they have to be explicitly `exported`. This means the exported names, those not renamed, effectively become the public API of the library. These __exportable__ properties and methods are marked in the source, and documented in the [API docs](../apidoc). This is the officially supported API of the library. A build containing all these exportable names is known as a __full build__. A hosted version of this is available, which can be used by any application.
Using the advanced optimizations of the Closure Compiler means that properties and methods are renamed – `longMeaningfulName` might become `xB` – and so are effectively unusable in applications using the library. To be usable, they have to be explicitly `exported`. This means the exported names, those not renamed, effectively become the public API of the library. These __exportable__ properties and methods are marked in the source, and documented in the [API docs](../../apidoc). This is the officially supported API of the library. A build containing all these exportable names is known as a __full build__. A hosted version of this is available, which can be used by any application.
Although Closure library functions are widely used within OL3, none of them are exported. You will see references to them (they are all in the `goog` namespace) in the API docs, but these are for information only. You can use the Closure library in your own applications if you like, but this is not required.
@@ -35,10 +35,10 @@ OL3 uses a similar object hierarchy to the Closure library. There is a top-level
* simple objects containing static properties and methods, such as `ol.animation`; these also have a lower-case initial
* types, which have an upper-case initial. These are mainly 'classes', which here means a constructor function with prototypal inheritance, such as `ol.Map` or `ol.layer.Vector` (the Vector class within the layer namespace). There are however other, simpler, types, such as `ol.Extent`, which is an array.
In the API docs, the index on the left lists the namespaces and simple objects first, followed by the classes.
Class namespaces, such as `ol.layer` have a base class type with the same name, such as `ol.layer.Layer`. These are mainly abstract classes, from which the other subclasses inherit.
Source files are similarly organised, with a directory for each class namespace. Names are however all lower-case, and the subclasses repeat the superclass type in their name, for example, `ol/layer/vectorlayer.js`.
The naming structure means that there are sometimes 2 objects with the same name but different initial, such as `ol.feature`, a simple object with static functions to be used with features, and `ol.Feature`, a class used to instantiate new features. These two objects are however stored in the same file, in this case, `ol/feature.js`
OL3 follows the convention that the names of private properties and methods, that is, those that are not part of the API, end in an underscore. In general, instance properties are private and accessed using accessors.
<pid="shortdesc">Example of using the drag-and-drop interaction. Drag and drop GPX, GeoJSON, IGC, KML, or TopoJSON files on to the map.</p>
<pid="shortdesc">Example of using the drag-and-drop interaction. Drag and drop GPX, GeoJSON, IGC, KML, or TopoJSON files on to the map. There is no projection transform support, so this will only work with data in EPSG:4326 and EPSG:3857.</p>
<divid="docs">
<p>See the <ahref="drag-and-drop.js"target="_blank">drag-and-drop.js source</a> to see how this is done.</p>
Although the main purpose of these examples is to demonstrate how to use the API, they also serve other purposes in the development cycle, and so are not exactly as they would be in normal application code:
* every time the library changes, they are compiled together with the library as a basic check that they remain in sync with the library
* they use a special loader script to enable defining at run time which build mode (debug/whitespace/simple/advanced) to use
* they use a special loader script to enable defining at run time which build mode (raw/debug/advanced) to use
To enable this, examples have the following, not needed in application code:
@@ -13,4 +13,4 @@ To enable this, examples have the following, not needed in application code:
* html files load `example-behaviour.js` and some js files define the Map renderer option as `exampleNS.getRendererFromQueryString()`; application code would not need these
* in addition, examples use Twitter Bootstrap and jQuery; this is of course not a requirement - you may use whichever presentation/helper libraries you wish
See [Quick Start tutorial](http://ol3js.org/en/master/doc/quickstart.html) for a simple example of how application code would use the library.
See [Quick Start tutorial](http://openlayers.org/en/master/doc/quickstart.html) for a simple example of how application code would use the library.
Some files were not shown because too many files have changed in this diff
Show More
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
