Requirements for examples

[pagameba]

This is meant to be a starting point for discussion on how the ol3 examples should be structured to meet various needs. This is supposed to be a summary of our hangout discussion, if I have missed any points please add them.

I think, as the discussion evolves, we will want to capture the salient points and requirements in a wiki page but for now this is about gathering input from interested parties.

One basic assumption in all of this is that just modifying the hosted examples to use ol.js does not meet the project needs and I am discarding that as an option.

As I understand it, there are several user stories (please add more if they don't fit these ones)

1. As an OpenLayers Core Developer I want to execute integration tests with the examples so that I can ensure the exports and require dependencies are correct
   • export tests should against ol-all.js (is this right?)
   • testing require dependencies relies on goog.require and a loader to load them
2. As an OpenLayers Core Developer I want to run an example in debug mode so that I can easily investigate issues with the examples reported by Application Developers
   • run locally by a developer to investigate problems
   • use whitespace or loader mode to easily view code involved in the problem
3. As an Application Developer I want to see how to use the OpenLayers API to accomplish a specific task so that I can use the API correctly in my own code
   • use ol.js compiled in advanced mode

@marcjansen made a good point that the public, hosted examples could (and should) be used to promote the ability of the library to build aggressively minimized versions specific to an application. A couple of suggestions from this point were made, specifically

• each example could include an indication of how big an optimized build would be for this example. This could be computed during a release preparation phase and embedded in the examples
• each example could include a link to the online build tool that includes the configuration hash to reproduce a minimal build for the example. MooTools online build tool includes in the resulting build a link back to the builder that includes a hash that pre-selects the same options used to create the original build. Perhaps something like this could be used.

@ahocevar suggested using a templating system (such as jade) for the examples to ease the process of using them for development vs hosted versions. This could be combined with a local http server (node+express perhaps) to serve up the examples for development purposes.

It was suggested that hosting a debug build of the examples might be useful as well. The following might be use cases we want to incorporate ...

1. As an Application Developer I want to trace code from the example into OL core so that I understand how it works internally.
   • My feeling on this is that if they are willing to get into the weeds then they can run npm install ol3 && npm serve to get the examples in debug mode.
2. As an Application Developer I want to trace an error in the examples into the OL core so that **I can dig into it and provide more details or suggest a fix."
   • In this case, I think we want to encourage them to set up a local copy to put them on the path to eventually contributing a fix via PR.
3. As an Application Developer I want to what's going on under the hood in the online examples so that I can get a sense of how thing work without having to set up a working copy locally.
   • We could easily ignore this or push them towards using a working copy, but I think this point is about perception of the library and we should not discard it out of hand.

Whatever is decided, the build system needs to facilitate the preparation of the examples to meet each of the requirements. Ideally it could be done with a minimum of change to the actual examples themselves, or at least automated.

[probins]

on the debug build: an alternative for application developers who want to dig into what's going on is to use the whitespace build together with the console. And of course there's always the tried and tested 'look at the source'. :-) I don't myself feel any need for a debug build, but as you say if I did I can always install a development version on my local machine.

[probins]

each example could include an indication of how big an optimized build would be for this example. This could be computed during a release preparation phase and embedded in the examples

each example could include a link to the online build tool that includes the configuration hash to reproduce a minimal build for the example. MooTools online build tool includes in the resulting build a link back to the builder that includes a hash that pre-selects the same options used to create the original build. Perhaps something like this could be used.

it sounds to me like these are two different builds. AIUI the MooTools tool works on the basis of having the library split into predefined chunks of code, which you then assemble into a combined build. jQueryUI has a similar tool. Compiling app code with the ol library using advanced_optimizations is at a much lower level, only including the functions used. Of course, the online build tool could offer both options.

I think having the build size documented in each example is a good idea.

[elemoine]

1. As an OpenLayers Core Developer I want to execute integration tests with the examples so that I can ensure the exports and require dependencies are correct
   • export tests should against ol-all.js (is this right?)

No. See this ol3-dev email for more information. Currently we check the examples against ol.js, ol-simple.js and ol-whitespace.js (and in debug mode as well). See the check-example target. This may be overkill, I think we could check the examples against ol.js only.

[probins]

I think there is another 'user story': "I'm an app developer, and I want an example of how to create a custom build."

