Table of Contents
The goal is to make AMD use a straightforward and consistent with html application SDLC. It comprize the modules embedding and use convention, unification of documentation, tests, design and support.
The modular structure is normalized across project parts and emphasize individual SDLC for its modules from dedicated version control repository to folder hierarchy and AMD MIDs convention.
Present structure in amdharness-app repository serves design and development phase of SDLC. During release builds most of packages could be fused into one or few bundles and perhaps embedded into release version of HTML page. AmdHarness does not encourage such builds as there is not much benefits but there are plenty of drawbacks(blog TBD).
The main HTML page runtime engine of amdharness based application is loader.js module. It will be a primary, often single entry point to JS code, application-wide config is embedded here. The page specific parameters and code triggered via embedded into page SCRIPT require() statements.
loader.js performs run- and build-time time replacement of various package builds like debug vs release vs bundle. That historically been done by altering index.html config and script tag for different builds. loader.js will eliminate the need for index.html versions and open main build profile for all pages in app like tests so they will run against same JS environment as whole app.
loader.js minimizes initial UX and functional appearance by phasing the application resources load to
- initial(loading...) HTML+CSS+JS set
- front page UI components set resources
- rest of reused in various application modules dependencies
- leaving minor individual modules/widgets dependencies to run time.
The most popular APIs have dedicated MIDs for short naming and easy implementation switch. Among those:
- "cssQuery" - jQuery dom manipulation. There are 3 implementations to choose from:
- amdharness.org/CssQuery/dojo-jQuery - shim to load dojo/query and jQuery API support
- shimbhala.org/CssQuery/jQuery - shim for cssQuery css selector goup operations
- amdharness.org/CssQuery/jQuery - shim to load genuine jQuery via AMD
- "cssI!" AMD plugin to embed CSS link into page. Alternatives are XStyle, tbd.
- "textTemplate!" shortcut to "text!myTemplate.html!strip" pligin with following implementations:
- amdharness.org/amd/text/textTemplate - shim for "dojo/text!" with bug fixes for relative MIDs.
- "dojo/text" - genuine template loading plugin, does not support relative MIDs.
- require.js "text!" plugin, does not have a concept of context replacement, hence not aware of MIDs at all.
made a fist-class citizen. Shims embedded into loader.js will fix the lack of relative MIDs on page, template and parser levels in AMD provider like dojo or Require.js. I.e it is permitted and encouraged to use relative MIDs everywhere starting from HTML pages, test pages and templates.
loader.js reside within <var>app/loader</var> subfolder mapped to AmdHarness-app-loader-dojo repository embedded as git subtree. Such use of AmdHarness-loader [todo] as embedded in your project folder will allow:
- Keep index.html same for different builds
- Switch config profiles via pointing to different git submodule. Options are like:
- In release profile the
debug=1URL query parameter will switch the compiled bundles to matching revision of source code for simpler source-level troubleshooting.
- Future releases capabilities. There is a promise to keep listing of compatible loaders on project Wiki opened
- Application specific loader customization. Could be done by
- app-specific branching of selected default loader and applying app changes there.
- AmdHarnessLoader global variable (script attribute TBD) will customize page-specific parameters.
- Final release build could exclude as AMD as harness loader leaving just compiled bundle within loader.js ; Showcase TBD.
- In addition to index.html, the loader.js is used in folders/files of html templates or simple widget test pages.
- Commonly used module with given API are embedded into config: cssQuery (link) - jQuery API for html dom and events manipulation. Other tbd.
- Alternatives to toolkits. Many aspects of dojo toolkit could be implemented by other libraries like AMD loader by RequireJS, cssQuery by jQuery, etc.
You wanted to use CDN for multiple reasons like reduction of your server load or gain on CDN speed and presence in browser's cache (faster load). But since CDN is out of your control and could be blocked in some cases it is in app interest to fall back to copy deployed along with web application.
loader.js has the module defined as an array of URLs which will be tried in listed order until one will be resolved successfully. dojo.js is an AMD loader and a primary JS file used to make a distinction whether CDN has full dojo family module.
In amdharness-app the few CDN versions of dojo will be tried first and only if not found the local version will be used.
While module does not need to be part of project to be used by app via AMD, it is essential to be able consistently to track all modules revisions as one for maintenance and application release control.
Git subtree gives ability to embed exact revision of external module into source tree. In addition to keeping the track it will allow to make application-specific fixes into application repository without the need to alter original sources. Still permitting upstream commits to contribute your fixes to external module and also merging external module updates back to application.
Default dependency modules added to project by
To initialize another external module in application( replace <var>lib/dojotoolkit.org/dojo</var> with your org/module as folder path and your git link with revision ):
cd amdharness-app # make an "dojo" alias name for remote repo for brevity git remote add -t 1.10 dojo https://github.com/dojo/dojo.git git fetch dojo git subtree add -P lib/dojotoolkit.org/dojo dojo/1.10 --squash
you could use "master" instead of 1.10 branch to use the latest. It is advisable only when planning to change the module and contribute it back.
To see all remote aliases
git remote -v
To commit local changes into remote project.
- commit local changes
- subtree merge, pull and finally push to secondary repo branch.
git subtree merge -P app/loader master git subtree pull -P app/loader AmdHarness-app-loader-dojo master git subtree push -P app/loader AmdHarness-app-loader-dojo master