Development setup

Pocket.gl is based on these front-end libraries:

If you want to modify the source and test or build the library, you have to install first all the dependencies using Bower, a front-end package manager based on node.js.

Assumed you have already installed in your system node.js and npm, you can install Bower using npm.

$ npm install -g bower

Now, inside the project folder, run the following command to install all the dependencies:

$ bower install

If everything went right you should find all the external packages inside the bower_components directory.

Testing

The examples directory contains a series of shader examples. Each example is contained in a sub-directory of examples/data. The complete list of example directories is specified in the examples.js file. If you add a new example, you should add a new entry in the array inside examples.js. Point your browser to the examples folder through a local webserver to see all the examples in action (but if you use Firefox you can see the examples also through a file:// URL).

The index.html page runs the examples using the dist/pocket.gl.min.js build file. It is useful to check if the builds are working fine.

During development you should open the examples/dev-test.html page. This page loads all the source modules and external dependencies using require.js. Use this page to test changes to the code and to search for regressions by cycling through all the examples. Make sure to disable your browser cache when in development, because require.js will always load each module from the cache even if you reload the page on your browser. A simple way to disable the cache in Chrome is opening the Developer Tools window and check Disable cache inside the Network section; then, every time the developer tools are opened, the cache is disabled. If you are working with Firefox, you can open a new Private window and work there. If you are using Internet Explorer 11/Edge, open the Edge Deveveloper Tools and enable Always refresh from server inside the Network tool page.

Use Defensive Rendering

pocket.gl is designed to be embedded directly on a page without using iframes. We are rendering on somebody else’s DOM and this requires taking steps to output HTML and CSS that minimize the impact of the parent page on our application. The publisher could unknowingly have CSS rules and/or JavaScript code that inadvertently target our widget and wreak havoc.

Before writing HTML or CSS code, I recommend taking a look at the rules explained in this nice article: Defensive HTML and CSS.

Build

The build process is based on the require.js optimizer to combine all modules into a single (minified) file and on almond to add a replacement AMD loader for require.js when the library is used as a Browser Global instead of an AMD module.

These batch scripts can be used to build the library:

  • build/build.bat – will generate the dist/pocket.gl.js unminified library
  • build/build-min.bat – will generate the dist/pocket.gl.min.js minified library
  • build/build-all.bat – will generate both