Package examples in the build (dev2)

[cadaver]

This came up in a discussion with @jonnenauha . The current build system is missing a nice way to package the demos / examples along with the build.

[jonnenauha]

Right, due to the requirejs stuff (and how we use it atm.) this particular aspect of the build is kind of tricky. We want the examples to work while developing locally in requirejs mode with grunt dev and after producing a build without any extra steps.

Here are my suggested steps how to accomplish nice and developer friendly system.

Moving /examples

1. Move /examples under /html/examples. /html is the root where the client is ran. Easier to keep things simple when using relative refs etc.
2. Adding one extra ../ to the requirejs config baseUrl path in all of the examples should be enough in terms of mods. eg. https://github.com/realXtend/WebTundra/blob/dev2/examples/Physics2/main.js#L7

Dynamic example indexing

No one want to start upkeeping a file manually that lists all the examples a`la http://threejs.org/examples/ (not sure if they upkeep this manually, just an example, though I've noticed they upkeep lot of the docs by hand [no jsdoc etc. omg]).

We need to make this page visually appealing with screenshots and short descs of each examples. Easy one click run of the example. I'm thinking it should look something like the three.js landing page at http://threejs.org/ with some text and link on top what this thing actually is and what it can do. Each example should be sharable as a link so it just works when you share it (think facebook, email, slack).

• Create a dynamic /html/examples/index.html that resolves all the subdirs, fetches some default example-desc.json or similar to populate the UI.
  • This ofc means the naming of certain files needs to be mandatory like index.html main.js etc.
  • I don't actually know how in practical terms this should be done without relying on HTTP API hooks for listing. This kind of API is what our SDK provides to populate the UI, but lets say you host this with apache how would it work. I'll have to look into this.

Build automation to strip requirejs

This is where it gets a bit tricky, but it's pretty much the same thing we are now doing for any requirejs module under /src during the build. But in this case we would be processing the main.js files of all examples and modifying their index.html to include the build+deps and then the main.js file that will bootstrap the example (like it does now).

After build completes and /build/examples has been created find all main.js and index.html from the dir.

1. For main.js strip the require encaplusation out.
   • Remove top block from index 0 to the first instance of { after "require(" eg. https://github.com/realXtend/WebTundra/blob/dev2/examples/Physics2/main.js#L1-L48
   • Remove bottom block, anything after the last index of }) that is the remaining closing statement of require({ app code })
2. For index.html remove use of requirejs and inject needed core+deps include then include the main.js script eg. https://github.com/realXtend/WebTundra/blob/dev2/examples/Physics2/index.html#L25
   • This is fairly simple to do with finding/regexing certain strings and just replacing them with something else.
   • To be frank, all the index.html should be exactly the same under examples. The css etc. needs to be put into a .css file so we dont have to go into each file if we want to change the base css. As they are identical, we can just fixup one index.html and copy it to all of the subfolders. Never the less some examples might want to do some crazy stuff in thei index.html so maybe just better automate and process them one at a time.

The above thing is and looks complex, but at the end of the day its not that hard to automate with grunt. I've done exactly this with our html/client.html. Once done its really nice as you dont need to upkeep one file for local dev and one file for production. We also need to provide a build version of a generic client.html exactly like this.

Too much complexity?

The other option is to only provide examples a) for dev mode b) for build mode But not for both, if you don't want to manually upkeep two versions of index.html+main.js. At Admino our current example system is only for the build env. This is very annoying while you are developing the examples as a developer, if you do changes to core/plugins etc. you need to roll the complete build (that lets face it, is slow as shit).

I would really like to do this properly this time :)

---

Do note that this is a task for Adminotech. Me and @cvetan5 will work on this. I'm just letting you know the plan and what the rationale and challenges are behind this.

[jonnenauha]

The new grunt stuff @cvetan5 has already ported should bring the build steps for client.html so you can see whats happening there. We can do the examples in a similar fashion.