Merge pull request #2839 from tschaub/publish

Dependency updates and new package name.

CONTRIBUTING.md

@@ -4,18 +4,301 @@ Thanks for your interest in contributing to OpenLayers 3.
 
 ## Contributing Code
 
-Our preferred means of receiving contributions is through [pull
-requests](https://help.github.com/articles/using-pull-requests).
+Our preferred means of receiving contributions is through [pull requests](https://help.github.com/articles/using-pull-requests). Make sure
+that your pull request follows our pull request guidelines below before submitting it.
 
-See the [Developer
-Guide](https://github.com/openlayers/ol3/wiki/Developer-Guide) to get started
-with OpenLayers 3 development. This guide provides information you should know
-before creating pull requests.
+This page describes what you need to know to contribute code to ol3 as a developer.
 
-Note that, before accepting a contribution, we ask that you provide us
-a Contributor License Agreement. If you are making your contribution as part of
-work for your employer, please follow the guidelines on submitting a [Corporate
-Contributor License Agreement](http://www.openlayers.org/ccla.txt). If you are
+## Contributor License Agreement
+
+Before accepting a contribution, we ask that you provide us a Contributor
+License Agreement.  If you are making your contribution as part of work for
+your employer, please follow the guidelines on submitting a [Corporate
+Contributor License Agreement](https://raw.github.com/openlayers/cla/master/ccla.txt). If you are
 making your contribution as an individual, you can submit a digital [Individual
-Contributor License
-Agreement](https://docs.google.com/spreadsheet/viewform?formkey=dGNNVUJEMXF2dERTU0FXM3JjNVBQblE6MQ).
+Contributor License Agreement](https://docs.google.com/spreadsheet/viewform?formkey=dGNNVUJEMXF2dERTU0FXM3JjNVBQblE6MQ).
+
+## Setting up development environment
+
+You will obviously start by
+[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
+include:
+
+ * Lint
+ * Compile
+ * Tests
+
+
+### Follow OpenLayers 3's coding style
+
+OpenLayers 3 follows [Google's JavaScript Style
+Guide](http://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml).
+This is checked using the [Closure
+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
+history.
+[Reviewboard.org](http://www.reviewboard.org/docs/codebase/dev/git/clean-commits/)
+and [Pro GIT](http://git-scm.com/book/en/Git-Tools-Rewriting-History) have
+explain how to use them.
+
+
+### Use clear commit messages
+
+Commit messages should be short, begin with a verb in the imperative, and
+contain no trailing punctuation. We follow
+http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
+for the formatting of commit messages.
+
+Git commit message should look like:
+
+    Header line: explaining the commit in one line
+
+    Body of commit message is a few lines of text, explaining things
+    in more detail, possibly giving some background about the issue
+    being fixed, etc etc.
+
+    The body of the commit message can be several paragraphs, and
+    please do proper word-wrap and keep columns shorter than about
+    74 characters or so. That way "git log" will show things
+    nicely even when it's indented.
+
+    Further paragraphs come after blank lines.
+
+Please keep the header line short, no more than 50 characters.
+
+### Be possible to merge automatically
+
+Occasionally other changes to `master` might mean that your pull request cannot
+be merged automatically.  In this case you may need to rebase your branch on a
+more recent `master`, resolve any conflicts, and `git push --force` to update
+your branch so that it can be merged automatically.

README.md

@@ -2,9 +2,9 @@
 
 [![Travis CI Status](https://secure.travis-ci.org/openlayers/ol3.png)](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.
 

bin/loader_hosted_examples.js

@@ -1,13 +1,13 @@
 /**
- * Loader to add ol.css, ol.js and the example-specific js file to the
- * documents.
- *
  * This loader is used for the hosted examples. It is used in place of the
  * development loader (examples/loader.js).
  *
- * ol.js, ol-simple.js, ol-whitespace.js, and ol-deps.js are built
- * by OL3's build.py script. They are located in the ../build/ directory,
- * relatively to this script.
+ * The loader loads ol.js and the example's script in "production" mode; it
+ * loads Closure Library's base.js, ol-deps.js, the example's "goog.require"
+ * script, and the example's script in "development" mode.
+ *
+ * The ol.js and ol-deps.js scripts are built by OL3's build.py script.
+ * They are located in the ../build/ directory, relative to this script.
  *
  * The script must be named loader.js.
  *
@@ -54,20 +54,11 @@
     }
   }
 
-  var oljs = 'ol.js', mode;
-  if ('mode' in pageParams) {
-    mode = pageParams.mode.toLowerCase();
-    if (mode == 'debug') {
-      mode = 'raw';
-    }
-    if (mode != 'advanced' && mode != 'raw') {
-      oljs = 'ol-' + mode + '.js';
-    }
-  }
+  var raw = pageParams.mode && pageParams.mode.toLowerCase() === 'raw';
 
   var scriptId = encodeURIComponent(scriptParams.id);
-  if (mode != 'raw') {
-    document.write('<scr' + 'ipt type="text/javascript" src="../build/' + oljs + '"></scr' + 'ipt>');
+  if (!raw) {
+    document.write('<scr' + 'ipt type="text/javascript" src="../build/ol.js"></scr' + 'ipt>');
   } else {
     window.CLOSURE_NO_DEPS = true; // we've got our own deps file
     document.write('<scr' + 'ipt type="text/javascript" src="../closure-library/closure/goog/base.js"></scr' + 'ipt>');

build.py

@@ -1,25 +1,62 @@
 #!/usr/bin/env python
 
 from cStringIO import StringIO
+import glob
 import gzip
 import json
+import multiprocessing
 import os
-import glob
 import re
 import shutil
 import sys
 
 from pake import Target
 from pake import ifind, main, output, rule, target, variables, virtual, which
+from Queue import Queue
+from threading import Thread
+
+
+class ThreadPool:
+    """A basic pool of worker threads"""
+    class Worker(Thread):
+        def __init__(self, tasks):
+            Thread.__init__(self)
+            self.tasks = tasks
+            self.daemon = True # threads will be killed on exit
+            self.start()
+
+        def run(self):
+            while True:
+                # block until a task is ready to be done
+                function, args, kargs = self.tasks.get()
+                try:
+                    function(*args, **kargs)
+                except:
+                    print(sys.exc_info()[0])
+                    self.tasks.errors = True
+                self.tasks.task_done()
+
+    def __init__(self, num_threads = multiprocessing.cpu_count() + 1):
+        self.tasks = Queue(num_threads)
+        self.tasks.errors = False
+        # create num_threads Workers, by default the number of CPUs + 1
+        for _ in range(num_threads): self.Worker(self.tasks)
+
+    def add_task(self, function, *args, **kargs):
+        self.tasks.put((function, args, kargs))
+
+    def wait_completion(self):
+        # wait for the queue to be empty
+        self.tasks.join()
+        return self.tasks.errors
 
 
 if sys.platform == 'win32':
 
     win = {
+        'CLEANCSS': './node_modules/.bin/cleancss',
         'GIT': 'git.exe',
         'GJSLINT': 'gjslint.exe',
-        'JAVA': 'java.exe',
-        'JAR': 'jar.exe',
         'JSDOC': './node_modules/.bin/jsdoc',
         'JSHINT': './node_modules/.bin/jshint',
         'PYTHON': 'python.exe',
@@ -28,24 +65,6 @@ if sys.platform == 'win32':
 
     sys_dir = os.environ.get('SYSTEMDRIVE')
     program_files = os.environ.get('PROGRAMFILES')
-    java_home = os.environ.get('JAVA_HOME')
-
-    if not java_home:
-        # Following lines choose sensible defaults to guess JAVA_HOME in
-        # 32/64bit Program Files folder opting for the most current version.
-        search_term = os.path.join(sys_dir, os.sep, 'Program Files*', 'Java', 'jdk*')
-        found_jdks = sorted(glob.glob(search_term), key=lambda x: x[-8:])
-        if found_jdks:
-            java_home = found_jdks[-1]
-
-    if java_home:
-        if not which(win['JAVA']):
-            win['JAVA'] = os.path.join(java_home, 'bin', 'java.exe')
-        if not which(win['JAR']):
-            win['JAR'] = os.path.join(java_home, 'bin', 'jar.exe')
-    elif not which(win['JAVA']):
-        win['JAVA'] = os.path.join(program_files,
-                                   'Java', 'jre7', 'bin', 'java.exe')
 
     if not which(win['GIT']):
         win['GIT'] = os.path.join(program_files, 'Git', 'cmd', 'git.exe')
@@ -70,11 +89,10 @@ if sys.platform == 'win32':
         setattr(variables, program, path)
 
 else:
+    variables.CLEANCSS = './node_modules/.bin/cleancss'
     variables.GIT = 'git'
     variables.GJSLINT = 'gjslint'
     variables.JSHINT = './node_modules/.bin/jshint'
-    variables.JAVA = 'java'
-    variables.JAR = 'jar'
     variables.JSDOC = './node_modules/.bin/jsdoc'
     variables.PYTHON = 'python'
     variables.PHANTOMJS = './node_modules/.bin/phantomjs'
@@ -82,12 +100,10 @@ else:
 variables.BRANCH = output(
     '%(GIT)s', 'rev-parse', '--abbrev-ref', 'HEAD').strip()
 
-EXECUTABLES = [variables.GIT, variables.GJSLINT, variables.JAVA, variables.JAR,
+EXECUTABLES = [variables.CLEANCSS, variables.GIT, variables.GJSLINT,
                variables.JSDOC, variables.JSHINT, variables.PYTHON,
                variables.PHANTOMJS]
 
-EXPORTS = 'build/exports.js'
-
 EXAMPLES = [path
             for path in ifind('examples')
             if path.endswith('.html')
@@ -97,9 +113,7 @@ EXAMPLES_SRC = [path
                 for path in ifind('examples')
                 if path.endswith('.js')
                 if not path.endswith('.combined.js')
-                if not path.startswith('examples/bootstrap')
                 if path != 'examples/Jugl.js'
-                if path != 'examples/jquery.min.js'
                 if path != 'examples/example-list.js']
 
 EXAMPLES_JSON = ['build/' + example.replace('.html', '.json')
@@ -123,6 +137,10 @@ SPEC = [path
         for path in ifind('test/spec')
         if path.endswith('.js')]
 
+TASKS = [path
+         for path in ifind('tasks')
+         if path.endswith('.js')]
+
 SRC = [path
        for path in ifind('src/ol')
        if path.endswith('.js')
@@ -145,56 +163,36 @@ def report_sizes(t):
 virtual('default', 'build')
 
 
-virtual('ci', 'lint', 'jshint', 'build', 'build-all',
-        'test', 'build/examples/all.combined.js', 'check-examples', 'apidoc')
+virtual('ci', 'lint', 'build', 'test',
+    'build/examples/all.combined.js', 'check-examples', 'apidoc')
 
 
-virtual('build', 'build/ol.css', 'build/ol.js',
-        'build/ol-simple.js', 'build/ol-whitespace.js')
+virtual('build', 'build/ol.css', 'build/ol.js', 'build/ol-debug.js')
 
 
-virtual('check', 'lint', 'jshint', 'build/ol-all.js', 'test')
+virtual('check', 'lint', 'build/ol.js', 'test')
 
 
 virtual('todo', 'fixme')
 
 
-@target('build/ol.css', 'build/ol.js')
+@target('build/ol.css', 'css/ol.css')
 def build_ol_css(t):
-    t.touch()
+    t.output('%(CLEANCSS)s', 'css/ol.css')
 
 
-@target('build/ol.js', SRC, SHADER_SRC, 'buildcfg/ol.json')
+@target('build/ol.js', SRC, SHADER_SRC, 'config/ol.json')
 def build_ol_new_js(t):
-    t.run('node', 'tasks/build.js', 'buildcfg/ol.json', 'build/ol.js')
+    t.run('node', 'tasks/build.js', 'config/ol.json', 'build/ol.js')
     report_sizes(t)
 
 
-@target('build/ol-simple.js', SRC, SHADER_SRC, 'buildcfg/ol-simple.json')
-def build_ol_simple_js(t):
-    t.run('node', 'tasks/build.js', 'buildcfg/ol-simple.json', 'build/ol-simple.js')
+@target('build/ol-debug.js', SRC, SHADER_SRC, 'config/ol-debug.json')
+def build_ol_debug_js(t):
+    t.run('node', 'tasks/build.js', 'config/ol-debug.json', 'build/ol-debug.js')
     report_sizes(t)
 
 
-@target('build/ol-whitespace.js', SRC, SHADER_SRC, 'buildcfg/ol-whitespace.json')
-def build_ol_whitespace_js(t):
-    t.run('node', 'tasks/build.js', 'buildcfg/ol-whitespace.json', 'build/ol-whitespace.js')
-    report_sizes(t)
-
-
-virtual('build-all', 'build/ol-all.js')
-
-
-@target('build/ol-all.js', SRC, SHADER_SRC, 'buildcfg/ol-all.json')
-def build_ol_all_js(t):
-    t.run('node', 'tasks/build.js', 'buildcfg/ol-all.json', 'build/ol-all.js')
-
-
-@target(EXPORTS, SRC)
-def build_exports_js(t):
-    t.run('node', 'tasks/generate-exports.js', EXPORTS)
-
-
 for glsl_src in GLSL_SRC:
     def shader_src_helper(glsl_src):
         @target(glsl_src.replace('.glsl', 'shader.js'), glsl_src,
@@ -238,9 +236,9 @@ def examples_examples_list_js(t):
 
 
 @target('build/examples/all.combined.js', 'build/examples/all.js',
-        SRC, SHADER_SRC, 'buildcfg/examples-all.json')
+        SRC, SHADER_SRC, 'config/examples-all.json')
 def build_examples_all_combined_js(t):
-    t.run('node', 'tasks/build.js', 'buildcfg/examples-all.json',
+    t.run('node', 'tasks/build.js', 'config/examples-all.json',
           'build/examples/all.combined.js')
     report_sizes(t)
 
@@ -253,31 +251,47 @@ def build_examples_all_js(t):
 @rule(r'\Abuild/examples/(?P<id>.*).json\Z')
 def examples_star_json(name, match):
     def action(t):
-        # It would make more sense to use olx.js as an input file here. We use
-        # it as an externs file instead to prevent "Cannot read property '*' of
-        # undefined" error when running examples in "raw" or "whitespace" mode.
-        # Note that we use the proper way in buildcfg/examples-all.json, which
-        # is only used to check the examples code using the compiler.
+
+        # When compiling the ol3 code and the application code together it is
+        # better to use oli.js and olx.js files as "input" files rather than
+        # "externs" files. Indeed, externs prevent renaming, which is neither
+        # necessary nor desirable in this case.
+        #
+        # oli.js and olx.js do not provide or require namespaces (using
+        # "goog.provide" or "goog.require"). For that reason, if they are
+        # specified as input files through the "src" property, then
+        # closure-util will exclude them when creating the dependencies graph.
+        # So the compile "js" property is used instead. With that property the
+        # oli.js and olx.js files are passed directly to the compiler. And by
+        # setting "manage_closure_dependencies" to "true" the compiler will not
+        # exclude them from its dependencies graph.
+
         content = json.dumps({
           "exports": [],
-          "src": ["src/**/*.js", "examples/%(id)s.js" % match.groupdict()],
+          "src": [
+            "src/**/*.js",
+            "examples/%(id)s.js" % match.groupdict()],
           "compile": {
+            "js": [
+              "externs/olx.js",
+              "externs/oli.js",
+            ],
             "externs": [
               "externs/bingmaps.js",
               "externs/bootstrap.js",
               "externs/closure-compiler.js",
               "externs/example.js",
               "externs/geojson.js",
-              "externs/jquery-1.7.js",
-              "externs/oli.js",
-              "externs/olx.js",
+              "externs/jquery-1.9.js",
               "externs/proj4js.js",
               "externs/tilejson.js",
               "externs/topojson.js",
               "externs/vbarray.js"
             ],
             "define": [
+              "goog.array.ASSUME_NATIVE_FUNCTIONS=true",
               "goog.dom.ASSUME_STANDARDS_MODE=true",
+              "goog.json.USE_NATIVE_JSON=true",
               "goog.DEBUG=false"
             ],
             "jscomp_error": [
@@ -296,6 +310,7 @@ def examples_star_json(name, match):
               "duplicate",
               "duplicateMessage",
               "es3",
+              "es5Strict",
               "externsValidation",
               "fileoverviewTags",
               "globalThis",
@@ -310,17 +325,16 @@ def examples_star_json(name, match):
               "tweakValidation",
               "undefinedNames",
               "undefinedVars",
-              "unknownDefines",
               "uselessCode",
               "violatedModuleDep",
               "visibility"
             ],
+            "jscomp_off": [
+              "unknownDefines"
+            ],
             "extra_annotation_name": [
               "api", "observable"
             ],
-            "jscomp_off": [
-              "es5Strict"
-            ],
             "compilation_level": "ADVANCED",
             "output_wrapper": "// OpenLayers 3. See http://ol3.js.org/\n(function(){%output%})();",
             "use_types_for_optimization": True,
@@ -350,10 +364,10 @@ def serve(t):
 
 
 virtual('lint', 'build/lint-timestamp', 'build/check-requires-timestamp',
-    'build/check-whitespace-timestamp')
+    'build/check-whitespace-timestamp', 'jshint')
 
 
-@target('build/lint-timestamp', SRC, EXPORTS, EXAMPLES_SRC, SPEC, precious=True)
+@target('build/lint-timestamp', SRC, EXAMPLES_SRC, SPEC, precious=True)
 def build_lint_src_timestamp(t):
     t.run('%(GJSLINT)s',
           '--jslint_error=all',
@@ -365,7 +379,7 @@ def build_lint_src_timestamp(t):
 
 virtual('jshint', 'build/jshint-timestamp')
 
-@target('build/jshint-timestamp', SRC, EXPORTS, EXAMPLES_SRC, SPEC,
+@target('build/jshint-timestamp', SRC, EXAMPLES_SRC, SPEC, TASKS,
         precious=True)
 def build_jshint_timestamp(t):
     t.run(variables.JSHINT, '--verbose', t.newer(t.dependencies))
@@ -535,7 +549,7 @@ def build_check_requires_timestamp(t):
     t.touch()
 
 
-@target('build/check-whitespace-timestamp', SRC, EXPORTS, EXAMPLES_SRC,
+@target('build/check-whitespace-timestamp', SRC, EXAMPLES_SRC,
         SPEC, JSDOC_SRC, precious=True)
 def build_check_whitespace_timestamp(t):
     CR_RE = re.compile(r'\r')
@@ -572,10 +586,10 @@ virtual('apidoc', 'build/jsdoc-%(BRANCH)s-timestamp' % vars(variables))
 
 
 @target('build/jsdoc-%(BRANCH)s-timestamp' % vars(variables), 'host-resources',
-        EXPORTS, SRC, SHADER_SRC,
-        ifind('apidoc/template'))
+        SRC, SHADER_SRC, ifind('config/jsdoc/api/template'))
 def jsdoc_BRANCH_timestamp(t):
-    t.run('%(JSDOC)s', 'apidoc/index.md', '-c', 'apidoc/conf.json',
+    t.run('%(JSDOC)s', 'config/jsdoc/api/index.md',
+          '-c', 'config/jsdoc/api/conf.json',
           '-d', 'build/hosted/%(BRANCH)s/apidoc')
     t.touch()
 
@@ -637,12 +651,10 @@ def host_examples(t):
         split_example_file(example, examples_dir % vars(variables))
     t.cp_r('examples/data', examples_dir + '/data')
     t.cp('bin/loader_hosted_examples.js', examples_dir + '/loader.js')
-    t.cp('build/ol.js', 'build/ol-simple.js', 'build/ol-whitespace.js',
-         build_dir)
+    t.cp('build/ol.js', 'build/ol-debug.js', build_dir)
     t.cp('build/ol.css', css_dir)
     t.cp('examples/index.html', 'examples/example-list.js',
-         'examples/example-list.xml', 'examples/Jugl.js',
-         'examples/jquery.min.js', examples_dir)
+         'examples/example-list.xml', 'examples/Jugl.js', examples_dir)
     t.rm_rf('build/hosted/%(BRANCH)s/closure-library')
     t.cp_r(closure_lib_path, 'build/hosted/%(BRANCH)s/closure-library')
     t.rm_rf('build/hosted/%(BRANCH)s/ol')
@@ -661,10 +673,14 @@ def check_examples(t):
     examples = ['build/hosted/%(BRANCH)s/' + e
                 for e in EXAMPLES
                 if not open(e.replace('.html', '.js'), 'rU').readline().startswith('// NOCOMPILE')]
-    all_examples = \
-        [e + '?mode=advanced' for e in examples]
+    all_examples = [e + '?mode=advanced' for e in examples]
+    # Run the examples checks in a pool of threads
+    pool = ThreadPool()
     for example in all_examples:
-        t.run('%(PHANTOMJS)s', 'bin/check-example.js', example)
+        pool.add_task(t.run, '%(PHANTOMJS)s', 'bin/check-example.js', example)
+    errors = pool.wait_completion()
+    if errors:
+        sys.exit(1)
 
 
 @target('test', phony=True)

buildcfg/jsdoc/info/publish.js

@@ -1,60 +0,0 @@
-/**
- * @fileoverview Generates JSON output based on exportable symbols (those with
- * an api tag) and boolean defines (with a define tag and a default value).
- */
-var assert = require('assert');
-var fs = require('fs');
-var path = require('path');
-
-
-/**
- * Publish hook for the JSDoc template.  Writes to JSON stdout.
- * @param {function} data The root of the Taffy DB containing doclet records.
- * @param {Object} opts Options.
- */
-exports.publish = function(data, opts) {
-  var cwd = process.cwd();
-
-  // get all doclets with the "api" property or define (excluding enums,
-  // typedefs and events)
-  var docs = data(
-      [{define: {isObject: true}}, {api: {isString: true}}],
-      {isEnum: {'!is': true}},
-      {kind: {'!is': 'typedef'}},
-      {kind: {'!is': 'event'}}).get();
-
-  // get symbols data, filter out those that are members of private classes
-  var symbols = [];
-  var defines = [];
-  docs.filter(function(doc) {
-    var include = true;
-    var constructor = doc.memberof;
-    if (constructor && constructor.substr(-1) === '_') {
-      assert.strictEqual(doc.inherited, true,
-          'Unexpected export on private class: ' + doc.longname);
-      include = false;
-    }
-    return include;
-  }).forEach(function(doc) {
-    if (doc.define) {
-      defines.push({
-        name: doc.longname,
-        description: doc.description,
-        path: path.join(doc.meta.path, doc.meta.filename),
-        default: doc.define.default
-      });
-    } else {
-      symbols.push({
-        name: doc.longname,
-        kind: doc.kind,
-        description: doc.classdesc || doc.description,
-        extends: doc.augments,
-        path: path.join(doc.meta.path, doc.meta.filename)
-      });
-    }
-  });
-
-  process.stdout.write(
-      JSON.stringify({symbols: symbols, defines: defines}, null, 2));
-
-};

buildcfg/ol-all.json

@@ -1,65 +0,0 @@
-{
-  "exports": ["*"],
-  "src": ["src/**/*.js"],
-  "compile": {
-    "externs": [
-      "externs/bingmaps.js",
-      "externs/closure-compiler.js",
-      "externs/geojson.js",
-      "externs/oli.js",
-      "externs/olx.js",
-      "externs/proj4js.js",
-      "externs/tilejson.js",
-      "externs/topojson.js",
-      "externs/vbarray.js"
-    ],
-    "define": [
-      "goog.dom.ASSUME_STANDARDS_MODE=true",
-      "goog.DEBUG=false"
-    ],
-    "jscomp_error": [
-      "accessControls",
-      "ambiguousFunctionDecl",
-      "checkEventfulObjectDisposal",
-      "checkRegExp",
-      "checkStructDictInheritance",
-      "checkTypes",
-      "checkVars",
-      "const",
-      "constantProperty",
-      "deprecated",
-      "duplicateMessage",
-      "es3",
-      "externsValidation",
-      "fileoverviewTags",
-      "globalThis",
-      "internetExplorerChecks",
-      "invalidCasts",
-      "misplacedTypeAnnotation",
-      "missingGetCssName",
-      "missingProperties",
-      "missingProvide",
-      "missingRequire",
-      "missingReturn",
-      "newCheckTypes",
-      "nonStandardJsDocs",
-      "suspiciousCode",
-      "strictModuleDepCheck",
-      "typeInvalidation",
-      "undefinedNames",
-      "undefinedVars",
-      "unknownDefines",
-      "uselessCode",
-      "visibility"
-    ],
-    "extra_annotation_name": [
-      "api", "observable"
-    ],
-    "jscomp_off": [
-      "es5Strict"
-    ],
-    "compilation_level": "ADVANCED",
-    "output_wrapper": "// OpenLayers 3. See http://ol3.js.org/\n(function(){%output%})();",
-    "use_types_for_optimization": true
-  }
-}

buildcfg/ol-simple.json

@@ -1,66 +0,0 @@
-{
-  "exports": ["*"],
-  "src": ["src/**/*.js"],
-  "compile": {
-    "externs": [
-      "externs/bingmaps.js",
-      "externs/closure-compiler.js",
-      "externs/geojson.js",
-      "externs/oli.js",
-      "externs/olx.js",
-      "externs/proj4js.js",
-      "externs/tilejson.js",
-      "externs/topojson.js",
-      "externs/vbarray.js"
-    ],
-    "define": [
-      "goog.dom.ASSUME_STANDARDS_MODE=true",
-      "goog.DEBUG=false"
-    ],
-    "jscomp_error": [
-      "accessControls",
-      "ambiguousFunctionDecl",
-      "checkEventfulObjectDisposal",
-      "checkRegExp",
-      "checkStructDictInheritance",
-      "checkTypes",
-      "checkVars",
-      "const",
-      "constantProperty",
-      "deprecated",
-      "duplicateMessage",
-      "es3",
-      "externsValidation",
-      "fileoverviewTags",
-      "globalThis",
-      "internetExplorerChecks",
-      "invalidCasts",
-      "misplacedTypeAnnotation",
-      "missingGetCssName",
-      "missingProperties",
-      "missingProvide",
-      "missingRequire",
-      "missingReturn",
-      "newCheckTypes",
-      "nonStandardJsDocs",
-      "suspiciousCode",
-      "strictModuleDepCheck",
-      "typeInvalidation",
-      "undefinedNames",
-      "undefinedVars",
-      "unknownDefines",
-      "uselessCode",
-      "visibility"
-    ],
-    "extra_annotation_name": [
-      "api", "observable"
-    ],
-    "jscomp_off": [
-      "es5Strict"
-    ],
-    "compilation_level": "SIMPLE",
-    "output_wrapper": "%output%",
-    "use_types_for_optimization": false,
-    "manage_closure_dependencies": true
-  }
-}

buildcfg/ol-whitespace.json

@@ -1,66 +0,0 @@
-{
-  "exports": ["*"],
-  "src": ["src/**/*.js"],
-  "compile": {
-    "externs": [
-      "externs/bingmaps.js",
-      "externs/closure-compiler.js",
-      "externs/geojson.js",
-      "externs/oli.js",
-      "externs/olx.js",
-      "externs/proj4js.js",
-      "externs/tilejson.js",
-      "externs/topojson.js",
-      "externs/vbarray.js"
-    ],
-    "define": [
-      "goog.dom.ASSUME_STANDARDS_MODE=true",
-      "goog.DEBUG=false"
-    ],
-    "jscomp_error": [
-      "accessControls",
-      "ambiguousFunctionDecl",
-      "checkEventfulObjectDisposal",
-      "checkRegExp",
-      "checkStructDictInheritance",
-      "checkTypes",
-      "checkVars",
-      "const",
-      "constantProperty",
-      "deprecated",
-      "duplicateMessage",
-      "es3",
-      "externsValidation",
-      "fileoverviewTags",
-      "globalThis",
-      "internetExplorerChecks",
-      "invalidCasts",
-      "misplacedTypeAnnotation",
-      "missingGetCssName",
-      "missingProperties",
-      "missingProvide",
-      "missingRequire",
-      "missingReturn",
-      "newCheckTypes",
-      "nonStandardJsDocs",
-      "suspiciousCode",
-      "strictModuleDepCheck",
-      "typeInvalidation",
-      "undefinedNames",
-      "undefinedVars",
-      "unknownDefines",
-      "uselessCode",
-      "visibility"
-    ],
-    "extra_annotation_name": [
-      "api", "observable"
-    ],
-    "jscomp_off": [
-      "es5Strict"
-    ],
-    "compilation_level": "WHITESPACE_ONLY",
-    "output_wrapper": "var CLOSURE_DEPS = false;\n%output%",
-    "use_types_for_optimization": false,
-    "manage_closure_dependencies": true
-  }
-}

buildcfg/readme.md

@@ -1,12 +0,0 @@
-# Build configs
-
-This directory includes configuration files (json) for the tasks/build.js
-build script.
-
-Notes:
-
-`use_types_for_optimization` is set to `false` for the SIMPLE and WHITESPACE
-builds.  If it was set to `true` we would get function names like
-`ol_control_Control_prototype$setMap` in the compiled code when using the
-SIMPLE compilation. `use_types_for_optimization` is only appropriate for
-ADVANCED compilation. To be sure we also don't set it for WHITESPACE.

closure-util.json

@@ -1,3 +1,3 @@
 {
-  "library_url": "https://github.com/google/closure-library/archive/ab89cf45c216615d73a2f5dea720afb9d3415d1f.zip"
+  "library_url": "https://github.com/google/closure-library/archive/fb35d5232edef340dd9a7c6e479556829d0fa452.zip"
 }

config/examples-all.json

@@ -1,23 +1,30 @@
 {
   "exports": [],
-  "src": ["src/**/*.js", "build/examples/all.js"],
+  "src": [
+    "src/**/*.js",
+    "build/examples/all.js"
+  ],
   "compile": {
+    "js": [
+      "externs/olx.js",
+      "externs/oli.js"
+    ],
     "externs": [
       "externs/bingmaps.js",
       "externs/bootstrap.js",
       "externs/closure-compiler.js",
       "externs/example.js",
       "externs/geojson.js",
-      "externs/jquery-1.7.js",
-      "externs/oli.js",
-      "externs/olx.js",
+      "externs/jquery-1.9.js",
       "externs/proj4js.js",
       "externs/tilejson.js",
       "externs/topojson.js",
       "externs/vbarray.js"
     ],
     "define": [
+      "goog.array.ASSUME_NATIVE_FUNCTIONS=true",
       "goog.dom.ASSUME_STANDARDS_MODE=true",
+      "goog.json.USE_NATIVE_JSON=true",
       "goog.DEBUG=false"
     ],
     "jscomp_error": [
@@ -33,6 +40,7 @@
       "deprecated",
       "duplicateMessage",
       "es3",
+      "es5Strict",
       "externsValidation",
       "fileoverviewTags",
       "globalThis",
@@ -58,11 +66,8 @@
     "extra_annotation_name": [
       "api", "observable"
     ],
-    "jscomp_off": [
-      "es5Strict"
-    ],
     "compilation_level": "ADVANCED",
-    "output_wrapper": "// OpenLayers 3. See http://ol3.js.org/\n(function(){%output%})();",
+    "output_wrapper": "// OpenLayers 3. See http://ol3js.org/\n(function(){%output%})();",
     "use_types_for_optimization": true,
     "manage_closure_dependencies": true
 

config/jsdoc/api/conf.json

@@ -1,7 +1,7 @@
 {
     "opts": {
         "recurse": true,
-        "template": "apidoc/template"
+        "template": "config/jsdoc/api/template"
     },
     "tags": {
         "allowUnknownTags": true
@@ -17,12 +17,12 @@
     },
     "plugins": [
         "node_modules/jsdoc/plugins/markdown",
-        "apidoc/plugins/inheritdoc",
-        "apidoc/plugins/interface",
-        "apidoc/plugins/typedefs",
-        "apidoc/plugins/events",
-        "apidoc/plugins/observable",
-        "apidoc/plugins/api"
+        "config/jsdoc/api/plugins/inheritdoc",
+        "config/jsdoc/api/plugins/interface",
+        "config/jsdoc/api/plugins/typedefs",
+        "config/jsdoc/api/plugins/events",
+        "config/jsdoc/api/plugins/observable",
+        "config/jsdoc/api/plugins/api"
     ],
     "markdown": {
         "parser": "gfm"

config/jsdoc/api/index.md

@@ -30,7 +30,7 @@ Interactions for [vector features](ol.Feature.html)
 <br>[Formats](ol.format.Feature.html) for reading/writing vector data
 <br>[ol.format.WMSCapabilities](ol.format.WMSCapabilities.html)</td></tr>
 <tr><th>Projections</th><th>2-way bindings</th><th>Other components</th></tr>
-<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>

config/jsdoc/api/plugins/api.js

@@ -72,7 +72,6 @@ function includeAugments(doclet) {
 }
 
 var api = [];
-var augments = {};
 var classes = {};
 
 exports.handlers = {

config/jsdoc/api/plugins/events.js

@@ -19,7 +19,7 @@ exports.handlers = {
 
   parseComplete: function(e) {
     var doclets = e.doclets;
-    var eventClass, doclet, i, ii, j, jj, event, fires;
+    var doclet, i, ii, j, jj, event, fires;
     for (i = 0, ii = doclets.length - 1; i < ii; ++i) {
       doclet = doclets[i];
       if (doclet.fires) {

config/jsdoc/api/plugins/inheritdoc.js

@@ -87,7 +87,7 @@ exports.handlers = {
               for (l = candidates.length - 1; l >= 0; --l) {
                 candidate = candidates[l];
                 if (candidate && !candidate.inheritdoc) {
-                  stability = candidate.stability || incompleteDoclet.stability
+                  stability = candidate.stability || incompleteDoclet.stability;
                   if (stability) {
                     incompleteDoclet.stability = stability;
                     for (key in candidate) {

config/jsdoc/api/plugins/interface.js

@@ -1,4 +1,3 @@
-var util = require('util');
 exports.defineTags = function(dictionary) {
 
   var classTag = dictionary.lookUp('class');

config/jsdoc/api/plugins/observable.js

@@ -34,6 +34,9 @@ exports.handlers = {
         } else if (doclet.name.indexOf('set') === 0) {
           observable.readonly = false;
         }
+        if (doclet.stability) {
+          observable.stability = doclet.stability;
+        }
         if (!cls.observables) {
           cls.observables = [];
         }
@@ -44,7 +47,7 @@ exports.handlers = {
         if (!cls.fires) {
           cls.fires = [];
         }
-        var event = 'ol.ObjectEvent#event:change:' + name.toLowerCase();
+        event = 'ol.ObjectEvent#event:change:' + name;
         if (cls.fires.indexOf(event) == -1) {
           cls.fires.push(event);
         }

config/jsdoc/api/plugins/typedefs.js

@@ -28,6 +28,10 @@ exports.handlers = {
   newDoclet: function(e) {
     var doclet = e.doclet;
     if (doclet.meta.filename == 'olx.js') {
+      // do nothing if not marked @api
+      if (!doclet.stability) {
+        return;
+      }
       if (doclet.kind == 'typedef') {
         lastOlxTypedef = doclet;
         olxTypes[doclet.longname] = [];

config/jsdoc/api/template/publish.js

@@ -79,14 +79,6 @@ function addSignatureTypes(f) {
     f.signature = (f.signature || '') + '<span class="type-signature">'+(types.length? ' :'+types.join('|') : '')+' </span>';
 }
 
-function addAttribs(f) {
-    var attribs = helper.getAttribs(f);
-
-    if (attribs.length) {
-        f.attribs = '<span class="type-signature ' + (attribs[0] === 'static' ? 'static' : '') + '">' + htmlsafe(attribs.length ? attribs.join(',') : '') + ' </span>';
-    }    
-}
-
 function shortenPaths(files, commonPrefix) {
     // always use forward slashes
     var regexp = new RegExp('\\\\', 'g');
@@ -198,11 +190,19 @@ function attachModuleSymbols(doclets, modules) {
  */
 function buildNav(members) {
     var nav = [];
-
-    if (members.namespaces.length) {
-        _.each(members.namespaces, function (v) {
-          // exclude 'olx' from sidebar
-          if (v.longname.indexOf('olx') !== 0) {
+    // merge namespaces and classes, then sort
+    var merged = members.namespaces.concat(members.classes);
+    merged.sort(function (a, b) {
+      if (a.longname > b.longname)
+        return 1;
+      if (a.longname < b.longname)
+        return -1;
+      return 0;
+    });
+    _.each(merged, function (v) {
+      // exclude 'olx' and interfaces from sidebar
+      if (v.longname.indexOf('olx') !== 0 && v.interface !== true) {
+          if (v.kind == 'namespace') {
             nav.push({
                 type: 'namespace',
                 longname: v.longname,
@@ -225,13 +225,7 @@ function buildNav(members) {
                 })
             });
           }
-        });
-    }
-
-    if (members.classes.length) {
-        _.each(members.classes, function (v) {
-          // ignore interfaces
-          if (v.interface !== true) {
+          if (v.kind == 'class') {
             nav.push({
                 type: 'class',
                 longname: v.longname,
@@ -255,9 +249,8 @@ function buildNav(members) {
                 })
             });
           }
-        });
-    }
-
+      }
+    });
     return nav;
 }
 
@@ -404,7 +397,6 @@ exports.publish = function(taffyData, opts, tutorials) {
         if ( needsSignature(doclet) ) {
             addSignatureParams(doclet);
             addSignatureReturns(doclet);
-            addAttribs(doclet);
         }
     });
     
@@ -414,12 +406,10 @@ exports.publish = function(taffyData, opts, tutorials) {
 
         if (doclet.kind === 'member') {
             addSignatureTypes(doclet);
-            addAttribs(doclet);
         }
         
         if (doclet.kind === 'constant') {
             addSignatureTypes(doclet);
-            addAttribs(doclet);
             doclet.kind = 'member';
         }
     });

config/jsdoc/api/template/static/scripts/main.js

@@ -52,4 +52,13 @@ $(function () {
 
     $(window).on('resize', _onResize);
     _onResize();
-});
+
+    // show/hide unstable items
+    var unstable = $('.unstable');
+    var stabilityToggle = $('#stability-toggle');
+    stabilityToggle.change(function() {
+        unstable.toggle(!this.checked);
+        return false;
+    });
+    unstable.toggle(!stabilityToggle[0].checked);
+});

config/jsdoc/api/template/static/styles/jaguar.css

@@ -183,6 +183,10 @@ li {
   font-size: 0.8em;
   padding: 2px 4px;
 }
+td.description span.stability {
+  float: left;
+  margin-right: 0.5em;
+}
 span.type-signature.static {
   margin-right: 3px;
 }
@@ -282,7 +286,6 @@ span.type-signature.static {
   width: 110px;
 }
 .main table .type {
-  width: 60px;
   color: #aaa;
   font-size: 12px;
 }
@@ -369,3 +372,12 @@ footer {
 .main .readme table ul li {
   margin-bottom: 0;
 }
+.unstable {
+  display: none;
+}
+#stability {
+  color: white;
+  position: absolute;
+  top: 1em;
+  right: 8em;
+}

config/jsdoc/api/template/tmpl/layout.tmpl

@@ -18,8 +18,11 @@
 <div class="navbar navbar-inverse navbar-fixed-top">
   <div class="navbar-inner">
     <div class="container">
-      <a class="brand" href="/"><img src="../resources/logo.png"> OpenLayers 3</a>
+      <a class="brand" href="/"><img src="../resources/logo.png" width="40"> OpenLayers 3</a>
       <a class="brand" href="index.html">API Documentation</a>
+      <label id="stability">
+        <input type="checkbox" id="stability-toggle" checked> Stable Only
+      </label>
     </div>
   </div>
 </div>

config/jsdoc/api/template/tmpl/members.tmpl

@@ -9,7 +9,7 @@ if (data.type && data.type.names) {
     });
 }
 ?>
-<dt>
+<dt class="<?js= (data.stability && data.stability !== 'stable') ? 'unstable' : '' ?>">
     <div class="nameContainer">
         <h4 class="name" id="<?js= id ?>">
             <?js= data.attribs + (data.scope === 'static' ? longname : name)  + typeSignature ?>
@@ -20,7 +20,7 @@ if (data.type && data.type.names) {
     <p class="summary"><?js= summary ?></p>
     <?js } ?>
 </dt>
-<dd>
+<dd class="<?js= (data.stability && data.stability !== 'stable') ? 'unstable' : '' ?>">
     <?js if (data.description) { ?>
     <div class="description">
         <?js= data.description ?>

config/jsdoc/api/template/tmpl/method.tmpl

@@ -2,7 +2,7 @@
 var data = obj;
 var self = this;
 ?>
-<dt>
+<dt class="<?js= (data.stability && data.stability !== 'stable') ? 'unstable' : '' ?>">
     <div class="nameContainer<?js if (data.inherited) { ?> inherited<?js } ?>">
         <?js if (data.stability || kind !== 'class') { ?>
         <h4 class="name" id="<?js= id ?>">
@@ -23,7 +23,7 @@ var self = this;
     <p class="summary"><?js= summary ?></p>
     <?js } ?>
 </dt>
-<dd>
+<dd class="<?js= (data.stability && data.stability !== 'stable') ? 'unstable' : '' ?>">
     
     <?js if (data.description) { ?>
     <div class="description">
@@ -67,7 +67,7 @@ var self = this;
               description = eventDoclet.description.replace(/<[^>]*>/g, '');
             }
         ?>
-        <li>
+        <li class="<?js= (eventDoclet || data).stability !== 'stable' ? 'unstable' : '' ?>">
             <code><?js= self.linkto(f, type) ?></code>
             <?js if (eventClassName) {
               var eventClass = self.find({longname: eventClassName})[0];

config/jsdoc/api/template/tmpl/navigation.tmpl

@@ -15,7 +15,6 @@ var self = this;
                 <?js if (item.type === 'namespace' &&
                         (item.members.length + item.typedefs.length + item.methods.length +
                          item.events.length > 0)) { ?>
-                <span class="static">static</span>
                 <?js } ?>
             </span>
             <ul class="members itemMembers">
@@ -40,7 +39,9 @@ var self = this;
             <?js
                 item.typedefs.forEach(function (v) {
             ?>
-                <li data-name="<?js= v.longname ?>"><?js= self.linkto(v.longname, v.name) ?></li>
+                <li data-name="<?js= v.longname ?>" class="<?js= v.stability !== 'stable' ? 'unstable' : ''?>">
+                    <?js= self.linkto(v.longname, v.name) ?>
+                </li>
             <?js
                 });
             }
@@ -55,36 +56,9 @@ var self = this;
 
                 item.methods.forEach(function (v) {
             ?>
-                <li data-name="<?js= v.longname ?>"><?js= self.linkto(v.longname, v.name) ?></li>
-            <?js
-                });
-            }
-            ?>
-            </ul>
-            <ul class="fires itemMembers">
-            <?js
-            if (item.fires && item.fires.length) {
-            ?>
-            <span class="subtitle">Fires</span>
-            <?js
-                item.fires.forEach(function (v) {
-                    v = self.find({longname: v})[0] || {longname: v, name: v.split(/#?event:/)[1]};
-            ?>
-                <li data-name="<?js= v.longname ?>"><?js= self.linkto(v.longname, v.name) ?></li>
-            <?js
-                });
-            }
-            ?>
-            </ul>
-            <ul class="events itemMembers">
-            <?js
-            if (item.events.length) {
-            ?>
-            <span class="subtitle">Events</span>
-            <?js
-                item.events.forEach(function (v) {
-            ?>
-                <li data-name="<?js= v.longname ?>"><?js= self.linkto(v.longname, v.name) ?></li>
+                <li data-name="<?js= v.longname ?>" class="<?js= v.stability !== 'stable' ? 'unstable' : ''?>">
+                    <?js= self.linkto(v.longname, v.name) ?>
+                </li>
             <?js
                 });
             }

config/jsdoc/api/template/tmpl/observables.tmpl

@@ -21,7 +21,7 @@
         var setter = prop.readonly ? 'no' : 'yes';
   ?>
 
-    <tr>
+    <tr class="<?js= prop.stability !== 'stable' ? 'unstable' : '' ?>">
       <td class="name"><code><?js= prop.name ?></code></td>
       <td class="type">
       <?js if (prop.type && prop.type.names) {?>

config/jsdoc/api/template/tmpl/params.tmpl

@@ -71,7 +71,7 @@
 	        if (!param) { return; }
 	?>
 	
-        <tr>
+        <tr class="<?js= (param.stability && param.stability !== 'stable') ? 'unstable' : '' ?>">
             <?js if (params.hasName) {?>
                 <td class="name"><code><?js= param.name.replace(/^opt_/, "") ?></code></td>
             <?js } ?>
@@ -93,17 +93,8 @@
             <?js } ?>
             
             <td<?js= (param.subparams ? ' colspan=' + colspan : ' ') ?> class="description last">
-                <?js if (params.hasAttributes) {?>
-                    <?js if (param.optional) { ?>
-                        <span class="optional">optional</span>
-                    <?js } ?>
-                    <?js if (param.nullable) { ?>
-                        <span class="nullable">nullable</span>
-                    <?js } ?>
-              
-                    <?js if (param.variable) { ?>
-                        <span class="repeatable">repeatable</span>
-                    <?js } ?>
+                <?js if (param.stability) { ?>
+                    <?js= self.partial('stability.tmpl', param) ?>
                 <?js } ?>
                 <?js= param.description ?><?js if (param.subparams) { ?>
                 <?js= self.partial('params.tmpl', param.subparams) ?>

config/jsdoc/info/conf.json

@@ -1,7 +1,7 @@
 {
     "opts": {
         "recurse": true,
-        "template": "buildcfg/jsdoc/info"
+        "template": "config/jsdoc/info"
     },
     "tags": {
         "allowUnknownTags": true
@@ -10,7 +10,8 @@
         "includePattern": "\\.js$"
     },
     "plugins": [
-        "buildcfg/jsdoc/info/api-plugin",
-        "buildcfg/jsdoc/info/define-plugin"
+        "config/jsdoc/info/api-plugin",
+        "config/jsdoc/info/define-plugin",
+        "config/jsdoc/info/virtual-plugin"
     ]
 }

config/jsdoc/info/publish.js

@@ -0,0 +1,175 @@
+/**
+ * @fileoverview Generates JSON output based on exportable symbols (those with
+ * an api tag) and boolean defines (with a define tag and a default value).
+ */
+var assert = require('assert');
+var fs = require('fs');
+var path = require('path');
+
+
+/**
+ * Publish hook for the JSDoc template.  Writes to JSON stdout.
+ * @param {function} data The root of the Taffy DB containing doclet records.
+ * @param {Object} opts Options.
+ */
+exports.publish = function(data, opts) {
+
+  function getTypes(data) {
+    var types = [];
+    data.forEach(function(name) {
+      types.push(name.replace(/^function$/, 'Function'));
+    });
+    return types;
+  }
+
+  // get all doclets with the "api" property or define (excluding events) or
+  // with olx namespace
+  var classes = {};
+  var docs = data(
+      [
+        {define: {isObject: true}},
+        function() {
+          if (this.kind == 'class') {
+            if (!('extends' in this) || typeof this.api == 'string') {
+              classes[this.longname] = this;
+              return true;
+            }
+          }
+          return (typeof this.api == 'string' ||
+              this.meta && (/[\\\/]externs$/).test(this.meta.path));
+        }
+      ],
+      {kind: {'!is': 'file'}},
+      {kind: {'!is': 'event'}}).get();
+
+  // get symbols data, filter out those that are members of private classes
+  var symbols = [];
+  var defines = [];
+  var typedefs = [];
+  var externs = [];
+  var base = [];
+  var augments = {};
+  var names = {};
+  docs.filter(function(doc) {
+    var include = true;
+    var constructor = doc.memberof;
+    if (constructor && constructor.substr(-1) === '_') {
+      assert.strictEqual(doc.inherited, true,
+          'Unexpected export on private class: ' + doc.longname);
+      include = false;
+    }
+    return include;
+  }).forEach(function(doc) {
+    var isExterns = (/[\\\/]externs$/).test(doc.meta.path);
+    if (isExterns && doc.longname.indexOf('olx.') === 0) {
+      if (doc.kind == 'typedef') {
+        typedefs.push({
+          name: doc.longname,
+          types: ['{}']
+        });
+      } else {
+        var typedef = typedefs[typedefs.length - 1];
+        var type = typedef.types[0];
+        typedef.types[0] = type
+            .replace(/\}$/, ', ' + doc.longname.split('#')[1] +
+                ': (' + getTypes(doc.type.names).join('|') + ')}')
+            .replace('{, ', '{');
+      }
+    } else if (doc.define) {
+      defines.push({
+        name: doc.longname,
+        description: doc.description,
+        path: path.join(doc.meta.path, doc.meta.filename),
+        default: doc.define.default
+      });
+    } else if (doc.kind == 'typedef' || doc.isEnum === true) {
+      typedefs.push({
+        name: doc.longname,
+        types: getTypes(doc.type.names)
+      });
+    } else {
+      var types;
+      var symbol = {
+        name: doc.longname,
+        kind: doc.kind,
+        description: doc.classdesc || doc.description,
+        stability: doc.api,
+        path: path.join(doc.meta.path, doc.meta.filename)
+      };
+      if (doc.augments) {
+        symbol.extends = doc.augments[0];
+      }
+      if (doc.virtual) {
+        symbol.virtual = true;
+      }
+      if (doc.type) {
+        symbol.types = getTypes(doc.type.names);
+      }
+      if (doc.params) {
+        var params = [];
+        doc.params.forEach(function(param) {
+          var paramInfo = {
+            name: param.name
+          };
+          params.push(paramInfo);
+          paramInfo.types = getTypes(param.type.names);
+          if (typeof param.variable == 'boolean') {
+            paramInfo.variable = param.variable;
+          }
+          if (typeof param.optional == 'boolean') {
+            paramInfo.optional = param.optional;
+          }
+          if (typeof param.nullable == 'boolean') {
+            paramInfo.nullable = param.nullable;
+          }
+        });
+        symbol.params = params;
+      }
+      if (doc.returns) {
+        symbol.returns = {
+          types: getTypes(doc.returns[0].type.names)
+        };
+        if (typeof doc.returns[0].nullable == 'boolean') {
+          symbol.returns.nullable = doc.returns[0].nullable;
+        }
+      }
+      if (doc.tags) {
+        doc.tags.every(function(tag) {
+          if (tag.title == 'template') {
+            symbol.template = tag.value;
+            return false;
+          }
+          return true;
+        });
+      }
+
+      var target = isExterns ? externs : (doc.api ? symbols : base);
+      target.push(symbol);
+      names[symbol.name] = true;
+
+      if (doc.api && symbol.extends) {
+        while (symbol.extends in classes && !classes[symbol.extends].api &&
+            classes[symbol.extends].augments) {
+          symbol.extends = classes[symbol.extends].augments[0];
+        }
+        if (symbol.extends) {
+          augments[symbol.extends] = true;
+        }
+      }
+    }
+  });
+
+  base = base.filter(function(symbol) {
+    return (symbol.name in augments || symbol.virtual);
+  });
+
+  process.stdout.write(
+      JSON.stringify({
+        symbols: symbols,
+        defines: defines,
+        typedefs: typedefs,
+        externs: externs,
+        base: base
+      }, null, 2));
+
+};

config/jsdoc/info/virtual-plugin.js

@@ -0,0 +1,16 @@
+/**
+ * Handle the interface and abstract annotations.
+ * @param {Object} dictionary The tag dictionary.
+ */
+exports.defineTags = function(dictionary) {
+
+  var classTag = dictionary.lookUp('class');
+  dictionary.defineTag('interface', {
+    mustHaveValue: false,
+    onTagged: function(doclet, tag) {
+      classTag.onTagged.apply(this, arguments);
+      doclet.virtual = true;
+    }
+  });
+
+};

config/ol-debug.json

@@ -0,0 +1,3 @@
+{
+  "exports": ["*"]
+}

config/ol.json

@@ -1,6 +1,5 @@
 {
   "exports": ["*"],
-  "src": ["src/**/*.js"],
   "compile": {
     "externs": [
       "externs/bingmaps.js",
@@ -14,7 +13,9 @@
       "externs/vbarray.js"
     ],
     "define": [
+      "goog.array.ASSUME_NATIVE_FUNCTIONS=true",
       "goog.dom.ASSUME_STANDARDS_MODE=true",
+      "goog.json.USE_NATIVE_JSON=true",
       "goog.DEBUG=false"
     ],
     "jscomp_error": [
@@ -30,6 +31,7 @@
       "deprecated",
       "duplicateMessage",
       "es3",
+      "es5Strict",
       "externsValidation",
       "fileoverviewTags",
       "globalThis",
@@ -55,11 +57,8 @@
     "extra_annotation_name": [
       "api", "observable"
     ],
-    "jscomp_off": [
-      "es5Strict"
-    ],
     "compilation_level": "ADVANCED",
-    "output_wrapper": "// OpenLayers 3. See http://ol3.js.org/\n(function(){%output%})();",
+    "output_wrapper": "(function(){%output%})();",
     "use_types_for_optimization": true,
     "manage_closure_dependencies": true
   }

config/readme.md

@@ -0,0 +1,3 @@
+# Configuration Files
+
+This directory includes configuration files for the build scripts in and documentation templates.

css/ol.css

@@ -55,6 +55,10 @@
   right: .5em;
   transition: opacity .25s;
 }
+.ol-rotate.ol-hidden {
+  opacity: 0;
+  display: none;
+}
 .ol-zoom-extent {
   top: 4.643em;
   left: .5em;
@@ -191,6 +195,7 @@ button.ol-full-screen-true:after {
   text-align: right;
   bottom: .5em;
   right: .5em;
+  max-width: calc(100% - 1.3em);
 }
 
 .ol-attribution ul {
@@ -200,6 +205,7 @@ button.ol-full-screen-true:after {
   line-height: 1.375em;
   color: #000;
   text-shadow: 0 0 2px #fff;
+  max-width: calc(100% - 3.6em);
 }
 .ol-attribution li {
   display: inline;
@@ -219,6 +225,9 @@ button.ol-full-screen-true:after {
 .ol-attribution.ol-collapsed ul {
   display: none;
 }
+.ol-attribution.ol-logo-only ul {
+  display: block;
+}
 .ol-attribution:not(.ol-collapsed) {
   background: rgba(255,255,255,0.8);
 }
@@ -229,10 +238,17 @@ button.ol-full-screen-true:after {
   height: 1.1em;
   line-height: 1em;
 }
+.ol-attribution.ol-logo-only {
+  background: transparent;
+  bottom: .4em;
+  height: 1.1em;
+  line-height: 1em;
+}
 .ol-attribution.ol-uncollapsible img {
   margin-top: -.2em;
   max-height: 1.6em;
 }
+.ol-attribution.ol-logo-only button,
 .ol-attribution.ol-uncollapsible button {
   display: none;
 }
@@ -243,29 +259,20 @@ button.ol-full-screen-true:after {
   left: .5em;
   background: #eee;
   background: rgba(255, 255, 255, 0.4);
-  border-radius: 4px;
-  outline: none;
-  overflow: hidden;
-  width: 1.5675em;
+  width: 24px;
   height: 200px;
-  padding: 3px;
-  margin: 0;
 }
 .ol-zoomslider-thumb {
   position: absolute;
-  display: block;
   background: #7b98bc;
   background: rgba(0,60,136,0.5);
   border-radius: 2px;
-  outline: none;
-  overflow: hidden;
   cursor: pointer;
-  font-size: 1.14em;
-  height: 1em;
-  width: 1.375em;
+  height: 10px;
+  width: 22px;
   margin: 3px;
-  padding: 0;
 }
+
 .ol-touch .ol-zoomslider {
   top: 5.5em;
   width: 2.052em;
@@ -280,3 +287,40 @@ button.ol-full-screen-true:after {
 .ol-has-tooltip [role=tooltip] {
   font-family: 'Lucida Grande',Verdana,Geneva,Lucida,Arial,Helvetica,sans-serif;
 }
+
+.ol-overviewmap {
+  position: absolute;
+  left: 0.5em;
+  bottom: 0.5em;
+}
+.ol-overviewmap.ol-uncollapsible {
+  bottom: 0;
+  left: 0;
+  border-radius: 0 4px 0 0;
+}
+.ol-overviewmap .ol-overviewmap-map,
+.ol-overviewmap button {
+  display: inline-block;
+}
+.ol-overviewmap .ol-overviewmap-map {
+  border: 1px solid #7b98bc;
+  height: 150px;
+  margin: 2px;
+  width: 150px;
+}
+.ol-overviewmap:not(.ol-collapsed) button{
+  bottom: 1px;
+  left: 2px;
+  position: absolute;
+}
+.ol-overviewmap:not(.ol-collapsed) button:hover [role=tooltip],
+.ol-overviewmap.ol-collapsed .ol-overviewmap-map,
+.ol-overviewmap.ol-uncollapsible button {
+  display: none;
+}
+.ol-overviewmap:not(.ol-collapsed) {
+  background: rgba(255,255,255,0.8);
+}
+.ol-overviewmap-box {
+  border: 2px dotted rgba(0,60,136,0.7);
+}

doc/quickstart.hbs

@@ -13,14 +13,14 @@ Below you'll find a complete working example.  Create a new file, copy in the co
 <!doctype html>
 <html lang="en">
   <head>
-    <link rel="stylesheet" href="http://ol3js.org/en/{{ latest }}/css/ol.css" type="text/css">
+    <link rel="stylesheet" href="http://openlayers.org/en/{{ latest }}/css/ol.css" type="text/css">
     <style>
       .map {
         height: 400px;
         width: 100%;
       }
     </style>
-    <script src="http://ol3js.org/en/{{ latest }}/build/ol.js" type="text/javascript"></script>
+    <script src="http://openlayers.org/en/{{ latest }}/build/ol.js" type="text/javascript"></script>
     <title>OpenLayers 3 example</title>
   </head>
   <body>
@@ -55,10 +55,10 @@ To include a map a web page you will need 3 things:
 ### Include OpenLayers
 
 ```xml
-  <script src="http://ol3js.org/en/{{ latest }}/build/ol.js" type="text/javascript"></script>
+  <script src="http://openlayers.org/en/{{ latest }}/build/ol.js" type="text/javascript"></script>
 ```
 
-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.
 
 
 ### `<div>` to contain the map

doc/tutorials/introduction.md

@@ -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.

examples/accessible.html

@@ -64,7 +64,7 @@
 
     </div>
 
-    <script src="jquery.min.js" type="text/javascript"></script>
+    <script src="../resources/jquery.min.js" type="text/javascript"></script>
     <script src="../resources/example-behaviour.js" type="text/javascript"></script>
     <script src="loader.js?id=accessible" type="text/javascript"></script>
 

examples/animation.html

@@ -57,7 +57,7 @@
 
     </div>
 
-    <script src="jquery.min.js" type="text/javascript"></script>
+    <script src="../resources/jquery.min.js" type="text/javascript"></script>
     <script src="../resources/example-behaviour.js" type="text/javascript"></script>
     <script src="loader.js?id=animation" type="text/javascript"></script>
 

examples/attributions.html

@@ -43,7 +43,7 @@
 
     </div>
 
-    <script src="jquery.min.js" type="text/javascript"></script>
+    <script src="../resources/jquery.min.js" type="text/javascript"></script>
     <script src="../resources/example-behaviour.js" type="text/javascript"></script>
     <script src="loader.js?id=attributions" type="text/javascript"></script>
 

examples/bind-input.html

@@ -84,7 +84,7 @@
 
     </div>
 
-    <script src="jquery.min.js" type="text/javascript"></script>
+    <script src="../resources/jquery.min.js" type="text/javascript"></script>
     <script src="../resources/example-behaviour.js" type="text/javascript"></script>
     <script src="loader.js?id=bind-input" type="text/javascript"></script>
 

examples/bind-input.js

@@ -1,17 +1,17 @@
-goog.require('ol.BrowserFeature');
 goog.require('ol.Map');
 goog.require('ol.View');
 goog.require('ol.control');
 goog.require('ol.dom.Input');
+goog.require('ol.has');
 goog.require('ol.layer.Tile');
 goog.require('ol.source.OSM');
 
 
 function checkWebGL(evt) {
   document.getElementById('no-webgl').style.display =
-      ol.BrowserFeature.HAS_WEBGL ? 'none' : '';
+      ol.has.WEBGL ? 'none' : '';
   document.getElementById('has-webgl').style.display =
-      ol.BrowserFeature.HAS_WEBGL && !evt.glContext ? '' : 'none';
+      ol.has.WEBGL && !evt.glContext ? '' : 'none';
   document.getElementById('webgl').style.display =
       evt.glContext ? '' : 'none';
 }

examples/bing-maps.html

@@ -42,6 +42,7 @@
           <h4 id="title">Bing Maps example</h4>
           <p id="shortdesc">Example of a Bing Maps layer.</p>
           <div id="docs">
+            <p>When the Bing Maps tile service doesn't have tiles for a given resolution and region it returns "placeholder" tiles indicating that. Zoom the map beyond level 19 to see the "placeholder" tiles. If you want OpenLayers to display stretched tiles in place of "placeholder" tiles beyond zoom level 19 then set <code>maxZoom</code> to <code>19</code> in the options passed to <code>ol.source.BingMaps</code>.</p>
             <p>See the <a href="bing-maps.js" target="_blank">bing-maps.js source</a> to see how this is done.</p>
           </div>
           <div id="tags">bing, bing-maps</div>
@@ -51,7 +52,7 @@
 
     </div>
 
-    <script src="jquery.min.js" type="text/javascript"></script>
+    <script src="../resources/jquery.min.js" type="text/javascript"></script>
     <script src="../resources/example-behaviour.js" type="text/javascript"></script>
     <script src="loader.js?id=bing-maps" type="text/javascript"></script>
 

examples/bing-maps.js

@@ -20,6 +20,9 @@ for (i = 0, ii = styles.length; i < ii; ++i) {
     source: new ol.source.BingMaps({
       key: 'Ak-dzM4wZjSqTlzveKz5u0d4IQ4bRzVI309GxmkgSVr1ewS6iPSrOvOKhA-CJlm3',
       imagerySet: styles[i]
+      // use maxZoom 19 to see stretched tiles instead of the BingMaps
+      // "no photos at this zoom level" tiles
+      // maxZoom: 19
     })
   }));
 }

examples/box-selection.html

@@ -0,0 +1,59 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta http-equiv="X-UA-Compatible" content="chrome=1">
+    <meta name="viewport" content="initial-scale=1.0, user-scalable=no, width=device-width">
+    <link rel="stylesheet" href="../css/ol.css" type="text/css">
+    <link rel="stylesheet" href="../resources/bootstrap/css/bootstrap.min.css" type="text/css">
+    <link rel="stylesheet" href="../resources/layout.css" type="text/css">
+    <link rel="stylesheet" href="../resources/bootstrap/css/bootstrap-responsive.min.css" type="text/css">
+    <title>Box selection example</title>
+  </head>
+  <body>
+
+    <div class="navbar navbar-inverse navbar-fixed-top">
+      <div class="navbar-inner">
+        <div class="container">
+          <a class="brand" href="./"><img src="../resources/logo.png"> OpenLayers 3 Examples</a>
+        </div>
+      </div>
+    </div>
+
+    <div class="container-fluid">
+
+      <div class="row-fluid">
+        <div class="span12">
+          <div id="map" class="map"></div>
+        </div>
+      </div>
+
+      <div class="row-fluid">
+
+        <div class="span4">
+          <h4 id="title">Box selection example</h4>
+          <p id="shortdesc">Using a DragBox interaction to select features.</p>
+          <div id="docs">
+            <p>This example shows how to use a <code>DragBox</code> interaction to select features. Selected features are added
+            to the feature overlay of a select interaction (<code>ol.interaction.Select</code>) for highlighting.</p>
+            <p>Use <code>SHIFT+drag</code> to draw boxes.</p>
+            <p>See the <a href="box-selection.js" target="_blank">box-selection.js source</a> to see how this is done.</p>
+          </div>
+          <div id="tags">DragBox, feature, selection, box</div>
+        </div>
+        <div class="span4 offset4">
+          <div id="info" class="alert alert-success">
+            &nbsp;
+          </div>
+        </div>
+
+      </div>
+
+    </div>
+
+    <script src="../resources/jquery.min.js" type="text/javascript"></script>
+    <script src="../resources/example-behaviour.js" type="text/javascript"></script>
+    <script src="loader.js?id=box-selection" type="text/javascript"></script>
+
+  </body>
+</html>

examples/box-selection.js

@@ -0,0 +1,81 @@
+goog.require('ol.Map');
+goog.require('ol.View');
+goog.require('ol.events.condition');
+goog.require('ol.interaction');
+goog.require('ol.interaction.DragBox');
+goog.require('ol.interaction.Select');
+goog.require('ol.layer.Tile');
+goog.require('ol.layer.Vector');
+goog.require('ol.source.GeoJSON');
+goog.require('ol.source.OSM');
+goog.require('ol.style.Stroke');
+goog.require('ol.style.Style');
+
+
+var vectorSource = new ol.source.GeoJSON({
+  projection: 'EPSG:3857',
+  url: 'data/geojson/countries.geojson'
+});
+
+
+var map = new ol.Map({
+  layers: [
+    new ol.layer.Tile({
+      source: new ol.source.OSM()
+    }),
+    new ol.layer.Vector({
+      source: vectorSource
+    })
+  ],
+  renderer: 'canvas',
+  target: 'map',
+  view: new ol.View({
+    center: [0, 0],
+    zoom: 2
+  })
+});
+
+// a normal select interaction to handle click
+var select = new ol.interaction.Select();
+map.addInteraction(select);
+
+var selectedFeatures = select.getFeatures();
+
+// a DragBox interaction used to select features by drawing boxes
+var dragBox = new ol.interaction.DragBox({
+  condition: ol.events.condition.shiftKeyOnly,
+  style: new ol.style.Style({
+    stroke: new ol.style.Stroke({
+      color: [0, 0, 255, 1]
+    })
+  })
+});
+
+map.addInteraction(dragBox);
+
+var infoBox = document.getElementById('info');
+
+dragBox.on('boxend', function(e) {
+  // features that intersect the box are added to the collection of
+  // selected features, and their names are displayed in the "info"
+  // div
+  var info = [];
+  var extent = dragBox.getGeometry().getExtent();
+  vectorSource.forEachFeatureIntersectingExtent(extent, function(feature) {
+    selectedFeatures.push(feature);
+    info.push(feature.get('name'));
+  });
+  if (info.length > 0) {
+    infoBox.innerHTML = info.join(', ');
+  }
+});
+
+// clear selection when drawing a new box and when clicking on the map
+dragBox.on('boxstart', function(e) {
+  selectedFeatures.clear();
+  infoBox.innerHTML = ' ';
+});
+map.on('click', function() {
+  selectedFeatures.clear();
+  infoBox.innerHTML = ' ';
+});

examples/brightness-contrast.html

@@ -66,7 +66,7 @@
 
     </div>
 
-    <script src="jquery.min.js" type="text/javascript"></script>
+    <script src="../resources/jquery.min.js" type="text/javascript"></script>
     <script src="../resources/example-behaviour.js" type="text/javascript"></script>
     <script src="loader.js?id=brightness-contrast" type="text/javascript"></script>
 

examples/brightness-contrast.js

@@ -1,6 +1,6 @@
-goog.require('ol.BrowserFeature');
 goog.require('ol.Map');
 goog.require('ol.View');
+goog.require('ol.has');
 goog.require('ol.layer.Tile');
 goog.require('ol.source.MapQuest');
 
@@ -14,7 +14,7 @@ function setResetContrastButtonHTML() {
   resetContrast.innerHTML = 'Contrast (' + layer.getContrast().toFixed(3) + ')';
 }
 
-if (!ol.BrowserFeature.HAS_WEBGL) {
+if (!ol.has.WEBGL) {
   var info = document.getElementById('no-webgl');
   /**
    * display error message

examples/canvas-tiles.html

@@ -44,7 +44,7 @@
 
     </div>
 
-    <script src="jquery.min.js" type="text/javascript"></script>
+    <script src="../resources/jquery.min.js" type="text/javascript"></script>
     <script src="../resources/example-behaviour.js" type="text/javascript"></script>
     <script src="loader.js?id=canvas-tiles" type="text/javascript"></script>
 

examples/center.html

@@ -123,7 +123,7 @@
 
     </div>
 
-    <script src="jquery.min.js" type="text/javascript"></script>
+    <script src="../resources/jquery.min.js" type="text/javascript"></script>
     <script src="loader.js?id=center" type="text/javascript"></script>
     <script src="../resources/example-behaviour.js" type="text/javascript"></script>
 

examples/cluster.html

@@ -8,7 +8,7 @@
     <link rel="stylesheet" href="../resources/bootstrap/css/bootstrap.min.css" type="text/css">
     <link rel="stylesheet" href="../resources/layout.css" type="text/css">
     <link rel="stylesheet" href="../resources/bootstrap/css/bootstrap-responsive.min.css" type="text/css">
-    <title>R-Tree example</title>
+    <title>Clustering example</title>
   </head>
   <body>
 
@@ -31,21 +31,21 @@
       <div class="row-fluid">
 
         <div class="span12">
-          <h4 id="title">R-Tree example</h4>
-          <p id="shortdesc">R-Tree example. Please note that this example only works locally, it does not work when the examples are hosted.  This is because it accesses internals the R-Tree data structure, which are not exported in the API.</p>
+          <h4 id="title">Clustering example</h4>
+          <p id="shortdesc">Example of using <code>ol.Cluster</code>.</p>
           <div id="docs">
-            <p>See the <a href="rtree.js" target="_blank">rtree.js source</a> to see how this is done.</p>
+            <p>See the <a href="cluster.js" target="_blank">cluster.js source</a> to see how this is done.</p>
           </div>
-          <div id="tags">vector, rtree</div>
+          <div id="tags">cluster vector</div>
         </div>
 
       </div>
 
     </div>
 
-    <script src="jquery.min.js" type="text/javascript"></script>
+    <script src="../resources/jquery.min.js" type="text/javascript"></script>
     <script src="../resources/example-behaviour.js" type="text/javascript"></script>
-    <script src="loader.js?id=rtree" type="text/javascript"></script>
+    <script src="loader.js?id=cluster" type="text/javascript"></script>
 
   </body>
 </html>

examples/cluster.js

@@ -0,0 +1,80 @@
+goog.require('ol.Feature');
+goog.require('ol.Map');
+goog.require('ol.View');
+goog.require('ol.geom.Point');
+goog.require('ol.layer.Tile');
+goog.require('ol.layer.Vector');
+goog.require('ol.source.Cluster');
+goog.require('ol.source.MapQuest');
+goog.require('ol.source.Vector');
+goog.require('ol.style.Circle');
+goog.require('ol.style.Fill');
+goog.require('ol.style.Stroke');
+goog.require('ol.style.Style');
+goog.require('ol.style.Text');
+
+
+var count = 20000;
+var features = new Array(count);
+var e = 4500000;
+for (var i = 0; i < count; ++i) {
+  var coordinates = [2 * e * Math.random() - e, 2 * e * Math.random() - e];
+  features[i] = new ol.Feature(new ol.geom.Point(coordinates));
+}
+
+var source = new ol.source.Vector({
+  features: features
+});
+
+var clusterSource = new ol.source.Cluster({
+  distance: 40,
+  source: source
+});
+
+var styleCache = {};
+var clusters = new ol.layer.Vector({
+  source: clusterSource,
+  style: function(feature, resolution) {
+    var size = feature.get('features').length;
+    var style = styleCache[size];
+    if (!style) {
+      style = [new ol.style.Style({
+        image: new ol.style.Circle({
+          radius: 10,
+          stroke: new ol.style.Stroke({
+            color: '#fff'
+          }),
+          fill: new ol.style.Fill({
+            color: '#3399CC'
+          })
+        }),
+        text: new ol.style.Text({
+          text: size.toString(),
+          fill: new ol.style.Fill({
+            color: '#fff'
+          })
+        })
+      })];
+      styleCache[size] = style;
+    }
+    return style;
+  }
+});
+
+var raster = new ol.layer.Tile({
+  source: new ol.source.MapQuest({layer: 'sat'})
+});
+
+var raw = new ol.layer.Vector({
+  source: source
+});
+
+var map = new ol.Map({
+  layers: [raster, clusters],
+  renderer: 'canvas',
+  target: 'map',
+  view: new ol.View({
+    center: [0, 0],
+    zoom: 2
+  })
+});

examples/custom-controls.html

@@ -82,7 +82,7 @@
       </div>
     </div>
 
-    <script src="jquery.min.js" type="text/javascript"></script>
+    <script src="../resources/jquery.min.js" type="text/javascript"></script>
     <script src="../resources/example-behaviour.js" type="text/javascript"></script>
     <script src="loader.js?id=custom-controls" type="text/javascript"></script>
 

examples/d3.html

@@ -44,7 +44,7 @@
 
     </div>
 
-    <script src="jquery.min.js" type="text/javascript"></script>
+    <script src="../resources/jquery.min.js" type="text/javascript"></script>
     <script src="http://d3js.org/d3.v3.min.js"></script>
     <script src="http://d3js.org/topojson.v1.min.js"></script>
     <script src="../resources/example-behaviour.js" type="text/javascript"></script>

examples/device-orientation.html

@@ -50,7 +50,7 @@
 
     </div>
 
-    <script src="jquery.min.js" type="text/javascript"></script>
+    <script src="../resources/jquery.min.js" type="text/javascript"></script>
     <script src="../resources/example-behaviour.js" type="text/javascript"></script>
     <script src="loader.js?id=device-orientation" type="text/javascript"></script>
 

examples/drag-and-drop-image-vector.html

@@ -48,7 +48,7 @@
 
     </div>
 
-    <script src="jquery.min.js" type="text/javascript"></script>
+    <script src="../resources/jquery.min.js" type="text/javascript"></script>
     <script src="../resources/example-behaviour.js" type="text/javascript"></script>
     <script src="loader.js?id=drag-and-drop-image-vector" type="text/javascript"></script>
 

examples/drag-and-drop.html

@@ -32,7 +32,7 @@
 
         <div class="span4">
           <h4 id="title">Drag-and-Drop example</h4>
-          <p id="shortdesc">Example of using the drag-and-drop interaction. Drag and drop GPX, GeoJSON, IGC, KML, or TopoJSON files on to the map.</p>
+          <p id="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>
           <div id="docs">
             <p>See the <a href="drag-and-drop.js" target="_blank">drag-and-drop.js source</a> to see how this is done.</p>
           </div>
@@ -48,7 +48,7 @@
 
     </div>
 
-    <script src="jquery.min.js" type="text/javascript"></script>
+    <script src="../resources/jquery.min.js" type="text/javascript"></script>
     <script src="../resources/example-behaviour.js" type="text/javascript"></script>
     <script src="loader.js?id=drag-and-drop" type="text/javascript"></script>
 

examples/drag-rotate-and-zoom.html

@@ -44,7 +44,7 @@
 
     </div>
 
-    <script src="jquery.min.js" type="text/javascript"></script>
+    <script src="../resources/jquery.min.js" type="text/javascript"></script>
     <script src="../resources/example-behaviour.js" type="text/javascript"></script>
     <script src="loader.js?id=drag-rotate-and-zoom" type="text/javascript"></script>
 

examples/draw-and-modify-features.html

@@ -53,7 +53,7 @@
 
     </div>
 
-    <script src="jquery.min.js" type="text/javascript"></script>
+    <script src="../resources/jquery.min.js" type="text/javascript"></script>
     <script src="../resources/example-behaviour.js" type="text/javascript"></script>
     <script src="loader.js?id=draw-and-modify-features" type="text/javascript"></script>
 

examples/draw-features.html

@@ -53,7 +53,7 @@
 
     </div>
 
-    <script src="jquery.min.js" type="text/javascript"></script>
+    <script src="../resources/jquery.min.js" type="text/javascript"></script>
     <script src="../resources/example-behaviour.js" type="text/javascript"></script>
     <script src="loader.js?id=draw-features" type="text/javascript"></script>
 

examples/dynamic-data.html

@@ -43,7 +43,7 @@
 
     </div>
 
-    <script src="jquery.min.js" type="text/javascript"></script>
+    <script src="../resources/jquery.min.js" type="text/javascript"></script>
     <script src="../resources/example-behaviour.js" type="text/javascript"></script>
     <script src="loader.js?id=dynamic-data" type="text/javascript"></script>
 

examples/epsg-4326.html

@@ -43,7 +43,7 @@
 
     </div>
 
-    <script src="jquery.min.js" type="text/javascript"></script>
+    <script src="../resources/jquery.min.js" type="text/javascript"></script>
     <script src="../resources/example-behaviour.js" type="text/javascript"></script>
     <script src="loader.js?id=epsg-4326" type="text/javascript"></script>