I've been trying out various custom builds and realise that app developers face similar issues if they want to do this. Building the examples could show how.

For development, the simplest is to use a pre-built; probably ol.js for the most part, with ol-whitespace.js for debugging. You just load that in a script tag. You may just deploy that in production. But as you get near to deployment, you may want a more specific build. If so, whether that be built locally or with an online tool, you have a similar situation with your first user story: you have to create a dependency tree, and to do that you have to provide a list of the namespaces you want to use. You can provide a list to closurebuilder (-n ol.Map -n ol.View2D etc) which is probably enough if you only have one or a small number of apps to build. The alternative is to use goog.require()s, as the examples are currently doing. However, you don't want these if you're using a pre-built, so my solution for using either/or is to put the require()s together with a goog.provide('myapp') in a separate file (similar to the build.cfg in ol2), and give this to closurebuilder (along with --root=ol3/src and whatever else you need) to build the dependency tree and the uncompiled script; then give this script together with myapp.js to the compiler. Then, all you have to do is change the script tag to use your build rather than the standard one. I don't need a loader for that; any editor will do :-)

With advanced builds, you also have to think about what externs/exports you need. Again, the examples could perhaps should demonstrate this.

[elemoine]

Thanks @probins. In my mind custom builds don't include application code (ol code only) and are always compiled with ADVANCED optimizations. I'm not sure custom builds created with SIMPLE optimizations make sense, because I fear that "simple builds" will always be big – we, for example, depend on goog packages/files that include (possibly lot of) code that we don't use. I may wrong, but "custom advanced builds" sound like a better target to me.

Also, as an application developer, I want to create a build config file (a text file, yaml for example), that I commit into my project's code repository. Online tools are nice, but I personally want to version-control my build config/profile.

I had imagined (I just did actually) something like this for build config files:

# References to ol exports files (a.k.a. pre-packaged exports)
exports_files:
- src/ol/map.exports
- src/ol/view2d.exports
- src/ol/source/osmsource.exports

# Additional exports
# Allows for finer-grained exports, and for exporting things that are otherwise considered private
exports:
- @exportProperty ol.Map.prototype.getPixelFromCoordinate

# Defines (compilation-level variables)
# For example used to include/exclude big functionality chunks.
defines:
  ol.ENABLE_WEBGL: false
  ol.ENABLE_DOM: false
  ol.ENABLE_TOUCH: true

Interested to know if that makes sense to others.

[probins]

In my mind custom builds don't include application code

be interested in your reasons for this. To me, a major advantage of advanced compile is that I can include my own code and only get the functionality I use, so a much smaller build. And I would prefer to use the tools provided by Closure rather than have a separate/additional config file; I can put compiler options like defines (not currently documented, btw) in a flagfile.

[elemoine]

In my mind custom builds don't include application code

be interested in your reasons for this.

Because I write application code, and use libraries (Angular), that don't conform to the restrictions imposed by the advanced optimizations. And I think I'm not the only one.

[probins]

right. Well, in that case, compiling the examples probably isn't too relevant to you.

That means you can't customise the library, for example, sub-classing, doesn't it? I haven't tried, but I'm thinking that if you want to create a sub-class, then you need to compile it with the library class.

[elemoine]

right. Well, in that case, compiling the examples probably isn't too relevant to you.

Compiling the examples help maintain the examples. It gives us confidence that the examples work with the lib. That's it.

That means you can't customise the library, for example, sub-classing, doesn't it? I haven't tried, but I'm thinking that if you want to create a sub-class, then you need to compile it with the library class.

You can. See http://ol3js.org/en/master/examples/custom-controls.js.

[probins]

I think we could check the examples against ol.js only.

if you make this change, then ISTM @pagameba's story 1 becomes like story 3 and no longer needs a loader

[probins]

and another user story: I'm a core developer and want to check that examples function with different renderers.
At the moment, the renderer fromquerydata thingy is in most examples. I think this is misleading, as it implies that apps have to have this, but it's not something you would normally have in production code. At the least, I think there should be a comment in the examples to explain why it's in there.

[probins]

and a further user story: I'm a developer and want to contribute examples

[elemoine]

With Tim's work on build.js and the ongoing work on removing Plovr (#2222) we can close this.