OpenLayers 3
Hosted Examples
The examples are hosted on GitHub (as GitHub pages). See http://openlayers.github.com/ol3/master/examples/.
Build OpenLayers 3
Run build.py:
$ ./build.py
Windows users should run build instead.
Run examples locally
Run the Plovr web server with:
$ ./build.py serve
Windows users should run build serve instead.
Then, either open one of the example html files from the examples directory directly in your browser, or start a simple webserver, for example:
$ python -mSimpleHTTPServer
and explore the examples/ directory, for example by opening
http://localhost:8000/examples/side-by-side.html.
You can turn off compilation by appending ?mode=RAW to the URL, for example
http://localhost:8000/examples/side-by-side.html?mode=RAW. (By default mode is ADVANCED.)
The examples can also be run against the ol.js standalone lib, without Plovr,
just like the examples hosted
on GitHub. You will want to run the examples against the standalone lib to verify
that will work correctly when copied on GitHub (as GitHub pages). Start by executing
the hostexamples build target:
$ ./build.py hostexamples
This will build ol.js and ol.css, creates the examples index page, and copy everything to
build/gh-pages/<branch_name>/, where <branch_name> is the name of the local checked
out Git branch. You can now open the build/gh-pages/<branch_name>examples directory
in the browser, for example: http://localhost:8000/build/gh-pages/master/examples/side-by-side.html.
Run tests
Run the plovr web server (see above), and either open the test/ol.html file
in the browser (e.g. http://localhost:8000/test/ol.html), or run ./build.py test
on the console (headless testing with PhantomJS, make sure to install it first from http://phantomjs.org/download.html).
See also the test-specific readme.
Run the linter
First, install the Closure Linter. Then:
$ ./build.py lint
Run the precommit hook before pushing a commit:
$ ./build.py precommit
Add 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/full-screen.html and examples/full-screen.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.
build.py serve should be stopped and restarted for the
loader.js?id=<example_name> script tag to refer to a valid URL. build.py serve triggers the examples target which creates a Plovr JSON file for each
example.
A note on the use of the goog namespace in the 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), with Plovr in ADVANCED mode, and with Plovr in RAW (debug) mode.
Running the examples with Plovr makes it mandatory to declare dependencies with
goog.require statements. And for the examples to also run with the standalone
lib we export
goog.require as the null function.
Exporting goog.require has a side effect: it adds the goog namespace object
to the global object. This is why we can, for example, have if (goog.DEBUG)
statements in the code of the examples.