The Launchpad JavaScript Build System

Current in process of deprecating, see combo loader docs below.

Most of the Launchpad JavaScript is bundled, minified, and distributed in one large stand-alone file: launchpad.js.

Adding new JavaScript modules

To add a new JavaScript module simply add a new <script> line to lib/lp/app/templates/base-layout-macros.pt in the large <devmode> JavaScript block. The file you add to the list will be automatically included in the launchpad.js roll-up and used by both the test runner and the LP production site.

Two special scripts, utilities/yui_deps.py and utilities/lp-deps.py, look in lib/lp/app/templates/base-layout-macros.pt for <script> lines. The corresponding minified script files (the version of the file ending with "-min.js") will be added to launchpad.js.

After making your changes you will probably want to run:

$ make clean_js && make jsbuild

Adding a third-party widget

The current story for adding a third-party widget is to put it in lib/lp/contrib. (You can read the mailing list discussion about the adoption of this location.)

For CSS, follow the rules above to modify the tools. If other assets are needed, you'll need to create a link in lib/canonical/launchpad/icing to the proper place in lib/lp/contrib so the assets can be found. See lib/canonical/launchpad/icing/yui3-gallery for an example.

New Combo loader Setup

Currently an alternative JavaScript build process is under development using the YUI combo loader system. JavaScipt files are copied and minified into a build directory build/js/.

Files are served out of the build/js directory based on the YUI combo loader config that is constructed in the lib/lp/app/templates/base-layout-macros.pt. These are combined and served out via the convoy wsgi application through Aapche.

Developing Javascript

Because the JS files need to be copied from the Launchpad tree into the build directory, changes to any JS files must trigger a build. You can build manually using make jsbuild. There's also a helper script that can watch the launchpad tree for any JS changes and auto build as the changes occur. You can start that process with make jsbuild_watch. This allows for faster JS development iterating.

Adding new Javascript modules

To add new JS to Launchpad, it needs to go into a proper YUI module. All modules should be located either in an app, such as lib/lp/bugs/javascript/, or in the base shared space lib/lp/app/javascript/.

Running a make jsbuild will copy the new module into the build directory in the proper location.

Once the files is created and part of the build directory, you can just include that module name in any YUI block.

    LPJS.use('modulename', function (Y)...

The combo loader will serve your new module when you reload the page with that content on it.

Launchpad CSS

Adding a new CSS file

Launchpad combines and minifies all of its CSS files into 'combo.css' before publishing them. The build tool is SCSS, installed via NPM. To add a new CSS file, add a reference to 'combo.scss'. New YUI/LP components can be added to css/components/_index.scss.