From 6966863dc3f6314fbba5eb9077a0eaa0dece51d6 Mon Sep 17 00:00:00 2001 From: Joe Catera Date: Tue, 5 Jun 2012 12:06:23 -0700 Subject: [PATCH 01/45] Started draft docs for the resource store. --- docs/dev_guide/topics/resource_store.rst | 61 ++++++++++++++++++++++++ 1 file changed, 61 insertions(+) create mode 100644 docs/dev_guide/topics/resource_store.rst diff --git a/docs/dev_guide/topics/resource_store.rst b/docs/dev_guide/topics/resource_store.rst new file mode 100644 index 000000000..582b6a934 --- /dev/null +++ b/docs/dev_guide/topics/resource_store.rst @@ -0,0 +1,61 @@ +============== +Resource Store +============== + + +Intro +===== + +Purpose +------- + +Benefits +-------- + +How it Works? +------------- + +Resource Metadata +================= + +Resource Store Addons +===================== + +Intro +----- + +Requirements +------------ + +Core Addons +----------- + +selector +```````` + +config +`````` + +Additional Addons +----------------- + +instance +```````` + +routes +`````` + +staticHandler +````````````` + +yui +``` + +shaker +`````` + +Creating Custom Addons +---------------------- + + + From 9e44477f2b7c301799716a48ffd2fc05e82eeac8 Mon Sep 17 00:00:00 2001 From: Joe Catera Date: Wed, 6 Jun 2012 14:43:01 -0700 Subject: [PATCH 02/45] Stubbed out chapter, added notes, created table for metadata. --- docs/dev_guide/topics/resource_store.rst | 269 ++++++++++++++++++++++- 1 file changed, 267 insertions(+), 2 deletions(-) diff --git a/docs/dev_guide/topics/resource_store.rst b/docs/dev_guide/topics/resource_store.rst index 582b6a934..c2caff1c0 100644 --- a/docs/dev_guide/topics/resource_store.rst +++ b/docs/dev_guide/topics/resource_store.rst @@ -3,38 +3,206 @@ Resource Store ============== + +.. Questions: + +.. Need definition for the resource store + +.. benefits? + +.. What is the location for the metadata? Is it a JSON config file like application.json + +.. metadata object: required, data types, defaults, examples + +.. resource addon examples + + Intro ===== +allow the resource store to have addons +move most (all?) of the current resource store functionality into addons that ship with mojito + +What is a Mojito Resource? +-------------------------- + Purpose ------- +Allow developers to write resource store addons to do interesting things with resources + + +specifically, allow the application authors to write resource store addons to accomplish interesting things with resources + +provide a mechanism so that addons can use AOP on the resource store (including addons) +provide a mechanism for other kinds of future-enabling extension points +allow custom (app-author provided) context-to-selector mapping +allow custom (app-author provided) resource types + + Benefits -------- +- developers can customize certain core features of Mojito through resource store addons, such as routing, selector +- developers can create new resource types + + How it Works? ------------- +#. loading resources from disk, resolving versions (as described above) +#. precalculating YUI module dependencies +#. expanding the specs into full instances +#. loading and parsing (via YCB) configuration files +#. (slightly) special loading of the routes files +#. calculating static handler URLs +#. calculating rollups and inline CSS + Resource Metadata ================= +Location +-------- + +Metadata Object +--------------- + ++------------------------+---------------+-----------+---------------+-------------------------------------------+ +| Property | Data Type | Required? | Default Value | Description | ++========================+===============+===========+===============+===========================================+ +| ``affinity`` | string | -- | -- | "server", "client", or "common" | ++------------------------+---------------+-----------+---------------+-------------------------------------------+ +| ``fs`` | string | -- | none | filesystem details | ++------------------------+---------------+-----------+---------------+-------------------------------------------+ +| ``id`` | string | yes | none | unique ID. common to all versions of the | +| | | | | resource. (typically | +| | | | | {type}-{subtype}-{name}) | ++------------------------+---------------+-----------+---------------+-------------------------------------------+ +| `` mojit`` | string | -- | none | which mojit this applies to, if any | +| | | | | ("shared" means the resource is available | +| | | | | to all mojits) | ++------------------------+---------------+-----------+---------------+-------------------------------------------+ +| ``name`` | string | yes | none | // name. common to all versions of the | +| | | | | resource | ++------------------------+---------------+-----------+---------------+-------------------------------------------+ +| `` pkg`` | string | -- | none | // packaging details | ++------------------------+---------------+-----------+---------------+-------------------------------------------+ +| `` source`` | string | no | | When ``true``, the ``manifest`` | +| | | | | attribute is added to ````. | ++------------------------+---------------+-----------+---------------+-------------------------------------------+ +| ``staticHandlerURL`` | string | yes | none | // path used to load the resource | +| | | | | onto the client | ++------------------------+---------------+-----------+---------------+-------------------------------------------+ +| ``subtype`` | string | no | none | // not all types have a subtype | ++------------------------+---------------+-----------+---------------+-------------------------------------------+ +| ``type`` | string | yes | none | | ++------------------------+---------------+-----------+---------------+-------------------------------------------+ +| ``yui`` | string | yes | none | // for resources that are YUI modules | ++------------------------+---------------+-----------+---------------+-------------------------------------------+ + + + +Example +------- + +.. code-block:: javascript + + { + source: // where the resource came from (not shipped to client) + fs: // filesystem details + pkg: // packaging details + mojit: // which mojit this applies to, if any ("shared" means the resource is available to all mojits) + type: + subtype: // not all types have a subtype + name: // name. common to all versions of the resource + id: // unique ID. common to all versions of the resource. (typically {type}-{subtype}-{name}) + staticHandlerURL: // path used to load the resource onto the client + yui: // for resources that are YUI modules + + // these are only used in the metadata for each resource version. the metadata + // for resolved resources won't have these, since they're intrinsically part of + // the resolved resource. + affinity: // "server", "client", or "common" + selector: + } + + Resource Store Addons ===================== Intro ----- + + Requirements ------------ Core Addons ----------- +How They Work +````````````` + +- walk resource versions, gathering mojit-specific resources into mojits +- precalculates ("resolves") which resource versions are used for each version of the mojit +- also keeps track of app-level resources (archetypes, commands, config files, and middleware). +- these are not versioned (no resolution needed) +- these are not otherwise grouped together +- provides methods for events, including those specialized for AOP +- host for addons +- explicitly uses these addons: selector, config +- is a YUI Base, in part to enable plugins to be implemented as YUI Plugin modules + - also provides event subsystem + - also provides simple AOP subsystem (beforeHostMethod() and afterHostMethod()) + selector ```````` +implements context-to-selector mapping +place where user implements their custom implementation +mojito ships with a default implementation, which the user can override + +returns a priority-orders list of selectors (aka POSL) + +Description +~~~~~~~~~~~ + +Requirements +~~~~~~~~~~~~ +since this is used directly by the core, all implementations need to provide the following method: +getListFromContext(ctx) + +Example +~~~~~~~ + config `````` +Description +~~~~~~~~~~~ + +provides access to the contents of the configuration files +defines new mojit-specific resource type: config (for the mojit's definition.json and defaults.json) +defines new app-level resource type: config (for application.json, routes.json, dimensions.json, etc) +mojito ships with a default implementation. it's not expected that users will write their own + +default implementation: +preloadFile() registers config files as type:config resources +listens for an event signifying the end of preload() +preloads the contents of the json files + +Requirements +~~~~~~~~~~~~ + +since this is used directly by the core, all implementations need to provide the following methods: +readYCBDimensions(cb) +returns all the defined YCB dimensions +readResource(ctx, res, cb) +reads the config file pointed to by the resource + +Example +~~~~~~~ + Additional Addons ----------------- @@ -42,20 +210,117 @@ Additional Addons instance ```````` +Description +~~~~~~~~~~~ + +provides access to mojit details +expands specs into full instances +defines new app-level resource type: spec (found in mojits/*/specs/*.json) +not used by resource store core, but critical to the mojito kernel + +Requirements +~~~~~~~~~~~~ + +mojito ships with a default implementation. it's not expected that users will write their own +getMojitDetails(ctx, mojitType, cb) +returns a single structure that contains all details needed by the mojito kernel +this is made by aggregating information from all the resources in the mojit +expandSpec(ctx, spec, cb) +takes the spec and expands it into the full mojit instance data needed by the mojito kernel + +Example +~~~~~~~ + + routes `````` +Description +~~~~~~~~~~~ + +provides access to the routes +not used by resource store core, but critical to the server-side mojito +mojito ships with a default implementation. it's not expected that users will write their own +provides a sugar method for reading all routes files, returning a single merged result + + +Requirements +~~~~~~~~~~~~ + +Example +~~~~~~~ + staticHandler ````````````` +Description +~~~~~~~~~~~ +calculates/manages the static handler URLs for resources +not used by resource store core, but used by the static handler middleware + + +Requirements +~~~~~~~~~~~~ + +before addResourceVersion() +for affinity:client resources, sets staticHandlerURL to the static handler URL for the resource +the URL might be a rollup URL +provides a method for the static handler middleware to find the filesystem path for a URL + +Example +~~~~~~~ + yui ``` -shaker -`````` +Description +~~~~~~~~~~~ + +detects which resources are YUI modules, gathering additional metadata +defines new mojit-specific resource type: yui-module (found in autoload/ or yui_modules/) +defines new mojit-specific resource type: yui-lang (found in lang/) +precalculates YUI dependencies for mojit controllers and binders +mojito ships with a default implementation. it's not expected that users will write their own + +Requirements +~~~~~~~~~~~~ +after preloadFile() +if in autoload/ or yui_modules/ makes a type:yui-module resource +if in lang/ makes a type:yui-lang resource +before addResourceVersion() +if it's a resource implemented as a YUI module, gathers the YUI module metadata about it +after resolveMojit() +calculates the YUI module dependencies for the controller +calculates the YUI module dependencies for each binder + +Example +~~~~~~~ + Creating Custom Addons ---------------------- +General Process +``````````````` + +Requirements +```````````` + +Example +``````` +shaker +~~~~~~ + +not part of mojito, given here as an example + +tweaks the staticHandlerURL to something very sophisticated +can be on CDN +can be multi-mojit rollup +listen for staticHandlerURL resource field change +updates to sophisticated version + + + + From 80edfa91c86eb78914725080f42941da0a5f85c9 Mon Sep 17 00:00:00 2001 From: Joe Catera Date: Thu, 7 Jun 2012 09:57:15 -0700 Subject: [PATCH 03/45] Adding notes to docs. --- docs/dev_guide/topics/resource_store.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/dev_guide/topics/resource_store.rst b/docs/dev_guide/topics/resource_store.rst index c2caff1c0..7bfde8846 100644 --- a/docs/dev_guide/topics/resource_store.rst +++ b/docs/dev_guide/topics/resource_store.rst @@ -16,6 +16,12 @@ Resource Store .. resource addon examples +.. Notes: + +.. the new RS is uses the YUI Plugin mechanism to mix in the RS addons. +.. http://yuilibrary.com/yui/docs/plugin/ +.. redirect users to the yui docs on that topic + Intro ===== From f7d76dd4f4be2c9a1ba55833ca37603c82102bde Mon Sep 17 00:00:00 2001 From: Joe Catera Date: Thu, 7 Jun 2012 14:58:13 -0700 Subject: [PATCH 04/45] Adding code examples of resource addons that come with Mojito. --- docs/dev_guide/topics/resource_store.rst | 430 +++++++++++++++++++++++ 1 file changed, 430 insertions(+) diff --git a/docs/dev_guide/topics/resource_store.rst b/docs/dev_guide/topics/resource_store.rst index 7bfde8846..48aff2378 100644 --- a/docs/dev_guide/topics/resource_store.rst +++ b/docs/dev_guide/topics/resource_store.rst @@ -209,6 +209,192 @@ reads the config file pointed to by the resource Example ~~~~~~~ +.. code-block:: javascript + + + YUI.add('addon-rs-config', function(Y, NAME) { + + var libfs = require('fs'), + libpath = require('path'), + libycb = require(libpath.join(__dirname, '../../../libs/ycb')); + + function RSAddonConfig() { + RSAddonConfig.superclass.constructor.apply(this, arguments); + } + RSAddonConfig.NS = 'config'; + RSAddonConfig.ATTRS = {}; + + Y.extend(RSAddonConfig, Y.Plugin.Base, { + + initializer: function(config) { + this.rs = config.host; + this.appRoot = config.appRoot; + this.mojitoRoot = config.mojitoRoot; + this.afterHostMethod('findResourceByConvention', this.findResourceByConvention, this); + this.beforeHostMethod('parseResource', this.parseResource, this); + + this._jsonCache = {}; // fullPath: contents as JSON object + this._ycbCache = {}; // fullPath: YCB config object + this._ycbDims = this._readYcbDimensions(); + }, + + + destructor: function() { + // TODO: needed to break cycle so we don't leak memory? + this.rs = null; + }, + + + getDimensions: function() { + return this.rs.cloneObj(this._ycbDims); + }, + + + /** + * Reads and parses a JSON file + * + * @method readConfigJSON + * @param fullPath {string} path to JSON file + * @return {mixed} contents of JSON file + */ + // TODO: async interface + readConfigJSON: function(fullPath) { + var json, + contents; + if (!libpath.existsSync(fullPath)) { + return {}; + } + json = this._jsonCache[fullPath]; + if (!json) { + try { + contents = libfs.readFileSync(fullPath, 'utf-8'); + json = JSON.parse(contents); + } catch (e) { + throw new Error('Error parsing JSON file: ' + fullPath); + } + this._jsonCache[fullPath] = json; + } + return json; + }, + + + /** + * reads a configuration file that is in YCB format + * + * @method readConfigYCB + * @param ctx {object} runtime context + * @param fullPath {string} path to the YCB file + * @return {object} the contextualized configuration + */ + // TODO: async interface + readConfigYCB: function(fullPath, ctx) { + var cacheKey, + json, + ycb; + + ctx = this.rs.mergeRecursive(this.rs.getStaticContext(), ctx); + + ycb = this._ycbCache[fullPath]; + if (!ycb) { + json = this.readConfigJSON(fullPath); + json = this._ycbDims.concat(json); + ycb = new libycb.Ycb(json); + this._ycbCache[fullPath] = ycb; + } + return ycb.read(ctx, {}); + }, + + + findResourceByConvention: function(source, mojitType) { + var fs = source.fs, + use = false; + + // we only care about files + if (!fs.isFile) { + return; + } + // we don't care about files in subdirectories + if ('.' !== fs.subDir) { + return; + } + // we only care about json files + if ('.json' !== fs.ext) { + return; + } + // use package.json for the app and the mojit + if ('package' === fs.basename && 'bundle' !== fs.rootType) { + use = true; + } + // use all configs in the application + if ('app' === fs.rootType) { + use = true; + } + // use configs from non-shared mojit resources + if (mojitType && 'shared' !== mojitType) { + use = true; + } + if (!use) { + return; + } + + return new Y.Do.AlterReturn(null, { + type: 'config' + }); + }, + + + parseResource: function(source, type, subtype, mojitType) { + var baseParts, + res; + + if ('config' !== type) { + return; + } + + baseParts = source.fs.basename.split('.'); + res = { + source: source, + type: 'config', + affinity: 'common', + selector: '*' + }; + if ('app' !== source.fs.rootType) { + res.mojit = mojitType; + } + if (baseParts.length !== 1) { + Y.log('invalid config filename. skipping ' + source.fs.fullPath, 'warn', NAME); + return; + } + res.name = libpath.join(source.fs.subDir, baseParts.join('.')); + res.id = [res.type, res.subtype, res.name].join('-'); + return new Y.Do.Halt(null, res); + }, + + + /** + * Read the application's dimensions.json file for YCB processing. If not + * available, fall back to the framework's default dimensions.json. + * + * @method _readYcbDimensions + * @return {array} contents of the dimensions.json file + * @private + */ + _readYcbDimensions: function() { + var path = libpath.join(this.appRoot, 'dimensions.json'); + if (!libpath.existsSync(path)) { + path = libpath.join(this.mojitoRoot, 'dimensions.json'); + } + return this.readConfigJSON(path); + } + + + }); + Y.namespace('mojito.addons.rs'); + Y.mojito.addons.rs.config = RSAddonConfig; + + }, '0.0.1', { requires: ['plugin', 'oop']}); + + Additional Addons ----------------- @@ -256,6 +442,75 @@ Requirements Example ~~~~~~~ +YUI.add('addon-rs-routes', function(Y, NAME) { + + var libpath = require('path'), + libycb = require(libpath.join(__dirname, '../../../libs/ycb')); + + function RSAddonRoutes() { + RSAddonRoutes.superclass.constructor.apply(this, arguments); + } + RSAddonRoutes.NS = 'routes'; + RSAddonRoutes.DEPS = ['config']; + RSAddonRoutes.ATTRS = {}; + + Y.extend(RSAddonRoutes, Y.Plugin.Base, { + + initializer: function(config) { + this.rs = config.host; + this.appRoot = config.appRoot; + }, + + + destructor: function() { + // TODO: needed to break cycle so we don't leak memory? + this.rs = null; + }, + + + read: function(env, ctx, cb) { + ctx.runtime = env; + var appConfig = this.rs.getAppConfig(ctx), + routesFiles = appConfig.routesFiles, + p, + path, + fixedPaths = {}, + out = {}, + ress, + r, + res, + path, + routes; + + for (p = 0; p < routesFiles.length; p += 1) { + path = routesFiles[p]; + // relative paths are relative to the application + if ('/' !== path.charAt(1)) { + path = libpath.join(this.appRoot, path); + } + fixedPaths[path] = true; + } + + ress = this.rs.getResources(env, ctx, {type:'config'}); + for (r = 0; r < ress.length; r += 1) { + res = ress[r]; + if (fixedPaths[res.source.fs.fullPath]) { + routes = this.rs.config.readConfigYCB(res.source.fs.fullPath, ctx); + out = Y.merge(out, routes); + } + } + + cb(null, out); + } + + + }); + Y.namespace('mojito.addons.rs'); + Y.mojito.addons.rs.routes = RSAddonRoutes; + +}, '0.0.1', { requires: ['plugin', 'oop']}); + + staticHandler ````````````` @@ -276,6 +531,7 @@ provides a method for the static handler middleware to find the filesystem path Example ~~~~~~~ + yui ``` @@ -302,6 +558,178 @@ calculates the YUI module dependencies for each binder Example ~~~~~~~ +.. code-block:: javascript + + /* + * Copyright (c) 2012, Yahoo! Inc. All rights reserved. + * Copyrights licensed under the New BSD License. + * See the accompanying LICENSE file for terms. + */ + + YUI.add('addon-rs-yui', function(Y, NAME) { + + var libfs = require('fs'), + libpath = require('path'), + libvm = require('vm'); + + function RSAddonYUI() { + RSAddonYUI.superclass.constructor.apply(this, arguments); + } + RSAddonYUI.NS = 'yui'; + RSAddonYUI.ATTRS = {}; + + Y.extend(RSAddonYUI, Y.Plugin.Base, { + + initializer: function(config) { + this.rs = config.host; + this.appRoot = config.appRoot; + this.mojitoRoot = config.mojitoRoot; + this.afterHostMethod('findResourceByConvention', this.findResourceByConvention, this); + this.beforeHostMethod('parseResource', this.parseResource, this); + this.beforeHostMethod('addResourceVersion', this.addResourceVersion, this); + }, + + + destructor: function() { + // TODO: needed to break cycle so we don't leak memory? + this.rs = null; + }, + + + findResourceByConvention: function(source, mojitType) { + var fs = source.fs; + + if (!fs.isFile) { + return; + } + if ('.js' !== fs.ext) { + return; + } + + if (fs.subDirArray.length >= 1 && ('autoload' === fs.subDirArray[0] || 'yui_modules' === fs.subDirArray[0])) { + return new Y.Do.AlterReturn(null, { + type: 'yui-module', + skipSubdirParts: 1 + }); + } + + if (fs.subDirArray.length >= 1 && 'lang' === fs.subDirArray[0]) { + return new Y.Do.AlterReturn(null, { + type: 'yui-lang', + skipSubdirParts: 1 + }); + } + }, + + + parseResource: function(source, type, subtype, mojitType) { + var fs = source.fs, + baseParts, + res; + + if ('yui-lang' === type) { + res = { + source: source, + mojit: mojitType, + type: 'yui-lang', + affinity: 'common', + selector: '*' + }; + if (!res.yui) { + res.yui = {}; + } + if (fs.basename === mojitType) { + res.yui.lang = ''; + } else if (mojitType === fs.basename.substr(0, mojitType.length)) { + res.yui.lang = fs.basename.substr(mojitType.length + 1); + } else { + logger.log('invalid YUI lang file format. skipping ' + fs.fullPath, 'error', NAME); + } + res.name = res.yui.lang; + res.id = [res.type, res.subtype, res.name].join('-'); + return new Y.Do.Halt(null, res); + } + + if ('yui-module' === type) { + baseParts = fs.basename.split('.'), + res = { + source: source, + mojit: mojitType, + type: 'yui-module', + affinity: 'server', + selector: '*' + }; + if (baseParts.length >= 3) { + res.selector = baseParts.pop(); + } + if (baseParts.length >= 2) { + res.affinity = baseParts.pop(); + } + if (baseParts.length !== 1) { + Y.log('invalid yui-module filename. skipping ' + fs.fullPath, 'warn', NAME); + return; + } + this._parseYUIModule(res); + res.name = res.yui.name; + res.id = [res.type, res.subtype, res.name].join('-'); + return new Y.Do.Halt(null, res); + } + }, + + + addResourceVersion: function(res) { + if ('.js' !== res.source.fs.ext) { + return; + } + if (res.yui && res.yui.name) { + // work done already + return; + } + // ASSUMPTION: no app-level resources are YUI modules + if (!res.mojit) { + return; + } + this._parseYUIModule(res); + }, + + + _parseYUIModule: function(res) { + var file, + ctx, + yui = {}; + file = libfs.readFileSync(res.source.fs.fullPath, 'utf8'); + ctx = { + console: { + log: function() {} + }, + window: {}, + document: {}, + YUI: { + add: function(name, fn, version, meta) { + yui.name = name; + yui.version = version; + yui.meta = meta || {}; + } + } + }; + try { + libvm.runInNewContext(file, ctx, res.source.fs.fullPath); + } catch (e) { + yui = null; + Y.log(e.message + '\n' + e.stack, 'error', NAME); + } + if (yui) { + res.yui = Y.merge(res.yui || {}, yui); + } + } + + + }); + Y.namespace('mojito.addons.rs'); + Y.mojito.addons.rs.yui = RSAddonYUI; + + }, '0.0.1', { requires: ['plugin', 'oop']}); + Creating Custom Addons ---------------------- @@ -314,6 +742,8 @@ Requirements Example ``````` + + shaker ~~~~~~ From 23ae6a90d03e8e252fd124d592028cdee03c6c06 Mon Sep 17 00:00:00 2001 From: Joe Catera Date: Fri, 8 Jun 2012 11:56:56 -0700 Subject: [PATCH 05/45] Reorganized doc, added sections, rewrote parts. --- docs/dev_guide/topics/resource_store.rst | 115 ++++++++++++++--------- 1 file changed, 69 insertions(+), 46 deletions(-) diff --git a/docs/dev_guide/topics/resource_store.rst b/docs/dev_guide/topics/resource_store.rst index 48aff2378..04d7e0791 100644 --- a/docs/dev_guide/topics/resource_store.rst +++ b/docs/dev_guide/topics/resource_store.rst @@ -21,19 +21,66 @@ Resource Store .. the new RS is uses the YUI Plugin mechanism to mix in the RS addons. .. http://yuilibrary.com/yui/docs/plugin/ .. redirect users to the yui docs on that topic +.. AOP: aspect-oriented programming or attribute oriented programming or something else? +.. allow the resource store to have addons +.. move most (all?) of the current resource store functionality into addons that ship with mojito +.. Examples of how to use the resource store Intro ===== -allow the resource store to have addons -move most (all?) of the current resource store functionality into addons that ship with mojito +The resource store is the Mojito framework code that managers and keeps track of the resources in your Mojito applications. +The resource store uses addons to do much of the work, which you can read about in `Resource Store Addons <>`_. +The code for the resource store is a `YUI Base `_, which enables plugins to be implemented as `YUI Plugin modules `_. +Being a YUI Base, the resource store also provides an event subsystem and a simple AOP substystem (methods ``beforeHostMethod`` and ``afterHostMethod``). + + What is a Mojito Resource? -------------------------- -Purpose -------- +At the application level, resources include archetypes, commands, configuration files, and middleware. At the mojit level, +resources include controllers, models, binders, configuration files, and views. Developers can also create their own types of +resources. + + +What Does the Resource Store Do? +-------------------------------- + +#. Load the resources from disk and resolving versions if any exist. +#. Precalculate the YUI module dependencies of the resources. +#. Expanding the specs (??) into full instances. +#. Load and parse context configuration files. +#. Load the routes files. +#. Calculate static handler URLs. +#. Calculate rollups and inline CSS. + +.. Don't think the following section is needed, but am leaving in doc for personal reference right now. + +General Process of Resource Store +--------------------------------- + +Understanding the workflow of the resource store will give help those who want to customize addons to write code and +help others who don't plan on customizing addons to debug. + +- walk resource versions, gathering mojit-specific resources into mojits +- precalculates ("resolves") which resource versions are used for each version of the mojit +- also keeps track of app-level resources (archetypes, commands, config files, and middleware). +- these are not versioned (no resolution needed) +- these are not otherwise grouped together +- provides methods for events, including those specialized for AOP +- host for addons +- explicitly uses these addons: selector, config +- is a YUI Base, in part to enable plugins to be implemented as YUI Plugin modules + - also provides event subsystem + - also provides simple AOP subsystem (beforeHostMethod() and afterHostMethod()) + +How Can Developers Use the Resource Store? +------------------------------------------ + +Developers can write addons for the resource store to have finer grain control over the management of resources +or extend the functionality of the resource store. The resource store has Allow developers to write resource store addons to do interesting things with resources @@ -46,23 +93,7 @@ allow custom (app-author provided) context-to-selector mapping allow custom (app-author provided) resource types -Benefits --------- - -- developers can customize certain core features of Mojito through resource store addons, such as routing, selector -- developers can create new resource types - - -How it Works? -------------- - -#. loading resources from disk, resolving versions (as described above) -#. precalculating YUI module dependencies -#. expanding the specs into full instances -#. loading and parsing (via YCB) configuration files -#. (slightly) special loading of the routes files -#. calculating static handler URLs -#. calculating rollups and inline CSS +To see the code for the resource store, see the `store.server.js `_. Resource Metadata ================= @@ -70,9 +101,15 @@ Resource Metadata Location -------- + Metadata Object --------------- +.. need better descriptions +.. default values +.. required +.. the table below is a rough approximation + +------------------------+---------------+-----------+---------------+-------------------------------------------+ | Property | Data Type | Required? | Default Value | Description | +========================+===============+===========+===============+===========================================+ @@ -111,6 +148,8 @@ Metadata Object Example ------- +.. need a real example + .. code-block:: javascript { @@ -133,35 +172,19 @@ Example } -Resource Store Addons -===================== +Built-In Resource Store Addons +========================== Intro ----- +Mojito comes with built-in resource store addons that are used by the resource store +and the Mojito framework. These resource store addons are required by the resource store and +the Mojito framework, so particular care must be taken when creating custom versions of them. +This chapter takes a look at the built-in resource store addons, so you can better understand their use or +customize your own versions. -Requirements ------------- - -Core Addons ------------ - -How They Work -````````````` - -- walk resource versions, gathering mojit-specific resources into mojits -- precalculates ("resolves") which resource versions are used for each version of the mojit -- also keeps track of app-level resources (archetypes, commands, config files, and middleware). -- these are not versioned (no resolution needed) -- these are not otherwise grouped together -- provides methods for events, including those specialized for AOP -- host for addons -- explicitly uses these addons: selector, config -- is a YUI Base, in part to enable plugins to be implemented as YUI Plugin modules - - also provides event subsystem - - also provides simple AOP subsystem (beforeHostMethod() and afterHostMethod()) - selector ```````` @@ -184,6 +207,7 @@ Example config `````` + Description ~~~~~~~~~~~ @@ -396,8 +420,7 @@ Example -Additional Addons ------------------ + instance ```````` From 1744073f8e2220ff1f56c2eb7ef246b155605889 Mon Sep 17 00:00:00 2001 From: Joe Catera Date: Mon, 11 Jun 2012 19:14:58 -0700 Subject: [PATCH 06/45] Fleshed out the table for metadata, worked on the built-in addons. --- docs/dev_guide/topics/resource_store.rst | 420 ++++++++++++++++------- 1 file changed, 297 insertions(+), 123 deletions(-) diff --git a/docs/dev_guide/topics/resource_store.rst b/docs/dev_guide/topics/resource_store.rst index 04d7e0791..1b37c3b4a 100644 --- a/docs/dev_guide/topics/resource_store.rst +++ b/docs/dev_guide/topics/resource_store.rst @@ -4,146 +4,224 @@ Resource Store -.. Questions: - -.. Need definition for the resource store - -.. benefits? +.. General Questions: -.. What is the location for the metadata? Is it a JSON config file like application.json +.. 1. Need formal definition for the resource store and resource. -.. metadata object: required, data types, defaults, examples +.. 2. What are the benefits of using the resource store? -.. resource addon examples +.. 3. Should the title of this chapter be about what users can do with resource store? I'm not sure if developers +.. will even read this chapter because they won't necessarily know what the resource store is. -.. Notes: +.. 4. Does AOP stand for aspect-oriented programming, attribute oriented programming, or something else? -.. the new RS is uses the YUI Plugin mechanism to mix in the RS addons. -.. http://yuilibrary.com/yui/docs/plugin/ -.. redirect users to the yui docs on that topic -.. AOP: aspect-oriented programming or attribute oriented programming or something else? -.. allow the resource store to have addons -.. move most (all?) of the current resource store functionality into addons that ship with mojito -.. Examples of how to use the resource store +.. _resource_store_intro: Intro ===== The resource store is the Mojito framework code that managers and keeps track of the resources in your Mojito applications. -The resource store uses addons to do much of the work, which you can read about in `Resource Store Addons <>`_. +The resource store uses addons to do much of the work, which you can read about in `Built-In Resource Store Addons `_. The code for the resource store is a `YUI Base `_, which enables plugins to be implemented as `YUI Plugin modules `_. -Being a YUI Base, the resource store also provides an event subsystem and a simple AOP substystem (methods ``beforeHostMethod`` and ``afterHostMethod``). +Being a YUI Base, the resource store also provides an event subsystem and a simple AOP subsystem (methods ``beforeHostMethod`` and ``afterHostMethod``). +.. _intro-what: What is a Mojito Resource? -------------------------- At the application level, resources include archetypes, commands, configuration files, and middleware. At the mojit level, resources include controllers, models, binders, configuration files, and views. Developers can also create their own types of -resources. +resources. See `Types of Resources `_ for descriptions of the resource types. -What Does the Resource Store Do? --------------------------------- +.. _intro-do: -#. Load the resources from disk and resolving versions if any exist. -#. Precalculate the YUI module dependencies of the resources. -#. Expanding the specs (??) into full instances. -#. Load and parse context configuration files. -#. Load the routes files. -#. Calculate static handler URLs. -#. Calculate rollups and inline CSS. +How Does the Resource Store Work? +---------------------------------- -.. Don't think the following section is needed, but am leaving in doc for personal reference right now. +.. Questions: -General Process of Resource Store ---------------------------------- +.. 1. What does 'host for addons' mean? (It's mentioned in the 'core' section of the twiki.) Understanding the workflow of the resource store will give help those who want to customize addons to write code and -help others who don't plan on customizing addons to debug. - -- walk resource versions, gathering mojit-specific resources into mojits -- precalculates ("resolves") which resource versions are used for each version of the mojit -- also keeps track of app-level resources (archetypes, commands, config files, and middleware). -- these are not versioned (no resolution needed) -- these are not otherwise grouped together -- provides methods for events, including those specialized for AOP -- host for addons -- explicitly uses these addons: selector, config -- is a YUI Base, in part to enable plugins to be implemented as YUI Plugin modules - - also provides event subsystem - - also provides simple AOP subsystem (beforeHostMethod() and afterHostMethod()) +help others who don't plan on customizing addons to debug. + +In short, the resource store walks through the application-level, +mojit-level, and npm module files (in that order) of a Mojito application, determines what type of resource each file is, +creates an instance of the resource, and then registers the instance. + +During this process, the resource store is also doing the following: + +- precalculating ("resolving") which resource versions are used for each version of the mojit. +- keeping track of app-level resources (archetypes, commands, config files, and middleware). +- providing methods for events, including those specialized for AOP. +- explicitly using the addons `selector `_ and `config `_ + + +To see the code for the resource store, see `store.server.js `_ in +the `Mojito GitHub repository `_. + + +.. _intro-use: How Can Developers Use the Resource Store? ------------------------------------------ +.. Questions: + +.. 1. Do we have any concrete or hypothesized examples of using AOP (still need to know what this is) on the resource store, creating resource +.. types, or mapping contexts to selectors? +.. 2. Are there any other benefits for developers? + Developers can write addons for the resource store to have finer grain control over the management of resources -or extend the functionality of the resource store. The resource store has +or extend the functionality of the resource store. As a developer, you can write custom addons to use AOP +on the resource store, create resource types, and map contexts to selectors. -Allow developers to write resource store addons to do interesting things with resources +.. _resource_store-metadata: -specifically, allow the application authors to write resource store addons to accomplish interesting things with resources +Resource Metadata +================= -provide a mechanism so that addons can use AOP on the resource store (including addons) -provide a mechanism for other kinds of future-enabling extension points -allow custom (app-author provided) context-to-selector mapping -allow custom (app-author provided) resource types -To see the code for the resource store, see the `store.server.js `_. +.. Questions: -Resource Metadata -================= +.. _metadata-location: Location -------- +.. What is the location for the metadata? Is it a JSON config file like application.json? If so, what is the file name? + +.. _metadata-obj: Metadata Object --------------- -.. need better descriptions -.. default values -.. required -.. the table below is a rough approximation - -+------------------------+---------------+-----------+---------------+-------------------------------------------+ -| Property | Data Type | Required? | Default Value | Description | -+========================+===============+===========+===============+===========================================+ -| ``affinity`` | string | -- | -- | "server", "client", or "common" | -+------------------------+---------------+-----------+---------------+-------------------------------------------+ -| ``fs`` | string | -- | none | filesystem details | -+------------------------+---------------+-----------+---------------+-------------------------------------------+ -| ``id`` | string | yes | none | unique ID. common to all versions of the | -| | | | | resource. (typically | -| | | | | {type}-{subtype}-{name}) | -+------------------------+---------------+-----------+---------------+-------------------------------------------+ -| `` mojit`` | string | -- | none | which mojit this applies to, if any | -| | | | | ("shared" means the resource is available | -| | | | | to all mojits) | -+------------------------+---------------+-----------+---------------+-------------------------------------------+ -| ``name`` | string | yes | none | // name. common to all versions of the | -| | | | | resource | -+------------------------+---------------+-----------+---------------+-------------------------------------------+ -| `` pkg`` | string | -- | none | // packaging details | -+------------------------+---------------+-----------+---------------+-------------------------------------------+ -| `` source`` | string | no | | When ``true``, the ``manifest`` | -| | | | | attribute is added to ````. | -+------------------------+---------------+-----------+---------------+-------------------------------------------+ -| ``staticHandlerURL`` | string | yes | none | // path used to load the resource | -| | | | | onto the client | -+------------------------+---------------+-----------+---------------+-------------------------------------------+ -| ``subtype`` | string | no | none | // not all types have a subtype | -+------------------------+---------------+-----------+---------------+-------------------------------------------+ -| ``type`` | string | yes | none | | -+------------------------+---------------+-----------+---------------+-------------------------------------------+ -| ``yui`` | string | yes | none | // for resources that are YUI modules | -+------------------------+---------------+-----------+---------------+-------------------------------------------+ - +.. Questions: +.. 0. Is the data type string for all of the properties? + +.. 1. Please review and improve descriptions. The twiki and source code didn't offer much info for some. + +.. 2. It would be nice to list default values, but if most properties don't have default values, then I could remove this column. + +.. 3. Need to know what properties are required. + +.. 4. The list of properties was taken from the twiki and the source code. I have added both sets of properties to the table, +.. by I imagine some do not belong. + +.. 5. For ``configType``, what does it mean to specify a type of configuration? Do I need a section listing the types of configs w/ descriptions, +.. like the "Types of Resources" section below? + +.. 6. Need a description for ``subtype`` and examples. + +.. 7. What are the Mojito subsystems that addons can be added to? + +.. 8. Do we have a better description for ``name``? Any syntax convention, default values, or possible values? + +.. 9. How do you specify metadata such as the dependencies (``require``) and languages with ``yuiModuleMeta``? + + + + ++------------------------+---------------+-----------+---------------+---------------------------+---------------------------------------------+ +| Property | Data Type | Required? | Default Value | Possible Values | Description | ++========================+===============+===========+===============+===========================+=============================================+ +| ``addonType`` | string | -- | -- | | Specifies the mojito subsystem to which the | +| | | | | | addon should be added and is required if | +| | | | | | type if ``type=addon``. | ++------------------------+---------------+-----------+---------------+---------------------------+---------------------------------------------+ +| ``affinity`` | string | -- | -- | ``server``, ``client``, | | +| | | | | ``common`` | | ++------------------------+---------------+-----------+---------------+---------------------------+---------------------------------------------+ +| ``assetType`` | string | -- | -- | ``css``, ``js``, ``png``, | Specifies the type of asset and is required | +| | | | | ``png``, ``swf`` | if ``type=asset``. | ++------------------------+---------------+-----------+---------------+---------------------------+---------------------------------------------+ +| ``configType`` | string | -- | -- | | Specifies the type of configuration and is | +| | | | | | required if ``type=config``. | ++------------------------+---------------+-----------+---------------+---------------------------+---------------------------------------------+ +| ``fsPath`` | string | -- | none | | The path on the filesystem to the resource. | ++------------------------+---------------+-----------+---------------+---------------------------+---------------------------------------------+ +| ``id`` | string | yes | none | | A unique ID that is common to all versions | +| | | | | | of the resource. The ``id`` has the | +| | | | | | following syntax convention: | +| | | | | | ``{type}-{subtype}-{name}`` | ++------------------------+---------------+-----------+---------------+---------------------------+---------------------------------------------+ +| `` mojit`` | string | -- | none | | which mojit this applies to, if any | +| | | | | | ("shared" means the resource is available | +| | | | | | to all mojits) | ++------------------------+---------------+-----------+---------------+---------------------------+---------------------------------------------+ +| ``name`` | string | yes | none | | // name. common to all versions of the | +| | | | | | resource | ++------------------------+---------------+-----------+---------------+---------------------------+---------------------------------------------+ +| `` pkg`` | string | -- | none | | // packaging details | ++------------------------+---------------+-----------+---------------+---------------------------+---------------------------------------------+ +| `` source`` | string | no | | | where the resource came from | +| | | | | | (not shipped to client) | ++------------------------+---------------+-----------+---------------+---------------------------+---------------------------------------------+ +| ``staticHandlerURL`` | string | no | none | | The path used to load the resource | +| | | | | | onto the client. Used only for resources | +| | | | | | that can be deployed by reference to the | +| | | | | | client. | ++------------------------+---------------+-----------+---------------+---------------------------+---------------------------------------------+ +| ``subtype`` | string | no | none | | // not all types have a subtype | ++------------------------+---------------+-----------+---------------+---------------------------+---------------------------------------------+ +| ``type`` | string | yes | none | ``type=binder`` | | ++------------------------+---------------+-----------+---------------+---------------------------+---------------------------------------------+ +| ``viewEngine`` | string | no | none | ``mu``, ``dust`` | Specifies the view engine being used | +| | | | | | and is only used if ``type=view``. | ++------------------------+---------------+-----------+---------------+---------------------------+---------------------------------------------+ +| ``viewOutputFormat`` | string | no | none | ``xml``, ``html`` | Specifies the view engine being used | +| | | | | | and is only used if ``type=view``. | ++------------------------+---------------+-----------+---------------+---------------------------+---------------------------------------------+ +| ``yui`` | string | no | none | | // for resources that are YUI modules | ++------------------------+---------------+-----------+---------------+---------------------------+---------------------------------------------+ +| ``yuiModuleMeta`` | string | no | none | | Specifies the metadata, such dependencies, | +| | | | | | languages, etc., for a YUI 3 module. | ++------------------------+---------------+-----------+---------------+---------------------------+---------------------------------------------+ +| ``yuiModuleName`` | string | no | none | | The name of any resource delivered as a | +| | | | | | YUI 3 module. The ``type`` must be | +| | | | | | ``yui-module``. | ++------------------------+---------------+-----------+---------------+---------------------------+---------------------------------------------+ +| ``yuiModuleVersion`` | string | no | none | | The version of any resource delivered as a | +| | | | | | YUI 3 module. The ``type`` must be | +| | | | | | ``yui-module``. | ++------------------------+---------------+-----------+---------------+---------------------------+---------------------------------------------+ +| ``yuiSortedPaths`` | string | no | none | | For any resource delivered as a YUI3 module,| +| | | | | | this is the list of YUI modules required by | +| | | | | | the module with transitive dependencies | +| | | | | | resolved. The ``type`` must be | +| | | | | | ``yui-module``. ++------------------------+---------------+-----------+---------------+---------------------------+---------------------------------------------+ + + +.. _metadata_obj-types_resources: + +Types of Resources +`````````````````` + +The ``type`` property of the metadata object can have any of the following values: + +- ``config`` - a piece of configuration, sometimes for another resource +- ``controller`` - the controller for a mojit +- ``model`` - a model for a mojit +- ``view`` - a view for a mojit +- ``binder`` - a binder for a mojit +- ``action`` - an action to augment the controller +- ``asset`` - an asset (css, js, image, etc.) +- ``addon`` - an addon to the mojito system +- ``spec`` - the configuration for a mojit instance +- ``yui-lang`` - a YUI3 language bundle +- ``yui-module`` - a YUI3 module (that isn't one of the above) + + + +.. _metadata-ex: Example ------- @@ -171,9 +249,13 @@ Example selector: } +.. _resource_store-builtin_addons: Built-In Resource Store Addons -========================== +============================== + + +.. _builtin_addons-intro: Intro ----- @@ -184,51 +266,109 @@ the Mojito framework, so particular care must be taken when creating custom vers This chapter takes a look at the built-in resource store addons, so you can better understand their use or customize your own versions. +.. _intro-selector: selector ```````` -implements context-to-selector mapping -place where user implements their custom implementation -mojito ships with a default implementation, which the user can override - -returns a priority-orders list of selectors (aka POSL) +.. _selector-desc: Description ~~~~~~~~~~~ +The ``selector`` addon maps contexts to selectors and then returns +a priority-ordered list (POSL) of selectors. Developers can implement their custom implementation +to override the built-in ``selector`` addon. + +.. _selector-reqs: + Requirements ~~~~~~~~~~~~ -since this is used directly by the core, all implementations need to provide the following method: + +Because this is used directly by the the resource store, all implementations need to provide the following method: + +``getListFromContext(ctx)`` + + getListFromContext(ctx) +~~~~~~~~~~~~~~~~~~~~~~~ + +.. Question: need description, spec, and example of ``ctx`` and return value. + +**Parameters:** + +- ``ctx`` + +**Return:** + +.. _selector-ex: Example ~~~~~~~ +.. _intro-config: + config `````` +.. _config-desc: + Description ~~~~~~~~~~~ -provides access to the contents of the configuration files -defines new mojit-specific resource type: config (for the mojit's definition.json and defaults.json) -defines new app-level resource type: config (for application.json, routes.json, dimensions.json, etc) -mojito ships with a default implementation. it's not expected that users will write their own +The ``config`` addon provides access to the contents of the configuration files and +defines new mojit-level ``config`` resource types (for the mojit's ``definition.json`` and ``defaults.json``) +and new app-level ``config`` resource types (for ``application.json``, ``routes.json``, ``dimensions.json``, etc.). +Although developers can override the built-in ``config`` addon, it is not recommended. + +.. Haven't decided whether to include this info: +.. default implementation: +.. preloadFile() registers config files as type:config resources +.. listens for an event signifying the end of preload() +.. preloads the contents of the json files -default implementation: -preloadFile() registers config files as type:config resources -listens for an event signifying the end of preload() -preloads the contents of the json files +.. _config-reqs: Requirements ~~~~~~~~~~~~ -since this is used directly by the core, all implementations need to provide the following methods: +Because this is used directly by the resource store, all implementations need to provide the following methods: + +- ``readYCBDimensions(cb)`` +- ``readResource(ctx, res, cb)`` + +readResource(ctx, res, cb) + + +.. _config-ex: + readYCBDimensions(cb) -returns all the defined YCB dimensions +~~~~~~~~~~~~~~~~~~~~~ + +.. Question: need description, spec, and example of ``cb`` and return value. + +Returns all the defined dimensions. + +**Parameters** + +- ``cb`` + +**Return:** + readResource(ctx, res, cb) -reads the config file pointed to by the resource +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. Question: need description, spec, and example of ``ctx``, ``res``, ``cb`` and return value. + +Reads the config file pointed to by the resource. + +**Parameters** + +- ``ctx`` +- ``res`` +- ``cb`` + +**Return:** Example ~~~~~~~ @@ -420,36 +560,52 @@ Example - +.. _intro-instance: instance ```````` +.. _instance-desc: + Description ~~~~~~~~~~~ -provides access to mojit details -expands specs into full instances -defines new app-level resource type: spec (found in mojits/*/specs/*.json) -not used by resource store core, but critical to the mojito kernel +The ``instance`` addon provides access to mojit details, expands specs into full instances, and +defines new app-level ``spec`` resource types (found in ``mojits/*/specs/*.json``) +The ``instance`` addon is not used by the resource store, but is critical to the Mojito framework. + +.. _instance-reqs: Requirements ~~~~~~~~~~~~ +Because this addon is critical to the Mojito framework, all implementations need to provide the following methods: + +- ``getMojitDetails(ctx, mojitType, cb)`` +- ``expandSpec(ctx, spec, cb)`` + mojito ships with a default implementation. it's not expected that users will write their own -getMojitDetails(ctx, mojitType, cb) + returns a single structure that contains all details needed by the mojito kernel this is made by aggregating information from all the resources in the mojit -expandSpec(ctx, spec, cb) + takes the spec and expands it into the full mojit instance data needed by the mojito kernel + + + +.. _instance-ex: + Example ~~~~~~~ +.. _intro-routes: routes `````` +.. _routes-desc: + Description ~~~~~~~~~~~ @@ -458,10 +614,13 @@ not used by resource store core, but critical to the server-side mojito mojito ships with a default implementation. it's not expected that users will write their own provides a sugar method for reading all routes files, returning a single merged result +.. _routes-reqs: Requirements ~~~~~~~~~~~~ +.. _routes-ex: + Example ~~~~~~~ @@ -534,14 +693,19 @@ YUI.add('addon-rs-routes', function(Y, NAME) { }, '0.0.1', { requires: ['plugin', 'oop']}); +.. _intro-staticHandler: + staticHandler ````````````` +.. _staticHandler-desc: + Description ~~~~~~~~~~~ calculates/manages the static handler URLs for resources not used by resource store core, but used by the static handler middleware +.. _staticHandler-reqs: Requirements ~~~~~~~~~~~~ @@ -551,13 +715,18 @@ for affinity:client resources, sets staticHandlerURL to the static handler URL f the URL might be a rollup URL provides a method for the static handler middleware to find the filesystem path for a URL +.. _staticHandler-ex: + Example ~~~~~~~ +.. _intro-yui: yui ``` +.. _yui-desc: + Description ~~~~~~~~~~~ @@ -567,6 +736,8 @@ defines new mojit-specific resource type: yui-lang (found in lang/) precalculates YUI dependencies for mojit controllers and binders mojito ships with a default implementation. it's not expected that users will write their own +.. _yui-reqs: + Requirements ~~~~~~~~~~~~ after preloadFile() @@ -578,6 +749,8 @@ after resolveMojit() calculates the YUI module dependencies for the controller calculates the YUI module dependencies for each binder +.. _yui-ex: + Example ~~~~~~~ @@ -754,21 +927,22 @@ Example }, '0.0.1', { requires: ['plugin', 'oop']}); -Creating Custom Addons ----------------------- + +Creating Custom Resource Store Addons +===================================== General Process -``````````````` +--------------- Requirements -```````````` +------------ Example -``````` +------- shaker -~~~~~~ +`````` not part of mojito, given here as an example From dd1fab412e3d9c5a83f7963c3d7c8ffad6e21550 Mon Sep 17 00:00:00 2001 From: Joe Catera Date: Tue, 12 Jun 2012 09:55:33 -0700 Subject: [PATCH 07/45] Adding more detail to the addons and more questions. --- docs/dev_guide/topics/resource_store.rst | 49 +++++++++++++++++------- 1 file changed, 35 insertions(+), 14 deletions(-) diff --git a/docs/dev_guide/topics/resource_store.rst b/docs/dev_guide/topics/resource_store.rst index 1b37c3b4a..f221ce4ba 100644 --- a/docs/dev_guide/topics/resource_store.rst +++ b/docs/dev_guide/topics/resource_store.rst @@ -3,7 +3,6 @@ Resource Store ============== - .. General Questions: .. 1. Need formal definition for the resource store and resource. @@ -90,6 +89,8 @@ Resource Metadata .. Questions: +.. 1. + .. _metadata-location: Location @@ -254,6 +255,7 @@ Example Built-In Resource Store Addons ============================== +.. Note: Replace code examples with links to Mojito source once the resource store addons have been merged into master. .. _builtin_addons-intro: @@ -313,6 +315,16 @@ config .. _config-desc: + + +.. Haven't decided whether to include this info: +.. default implementation: +.. preloadFile() registers config files as type:config resources +.. listens for an event signifying the end of preload() +.. preloads the contents of the json files + + + Description ~~~~~~~~~~~ @@ -321,11 +333,6 @@ defines new mojit-level ``config`` resource types (for the mojit's ``definition. and new app-level ``config`` resource types (for ``application.json``, ``routes.json``, ``dimensions.json``, etc.). Although developers can override the built-in ``config`` addon, it is not recommended. -.. Haven't decided whether to include this info: -.. default implementation: -.. preloadFile() registers config files as type:config resources -.. listens for an event signifying the end of preload() -.. preloads the contents of the json files .. _config-reqs: @@ -337,8 +344,6 @@ Because this is used directly by the resource store, all implementations need to - ``readYCBDimensions(cb)`` - ``readResource(ctx, res, cb)`` -readResource(ctx, res, cb) - .. _config-ex: @@ -599,20 +604,32 @@ takes the spec and expands it into the full mojit instance data needed by the mo Example ~~~~~~~ +.. Need example + .. _intro-routes: routes `````` +.. Questions: + +.. 1. Is the sugar method ``getRoutes`` in ``store.server.js``? + +.. 2. To write a custom ``routes`` addon, are developers required to override ``getRoutes`` with their own version of the function? + + .. _routes-desc: Description ~~~~~~~~~~~ -provides access to the routes -not used by resource store core, but critical to the server-side mojito -mojito ships with a default implementation. it's not expected that users will write their own -provides a sugar method for reading all routes files, returning a single merged result +The ``routes`` addon provides access to the routes. Athough the addon is +not used by resource store core, it is critical to the server-side Mojito +mojito ships with a default implementation. The resource store has a method +for returning all of the route files in a single merged result. Although +you can create a custom ``routes`` addon, we recommend using the built-in ``routes`` +addon. + .. _routes-reqs: @@ -702,8 +719,9 @@ staticHandler Description ~~~~~~~~~~~ -calculates/manages the static handler URLs for resources -not used by resource store core, but used by the static handler middleware + +The ``stackHandler`` addon calculates and manages the static handler URLs for resources. +The addon is not used by resource store core, but used by the static handler middleware. .. _staticHandler-reqs: @@ -931,6 +949,9 @@ Example Creating Custom Resource Store Addons ===================================== +Intro +----- + General Process --------------- From 0b1bafad80e54d1d3b3f1b8d28f99ce34e60f277 Mon Sep 17 00:00:00 2001 From: Joe Catera Date: Tue, 12 Jun 2012 14:59:32 -0700 Subject: [PATCH 08/45] Added questions and fixed metadata object table. --- docs/dev_guide/topics/n | 1 + docs/dev_guide/topics/resource_store.rst | 268 +++++++++++++++-------- 2 files changed, 175 insertions(+), 94 deletions(-) create mode 100644 docs/dev_guide/topics/n diff --git a/docs/dev_guide/topics/n b/docs/dev_guide/topics/n new file mode 100644 index 000000000..a25946e21 --- /dev/null +++ b/docs/dev_guide/topics/n @@ -0,0 +1 @@ +wq diff --git a/docs/dev_guide/topics/resource_store.rst b/docs/dev_guide/topics/resource_store.rst index f221ce4ba..619c4475f 100644 --- a/docs/dev_guide/topics/resource_store.rst +++ b/docs/dev_guide/topics/resource_store.rst @@ -73,6 +73,7 @@ How Can Developers Use the Resource Store? .. 1. Do we have any concrete or hypothesized examples of using AOP (still need to know what this is) on the resource store, creating resource .. types, or mapping contexts to selectors? + .. 2. Are there any other benefits for developers? Developers can write addons for the resource store to have finer grain control over the management of resources @@ -85,12 +86,18 @@ on the resource store, create resource types, and map contexts to selectors. Resource Metadata ================= +.. _metadata-intro: +Intro +----- .. Questions: .. 1. +The resource store uses metadata to find, load, parse, and create instances of resources. + + .. _metadata-location: Location @@ -116,92 +123,110 @@ Metadata Object .. 4. The list of properties was taken from the twiki and the source code. I have added both sets of properties to the table, .. by I imagine some do not belong. -.. 5. For ``configType``, what does it mean to specify a type of configuration? Do I need a section listing the types of configs w/ descriptions, -.. like the "Types of Resources" section below? - -.. 6. Need a description for ``subtype`` and examples. - -.. 7. What are the Mojito subsystems that addons can be added to? - -.. 8. Do we have a better description for ``name``? Any syntax convention, default values, or possible values? - -.. 9. How do you specify metadata such as the dependencies (``require``) and languages with ``yuiModuleMeta``? - - - - -+------------------------+---------------+-----------+---------------+---------------------------+---------------------------------------------+ -| Property | Data Type | Required? | Default Value | Possible Values | Description | -+========================+===============+===========+===============+===========================+=============================================+ -| ``addonType`` | string | -- | -- | | Specifies the mojito subsystem to which the | -| | | | | | addon should be added and is required if | -| | | | | | type if ``type=addon``. | -+------------------------+---------------+-----------+---------------+---------------------------+---------------------------------------------+ -| ``affinity`` | string | -- | -- | ``server``, ``client``, | | -| | | | | ``common`` | | -+------------------------+---------------+-----------+---------------+---------------------------+---------------------------------------------+ -| ``assetType`` | string | -- | -- | ``css``, ``js``, ``png``, | Specifies the type of asset and is required | -| | | | | ``png``, ``swf`` | if ``type=asset``. | -+------------------------+---------------+-----------+---------------+---------------------------+---------------------------------------------+ -| ``configType`` | string | -- | -- | | Specifies the type of configuration and is | -| | | | | | required if ``type=config``. | -+------------------------+---------------+-----------+---------------+---------------------------+---------------------------------------------+ -| ``fsPath`` | string | -- | none | | The path on the filesystem to the resource. | -+------------------------+---------------+-----------+---------------+---------------------------+---------------------------------------------+ -| ``id`` | string | yes | none | | A unique ID that is common to all versions | -| | | | | | of the resource. The ``id`` has the | -| | | | | | following syntax convention: | -| | | | | | ``{type}-{subtype}-{name}`` | -+------------------------+---------------+-----------+---------------+---------------------------+---------------------------------------------+ -| `` mojit`` | string | -- | none | | which mojit this applies to, if any | -| | | | | | ("shared" means the resource is available | -| | | | | | to all mojits) | -+------------------------+---------------+-----------+---------------+---------------------------+---------------------------------------------+ -| ``name`` | string | yes | none | | // name. common to all versions of the | -| | | | | | resource | -+------------------------+---------------+-----------+---------------+---------------------------+---------------------------------------------+ -| `` pkg`` | string | -- | none | | // packaging details | -+------------------------+---------------+-----------+---------------+---------------------------+---------------------------------------------+ -| `` source`` | string | no | | | where the resource came from | -| | | | | | (not shipped to client) | -+------------------------+---------------+-----------+---------------+---------------------------+---------------------------------------------+ -| ``staticHandlerURL`` | string | no | none | | The path used to load the resource | -| | | | | | onto the client. Used only for resources | -| | | | | | that can be deployed by reference to the | -| | | | | | client. | -+------------------------+---------------+-----------+---------------+---------------------------+---------------------------------------------+ -| ``subtype`` | string | no | none | | // not all types have a subtype | -+------------------------+---------------+-----------+---------------+---------------------------+---------------------------------------------+ -| ``type`` | string | yes | none | ``type=binder`` | | -+------------------------+---------------+-----------+---------------+---------------------------+---------------------------------------------+ -| ``viewEngine`` | string | no | none | ``mu``, ``dust`` | Specifies the view engine being used | -| | | | | | and is only used if ``type=view``. | -+------------------------+---------------+-----------+---------------+---------------------------+---------------------------------------------+ -| ``viewOutputFormat`` | string | no | none | ``xml``, ``html`` | Specifies the view engine being used | -| | | | | | and is only used if ``type=view``. | -+------------------------+---------------+-----------+---------------+---------------------------+---------------------------------------------+ -| ``yui`` | string | no | none | | // for resources that are YUI modules | -+------------------------+---------------+-----------+---------------+---------------------------+---------------------------------------------+ -| ``yuiModuleMeta`` | string | no | none | | Specifies the metadata, such dependencies, | -| | | | | | languages, etc., for a YUI 3 module. | -+------------------------+---------------+-----------+---------------+---------------------------+---------------------------------------------+ -| ``yuiModuleName`` | string | no | none | | The name of any resource delivered as a | -| | | | | | YUI 3 module. The ``type`` must be | -| | | | | | ``yui-module``. | -+------------------------+---------------+-----------+---------------+---------------------------+---------------------------------------------+ -| ``yuiModuleVersion`` | string | no | none | | The version of any resource delivered as a | -| | | | | | YUI 3 module. The ``type`` must be | -| | | | | | ``yui-module``. | -+------------------------+---------------+-----------+---------------+---------------------------+---------------------------------------------+ -| ``yuiSortedPaths`` | string | no | none | | For any resource delivered as a YUI3 module,| -| | | | | | this is the list of YUI modules required by | -| | | | | | the module with transitive dependencies | -| | | | | | resolved. The ``type`` must be | -| | | | | | ``yui-module``. -+------------------------+---------------+-----------+---------------+---------------------------+---------------------------------------------+ - - -.. _metadata_obj-types_resources: +.. 5. Need a description for ``subtype`` and examples. + +.. 6. What are the Mojito subsystems that addons can be added to? + +.. 7. Do we have a better description for ``name``? Any syntax convention, default values, or possible values? + +.. 8. What "filesystem details" are given for ``fs``? + +.. 9. What "package details" are given for ``pkg``? + + + + ++------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ +| Property | Data Type | Required? | Default Value | Possible Values | Description | ++========================+===============+===========+===============+=============================+=============================================+ +| ``affinity`` | string | -- | -- | ``server``, ``client``, | The affinity of the resource, which | +| | | | | ``common`` | indicates where the resource will be used. | ++------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ +| ``fs`` | string | yes | none | N/A | // filesystem details ==> ?? | ++------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ +| ``id`` | string | yes | none | N/A | A unique ID that is common to all versions | +| | | | | | of the resource. The ``id`` has the | +| | | | | | following syntax convention: | +| | | | | | ``{type}-{subtype}-{name}`` | ++------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ +| `` mojit`` | string | no | none | ``shared`` | The mojit, if any, that uses this resource | +| | | | | | The value ``"shared"`` means the resource | +| | | | | | is available to all mojits. | ++------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ +| ``name`` | string | yes | none | | // name. common to all versions of the | +| | | | | | resource | ++------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ +| `` pkg`` | string | -- | none | | // packaging details | ++------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ +| ``selector`` | string | no | "*" | | The version of the resource, not to be | +| | | | | | confused revisions that mark the change of | +| | | | | | the resource over time. For example, a | +| | | | | | resource could have a version for iPhones, | +| | | | | | Android devices, fallbacks, etc. | ++------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ +| `` source`` | string | no | | | Specifies where the resource came from | +| | | | | | (not shipped to client). | ++------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ +| ``staticHandlerURL`` | string | no | none | | The path used to load the resource | +| | | | | | onto the client. Used only for resources | +| | | | | | that can be deployed by reference to the | +| | | | | | client. | ++------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ +| ``subtype`` | string | no | none | ``action``, ``binder``, | | +| | | | | ``command``, ``middleware`` | | +| | | | | ``model``, ``view`` | | ++------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ +| ``type`` | string | yes | none | See `Types of Resources `_. | | ++------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ +| ``yui`` | string | no | none | | // for resources that are YUI modules | ++------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ + +.. + + Not sure where I got the following properties, but I'm reluctant to remove them until + I have confirmation that they are unnecessary. + + +------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ + | ``addonType`` | string | -- | -- | | Specifies the mojito subsystem to which the | + | | | | | | addon should be added and is required if | + | | | | | | type if ``type=addon``. | + +------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ + | ``assetType`` | string | -- | -- | ``css``, ``js``, ``png``, | Specifies the type of asset and is required | + | | | | | ``png``, ``swf`` | if ``type=asset``. | + +------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ + | ``configType`` | string | -- | -- | | Specifies the type of configuration and is | + | | | | | | required if ``type=config``. | + +------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ + | ``fsPath`` | string | -- | none | | The path on the filesystem to the resource. | + | ``viewEngine`` | string | no | none | ``mu``, ``dust`` | Specifies the view engine being used | + | | | | | | and is only used if ``type=view``. | + +------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ + | ``viewOutputFormat`` | string | no | none | ``xml``, ``html`` | Specifies the view engine being used | + | | | | | | and is only used if ``type=view``. | + +------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ + | ``yuiModuleMeta`` | string | no | none | | Specifies the metadata, such dependencies, | + | | | | | | languages, etc., for a YUI 3 module. | + +------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ + | ``yuiModuleName`` | string | no | none | | The name of any resource delivered as a | + | | | | | | YUI 3 module. The ``type`` must be | + | | | | | | ``yui-module``. | + +------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ + | ``yuiModuleVersion`` | string | no | none | | The version of any resource delivered as a | + | | | | | | YUI 3 module. The ``type`` must be | + | | | | | | ``yui-module``. | + +------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ + | ``yuiSortedPaths`` | string | no | none | | For any resource delivered as a YUI3 module,| + | | | | | | this is the list of YUI modules required by | + | | | | | | the module with transitive dependencies | + | | | | | | resolved. The ``type`` must be | + | | | | | | ``yui-module``. | + +------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ + + + + +.. _types_resources: Types of Resources `````````````````` @@ -952,26 +977,81 @@ Creating Custom Resource Store Addons Intro ----- +This section is intended only for those developers who need to override the built-in resource store +addons or create new resource store addons. In general, we recommend that you use the built-in resource +store addons. + General Process --------------- +.. Questions: + +.. Do these steps look accurate? (would like a little more detail) + +.. 1. Create file with metadata object. +.. 2. Install Shaker with npm. +.. 3. Create addon that uses Shaker. + + Requirements ------------ +.. Questions: + +.. 1. What are the requirements? (configuration, functions, objects, namespaces, etc.) + Example ------- - -shaker +Intro `````` -not part of mojito, given here as an example +In this example, you will learn how to create a resource store addon for +`Shaker `_, a static asset rollup manager for Mojito applications. + + +We'll take you through creating the metadata object and the ``shaker`` resource store addon. +You should be able to create your own resource store addons afterward and figure out how to +customize (and override) one of the built-in resource store addons. + +Creating Metadata Object +```````````````````````` +.. Questions: + +.. 1. Location and name of file containing ``metadata`` object? + +.. 2. The table of properties of the ``metadata`` object has to be completed first. + +.. 3. + +Installing Shaker +````````````````` + +.. Questions: + +.. 1. Should the ``package.json`` file specify ``shaker`` as a dependency? + +.. 2. Is the instruction below correct and sufficient? + + +From the application directory of your application, run the following command to install ``shaker`` into the ``node_modules`` directory: + +``$ npm install mojito-shaker`` + + +Writing Addon +````````````` +.. Questions: + +.. 1. Does the app-level resource store addon go in ``{app_dir}/addons/rs/``? +.. 2. Any file naming context for the resource store addon? +.. 3. Requirements that users should know for making their own resource store addons? +.. 4. Need code and high-level explanation of what's going on as well as a brief breakdown of salient points. + +The ``shaker`` addon will listen for changes to the ``staticHandlerURL`` +resource field and then update ``staticHandlerURL`` and then update the ``staticHandlerURL`` so that static assets can come from +a CDN and be part of a multi-mojit rollup. -tweaks the staticHandlerURL to something very sophisticated -can be on CDN -can be multi-mojit rollup -listen for staticHandlerURL resource field change -updates to sophisticated version From 0547f803d7186d50cb969caa6c75c7c20c8fa2e2 Mon Sep 17 00:00:00 2001 From: Joe Catera Date: Tue, 12 Jun 2012 18:30:41 -0700 Subject: [PATCH 09/45] Added more questions, completed some sections. --- docs/dev_guide/topics/resource_store.rst | 191 +++++++++++++++++++---- 1 file changed, 160 insertions(+), 31 deletions(-) diff --git a/docs/dev_guide/topics/resource_store.rst b/docs/dev_guide/topics/resource_store.rst index 619c4475f..a87a32e12 100644 --- a/docs/dev_guide/topics/resource_store.rst +++ b/docs/dev_guide/topics/resource_store.rst @@ -15,6 +15,16 @@ Resource Store .. 4. Does AOP stand for aspect-oriented programming, attribute oriented programming, or something else? +.. Answers: + +.. 1. + +.. 2. + +.. 3. + +.. 4. + .. _resource_store_intro: Intro @@ -45,11 +55,17 @@ How Does the Resource Store Work? .. 1. What does 'host for addons' mean? (It's mentioned in the 'core' section of the twiki.) +.. Answers: + +.. 1. + + + Understanding the workflow of the resource store will give help those who want to customize addons to write code and help others who don't plan on customizing addons to debug. In short, the resource store walks through the application-level, -mojit-level, and npm module files (in that order) of a Mojito application, determines what type of resource each file is, +mojit-level, and ``npm`` module files (in that order) of a Mojito application, determines what type of resource each file is, creates an instance of the resource, and then registers the instance. During this process, the resource store is also doing the following: @@ -76,6 +92,13 @@ How Can Developers Use the Resource Store? .. 2. Are there any other benefits for developers? +.. Answers: + +.. 1. + +.. 2. + + Developers can write addons for the resource store to have finer grain control over the management of resources or extend the functionality of the resource store. As a developer, you can write custom addons to use AOP on the resource store, create resource types, and map contexts to selectors. @@ -93,6 +116,11 @@ Intro .. Questions: +.. 1. Drew, based on your response to a question about the metadata, I'm not sure if developers define resource metadata. Do they, and if so, how +.. do they define the metadata (in some config file?)? + +.. Answers: + .. 1. The resource store uses metadata to find, load, parse, and create instances of resources. @@ -103,7 +131,13 @@ The resource store uses metadata to find, load, parse, and create instances of r Location -------- -.. What is the location for the metadata? Is it a JSON config file like application.json? If so, what is the file name? +.. Questions: + +.. 1. What is the location for the metadata? Is it a JSON config file like application.json? If so, what is the file name? + +.. Answers: + +.. 1. .. _metadata-obj: @@ -133,8 +167,29 @@ Metadata Object .. 9. What "package details" are given for ``pkg``? +.. Answers: +.. 0. +.. 1. + +.. 2. + +.. 3. + +.. 4. + +.. 5. + +.. 6. + +.. 7. + +.. 8. + +.. 9. + +.. Please fill in or correct the rows for the 'Required?', 'Default Value', 'Possible Values', and 'Description' columns below. +------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ | Property | Data Type | Required? | Default Value | Possible Values | Description | @@ -252,7 +307,9 @@ The ``type`` property of the metadata object can have any of the following value Example ------- -.. need a real example +.. Questions: + +.. 1. Do we have an example? .. code-block:: javascript @@ -320,7 +377,9 @@ Because this is used directly by the the resource store, all implementations nee getListFromContext(ctx) ~~~~~~~~~~~~~~~~~~~~~~~ -.. Question: need description, spec, and example of ``ctx`` and return value. +.. Question: + +.. 1. Need description, spec, and example of ``ctx`` and return value. **Parameters:** @@ -341,8 +400,10 @@ config .. _config-desc: +.. Questions: + +.. 1. Should the following be included? -.. Haven't decided whether to include this info: .. default implementation: .. preloadFile() registers config files as type:config resources .. listens for an event signifying the end of preload() @@ -375,7 +436,9 @@ Because this is used directly by the resource store, all implementations need to readYCBDimensions(cb) ~~~~~~~~~~~~~~~~~~~~~ -.. Question: need description, spec, and example of ``cb`` and return value. +.. Question: + +.. 1. Need description, spec, and example of ``cb`` and return value. Returns all the defined dimensions. @@ -388,7 +451,9 @@ Returns all the defined dimensions. readResource(ctx, res, cb) ~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. Question: need description, spec, and example of ``ctx``, ``res``, ``cb`` and return value. +.. Question: + +.. 1. Need description, spec, and example of ``ctx``, ``res``, ``cb`` and return value. Reads the config file pointed to by the resource. @@ -614,14 +679,25 @@ Because this addon is critical to the Mojito framework, all implementations need - ``getMojitDetails(ctx, mojitType, cb)`` - ``expandSpec(ctx, spec, cb)`` -mojito ships with a default implementation. it's not expected that users will write their own -returns a single structure that contains all details needed by the mojito kernel -this is made by aggregating information from all the resources in the mojit -takes the spec and expands it into the full mojit instance data needed by the mojito kernel +getMojitDetails(ctx, mojitType, cb) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. Question: + +.. 1. Need description, spec, and example of ``ctx``, ``mojitType``, ``cb`` and return value. +Returns a single structure that contains all details needed by the Mojito kernel +The structure is made by aggregating information from all the resources in the mojit. +**Parameters** + +- ``ctx`` +- ``mojitType`` +- ``cb`` + +**Return:** .. _instance-ex: @@ -629,26 +705,33 @@ takes the spec and expands it into the full mojit instance data needed by the mo Example ~~~~~~~ -.. Need example +.. Question: + +.. 1. Need example. .. _intro-routes: routes `````` + .. Questions: .. 1. Is the sugar method ``getRoutes`` in ``store.server.js``? .. 2. To write a custom ``routes`` addon, are developers required to override ``getRoutes`` with their own version of the function? +.. Answers: +.. 1. + +.. 2. .. _routes-desc: Description ~~~~~~~~~~~ -The ``routes`` addon provides access to the routes. Athough the addon is +The ``routes`` addon provides access to the routes. Although the addon is not used by resource store core, it is critical to the server-side Mojito mojito ships with a default implementation. The resource store has a method for returning all of the route files in a single merged result. Although @@ -661,6 +744,8 @@ addon. Requirements ~~~~~~~~~~~~ +None. + .. _routes-ex: Example @@ -747,16 +832,21 @@ Description The ``stackHandler`` addon calculates and manages the static handler URLs for resources. The addon is not used by resource store core, but used by the static handler middleware. +Developers should not need to write their own custom version of the ``staticHandler`` addon. + +Before the method ``addResourceVersion`` is called in the resource store, resources +with the ``client`` affinity set the ``staticHandlerURL`` property to the static handler URL. +The static handler URL can be a rollup URL. + +The ``staticHandler`` addon also provides a method for the static handler middleware to find the +filesystem path for a URL. .. _staticHandler-reqs: Requirements ~~~~~~~~~~~~ -before addResourceVersion() -for affinity:client resources, sets staticHandlerURL to the static handler URL for the resource -the URL might be a rollup URL -provides a method for the static handler middleware to find the filesystem path for a URL +None. .. _staticHandler-ex: @@ -773,24 +863,36 @@ yui Description ~~~~~~~~~~~ -detects which resources are YUI modules, gathering additional metadata -defines new mojit-specific resource type: yui-module (found in autoload/ or yui_modules/) -defines new mojit-specific resource type: yui-lang (found in lang/) -precalculates YUI dependencies for mojit controllers and binders -mojito ships with a default implementation. it's not expected that users will write their own +.. Questions: + +.. 1. Should the following be included: + +.. + + after preloadFile() + if in autoload/ or yui_modules/ makes a type:yui-module resource + if in lang/ makes a type:yui-lang resource + before addResourceVersion() + if it's a resource implemented as a YUI module, gathers the YUI module metadata about it + after resolveMojit() + calculates the YUI module dependencies for the controller + calculates the YUI module dependencies for each binder + +The ``yui`` addon has the following functions: + +- detects which resources are YUI modules and gathers additional metadata. +- defines new mojit-specific resource of type ``yui-module`` that are found in ``autoload/`` or ``yui_modules/``. +- defines new mojit-specific resource ot type ``yui-lang`` that are found in ``lang/``. +- precalculates YUI dependencies for mojit controllers and binders. + +The built-in ``yui`` addon will generally not need to be overridden with a custom version of the addon. .. _yui-reqs: Requirements ~~~~~~~~~~~~ -after preloadFile() -if in autoload/ or yui_modules/ makes a type:yui-module resource -if in lang/ makes a type:yui-lang resource -before addResourceVersion() -if it's a resource implemented as a YUI module, gathers the YUI module metadata about it -after resolveMojit() -calculates the YUI module dependencies for the controller -calculates the YUI module dependencies for each binder + +None. .. _yui-ex: @@ -1000,6 +1102,10 @@ Requirements .. 1. What are the requirements? (configuration, functions, objects, namespaces, etc.) +.. Answers: + +.. 1. + Example ------- @@ -1022,7 +1128,10 @@ Creating Metadata Object .. 2. The table of properties of the ``metadata`` object has to be completed first. -.. 3. +.. Answers: + +.. 1. + Installing Shaker ````````````````` @@ -1033,6 +1142,12 @@ Installing Shaker .. 2. Is the instruction below correct and sufficient? +.. Answers: + +.. 1. + +.. 2. + From the application directory of your application, run the following command to install ``shaker`` into the ``node_modules`` directory: @@ -1044,10 +1159,24 @@ Writing Addon .. Questions: .. 1. Does the app-level resource store addon go in ``{app_dir}/addons/rs/``? + .. 2. Any file naming context for the resource store addon? + .. 3. Requirements that users should know for making their own resource store addons? + .. 4. Need code and high-level explanation of what's going on as well as a brief breakdown of salient points. +.. Answers: + +.. 1. + +.. 2. + +.. 3. + +.. 4. + + The ``shaker`` addon will listen for changes to the ``staticHandlerURL`` resource field and then update ``staticHandlerURL`` and then update the ``staticHandlerURL`` so that static assets can come from a CDN and be part of a multi-mojit rollup. From 9d00b8eb666041966fb5b14bf5a4e245816a910e Mon Sep 17 00:00:00 2001 From: Joe Catera Date: Tue, 12 Jun 2012 18:32:25 -0700 Subject: [PATCH 10/45] Removing an errant file. --- docs/dev_guide/topics/n | 1 - 1 file changed, 1 deletion(-) delete mode 100644 docs/dev_guide/topics/n diff --git a/docs/dev_guide/topics/n b/docs/dev_guide/topics/n deleted file mode 100644 index a25946e21..000000000 --- a/docs/dev_guide/topics/n +++ /dev/null @@ -1 +0,0 @@ -wq From 1891e233b14a7691b7c2c006a984ba09e95aa146 Mon Sep 17 00:00:00 2001 From: Joe Catera Date: Tue, 12 Jun 2012 18:33:38 -0700 Subject: [PATCH 11/45] Renamed resource store doc to follow the same naming convention as the other topics. --- .../topics/{resource_store.rst => mojito_resource_store.rst} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/dev_guide/topics/{resource_store.rst => mojito_resource_store.rst} (100%) diff --git a/docs/dev_guide/topics/resource_store.rst b/docs/dev_guide/topics/mojito_resource_store.rst similarity index 100% rename from docs/dev_guide/topics/resource_store.rst rename to docs/dev_guide/topics/mojito_resource_store.rst From 99d94a5ba3b752c5e41040ed50beaab447c7be33 Mon Sep 17 00:00:00 2001 From: Joe Catera Date: Wed, 13 Jun 2012 10:42:59 -0700 Subject: [PATCH 12/45] Spell checked doc. --- .../topics/mojito_resource_store.rst | 2 +- .../topics/mojito_resource_store.rst.bak | 1189 +++++++++++++++++ 2 files changed, 1190 insertions(+), 1 deletion(-) create mode 100644 docs/dev_guide/topics/mojito_resource_store.rst.bak diff --git a/docs/dev_guide/topics/mojito_resource_store.rst b/docs/dev_guide/topics/mojito_resource_store.rst index a87a32e12..0beb05123 100644 --- a/docs/dev_guide/topics/mojito_resource_store.rst +++ b/docs/dev_guide/topics/mojito_resource_store.rst @@ -882,7 +882,7 @@ The ``yui`` addon has the following functions: - detects which resources are YUI modules and gathers additional metadata. - defines new mojit-specific resource of type ``yui-module`` that are found in ``autoload/`` or ``yui_modules/``. -- defines new mojit-specific resource ot type ``yui-lang`` that are found in ``lang/``. +- defines new mojit-specific resource of type ``yui-lang`` that are found in ``lang/``. - precalculates YUI dependencies for mojit controllers and binders. The built-in ``yui`` addon will generally not need to be overridden with a custom version of the addon. diff --git a/docs/dev_guide/topics/mojito_resource_store.rst.bak b/docs/dev_guide/topics/mojito_resource_store.rst.bak new file mode 100644 index 000000000..a87a32e12 --- /dev/null +++ b/docs/dev_guide/topics/mojito_resource_store.rst.bak @@ -0,0 +1,1189 @@ +============== +Resource Store +============== + + +.. General Questions: + +.. 1. Need formal definition for the resource store and resource. + +.. 2. What are the benefits of using the resource store? + +.. 3. Should the title of this chapter be about what users can do with resource store? I'm not sure if developers +.. will even read this chapter because they won't necessarily know what the resource store is. + +.. 4. Does AOP stand for aspect-oriented programming, attribute oriented programming, or something else? + + +.. Answers: + +.. 1. + +.. 2. + +.. 3. + +.. 4. + +.. _resource_store_intro: + +Intro +===== + +The resource store is the Mojito framework code that managers and keeps track of the resources in your Mojito applications. +The resource store uses addons to do much of the work, which you can read about in `Built-In Resource Store Addons `_. +The code for the resource store is a `YUI Base `_, which enables plugins to be implemented as `YUI Plugin modules `_. +Being a YUI Base, the resource store also provides an event subsystem and a simple AOP subsystem (methods ``beforeHostMethod`` and ``afterHostMethod``). + + +.. _intro-what: + +What is a Mojito Resource? +-------------------------- + +At the application level, resources include archetypes, commands, configuration files, and middleware. At the mojit level, +resources include controllers, models, binders, configuration files, and views. Developers can also create their own types of +resources. See `Types of Resources `_ for descriptions of the resource types. + + +.. _intro-do: + +How Does the Resource Store Work? +---------------------------------- + +.. Questions: + +.. 1. What does 'host for addons' mean? (It's mentioned in the 'core' section of the twiki.) + +.. Answers: + +.. 1. + + + +Understanding the workflow of the resource store will give help those who want to customize addons to write code and +help others who don't plan on customizing addons to debug. + +In short, the resource store walks through the application-level, +mojit-level, and ``npm`` module files (in that order) of a Mojito application, determines what type of resource each file is, +creates an instance of the resource, and then registers the instance. + +During this process, the resource store is also doing the following: + +- precalculating ("resolving") which resource versions are used for each version of the mojit. +- keeping track of app-level resources (archetypes, commands, config files, and middleware). +- providing methods for events, including those specialized for AOP. +- explicitly using the addons `selector `_ and `config `_ + + +To see the code for the resource store, see `store.server.js `_ in +the `Mojito GitHub repository `_. + + +.. _intro-use: + +How Can Developers Use the Resource Store? +------------------------------------------ + +.. Questions: + +.. 1. Do we have any concrete or hypothesized examples of using AOP (still need to know what this is) on the resource store, creating resource +.. types, or mapping contexts to selectors? + +.. 2. Are there any other benefits for developers? + +.. Answers: + +.. 1. + +.. 2. + + +Developers can write addons for the resource store to have finer grain control over the management of resources +or extend the functionality of the resource store. As a developer, you can write custom addons to use AOP +on the resource store, create resource types, and map contexts to selectors. + + +.. _resource_store-metadata: + +Resource Metadata +================= + +.. _metadata-intro: + +Intro +----- + +.. Questions: + +.. 1. Drew, based on your response to a question about the metadata, I'm not sure if developers define resource metadata. Do they, and if so, how +.. do they define the metadata (in some config file?)? + +.. Answers: + +.. 1. + +The resource store uses metadata to find, load, parse, and create instances of resources. + + +.. _metadata-location: + +Location +-------- + +.. Questions: + +.. 1. What is the location for the metadata? Is it a JSON config file like application.json? If so, what is the file name? + +.. Answers: + +.. 1. + +.. _metadata-obj: + +Metadata Object +--------------- + +.. Questions: + +.. 0. Is the data type string for all of the properties? + +.. 1. Please review and improve descriptions. The twiki and source code didn't offer much info for some. + +.. 2. It would be nice to list default values, but if most properties don't have default values, then I could remove this column. + +.. 3. Need to know what properties are required. + +.. 4. The list of properties was taken from the twiki and the source code. I have added both sets of properties to the table, +.. by I imagine some do not belong. + +.. 5. Need a description for ``subtype`` and examples. + +.. 6. What are the Mojito subsystems that addons can be added to? + +.. 7. Do we have a better description for ``name``? Any syntax convention, default values, or possible values? + +.. 8. What "filesystem details" are given for ``fs``? + +.. 9. What "package details" are given for ``pkg``? + +.. Answers: + +.. 0. + +.. 1. + +.. 2. + +.. 3. + +.. 4. + +.. 5. + +.. 6. + +.. 7. + +.. 8. + +.. 9. + +.. Please fill in or correct the rows for the 'Required?', 'Default Value', 'Possible Values', and 'Description' columns below. + ++------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ +| Property | Data Type | Required? | Default Value | Possible Values | Description | ++========================+===============+===========+===============+=============================+=============================================+ +| ``affinity`` | string | -- | -- | ``server``, ``client``, | The affinity of the resource, which | +| | | | | ``common`` | indicates where the resource will be used. | ++------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ +| ``fs`` | string | yes | none | N/A | // filesystem details ==> ?? | ++------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ +| ``id`` | string | yes | none | N/A | A unique ID that is common to all versions | +| | | | | | of the resource. The ``id`` has the | +| | | | | | following syntax convention: | +| | | | | | ``{type}-{subtype}-{name}`` | ++------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ +| `` mojit`` | string | no | none | ``shared`` | The mojit, if any, that uses this resource | +| | | | | | The value ``"shared"`` means the resource | +| | | | | | is available to all mojits. | ++------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ +| ``name`` | string | yes | none | | // name. common to all versions of the | +| | | | | | resource | ++------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ +| `` pkg`` | string | -- | none | | // packaging details | ++------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ +| ``selector`` | string | no | "*" | | The version of the resource, not to be | +| | | | | | confused revisions that mark the change of | +| | | | | | the resource over time. For example, a | +| | | | | | resource could have a version for iPhones, | +| | | | | | Android devices, fallbacks, etc. | ++------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ +| `` source`` | string | no | | | Specifies where the resource came from | +| | | | | | (not shipped to client). | ++------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ +| ``staticHandlerURL`` | string | no | none | | The path used to load the resource | +| | | | | | onto the client. Used only for resources | +| | | | | | that can be deployed by reference to the | +| | | | | | client. | ++------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ +| ``subtype`` | string | no | none | ``action``, ``binder``, | | +| | | | | ``command``, ``middleware`` | | +| | | | | ``model``, ``view`` | | ++------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ +| ``type`` | string | yes | none | See `Types of Resources `_. | | ++------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ +| ``yui`` | string | no | none | | // for resources that are YUI modules | ++------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ + +.. + + Not sure where I got the following properties, but I'm reluctant to remove them until + I have confirmation that they are unnecessary. + + +------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ + | ``addonType`` | string | -- | -- | | Specifies the mojito subsystem to which the | + | | | | | | addon should be added and is required if | + | | | | | | type if ``type=addon``. | + +------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ + | ``assetType`` | string | -- | -- | ``css``, ``js``, ``png``, | Specifies the type of asset and is required | + | | | | | ``png``, ``swf`` | if ``type=asset``. | + +------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ + | ``configType`` | string | -- | -- | | Specifies the type of configuration and is | + | | | | | | required if ``type=config``. | + +------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ + | ``fsPath`` | string | -- | none | | The path on the filesystem to the resource. | + | ``viewEngine`` | string | no | none | ``mu``, ``dust`` | Specifies the view engine being used | + | | | | | | and is only used if ``type=view``. | + +------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ + | ``viewOutputFormat`` | string | no | none | ``xml``, ``html`` | Specifies the view engine being used | + | | | | | | and is only used if ``type=view``. | + +------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ + | ``yuiModuleMeta`` | string | no | none | | Specifies the metadata, such dependencies, | + | | | | | | languages, etc., for a YUI 3 module. | + +------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ + | ``yuiModuleName`` | string | no | none | | The name of any resource delivered as a | + | | | | | | YUI 3 module. The ``type`` must be | + | | | | | | ``yui-module``. | + +------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ + | ``yuiModuleVersion`` | string | no | none | | The version of any resource delivered as a | + | | | | | | YUI 3 module. The ``type`` must be | + | | | | | | ``yui-module``. | + +------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ + | ``yuiSortedPaths`` | string | no | none | | For any resource delivered as a YUI3 module,| + | | | | | | this is the list of YUI modules required by | + | | | | | | the module with transitive dependencies | + | | | | | | resolved. The ``type`` must be | + | | | | | | ``yui-module``. | + +------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ + + + + +.. _types_resources: + +Types of Resources +`````````````````` + +The ``type`` property of the metadata object can have any of the following values: + +- ``config`` - a piece of configuration, sometimes for another resource +- ``controller`` - the controller for a mojit +- ``model`` - a model for a mojit +- ``view`` - a view for a mojit +- ``binder`` - a binder for a mojit +- ``action`` - an action to augment the controller +- ``asset`` - an asset (css, js, image, etc.) +- ``addon`` - an addon to the mojito system +- ``spec`` - the configuration for a mojit instance +- ``yui-lang`` - a YUI3 language bundle +- ``yui-module`` - a YUI3 module (that isn't one of the above) + + + +.. _metadata-ex: + +Example +------- + +.. Questions: + +.. 1. Do we have an example? + +.. code-block:: javascript + + { + source: // where the resource came from (not shipped to client) + fs: // filesystem details + pkg: // packaging details + mojit: // which mojit this applies to, if any ("shared" means the resource is available to all mojits) + type: + subtype: // not all types have a subtype + name: // name. common to all versions of the resource + id: // unique ID. common to all versions of the resource. (typically {type}-{subtype}-{name}) + staticHandlerURL: // path used to load the resource onto the client + yui: // for resources that are YUI modules + + // these are only used in the metadata for each resource version. the metadata + // for resolved resources won't have these, since they're intrinsically part of + // the resolved resource. + affinity: // "server", "client", or "common" + selector: + } + +.. _resource_store-builtin_addons: + +Built-In Resource Store Addons +============================== + +.. Note: Replace code examples with links to Mojito source once the resource store addons have been merged into master. + +.. _builtin_addons-intro: + +Intro +----- + +Mojito comes with built-in resource store addons that are used by the resource store +and the Mojito framework. These resource store addons are required by the resource store and +the Mojito framework, so particular care must be taken when creating custom versions of them. +This chapter takes a look at the built-in resource store addons, so you can better understand their use or +customize your own versions. + +.. _intro-selector: + +selector +```````` + +.. _selector-desc: + +Description +~~~~~~~~~~~ + +The ``selector`` addon maps contexts to selectors and then returns +a priority-ordered list (POSL) of selectors. Developers can implement their custom implementation +to override the built-in ``selector`` addon. + +.. _selector-reqs: + +Requirements +~~~~~~~~~~~~ + +Because this is used directly by the the resource store, all implementations need to provide the following method: + +``getListFromContext(ctx)`` + + +getListFromContext(ctx) +~~~~~~~~~~~~~~~~~~~~~~~ + +.. Question: + +.. 1. Need description, spec, and example of ``ctx`` and return value. + +**Parameters:** + +- ``ctx`` + +**Return:** + +.. _selector-ex: + +Example +~~~~~~~ + +.. _intro-config: + +config +`````` + +.. _config-desc: + + +.. Questions: + +.. 1. Should the following be included? + +.. default implementation: +.. preloadFile() registers config files as type:config resources +.. listens for an event signifying the end of preload() +.. preloads the contents of the json files + + + +Description +~~~~~~~~~~~ + +The ``config`` addon provides access to the contents of the configuration files and +defines new mojit-level ``config`` resource types (for the mojit's ``definition.json`` and ``defaults.json``) +and new app-level ``config`` resource types (for ``application.json``, ``routes.json``, ``dimensions.json``, etc.). +Although developers can override the built-in ``config`` addon, it is not recommended. + + +.. _config-reqs: + +Requirements +~~~~~~~~~~~~ + +Because this is used directly by the resource store, all implementations need to provide the following methods: + +- ``readYCBDimensions(cb)`` +- ``readResource(ctx, res, cb)`` + + +.. _config-ex: + +readYCBDimensions(cb) +~~~~~~~~~~~~~~~~~~~~~ + +.. Question: + +.. 1. Need description, spec, and example of ``cb`` and return value. + +Returns all the defined dimensions. + +**Parameters** + +- ``cb`` + +**Return:** + +readResource(ctx, res, cb) +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. Question: + +.. 1. Need description, spec, and example of ``ctx``, ``res``, ``cb`` and return value. + +Reads the config file pointed to by the resource. + +**Parameters** + +- ``ctx`` +- ``res`` +- ``cb`` + +**Return:** + +Example +~~~~~~~ + +.. code-block:: javascript + + + YUI.add('addon-rs-config', function(Y, NAME) { + + var libfs = require('fs'), + libpath = require('path'), + libycb = require(libpath.join(__dirname, '../../../libs/ycb')); + + function RSAddonConfig() { + RSAddonConfig.superclass.constructor.apply(this, arguments); + } + RSAddonConfig.NS = 'config'; + RSAddonConfig.ATTRS = {}; + + Y.extend(RSAddonConfig, Y.Plugin.Base, { + + initializer: function(config) { + this.rs = config.host; + this.appRoot = config.appRoot; + this.mojitoRoot = config.mojitoRoot; + this.afterHostMethod('findResourceByConvention', this.findResourceByConvention, this); + this.beforeHostMethod('parseResource', this.parseResource, this); + + this._jsonCache = {}; // fullPath: contents as JSON object + this._ycbCache = {}; // fullPath: YCB config object + this._ycbDims = this._readYcbDimensions(); + }, + + + destructor: function() { + // TODO: needed to break cycle so we don't leak memory? + this.rs = null; + }, + + + getDimensions: function() { + return this.rs.cloneObj(this._ycbDims); + }, + + + /** + * Reads and parses a JSON file + * + * @method readConfigJSON + * @param fullPath {string} path to JSON file + * @return {mixed} contents of JSON file + */ + // TODO: async interface + readConfigJSON: function(fullPath) { + var json, + contents; + if (!libpath.existsSync(fullPath)) { + return {}; + } + json = this._jsonCache[fullPath]; + if (!json) { + try { + contents = libfs.readFileSync(fullPath, 'utf-8'); + json = JSON.parse(contents); + } catch (e) { + throw new Error('Error parsing JSON file: ' + fullPath); + } + this._jsonCache[fullPath] = json; + } + return json; + }, + + + /** + * reads a configuration file that is in YCB format + * + * @method readConfigYCB + * @param ctx {object} runtime context + * @param fullPath {string} path to the YCB file + * @return {object} the contextualized configuration + */ + // TODO: async interface + readConfigYCB: function(fullPath, ctx) { + var cacheKey, + json, + ycb; + + ctx = this.rs.mergeRecursive(this.rs.getStaticContext(), ctx); + + ycb = this._ycbCache[fullPath]; + if (!ycb) { + json = this.readConfigJSON(fullPath); + json = this._ycbDims.concat(json); + ycb = new libycb.Ycb(json); + this._ycbCache[fullPath] = ycb; + } + return ycb.read(ctx, {}); + }, + + + findResourceByConvention: function(source, mojitType) { + var fs = source.fs, + use = false; + + // we only care about files + if (!fs.isFile) { + return; + } + // we don't care about files in subdirectories + if ('.' !== fs.subDir) { + return; + } + // we only care about json files + if ('.json' !== fs.ext) { + return; + } + // use package.json for the app and the mojit + if ('package' === fs.basename && 'bundle' !== fs.rootType) { + use = true; + } + // use all configs in the application + if ('app' === fs.rootType) { + use = true; + } + // use configs from non-shared mojit resources + if (mojitType && 'shared' !== mojitType) { + use = true; + } + if (!use) { + return; + } + + return new Y.Do.AlterReturn(null, { + type: 'config' + }); + }, + + + parseResource: function(source, type, subtype, mojitType) { + var baseParts, + res; + + if ('config' !== type) { + return; + } + + baseParts = source.fs.basename.split('.'); + res = { + source: source, + type: 'config', + affinity: 'common', + selector: '*' + }; + if ('app' !== source.fs.rootType) { + res.mojit = mojitType; + } + if (baseParts.length !== 1) { + Y.log('invalid config filename. skipping ' + source.fs.fullPath, 'warn', NAME); + return; + } + res.name = libpath.join(source.fs.subDir, baseParts.join('.')); + res.id = [res.type, res.subtype, res.name].join('-'); + return new Y.Do.Halt(null, res); + }, + + + /** + * Read the application's dimensions.json file for YCB processing. If not + * available, fall back to the framework's default dimensions.json. + * + * @method _readYcbDimensions + * @return {array} contents of the dimensions.json file + * @private + */ + _readYcbDimensions: function() { + var path = libpath.join(this.appRoot, 'dimensions.json'); + if (!libpath.existsSync(path)) { + path = libpath.join(this.mojitoRoot, 'dimensions.json'); + } + return this.readConfigJSON(path); + } + + + }); + Y.namespace('mojito.addons.rs'); + Y.mojito.addons.rs.config = RSAddonConfig; + + }, '0.0.1', { requires: ['plugin', 'oop']}); + + + +.. _intro-instance: + +instance +```````` + +.. _instance-desc: + +Description +~~~~~~~~~~~ + +The ``instance`` addon provides access to mojit details, expands specs into full instances, and +defines new app-level ``spec`` resource types (found in ``mojits/*/specs/*.json``) +The ``instance`` addon is not used by the resource store, but is critical to the Mojito framework. + +.. _instance-reqs: + +Requirements +~~~~~~~~~~~~ + +Because this addon is critical to the Mojito framework, all implementations need to provide the following methods: + +- ``getMojitDetails(ctx, mojitType, cb)`` +- ``expandSpec(ctx, spec, cb)`` + + + +getMojitDetails(ctx, mojitType, cb) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. Question: + +.. 1. Need description, spec, and example of ``ctx``, ``mojitType``, ``cb`` and return value. + +Returns a single structure that contains all details needed by the Mojito kernel +The structure is made by aggregating information from all the resources in the mojit. + +**Parameters** + +- ``ctx`` +- ``mojitType`` +- ``cb`` + +**Return:** + + +.. _instance-ex: + +Example +~~~~~~~ + +.. Question: + +.. 1. Need example. + +.. _intro-routes: + +routes +`````` + +.. Questions: + +.. 1. Is the sugar method ``getRoutes`` in ``store.server.js``? + +.. 2. To write a custom ``routes`` addon, are developers required to override ``getRoutes`` with their own version of the function? + +.. Answers: + +.. 1. + +.. 2. + +.. _routes-desc: + +Description +~~~~~~~~~~~ + +The ``routes`` addon provides access to the routes. Although the addon is +not used by resource store core, it is critical to the server-side Mojito +mojito ships with a default implementation. The resource store has a method +for returning all of the route files in a single merged result. Although +you can create a custom ``routes`` addon, we recommend using the built-in ``routes`` +addon. + + +.. _routes-reqs: + +Requirements +~~~~~~~~~~~~ + +None. + +.. _routes-ex: + +Example +~~~~~~~ + +YUI.add('addon-rs-routes', function(Y, NAME) { + + var libpath = require('path'), + libycb = require(libpath.join(__dirname, '../../../libs/ycb')); + + function RSAddonRoutes() { + RSAddonRoutes.superclass.constructor.apply(this, arguments); + } + RSAddonRoutes.NS = 'routes'; + RSAddonRoutes.DEPS = ['config']; + RSAddonRoutes.ATTRS = {}; + + Y.extend(RSAddonRoutes, Y.Plugin.Base, { + + initializer: function(config) { + this.rs = config.host; + this.appRoot = config.appRoot; + }, + + + destructor: function() { + // TODO: needed to break cycle so we don't leak memory? + this.rs = null; + }, + + + read: function(env, ctx, cb) { + ctx.runtime = env; + var appConfig = this.rs.getAppConfig(ctx), + routesFiles = appConfig.routesFiles, + p, + path, + fixedPaths = {}, + out = {}, + ress, + r, + res, + path, + routes; + + for (p = 0; p < routesFiles.length; p += 1) { + path = routesFiles[p]; + // relative paths are relative to the application + if ('/' !== path.charAt(1)) { + path = libpath.join(this.appRoot, path); + } + fixedPaths[path] = true; + } + + ress = this.rs.getResources(env, ctx, {type:'config'}); + for (r = 0; r < ress.length; r += 1) { + res = ress[r]; + if (fixedPaths[res.source.fs.fullPath]) { + routes = this.rs.config.readConfigYCB(res.source.fs.fullPath, ctx); + out = Y.merge(out, routes); + } + } + + cb(null, out); + } + + + }); + Y.namespace('mojito.addons.rs'); + Y.mojito.addons.rs.routes = RSAddonRoutes; + +}, '0.0.1', { requires: ['plugin', 'oop']}); + + +.. _intro-staticHandler: + +staticHandler +````````````` + +.. _staticHandler-desc: + +Description +~~~~~~~~~~~ + +The ``stackHandler`` addon calculates and manages the static handler URLs for resources. +The addon is not used by resource store core, but used by the static handler middleware. +Developers should not need to write their own custom version of the ``staticHandler`` addon. + +Before the method ``addResourceVersion`` is called in the resource store, resources +with the ``client`` affinity set the ``staticHandlerURL`` property to the static handler URL. +The static handler URL can be a rollup URL. + +The ``staticHandler`` addon also provides a method for the static handler middleware to find the +filesystem path for a URL. + +.. _staticHandler-reqs: + +Requirements +~~~~~~~~~~~~ + +None. + +.. _staticHandler-ex: + +Example +~~~~~~~ + +.. _intro-yui: + +yui +``` + +.. _yui-desc: + +Description +~~~~~~~~~~~ + +.. Questions: + +.. 1. Should the following be included: + +.. + + after preloadFile() + if in autoload/ or yui_modules/ makes a type:yui-module resource + if in lang/ makes a type:yui-lang resource + before addResourceVersion() + if it's a resource implemented as a YUI module, gathers the YUI module metadata about it + after resolveMojit() + calculates the YUI module dependencies for the controller + calculates the YUI module dependencies for each binder + +The ``yui`` addon has the following functions: + +- detects which resources are YUI modules and gathers additional metadata. +- defines new mojit-specific resource of type ``yui-module`` that are found in ``autoload/`` or ``yui_modules/``. +- defines new mojit-specific resource ot type ``yui-lang`` that are found in ``lang/``. +- precalculates YUI dependencies for mojit controllers and binders. + +The built-in ``yui`` addon will generally not need to be overridden with a custom version of the addon. + +.. _yui-reqs: + +Requirements +~~~~~~~~~~~~ + +None. + +.. _yui-ex: + +Example +~~~~~~~ + +.. code-block:: javascript + + /* + * Copyright (c) 2012, Yahoo! Inc. All rights reserved. + * Copyrights licensed under the New BSD License. + * See the accompanying LICENSE file for terms. + */ + + YUI.add('addon-rs-yui', function(Y, NAME) { + + var libfs = require('fs'), + libpath = require('path'), + libvm = require('vm'); + + function RSAddonYUI() { + RSAddonYUI.superclass.constructor.apply(this, arguments); + } + RSAddonYUI.NS = 'yui'; + RSAddonYUI.ATTRS = {}; + + Y.extend(RSAddonYUI, Y.Plugin.Base, { + + initializer: function(config) { + this.rs = config.host; + this.appRoot = config.appRoot; + this.mojitoRoot = config.mojitoRoot; + this.afterHostMethod('findResourceByConvention', this.findResourceByConvention, this); + this.beforeHostMethod('parseResource', this.parseResource, this); + this.beforeHostMethod('addResourceVersion', this.addResourceVersion, this); + }, + + + destructor: function() { + // TODO: needed to break cycle so we don't leak memory? + this.rs = null; + }, + + + findResourceByConvention: function(source, mojitType) { + var fs = source.fs; + + if (!fs.isFile) { + return; + } + if ('.js' !== fs.ext) { + return; + } + + if (fs.subDirArray.length >= 1 && ('autoload' === fs.subDirArray[0] || 'yui_modules' === fs.subDirArray[0])) { + return new Y.Do.AlterReturn(null, { + type: 'yui-module', + skipSubdirParts: 1 + }); + } + + if (fs.subDirArray.length >= 1 && 'lang' === fs.subDirArray[0]) { + return new Y.Do.AlterReturn(null, { + type: 'yui-lang', + skipSubdirParts: 1 + }); + } + }, + + + parseResource: function(source, type, subtype, mojitType) { + var fs = source.fs, + baseParts, + res; + + if ('yui-lang' === type) { + res = { + source: source, + mojit: mojitType, + type: 'yui-lang', + affinity: 'common', + selector: '*' + }; + if (!res.yui) { + res.yui = {}; + } + if (fs.basename === mojitType) { + res.yui.lang = ''; + } else if (mojitType === fs.basename.substr(0, mojitType.length)) { + res.yui.lang = fs.basename.substr(mojitType.length + 1); + } else { + logger.log('invalid YUI lang file format. skipping ' + fs.fullPath, 'error', NAME); + } + res.name = res.yui.lang; + res.id = [res.type, res.subtype, res.name].join('-'); + return new Y.Do.Halt(null, res); + } + + if ('yui-module' === type) { + baseParts = fs.basename.split('.'), + res = { + source: source, + mojit: mojitType, + type: 'yui-module', + affinity: 'server', + selector: '*' + }; + if (baseParts.length >= 3) { + res.selector = baseParts.pop(); + } + if (baseParts.length >= 2) { + res.affinity = baseParts.pop(); + } + if (baseParts.length !== 1) { + Y.log('invalid yui-module filename. skipping ' + fs.fullPath, 'warn', NAME); + return; + } + this._parseYUIModule(res); + res.name = res.yui.name; + res.id = [res.type, res.subtype, res.name].join('-'); + return new Y.Do.Halt(null, res); + } + }, + + + addResourceVersion: function(res) { + if ('.js' !== res.source.fs.ext) { + return; + } + if (res.yui && res.yui.name) { + // work done already + return; + } + // ASSUMPTION: no app-level resources are YUI modules + if (!res.mojit) { + return; + } + this._parseYUIModule(res); + }, + + + _parseYUIModule: function(res) { + var file, + ctx, + yui = {}; + file = libfs.readFileSync(res.source.fs.fullPath, 'utf8'); + ctx = { + console: { + log: function() {} + }, + window: {}, + document: {}, + YUI: { + add: function(name, fn, version, meta) { + yui.name = name; + yui.version = version; + yui.meta = meta || {}; + } + } + }; + try { + libvm.runInNewContext(file, ctx, res.source.fs.fullPath); + } catch (e) { + yui = null; + Y.log(e.message + '\n' + e.stack, 'error', NAME); + } + if (yui) { + res.yui = Y.merge(res.yui || {}, yui); + } + } + + + }); + Y.namespace('mojito.addons.rs'); + Y.mojito.addons.rs.yui = RSAddonYUI; + + }, '0.0.1', { requires: ['plugin', 'oop']}); + + + +Creating Custom Resource Store Addons +===================================== + +Intro +----- + +This section is intended only for those developers who need to override the built-in resource store +addons or create new resource store addons. In general, we recommend that you use the built-in resource +store addons. + +General Process +--------------- + +.. Questions: + +.. Do these steps look accurate? (would like a little more detail) + +.. 1. Create file with metadata object. +.. 2. Install Shaker with npm. +.. 3. Create addon that uses Shaker. + + +Requirements +------------ + +.. Questions: + +.. 1. What are the requirements? (configuration, functions, objects, namespaces, etc.) + +.. Answers: + +.. 1. + +Example +------- + +Intro +`````` + +In this example, you will learn how to create a resource store addon for +`Shaker `_, a static asset rollup manager for Mojito applications. + + +We'll take you through creating the metadata object and the ``shaker`` resource store addon. +You should be able to create your own resource store addons afterward and figure out how to +customize (and override) one of the built-in resource store addons. + +Creating Metadata Object +```````````````````````` +.. Questions: + +.. 1. Location and name of file containing ``metadata`` object? + +.. 2. The table of properties of the ``metadata`` object has to be completed first. + +.. Answers: + +.. 1. + + +Installing Shaker +````````````````` + +.. Questions: + +.. 1. Should the ``package.json`` file specify ``shaker`` as a dependency? + +.. 2. Is the instruction below correct and sufficient? + +.. Answers: + +.. 1. + +.. 2. + + +From the application directory of your application, run the following command to install ``shaker`` into the ``node_modules`` directory: + +``$ npm install mojito-shaker`` + + +Writing Addon +````````````` +.. Questions: + +.. 1. Does the app-level resource store addon go in ``{app_dir}/addons/rs/``? + +.. 2. Any file naming context for the resource store addon? + +.. 3. Requirements that users should know for making their own resource store addons? + +.. 4. Need code and high-level explanation of what's going on as well as a brief breakdown of salient points. + +.. Answers: + +.. 1. + +.. 2. + +.. 3. + +.. 4. + + +The ``shaker`` addon will listen for changes to the ``staticHandlerURL`` +resource field and then update ``staticHandlerURL`` and then update the ``staticHandlerURL`` so that static assets can come from +a CDN and be part of a multi-mojit rollup. + + + + + + + From c53a78c435c291cb83822b8f524348977d484c93 Mon Sep 17 00:00:00 2001 From: Joe Catera Date: Wed, 13 Jun 2012 12:18:39 -0700 Subject: [PATCH 13/45] Added questions and attempted to describe some parameters for functions that are required by resource store addons. --- .../topics/mojito_resource_store.rst | 82 +++++++++++++------ 1 file changed, 58 insertions(+), 24 deletions(-) diff --git a/docs/dev_guide/topics/mojito_resource_store.rst b/docs/dev_guide/topics/mojito_resource_store.rst index 0beb05123..cdce60ab0 100644 --- a/docs/dev_guide/topics/mojito_resource_store.rst +++ b/docs/dev_guide/topics/mojito_resource_store.rst @@ -41,9 +41,11 @@ Being a YUI Base, the resource store also provides an event subsystem and a simp What is a Mojito Resource? -------------------------- +A Mojito resource can be a unit of code or configuration that Mojito applications can include and use. At the application level, resources include archetypes, commands, configuration files, and middleware. At the mojit level, resources include controllers, models, binders, configuration files, and views. Developers can also create their own types of -resources. See `Types of Resources `_ for descriptions of the resource types. +resources to fit the need of their applications. See `Types of Resources `_ for descriptions of the +built-in resource types. .. _intro-do: @@ -75,9 +77,7 @@ During this process, the resource store is also doing the following: - providing methods for events, including those specialized for AOP. - explicitly using the addons `selector `_ and `config `_ - -To see the code for the resource store, see `store.server.js `_ in -the `Mojito GitHub repository `_. +To see the code for the resource store, see `store.server.js `_. .. _intro-use: @@ -88,7 +88,7 @@ How Can Developers Use the Resource Store? .. Questions: .. 1. Do we have any concrete or hypothesized examples of using AOP (still need to know what this is) on the resource store, creating resource -.. types, or mapping contexts to selectors? +.. types, or mapping contexts to selectors? Having a few of the most common use cases would be helpful. .. 2. Are there any other benefits for developers? @@ -167,6 +167,8 @@ Metadata Object .. 9. What "package details" are given for ``pkg``? +.. 10. Can you explain what the ``yui`` property does? Is it a Boolean that determines whether a resource is a YUI module or does it give info about the resource that is a YUI module? + .. Answers: .. 0. @@ -189,6 +191,8 @@ Metadata Object .. 9. +.. 10. + .. Please fill in or correct the rows for the 'Required?', 'Default Value', 'Possible Values', and 'Description' columns below. +------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ @@ -208,10 +212,11 @@ Metadata Object | | | | | | The value ``"shared"`` means the resource | | | | | | | is available to all mojits. | +------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ -| ``name`` | string | yes | none | | // name. common to all versions of the | -| | | | | | resource | +| ``name`` | string | yes | none | | The name of the resource that is common to | +| | | | | | all versions (i.e., iPhone/Android, etc.) | +| | | | | | of the resource. | +------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ -| `` pkg`` | string | -- | none | | // packaging details | +| `` pkg`` | string | -- | none | | // packaging details ==> what details? | +------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ | ``selector`` | string | no | "*" | | The version of the resource, not to be | | | | | | | confused revisions that mark the change of | @@ -234,7 +239,7 @@ Metadata Object | ``type`` | string | yes | none | See `Types of Resources `_. | | +------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ -| ``yui`` | string | no | none | | // for resources that are YUI modules | +| ``yui`` | string | no | none | | // for resources that are YUI modules ==?? | +------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ .. @@ -361,15 +366,18 @@ Description ~~~~~~~~~~~ The ``selector`` addon maps contexts to selectors and then returns -a priority-ordered list (POSL) of selectors. Developers can implement their custom implementation -to override the built-in ``selector`` addon. +a priority-ordered list (POSL) of selectors. + +**Who might want to customize their own version of the addon?** + +Developers wanting to use heir own algorithm for creating the POSL or refine the mapping of contexts to selector. .. _selector-reqs: Requirements ~~~~~~~~~~~~ -Because this is used directly by the the resource store, all implementations need to provide the following method: +Because the ``selector`` addon is used directly by the the resource store, all implementations need to provide the following method: ``getListFromContext(ctx)`` @@ -383,7 +391,7 @@ getListFromContext(ctx) **Parameters:** -- ``ctx`` +- ``ctx`` - The context that the application is running in. **Return:** @@ -417,7 +425,12 @@ Description The ``config`` addon provides access to the contents of the configuration files and defines new mojit-level ``config`` resource types (for the mojit's ``definition.json`` and ``defaults.json``) and new app-level ``config`` resource types (for ``application.json``, ``routes.json``, ``dimensions.json``, etc.). -Although developers can override the built-in ``config`` addon, it is not recommended. + + +**Who might want to customize their own version of the addon?** + +We do not recommend that developers create a customized ``config`` addon, but for those developers +who want to create new types of configuration files, you might want to create your own ``config`` addon. .. _config-reqs: @@ -444,7 +457,7 @@ Returns all the defined dimensions. **Parameters** -- ``cb`` +- ``cb`` - The callback function that is passed the defined dimensions. **Return:** @@ -459,9 +472,9 @@ Reads the config file pointed to by the resource. **Parameters** -- ``ctx`` -- ``res`` -- ``cb`` +- ``ctx`` - The context that the application is running in. +- ``res`` - +- ``cb`` - **Return:** @@ -665,10 +678,22 @@ instance Description ~~~~~~~~~~~ +.. Questions: + +.. 1. Who might want to create a custom version of this addon and why? + +.. Answers: + +.. 1. + The ``instance`` addon provides access to mojit details, expands specs into full instances, and defines new app-level ``spec`` resource types (found in ``mojits/*/specs/*.json``) The ``instance`` addon is not used by the resource store, but is critical to the Mojito framework. +**Who might want to customize their own version of the addon?** + + + .. _instance-reqs: Requirements @@ -693,9 +718,9 @@ The structure is made by aggregating information from all the resources in the m **Parameters** -- ``ctx`` -- ``mojitType`` -- ``cb`` +- ``ctx`` - The context that the application is running in. +- ``mojitType`` - The type of mojito for an instance that is defined in ``application.json``. +- ``cb`` - **Return:** @@ -734,10 +759,13 @@ Description The ``routes`` addon provides access to the routes. Although the addon is not used by resource store core, it is critical to the server-side Mojito mojito ships with a default implementation. The resource store has a method -for returning all of the route files in a single merged result. Although -you can create a custom ``routes`` addon, we recommend using the built-in ``routes`` -addon. +for returning all of the route files in a single merged result. +**Who might want to customize their own version of the addon?** + +We do not recommend that developers create a customized ``routes`` addon, but for those developers +who want to process the routes or add additional metadata, creating a custom ``routes`` addon might be +the solution. .. _routes-reqs: @@ -841,6 +869,9 @@ The static handler URL can be a rollup URL. The ``staticHandler`` addon also provides a method for the static handler middleware to find the filesystem path for a URL. +**Who might want to customize their own version of the addon?** + + .. _staticHandler-reqs: Requirements @@ -885,8 +916,11 @@ The ``yui`` addon has the following functions: - defines new mojit-specific resource of type ``yui-lang`` that are found in ``lang/``. - precalculates YUI dependencies for mojit controllers and binders. +**Who might want to customize their own version of the addon?** + The built-in ``yui`` addon will generally not need to be overridden with a custom version of the addon. + .. _yui-reqs: Requirements From acf7afd518efafac2b4b0b157b179cef1c7f47bd Mon Sep 17 00:00:00 2001 From: Joe Catera Date: Wed, 13 Jun 2012 12:19:47 -0700 Subject: [PATCH 14/45] Removing a backup file. --- .../topics/mojito_resource_store.rst.bak | 1189 ----------------- 1 file changed, 1189 deletions(-) delete mode 100644 docs/dev_guide/topics/mojito_resource_store.rst.bak diff --git a/docs/dev_guide/topics/mojito_resource_store.rst.bak b/docs/dev_guide/topics/mojito_resource_store.rst.bak deleted file mode 100644 index a87a32e12..000000000 --- a/docs/dev_guide/topics/mojito_resource_store.rst.bak +++ /dev/null @@ -1,1189 +0,0 @@ -============== -Resource Store -============== - - -.. General Questions: - -.. 1. Need formal definition for the resource store and resource. - -.. 2. What are the benefits of using the resource store? - -.. 3. Should the title of this chapter be about what users can do with resource store? I'm not sure if developers -.. will even read this chapter because they won't necessarily know what the resource store is. - -.. 4. Does AOP stand for aspect-oriented programming, attribute oriented programming, or something else? - - -.. Answers: - -.. 1. - -.. 2. - -.. 3. - -.. 4. - -.. _resource_store_intro: - -Intro -===== - -The resource store is the Mojito framework code that managers and keeps track of the resources in your Mojito applications. -The resource store uses addons to do much of the work, which you can read about in `Built-In Resource Store Addons `_. -The code for the resource store is a `YUI Base `_, which enables plugins to be implemented as `YUI Plugin modules `_. -Being a YUI Base, the resource store also provides an event subsystem and a simple AOP subsystem (methods ``beforeHostMethod`` and ``afterHostMethod``). - - -.. _intro-what: - -What is a Mojito Resource? --------------------------- - -At the application level, resources include archetypes, commands, configuration files, and middleware. At the mojit level, -resources include controllers, models, binders, configuration files, and views. Developers can also create their own types of -resources. See `Types of Resources `_ for descriptions of the resource types. - - -.. _intro-do: - -How Does the Resource Store Work? ----------------------------------- - -.. Questions: - -.. 1. What does 'host for addons' mean? (It's mentioned in the 'core' section of the twiki.) - -.. Answers: - -.. 1. - - - -Understanding the workflow of the resource store will give help those who want to customize addons to write code and -help others who don't plan on customizing addons to debug. - -In short, the resource store walks through the application-level, -mojit-level, and ``npm`` module files (in that order) of a Mojito application, determines what type of resource each file is, -creates an instance of the resource, and then registers the instance. - -During this process, the resource store is also doing the following: - -- precalculating ("resolving") which resource versions are used for each version of the mojit. -- keeping track of app-level resources (archetypes, commands, config files, and middleware). -- providing methods for events, including those specialized for AOP. -- explicitly using the addons `selector `_ and `config `_ - - -To see the code for the resource store, see `store.server.js `_ in -the `Mojito GitHub repository `_. - - -.. _intro-use: - -How Can Developers Use the Resource Store? ------------------------------------------- - -.. Questions: - -.. 1. Do we have any concrete or hypothesized examples of using AOP (still need to know what this is) on the resource store, creating resource -.. types, or mapping contexts to selectors? - -.. 2. Are there any other benefits for developers? - -.. Answers: - -.. 1. - -.. 2. - - -Developers can write addons for the resource store to have finer grain control over the management of resources -or extend the functionality of the resource store. As a developer, you can write custom addons to use AOP -on the resource store, create resource types, and map contexts to selectors. - - -.. _resource_store-metadata: - -Resource Metadata -================= - -.. _metadata-intro: - -Intro ------ - -.. Questions: - -.. 1. Drew, based on your response to a question about the metadata, I'm not sure if developers define resource metadata. Do they, and if so, how -.. do they define the metadata (in some config file?)? - -.. Answers: - -.. 1. - -The resource store uses metadata to find, load, parse, and create instances of resources. - - -.. _metadata-location: - -Location --------- - -.. Questions: - -.. 1. What is the location for the metadata? Is it a JSON config file like application.json? If so, what is the file name? - -.. Answers: - -.. 1. - -.. _metadata-obj: - -Metadata Object ---------------- - -.. Questions: - -.. 0. Is the data type string for all of the properties? - -.. 1. Please review and improve descriptions. The twiki and source code didn't offer much info for some. - -.. 2. It would be nice to list default values, but if most properties don't have default values, then I could remove this column. - -.. 3. Need to know what properties are required. - -.. 4. The list of properties was taken from the twiki and the source code. I have added both sets of properties to the table, -.. by I imagine some do not belong. - -.. 5. Need a description for ``subtype`` and examples. - -.. 6. What are the Mojito subsystems that addons can be added to? - -.. 7. Do we have a better description for ``name``? Any syntax convention, default values, or possible values? - -.. 8. What "filesystem details" are given for ``fs``? - -.. 9. What "package details" are given for ``pkg``? - -.. Answers: - -.. 0. - -.. 1. - -.. 2. - -.. 3. - -.. 4. - -.. 5. - -.. 6. - -.. 7. - -.. 8. - -.. 9. - -.. Please fill in or correct the rows for the 'Required?', 'Default Value', 'Possible Values', and 'Description' columns below. - -+------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ -| Property | Data Type | Required? | Default Value | Possible Values | Description | -+========================+===============+===========+===============+=============================+=============================================+ -| ``affinity`` | string | -- | -- | ``server``, ``client``, | The affinity of the resource, which | -| | | | | ``common`` | indicates where the resource will be used. | -+------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ -| ``fs`` | string | yes | none | N/A | // filesystem details ==> ?? | -+------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ -| ``id`` | string | yes | none | N/A | A unique ID that is common to all versions | -| | | | | | of the resource. The ``id`` has the | -| | | | | | following syntax convention: | -| | | | | | ``{type}-{subtype}-{name}`` | -+------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ -| `` mojit`` | string | no | none | ``shared`` | The mojit, if any, that uses this resource | -| | | | | | The value ``"shared"`` means the resource | -| | | | | | is available to all mojits. | -+------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ -| ``name`` | string | yes | none | | // name. common to all versions of the | -| | | | | | resource | -+------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ -| `` pkg`` | string | -- | none | | // packaging details | -+------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ -| ``selector`` | string | no | "*" | | The version of the resource, not to be | -| | | | | | confused revisions that mark the change of | -| | | | | | the resource over time. For example, a | -| | | | | | resource could have a version for iPhones, | -| | | | | | Android devices, fallbacks, etc. | -+------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ -| `` source`` | string | no | | | Specifies where the resource came from | -| | | | | | (not shipped to client). | -+------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ -| ``staticHandlerURL`` | string | no | none | | The path used to load the resource | -| | | | | | onto the client. Used only for resources | -| | | | | | that can be deployed by reference to the | -| | | | | | client. | -+------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ -| ``subtype`` | string | no | none | ``action``, ``binder``, | | -| | | | | ``command``, ``middleware`` | | -| | | | | ``model``, ``view`` | | -+------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ -| ``type`` | string | yes | none | See `Types of Resources `_. | | -+------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ -| ``yui`` | string | no | none | | // for resources that are YUI modules | -+------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ - -.. - - Not sure where I got the following properties, but I'm reluctant to remove them until - I have confirmation that they are unnecessary. - - +------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ - | ``addonType`` | string | -- | -- | | Specifies the mojito subsystem to which the | - | | | | | | addon should be added and is required if | - | | | | | | type if ``type=addon``. | - +------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ - | ``assetType`` | string | -- | -- | ``css``, ``js``, ``png``, | Specifies the type of asset and is required | - | | | | | ``png``, ``swf`` | if ``type=asset``. | - +------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ - | ``configType`` | string | -- | -- | | Specifies the type of configuration and is | - | | | | | | required if ``type=config``. | - +------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ - | ``fsPath`` | string | -- | none | | The path on the filesystem to the resource. | - | ``viewEngine`` | string | no | none | ``mu``, ``dust`` | Specifies the view engine being used | - | | | | | | and is only used if ``type=view``. | - +------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ - | ``viewOutputFormat`` | string | no | none | ``xml``, ``html`` | Specifies the view engine being used | - | | | | | | and is only used if ``type=view``. | - +------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ - | ``yuiModuleMeta`` | string | no | none | | Specifies the metadata, such dependencies, | - | | | | | | languages, etc., for a YUI 3 module. | - +------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ - | ``yuiModuleName`` | string | no | none | | The name of any resource delivered as a | - | | | | | | YUI 3 module. The ``type`` must be | - | | | | | | ``yui-module``. | - +------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ - | ``yuiModuleVersion`` | string | no | none | | The version of any resource delivered as a | - | | | | | | YUI 3 module. The ``type`` must be | - | | | | | | ``yui-module``. | - +------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ - | ``yuiSortedPaths`` | string | no | none | | For any resource delivered as a YUI3 module,| - | | | | | | this is the list of YUI modules required by | - | | | | | | the module with transitive dependencies | - | | | | | | resolved. The ``type`` must be | - | | | | | | ``yui-module``. | - +------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ - - - - -.. _types_resources: - -Types of Resources -`````````````````` - -The ``type`` property of the metadata object can have any of the following values: - -- ``config`` - a piece of configuration, sometimes for another resource -- ``controller`` - the controller for a mojit -- ``model`` - a model for a mojit -- ``view`` - a view for a mojit -- ``binder`` - a binder for a mojit -- ``action`` - an action to augment the controller -- ``asset`` - an asset (css, js, image, etc.) -- ``addon`` - an addon to the mojito system -- ``spec`` - the configuration for a mojit instance -- ``yui-lang`` - a YUI3 language bundle -- ``yui-module`` - a YUI3 module (that isn't one of the above) - - - -.. _metadata-ex: - -Example -------- - -.. Questions: - -.. 1. Do we have an example? - -.. code-block:: javascript - - { - source: // where the resource came from (not shipped to client) - fs: // filesystem details - pkg: // packaging details - mojit: // which mojit this applies to, if any ("shared" means the resource is available to all mojits) - type: - subtype: // not all types have a subtype - name: // name. common to all versions of the resource - id: // unique ID. common to all versions of the resource. (typically {type}-{subtype}-{name}) - staticHandlerURL: // path used to load the resource onto the client - yui: // for resources that are YUI modules - - // these are only used in the metadata for each resource version. the metadata - // for resolved resources won't have these, since they're intrinsically part of - // the resolved resource. - affinity: // "server", "client", or "common" - selector: - } - -.. _resource_store-builtin_addons: - -Built-In Resource Store Addons -============================== - -.. Note: Replace code examples with links to Mojito source once the resource store addons have been merged into master. - -.. _builtin_addons-intro: - -Intro ------ - -Mojito comes with built-in resource store addons that are used by the resource store -and the Mojito framework. These resource store addons are required by the resource store and -the Mojito framework, so particular care must be taken when creating custom versions of them. -This chapter takes a look at the built-in resource store addons, so you can better understand their use or -customize your own versions. - -.. _intro-selector: - -selector -```````` - -.. _selector-desc: - -Description -~~~~~~~~~~~ - -The ``selector`` addon maps contexts to selectors and then returns -a priority-ordered list (POSL) of selectors. Developers can implement their custom implementation -to override the built-in ``selector`` addon. - -.. _selector-reqs: - -Requirements -~~~~~~~~~~~~ - -Because this is used directly by the the resource store, all implementations need to provide the following method: - -``getListFromContext(ctx)`` - - -getListFromContext(ctx) -~~~~~~~~~~~~~~~~~~~~~~~ - -.. Question: - -.. 1. Need description, spec, and example of ``ctx`` and return value. - -**Parameters:** - -- ``ctx`` - -**Return:** - -.. _selector-ex: - -Example -~~~~~~~ - -.. _intro-config: - -config -`````` - -.. _config-desc: - - -.. Questions: - -.. 1. Should the following be included? - -.. default implementation: -.. preloadFile() registers config files as type:config resources -.. listens for an event signifying the end of preload() -.. preloads the contents of the json files - - - -Description -~~~~~~~~~~~ - -The ``config`` addon provides access to the contents of the configuration files and -defines new mojit-level ``config`` resource types (for the mojit's ``definition.json`` and ``defaults.json``) -and new app-level ``config`` resource types (for ``application.json``, ``routes.json``, ``dimensions.json``, etc.). -Although developers can override the built-in ``config`` addon, it is not recommended. - - -.. _config-reqs: - -Requirements -~~~~~~~~~~~~ - -Because this is used directly by the resource store, all implementations need to provide the following methods: - -- ``readYCBDimensions(cb)`` -- ``readResource(ctx, res, cb)`` - - -.. _config-ex: - -readYCBDimensions(cb) -~~~~~~~~~~~~~~~~~~~~~ - -.. Question: - -.. 1. Need description, spec, and example of ``cb`` and return value. - -Returns all the defined dimensions. - -**Parameters** - -- ``cb`` - -**Return:** - -readResource(ctx, res, cb) -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. Question: - -.. 1. Need description, spec, and example of ``ctx``, ``res``, ``cb`` and return value. - -Reads the config file pointed to by the resource. - -**Parameters** - -- ``ctx`` -- ``res`` -- ``cb`` - -**Return:** - -Example -~~~~~~~ - -.. code-block:: javascript - - - YUI.add('addon-rs-config', function(Y, NAME) { - - var libfs = require('fs'), - libpath = require('path'), - libycb = require(libpath.join(__dirname, '../../../libs/ycb')); - - function RSAddonConfig() { - RSAddonConfig.superclass.constructor.apply(this, arguments); - } - RSAddonConfig.NS = 'config'; - RSAddonConfig.ATTRS = {}; - - Y.extend(RSAddonConfig, Y.Plugin.Base, { - - initializer: function(config) { - this.rs = config.host; - this.appRoot = config.appRoot; - this.mojitoRoot = config.mojitoRoot; - this.afterHostMethod('findResourceByConvention', this.findResourceByConvention, this); - this.beforeHostMethod('parseResource', this.parseResource, this); - - this._jsonCache = {}; // fullPath: contents as JSON object - this._ycbCache = {}; // fullPath: YCB config object - this._ycbDims = this._readYcbDimensions(); - }, - - - destructor: function() { - // TODO: needed to break cycle so we don't leak memory? - this.rs = null; - }, - - - getDimensions: function() { - return this.rs.cloneObj(this._ycbDims); - }, - - - /** - * Reads and parses a JSON file - * - * @method readConfigJSON - * @param fullPath {string} path to JSON file - * @return {mixed} contents of JSON file - */ - // TODO: async interface - readConfigJSON: function(fullPath) { - var json, - contents; - if (!libpath.existsSync(fullPath)) { - return {}; - } - json = this._jsonCache[fullPath]; - if (!json) { - try { - contents = libfs.readFileSync(fullPath, 'utf-8'); - json = JSON.parse(contents); - } catch (e) { - throw new Error('Error parsing JSON file: ' + fullPath); - } - this._jsonCache[fullPath] = json; - } - return json; - }, - - - /** - * reads a configuration file that is in YCB format - * - * @method readConfigYCB - * @param ctx {object} runtime context - * @param fullPath {string} path to the YCB file - * @return {object} the contextualized configuration - */ - // TODO: async interface - readConfigYCB: function(fullPath, ctx) { - var cacheKey, - json, - ycb; - - ctx = this.rs.mergeRecursive(this.rs.getStaticContext(), ctx); - - ycb = this._ycbCache[fullPath]; - if (!ycb) { - json = this.readConfigJSON(fullPath); - json = this._ycbDims.concat(json); - ycb = new libycb.Ycb(json); - this._ycbCache[fullPath] = ycb; - } - return ycb.read(ctx, {}); - }, - - - findResourceByConvention: function(source, mojitType) { - var fs = source.fs, - use = false; - - // we only care about files - if (!fs.isFile) { - return; - } - // we don't care about files in subdirectories - if ('.' !== fs.subDir) { - return; - } - // we only care about json files - if ('.json' !== fs.ext) { - return; - } - // use package.json for the app and the mojit - if ('package' === fs.basename && 'bundle' !== fs.rootType) { - use = true; - } - // use all configs in the application - if ('app' === fs.rootType) { - use = true; - } - // use configs from non-shared mojit resources - if (mojitType && 'shared' !== mojitType) { - use = true; - } - if (!use) { - return; - } - - return new Y.Do.AlterReturn(null, { - type: 'config' - }); - }, - - - parseResource: function(source, type, subtype, mojitType) { - var baseParts, - res; - - if ('config' !== type) { - return; - } - - baseParts = source.fs.basename.split('.'); - res = { - source: source, - type: 'config', - affinity: 'common', - selector: '*' - }; - if ('app' !== source.fs.rootType) { - res.mojit = mojitType; - } - if (baseParts.length !== 1) { - Y.log('invalid config filename. skipping ' + source.fs.fullPath, 'warn', NAME); - return; - } - res.name = libpath.join(source.fs.subDir, baseParts.join('.')); - res.id = [res.type, res.subtype, res.name].join('-'); - return new Y.Do.Halt(null, res); - }, - - - /** - * Read the application's dimensions.json file for YCB processing. If not - * available, fall back to the framework's default dimensions.json. - * - * @method _readYcbDimensions - * @return {array} contents of the dimensions.json file - * @private - */ - _readYcbDimensions: function() { - var path = libpath.join(this.appRoot, 'dimensions.json'); - if (!libpath.existsSync(path)) { - path = libpath.join(this.mojitoRoot, 'dimensions.json'); - } - return this.readConfigJSON(path); - } - - - }); - Y.namespace('mojito.addons.rs'); - Y.mojito.addons.rs.config = RSAddonConfig; - - }, '0.0.1', { requires: ['plugin', 'oop']}); - - - -.. _intro-instance: - -instance -```````` - -.. _instance-desc: - -Description -~~~~~~~~~~~ - -The ``instance`` addon provides access to mojit details, expands specs into full instances, and -defines new app-level ``spec`` resource types (found in ``mojits/*/specs/*.json``) -The ``instance`` addon is not used by the resource store, but is critical to the Mojito framework. - -.. _instance-reqs: - -Requirements -~~~~~~~~~~~~ - -Because this addon is critical to the Mojito framework, all implementations need to provide the following methods: - -- ``getMojitDetails(ctx, mojitType, cb)`` -- ``expandSpec(ctx, spec, cb)`` - - - -getMojitDetails(ctx, mojitType, cb) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. Question: - -.. 1. Need description, spec, and example of ``ctx``, ``mojitType``, ``cb`` and return value. - -Returns a single structure that contains all details needed by the Mojito kernel -The structure is made by aggregating information from all the resources in the mojit. - -**Parameters** - -- ``ctx`` -- ``mojitType`` -- ``cb`` - -**Return:** - - -.. _instance-ex: - -Example -~~~~~~~ - -.. Question: - -.. 1. Need example. - -.. _intro-routes: - -routes -`````` - -.. Questions: - -.. 1. Is the sugar method ``getRoutes`` in ``store.server.js``? - -.. 2. To write a custom ``routes`` addon, are developers required to override ``getRoutes`` with their own version of the function? - -.. Answers: - -.. 1. - -.. 2. - -.. _routes-desc: - -Description -~~~~~~~~~~~ - -The ``routes`` addon provides access to the routes. Although the addon is -not used by resource store core, it is critical to the server-side Mojito -mojito ships with a default implementation. The resource store has a method -for returning all of the route files in a single merged result. Although -you can create a custom ``routes`` addon, we recommend using the built-in ``routes`` -addon. - - -.. _routes-reqs: - -Requirements -~~~~~~~~~~~~ - -None. - -.. _routes-ex: - -Example -~~~~~~~ - -YUI.add('addon-rs-routes', function(Y, NAME) { - - var libpath = require('path'), - libycb = require(libpath.join(__dirname, '../../../libs/ycb')); - - function RSAddonRoutes() { - RSAddonRoutes.superclass.constructor.apply(this, arguments); - } - RSAddonRoutes.NS = 'routes'; - RSAddonRoutes.DEPS = ['config']; - RSAddonRoutes.ATTRS = {}; - - Y.extend(RSAddonRoutes, Y.Plugin.Base, { - - initializer: function(config) { - this.rs = config.host; - this.appRoot = config.appRoot; - }, - - - destructor: function() { - // TODO: needed to break cycle so we don't leak memory? - this.rs = null; - }, - - - read: function(env, ctx, cb) { - ctx.runtime = env; - var appConfig = this.rs.getAppConfig(ctx), - routesFiles = appConfig.routesFiles, - p, - path, - fixedPaths = {}, - out = {}, - ress, - r, - res, - path, - routes; - - for (p = 0; p < routesFiles.length; p += 1) { - path = routesFiles[p]; - // relative paths are relative to the application - if ('/' !== path.charAt(1)) { - path = libpath.join(this.appRoot, path); - } - fixedPaths[path] = true; - } - - ress = this.rs.getResources(env, ctx, {type:'config'}); - for (r = 0; r < ress.length; r += 1) { - res = ress[r]; - if (fixedPaths[res.source.fs.fullPath]) { - routes = this.rs.config.readConfigYCB(res.source.fs.fullPath, ctx); - out = Y.merge(out, routes); - } - } - - cb(null, out); - } - - - }); - Y.namespace('mojito.addons.rs'); - Y.mojito.addons.rs.routes = RSAddonRoutes; - -}, '0.0.1', { requires: ['plugin', 'oop']}); - - -.. _intro-staticHandler: - -staticHandler -````````````` - -.. _staticHandler-desc: - -Description -~~~~~~~~~~~ - -The ``stackHandler`` addon calculates and manages the static handler URLs for resources. -The addon is not used by resource store core, but used by the static handler middleware. -Developers should not need to write their own custom version of the ``staticHandler`` addon. - -Before the method ``addResourceVersion`` is called in the resource store, resources -with the ``client`` affinity set the ``staticHandlerURL`` property to the static handler URL. -The static handler URL can be a rollup URL. - -The ``staticHandler`` addon also provides a method for the static handler middleware to find the -filesystem path for a URL. - -.. _staticHandler-reqs: - -Requirements -~~~~~~~~~~~~ - -None. - -.. _staticHandler-ex: - -Example -~~~~~~~ - -.. _intro-yui: - -yui -``` - -.. _yui-desc: - -Description -~~~~~~~~~~~ - -.. Questions: - -.. 1. Should the following be included: - -.. - - after preloadFile() - if in autoload/ or yui_modules/ makes a type:yui-module resource - if in lang/ makes a type:yui-lang resource - before addResourceVersion() - if it's a resource implemented as a YUI module, gathers the YUI module metadata about it - after resolveMojit() - calculates the YUI module dependencies for the controller - calculates the YUI module dependencies for each binder - -The ``yui`` addon has the following functions: - -- detects which resources are YUI modules and gathers additional metadata. -- defines new mojit-specific resource of type ``yui-module`` that are found in ``autoload/`` or ``yui_modules/``. -- defines new mojit-specific resource ot type ``yui-lang`` that are found in ``lang/``. -- precalculates YUI dependencies for mojit controllers and binders. - -The built-in ``yui`` addon will generally not need to be overridden with a custom version of the addon. - -.. _yui-reqs: - -Requirements -~~~~~~~~~~~~ - -None. - -.. _yui-ex: - -Example -~~~~~~~ - -.. code-block:: javascript - - /* - * Copyright (c) 2012, Yahoo! Inc. All rights reserved. - * Copyrights licensed under the New BSD License. - * See the accompanying LICENSE file for terms. - */ - - YUI.add('addon-rs-yui', function(Y, NAME) { - - var libfs = require('fs'), - libpath = require('path'), - libvm = require('vm'); - - function RSAddonYUI() { - RSAddonYUI.superclass.constructor.apply(this, arguments); - } - RSAddonYUI.NS = 'yui'; - RSAddonYUI.ATTRS = {}; - - Y.extend(RSAddonYUI, Y.Plugin.Base, { - - initializer: function(config) { - this.rs = config.host; - this.appRoot = config.appRoot; - this.mojitoRoot = config.mojitoRoot; - this.afterHostMethod('findResourceByConvention', this.findResourceByConvention, this); - this.beforeHostMethod('parseResource', this.parseResource, this); - this.beforeHostMethod('addResourceVersion', this.addResourceVersion, this); - }, - - - destructor: function() { - // TODO: needed to break cycle so we don't leak memory? - this.rs = null; - }, - - - findResourceByConvention: function(source, mojitType) { - var fs = source.fs; - - if (!fs.isFile) { - return; - } - if ('.js' !== fs.ext) { - return; - } - - if (fs.subDirArray.length >= 1 && ('autoload' === fs.subDirArray[0] || 'yui_modules' === fs.subDirArray[0])) { - return new Y.Do.AlterReturn(null, { - type: 'yui-module', - skipSubdirParts: 1 - }); - } - - if (fs.subDirArray.length >= 1 && 'lang' === fs.subDirArray[0]) { - return new Y.Do.AlterReturn(null, { - type: 'yui-lang', - skipSubdirParts: 1 - }); - } - }, - - - parseResource: function(source, type, subtype, mojitType) { - var fs = source.fs, - baseParts, - res; - - if ('yui-lang' === type) { - res = { - source: source, - mojit: mojitType, - type: 'yui-lang', - affinity: 'common', - selector: '*' - }; - if (!res.yui) { - res.yui = {}; - } - if (fs.basename === mojitType) { - res.yui.lang = ''; - } else if (mojitType === fs.basename.substr(0, mojitType.length)) { - res.yui.lang = fs.basename.substr(mojitType.length + 1); - } else { - logger.log('invalid YUI lang file format. skipping ' + fs.fullPath, 'error', NAME); - } - res.name = res.yui.lang; - res.id = [res.type, res.subtype, res.name].join('-'); - return new Y.Do.Halt(null, res); - } - - if ('yui-module' === type) { - baseParts = fs.basename.split('.'), - res = { - source: source, - mojit: mojitType, - type: 'yui-module', - affinity: 'server', - selector: '*' - }; - if (baseParts.length >= 3) { - res.selector = baseParts.pop(); - } - if (baseParts.length >= 2) { - res.affinity = baseParts.pop(); - } - if (baseParts.length !== 1) { - Y.log('invalid yui-module filename. skipping ' + fs.fullPath, 'warn', NAME); - return; - } - this._parseYUIModule(res); - res.name = res.yui.name; - res.id = [res.type, res.subtype, res.name].join('-'); - return new Y.Do.Halt(null, res); - } - }, - - - addResourceVersion: function(res) { - if ('.js' !== res.source.fs.ext) { - return; - } - if (res.yui && res.yui.name) { - // work done already - return; - } - // ASSUMPTION: no app-level resources are YUI modules - if (!res.mojit) { - return; - } - this._parseYUIModule(res); - }, - - - _parseYUIModule: function(res) { - var file, - ctx, - yui = {}; - file = libfs.readFileSync(res.source.fs.fullPath, 'utf8'); - ctx = { - console: { - log: function() {} - }, - window: {}, - document: {}, - YUI: { - add: function(name, fn, version, meta) { - yui.name = name; - yui.version = version; - yui.meta = meta || {}; - } - } - }; - try { - libvm.runInNewContext(file, ctx, res.source.fs.fullPath); - } catch (e) { - yui = null; - Y.log(e.message + '\n' + e.stack, 'error', NAME); - } - if (yui) { - res.yui = Y.merge(res.yui || {}, yui); - } - } - - - }); - Y.namespace('mojito.addons.rs'); - Y.mojito.addons.rs.yui = RSAddonYUI; - - }, '0.0.1', { requires: ['plugin', 'oop']}); - - - -Creating Custom Resource Store Addons -===================================== - -Intro ------ - -This section is intended only for those developers who need to override the built-in resource store -addons or create new resource store addons. In general, we recommend that you use the built-in resource -store addons. - -General Process ---------------- - -.. Questions: - -.. Do these steps look accurate? (would like a little more detail) - -.. 1. Create file with metadata object. -.. 2. Install Shaker with npm. -.. 3. Create addon that uses Shaker. - - -Requirements ------------- - -.. Questions: - -.. 1. What are the requirements? (configuration, functions, objects, namespaces, etc.) - -.. Answers: - -.. 1. - -Example -------- - -Intro -`````` - -In this example, you will learn how to create a resource store addon for -`Shaker `_, a static asset rollup manager for Mojito applications. - - -We'll take you through creating the metadata object and the ``shaker`` resource store addon. -You should be able to create your own resource store addons afterward and figure out how to -customize (and override) one of the built-in resource store addons. - -Creating Metadata Object -```````````````````````` -.. Questions: - -.. 1. Location and name of file containing ``metadata`` object? - -.. 2. The table of properties of the ``metadata`` object has to be completed first. - -.. Answers: - -.. 1. - - -Installing Shaker -````````````````` - -.. Questions: - -.. 1. Should the ``package.json`` file specify ``shaker`` as a dependency? - -.. 2. Is the instruction below correct and sufficient? - -.. Answers: - -.. 1. - -.. 2. - - -From the application directory of your application, run the following command to install ``shaker`` into the ``node_modules`` directory: - -``$ npm install mojito-shaker`` - - -Writing Addon -````````````` -.. Questions: - -.. 1. Does the app-level resource store addon go in ``{app_dir}/addons/rs/``? - -.. 2. Any file naming context for the resource store addon? - -.. 3. Requirements that users should know for making their own resource store addons? - -.. 4. Need code and high-level explanation of what's going on as well as a brief breakdown of salient points. - -.. Answers: - -.. 1. - -.. 2. - -.. 3. - -.. 4. - - -The ``shaker`` addon will listen for changes to the ``staticHandlerURL`` -resource field and then update ``staticHandlerURL`` and then update the ``staticHandlerURL`` so that static assets can come from -a CDN and be part of a multi-mojit rollup. - - - - - - - From ce65ffe80dd6cdd2d35993afb2cc75a8077c198b Mon Sep 17 00:00:00 2001 From: Joe Catera Date: Thu, 28 Jun 2012 17:53:07 -0700 Subject: [PATCH 15/45] Changed staticHandlerURL to url for addon and property. --- .../topics/mojito_resource_store.rst | 30 +++++++++---------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/docs/dev_guide/topics/mojito_resource_store.rst b/docs/dev_guide/topics/mojito_resource_store.rst index cdce60ab0..e76511b7d 100644 --- a/docs/dev_guide/topics/mojito_resource_store.rst +++ b/docs/dev_guide/topics/mojito_resource_store.rst @@ -227,11 +227,6 @@ Metadata Object | `` source`` | string | no | | | Specifies where the resource came from | | | | | | | (not shipped to client). | +------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ -| ``staticHandlerURL`` | string | no | none | | The path used to load the resource | -| | | | | | onto the client. Used only for resources | -| | | | | | that can be deployed by reference to the | -| | | | | | client. | -+------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ | ``subtype`` | string | no | none | ``action``, ``binder``, | | | | | | | ``command``, ``middleware`` | | | | | | | ``model``, ``view`` | | @@ -239,6 +234,11 @@ Metadata Object | ``type`` | string | yes | none | See `Types of Resources `_. | | +------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ +| ``url`` | string | no | none | | The path used to load the resource | +| | | | | | onto the client. Used only for resources | +| | | | | | that can be deployed by reference to the | +| | | | | | client. | ++------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ | ``yui`` | string | no | none | | // for resources that are YUI modules ==?? | +------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ @@ -848,38 +848,38 @@ YUI.add('addon-rs-routes', function(Y, NAME) { }, '0.0.1', { requires: ['plugin', 'oop']}); -.. _intro-staticHandler: +.. _url-intro: -staticHandler -````````````` +url +``` -.. _staticHandler-desc: +.. _url-desc: Description ~~~~~~~~~~~ -The ``stackHandler`` addon calculates and manages the static handler URLs for resources. +The ``url`` addon calculates and manages the static handler URLs for resources. The addon is not used by resource store core, but used by the static handler middleware. -Developers should not need to write their own custom version of the ``staticHandler`` addon. +Developers should not need to write their own custom version of the ``url`` addon. Before the method ``addResourceVersion`` is called in the resource store, resources -with the ``client`` affinity set the ``staticHandlerURL`` property to the static handler URL. +with the ``client`` affinity set the ``url`` property to the static handler URL. The static handler URL can be a rollup URL. -The ``staticHandler`` addon also provides a method for the static handler middleware to find the +The ``url`` addon also provides a method for the static handler middleware to find the filesystem path for a URL. **Who might want to customize their own version of the addon?** -.. _staticHandler-reqs: +.. _url-reqs: Requirements ~~~~~~~~~~~~ None. -.. _staticHandler-ex: +.. _url-ex: Example ~~~~~~~ From 25763310dd9787f255e291f44be89850a93cc44e Mon Sep 17 00:00:00 2001 From: Joe Catera Date: Tue, 3 Jul 2012 16:50:20 -0700 Subject: [PATCH 16/45] Updated resource store doc. --- .../topics/mojito_resource_store.rst | 79 ++++++++++++------- 1 file changed, 49 insertions(+), 30 deletions(-) diff --git a/docs/dev_guide/topics/mojito_resource_store.rst b/docs/dev_guide/topics/mojito_resource_store.rst index e76511b7d..404334fa1 100644 --- a/docs/dev_guide/topics/mojito_resource_store.rst +++ b/docs/dev_guide/topics/mojito_resource_store.rst @@ -413,10 +413,7 @@ config .. 1. Should the following be included? .. default implementation: -.. preloadFile() registers config files as type:config resources -.. listens for an event signifying the end of preload() -.. preloads the contents of the json files - +.. ``findResourceByConvention()`` registers config files as ``type:config`` resources Description @@ -440,14 +437,16 @@ Requirements Because this is used directly by the resource store, all implementations need to provide the following methods: -- ``readYCBDimensions(cb)`` -- ``readResource(ctx, res, cb)`` +- ``getDimensions()`` +- ``readConfigJSON(path)`` +- ``readConfigYCB(path, ctx)`` -.. _config-ex: -readYCBDimensions(cb) -~~~~~~~~~~~~~~~~~~~~~ +.. _config-getDimensions: + +getDimensions() +~~~~~~~~~~~~~~~ .. Question: @@ -457,24 +456,39 @@ Returns all the defined dimensions. **Parameters** -- ``cb`` - The callback function that is passed the defined dimensions. +None **Return:** -readResource(ctx, res, cb) -~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. _config-readConfigJSON: + +readConfigJSON(path) +~~~~~~~~~~~~~~~~~~~~ + +Reads the JSON configuration file. + +**Parameters** + +- ``path`` - The path to the JSON configuration file. -.. Question: -.. 1. Need description, spec, and example of ``ctx``, ``res``, ``cb`` and return value. +**Return:** + +.. _config-ex: -Reads the config file pointed to by the resource. +readConfigYCB(path, ctx) +~~~~~~~~~~~~~~~~~~~~~~~~ + +Reads the context configuration file. + +.. Question: + +.. 1. Need return value. **Parameters** -- ``ctx`` - The context that the application is running in. -- ``res`` - -- ``cb`` - +- ``path`` - The path to the context configuration file. +- ``ctx`` - The context configuration to read. **Return:** @@ -858,18 +872,22 @@ url Description ~~~~~~~~~~~ +.. Question: + +.. 1. Who might want to customize their own version of the addon? + The ``url`` addon calculates and manages the static handler URLs for resources. The addon is not used by resource store core, but used by the static handler middleware. Developers should not need to write their own custom version of the ``url`` addon. -Before the method ``addResourceVersion`` is called in the resource store, resources -with the ``client`` affinity set the ``url`` property to the static handler URL. +After the method ``preloadResourceVersions`` sets ``res.url`` to the static handler URL +for the resource, the method ``getMojitTypeDetails`` sets the mojit's ``assetsRoot``. The static handler URL can be a rollup URL. + The ``url`` addon also provides a method for the static handler middleware to find the filesystem path for a URL. -**Who might want to customize their own version of the addon?** .. _url-reqs: @@ -896,18 +914,20 @@ Description .. Questions: -.. 1. Should the following be included: +.. 1. Who might want to customize their own version of the addon? +.. 2. Should the following be included? .. - after preloadFile() - if in autoload/ or yui_modules/ makes a type:yui-module resource - if in lang/ makes a type:yui-lang resource + after findResourceByConvention() + - detect ``yui-module`` and ``yui-lang`` resources. before addResourceVersion() - if it's a resource implemented as a YUI module, gathers the YUI module metadata about it - after resolveMojit() - calculates the YUI module dependencies for the controller - calculates the YUI module dependencies for each binder + - if it's a resource implemented as a YUI module, gathers the YUI module metadata about it + on mojitResourceResolved() + - calculates the YUI module dependencies for the controller + - calculates the YUI module dependencies for each binder + on getMojitTypeDetails() + - add dependency information to the mojit's details The ``yui`` addon has the following functions: @@ -916,7 +936,6 @@ The ``yui`` addon has the following functions: - defines new mojit-specific resource of type ``yui-lang`` that are found in ``lang/``. - precalculates YUI dependencies for mojit controllers and binders. -**Who might want to customize their own version of the addon?** The built-in ``yui`` addon will generally not need to be overridden with a custom version of the addon. From e52fcf1caeb242942283401de5b9e8505eda7892 Mon Sep 17 00:00:00 2001 From: Joe Catera Date: Fri, 6 Jul 2012 10:05:33 -0700 Subject: [PATCH 17/45] Removed the instance built-in addon, added an audience section, spelled out AOP and linked it, removed addons that have become part of the resource store. --- .../topics/mojito_resource_store.rst | 973 +++--------------- 1 file changed, 153 insertions(+), 820 deletions(-) diff --git a/docs/dev_guide/topics/mojito_resource_store.rst b/docs/dev_guide/topics/mojito_resource_store.rst index 404334fa1..4cf74223c 100644 --- a/docs/dev_guide/topics/mojito_resource_store.rst +++ b/docs/dev_guide/topics/mojito_resource_store.rst @@ -3,43 +3,51 @@ Resource Store ============== -.. General Questions: - -.. 1. Need formal definition for the resource store and resource. +.. _resource_store_intro: -.. 2. What are the benefits of using the resource store? +Intro +===== -.. 3. Should the title of this chapter be about what users can do with resource store? I'm not sure if developers -.. will even read this chapter because they won't necessarily know what the resource store is. +The Resource Store (RS) is the Mojito substystem that manages metadata about the files in your Mojito applications. +The Resource Store (RS) manages metadata about the files in the application. Thus, +it is responsible for finding and classifying code and configuration files. -.. 4. Does AOP stand for aspect-oriented programming, attribute oriented programming, or something else? -.. Answers: +.. _intro-who: -.. 1. +Who Needs to Know About the Resource Store? +------------------------------------------- -.. 2. +Most Mojito application developers will not need to know much about the resource store other than what it does. Advanced Mojito application developers who +want to track new files types or modify information that the RS tracks through metadata. -.. 3. - -.. 4. - -.. _resource_store_intro: +.. _intro-use: -Intro -===== +How Can the Resource Store Help Developers? +------------------------------------------- -The resource store is the Mojito framework code that managers and keeps track of the resources in your Mojito applications. -The resource store uses addons to do much of the work, which you can read about in `Built-In Resource Store Addons `_. -The code for the resource store is a `YUI Base `_, which enables plugins to be implemented as `YUI Plugin modules `_. -Being a YUI Base, the resource store also provides an event subsystem and a simple AOP subsystem (methods ``beforeHostMethod`` and ``afterHostMethod``). +Developers can write addons for the resource store to have finer grain control over the management of resources +or extend the functionality of the resource store. As a developer, you can write custom addons to use AOP +on the resource store, create resource types, and map contexts to selectors. +Yes, if an advanced developer wants to write a Mojito commandline tool +to do interesting things with files/resources in the application. For +example, all of our commandline tools (except `start`) use the resource +store. + +Writing a RS addon lets a dev teach the RS how to track new file types, +augment the information that RS stores about file/code, or augment or +replace the information returned by RS. + .. _intro-what: -What is a Mojito Resource? --------------------------- +What is a Resource? +------------------- + +"A Mojito resource can be a unit of code or configuration that Mojito +applications can include and use." A Mojito resource can be a unit of code or configuration that Mojito applications can include and use. At the application level, resources include archetypes, commands, configuration files, and middleware. At the mojit level, @@ -47,21 +55,54 @@ resources include controllers, models, binders, configuration files, and views. resources to fit the need of their applications. See `Types of Resources `_ for descriptions of the built-in resource types. +.. From Drew's doc: -.. _intro-do: +Although, for Mojito, a "resource" is primarily something useful found on the filesystem, +the RS primarily cares about the *metadata* about each file. So, a "resource" in the RS +is an object containing metadata. -How Does the Resource Store Work? ----------------------------------- +Since there can be multiple files which are all conceptually different versions of the +same thing (think `views/index.mu.html` and `views/index.iphone.mu.html`), the RS defines +"resource version" as the metadata about each file and "resource" as the metadata +about the file chosen among the possible choices. -.. Questions: +The process of choosing which version of a resource to use is called "resolution" (or +"resolving the resource"). This act is one of the primary responsibilities of the Resource Store. +See "resolution and priorities" below. -.. 1. What does 'host for addons' mean? (It's mentioned in the 'core' section of the twiki.) +Some resources (and resource versions) are "mojit-level": the resource is scoped to a mojit. +Examples are controllers, views, and binders. -.. Answers: +Some resources (and resource versions) are "shared", which means that they are included in *all* +mojits. Most resource types that are "mojit-level" can also be shared. Examples of mojit-level +resource types that can't be shared are controllers, config files (such as `definition.json`), and +YUI language bundles. -.. 1. +Some resources are "app-level". These resources are truly global to the application. +Some example resource types are middleware, RS addons, architetypes, and commands. +(As an implementation detail, the RS still tracks resource versions for these kinds of resources +and then resolves those versions down to a chosen resource, even though there's only one version +of each resource. More work at server start, but less code to write and debug.) + +The RS primarily manages metadata about resources, so it calls the +metadata the "resource". The "resource" is just a JS object containing +metadata. The RS define certain keys with specific meanings. RS addons +can add, remove, or modify those keys/values as they see fit. (For +example, it is the yui RS addon that adds the "yui" key with metadata +about resources that are YUI modules. The RS itself doesn't populate +the "yui" key of each resource.) + +.. _intro-do: + +How Does the Resource Store Work? +---------------------------------- + +Resource store addons +The code for the resource store is a `YUI Base `_, which enables plugins to be implemented as `YUI Plugin modules `_. +Being a YUI Base, the resource store also provides an event subsystem and a simple aspect-oriented subsystem (methods ``beforeHostMethod`` and ``afterHostMethod``). +Mojito addons Understanding the workflow of the resource store will give help those who want to customize addons to write code and help others who don't plan on customizing addons to debug. @@ -80,29 +121,13 @@ During this process, the resource store is also doing the following: To see the code for the resource store, see `store.server.js `_. -.. _intro-use: - -How Can Developers Use the Resource Store? ------------------------------------------- - -.. Questions: - -.. 1. Do we have any concrete or hypothesized examples of using AOP (still need to know what this is) on the resource store, creating resource -.. types, or mapping contexts to selectors? Having a few of the most common use cases would be helpful. - -.. 2. Are there any other benefits for developers? - -.. Answers: - -.. 1. +Resource Store Addons +===================== -.. 2. - - -Developers can write addons for the resource store to have finer grain control over the management of resources -or extend the functionality of the resource store. As a developer, you can write custom addons to use AOP -on the resource store, create resource types, and map contexts to selectors. +The resource store uses addons to do much of the work, which you can read about in `Built-In Resource Store Addons `_. +Also, a RS "addon" is implemented using the YUI "plugin" mechanism. +"addon" is the Mojito terminology, and "plugin" is the YUI terminology. .. _resource_store-metadata: @@ -114,15 +139,6 @@ Resource Metadata Intro ----- -.. Questions: - -.. 1. Drew, based on your response to a question about the metadata, I'm not sure if developers define resource metadata. Do they, and if so, how -.. do they define the metadata (in some config file?)? - -.. Answers: - -.. 1. - The resource store uses metadata to find, load, parse, and create instances of resources. @@ -131,13 +147,9 @@ The resource store uses metadata to find, load, parse, and create instances of r Location -------- -.. Questions: - -.. 1. What is the location for the metadata? Is it a JSON config file like application.json? If so, what is the file name? - -.. Answers: - -.. 1. +The resource metadata is generated by code -- it has no representation +on the filesystem. It is generate during `preload()`, either by the RS +itself or by RS addons. .. _metadata-obj: @@ -169,32 +181,16 @@ Metadata Object .. 10. Can you explain what the ``yui`` property does? Is it a Boolean that determines whether a resource is a YUI module or does it give info about the resource that is a YUI module? -.. Answers: - -.. 0. - -.. 1. -.. 2. - -.. 3. - -.. 4. - -.. 5. - -.. 6. - -.. 7. - -.. 8. - -.. 9. - -.. 10. .. Please fill in or correct the rows for the 'Required?', 'Default Value', 'Possible Values', and 'Description' columns below. +ome values do have defaults, but it depends on the value of the "type" +key, and/or comes from the filename of the resource being represented. +For example, the "affinity" of views is "common" (since views are used +on both client and server), however the "affinity" for controllers comes +from the filename. + +------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ | Property | Data Type | Required? | Default Value | Possible Values | Description | +========================+===============+===========+===============+=============================+=============================================+ @@ -283,7 +279,13 @@ Metadata Object | | | | | | ``yui-module``. | +------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ - +It doesn't make sense to have a default value. The "name" is what +uniquely identifies the resource within type and subtype. For example, +views/index.mu.html might have "type:view", empty subtype, and +"name:index". The name should be the same for all -versions- of the +resource, so for example views/index.iphone.mu.html would have the exact +same type, subtype, and name as views/index.mu.html (only the "selector" +would be different). .. _types_resources: @@ -305,6 +307,15 @@ The ``type`` property of the metadata object can have any of the following value - ``yui-lang`` - a YUI3 language bundle - ``yui-module`` - a YUI3 module (that isn't one of the above) +Subtypes +```````` + +Subtype is used for certain types, but not others. For example, an +"type:addon" resource might have "subtype:ac" for AC addons, or +"subtype:view-engine" for view engines, or "subtype:rs" for RS addons. +For "type:archetype" the subtypes refers to the "type" described by +`mojito help create`. So, you could have "subtype:app" or +"subtype:mojit". (There might be more in the future!) .. _metadata-ex: @@ -337,14 +348,14 @@ Example selector: } -.. _resource_store-builtin_addons: +.. _resource_store-write_addons: -Built-In Resource Store Addons -============================== +Writing RS Addons +================= .. Note: Replace code examples with links to Mojito source once the resource store addons have been merged into master. -.. _builtin_addons-intro: +.. _write_addons-intro: Intro ----- @@ -355,6 +366,39 @@ the Mojito framework, so particular care must be taken when creating custom vers This chapter takes a look at the built-in resource store addons, so you can better understand their use or customize your own versions. +.. Link to API docs + +.. _resource_store-custom_addons: + +Creating Custom Versions of Built-In RS Addons +---------------------------------------------- + +This section is intended only for developers who need to override the built-in resource store +addons or create new resource store addons. In general, we recommend that you use the built-in resource +store addons. + +>> I think we should, by default, -not- document these. They have API +>> docs, so the users (which remember are advanced devs) can look at that +>> or their source code. The two possible exceptions to that are the +>> "selector" and "url" addons, which we expect some users might want to +>> make replacements for. Their replacements will need to follow the same +>> API, so we should document that API. This documentation is different +>> than the API documentation for the addon itself. That API doc says what +>> that addon implementation -does-, but the RS API docs should outline +>> what the RS -expects- the addon to do. + +"In general, we recommend that +>> you use the built-in versions of the "config" and "url" addons". As +>> mentioned before, we'll have to document the specific requirements for +>> writing a replacement for the "selector" or "url" RS addons. + +That's true for most of the RS addons, but not all, and it's just fine +if they write new addons. So, perhaps "In general, we recommend that +you use the built-in versions of the "config" and "url" addons". As +mentioned before, we'll have to document the specific requirements for +writing a replacement for the "selector" or "url" RS addons. + + .. _intro-selector: selector @@ -400,466 +444,7 @@ getListFromContext(ctx) Example ~~~~~~~ -.. _intro-config: - -config -`````` - -.. _config-desc: - - -.. Questions: - -.. 1. Should the following be included? - -.. default implementation: -.. ``findResourceByConvention()`` registers config files as ``type:config`` resources - - -Description -~~~~~~~~~~~ - -The ``config`` addon provides access to the contents of the configuration files and -defines new mojit-level ``config`` resource types (for the mojit's ``definition.json`` and ``defaults.json``) -and new app-level ``config`` resource types (for ``application.json``, ``routes.json``, ``dimensions.json``, etc.). - - -**Who might want to customize their own version of the addon?** - -We do not recommend that developers create a customized ``config`` addon, but for those developers -who want to create new types of configuration files, you might want to create your own ``config`` addon. - - -.. _config-reqs: - -Requirements -~~~~~~~~~~~~ - -Because this is used directly by the resource store, all implementations need to provide the following methods: - -- ``getDimensions()`` -- ``readConfigJSON(path)`` -- ``readConfigYCB(path, ctx)`` - - - -.. _config-getDimensions: - -getDimensions() -~~~~~~~~~~~~~~~ - -.. Question: - -.. 1. Need description, spec, and example of ``cb`` and return value. - -Returns all the defined dimensions. -**Parameters** - -None - -**Return:** - -.. _config-readConfigJSON: - -readConfigJSON(path) -~~~~~~~~~~~~~~~~~~~~ - -Reads the JSON configuration file. - -**Parameters** - -- ``path`` - The path to the JSON configuration file. - - -**Return:** - -.. _config-ex: - -readConfigYCB(path, ctx) -~~~~~~~~~~~~~~~~~~~~~~~~ - -Reads the context configuration file. - -.. Question: - -.. 1. Need return value. - -**Parameters** - -- ``path`` - The path to the context configuration file. -- ``ctx`` - The context configuration to read. - -**Return:** - -Example -~~~~~~~ - -.. code-block:: javascript - - - YUI.add('addon-rs-config', function(Y, NAME) { - - var libfs = require('fs'), - libpath = require('path'), - libycb = require(libpath.join(__dirname, '../../../libs/ycb')); - - function RSAddonConfig() { - RSAddonConfig.superclass.constructor.apply(this, arguments); - } - RSAddonConfig.NS = 'config'; - RSAddonConfig.ATTRS = {}; - - Y.extend(RSAddonConfig, Y.Plugin.Base, { - - initializer: function(config) { - this.rs = config.host; - this.appRoot = config.appRoot; - this.mojitoRoot = config.mojitoRoot; - this.afterHostMethod('findResourceByConvention', this.findResourceByConvention, this); - this.beforeHostMethod('parseResource', this.parseResource, this); - - this._jsonCache = {}; // fullPath: contents as JSON object - this._ycbCache = {}; // fullPath: YCB config object - this._ycbDims = this._readYcbDimensions(); - }, - - - destructor: function() { - // TODO: needed to break cycle so we don't leak memory? - this.rs = null; - }, - - - getDimensions: function() { - return this.rs.cloneObj(this._ycbDims); - }, - - - /** - * Reads and parses a JSON file - * - * @method readConfigJSON - * @param fullPath {string} path to JSON file - * @return {mixed} contents of JSON file - */ - // TODO: async interface - readConfigJSON: function(fullPath) { - var json, - contents; - if (!libpath.existsSync(fullPath)) { - return {}; - } - json = this._jsonCache[fullPath]; - if (!json) { - try { - contents = libfs.readFileSync(fullPath, 'utf-8'); - json = JSON.parse(contents); - } catch (e) { - throw new Error('Error parsing JSON file: ' + fullPath); - } - this._jsonCache[fullPath] = json; - } - return json; - }, - - - /** - * reads a configuration file that is in YCB format - * - * @method readConfigYCB - * @param ctx {object} runtime context - * @param fullPath {string} path to the YCB file - * @return {object} the contextualized configuration - */ - // TODO: async interface - readConfigYCB: function(fullPath, ctx) { - var cacheKey, - json, - ycb; - - ctx = this.rs.mergeRecursive(this.rs.getStaticContext(), ctx); - - ycb = this._ycbCache[fullPath]; - if (!ycb) { - json = this.readConfigJSON(fullPath); - json = this._ycbDims.concat(json); - ycb = new libycb.Ycb(json); - this._ycbCache[fullPath] = ycb; - } - return ycb.read(ctx, {}); - }, - - - findResourceByConvention: function(source, mojitType) { - var fs = source.fs, - use = false; - - // we only care about files - if (!fs.isFile) { - return; - } - // we don't care about files in subdirectories - if ('.' !== fs.subDir) { - return; - } - // we only care about json files - if ('.json' !== fs.ext) { - return; - } - // use package.json for the app and the mojit - if ('package' === fs.basename && 'bundle' !== fs.rootType) { - use = true; - } - // use all configs in the application - if ('app' === fs.rootType) { - use = true; - } - // use configs from non-shared mojit resources - if (mojitType && 'shared' !== mojitType) { - use = true; - } - if (!use) { - return; - } - - return new Y.Do.AlterReturn(null, { - type: 'config' - }); - }, - - - parseResource: function(source, type, subtype, mojitType) { - var baseParts, - res; - - if ('config' !== type) { - return; - } - - baseParts = source.fs.basename.split('.'); - res = { - source: source, - type: 'config', - affinity: 'common', - selector: '*' - }; - if ('app' !== source.fs.rootType) { - res.mojit = mojitType; - } - if (baseParts.length !== 1) { - Y.log('invalid config filename. skipping ' + source.fs.fullPath, 'warn', NAME); - return; - } - res.name = libpath.join(source.fs.subDir, baseParts.join('.')); - res.id = [res.type, res.subtype, res.name].join('-'); - return new Y.Do.Halt(null, res); - }, - - - /** - * Read the application's dimensions.json file for YCB processing. If not - * available, fall back to the framework's default dimensions.json. - * - * @method _readYcbDimensions - * @return {array} contents of the dimensions.json file - * @private - */ - _readYcbDimensions: function() { - var path = libpath.join(this.appRoot, 'dimensions.json'); - if (!libpath.existsSync(path)) { - path = libpath.join(this.mojitoRoot, 'dimensions.json'); - } - return this.readConfigJSON(path); - } - - - }); - Y.namespace('mojito.addons.rs'); - Y.mojito.addons.rs.config = RSAddonConfig; - - }, '0.0.1', { requires: ['plugin', 'oop']}); - - - -.. _intro-instance: - -instance -```````` - -.. _instance-desc: - -Description -~~~~~~~~~~~ - -.. Questions: - -.. 1. Who might want to create a custom version of this addon and why? - -.. Answers: - -.. 1. - -The ``instance`` addon provides access to mojit details, expands specs into full instances, and -defines new app-level ``spec`` resource types (found in ``mojits/*/specs/*.json``) -The ``instance`` addon is not used by the resource store, but is critical to the Mojito framework. - -**Who might want to customize their own version of the addon?** - - - -.. _instance-reqs: - -Requirements -~~~~~~~~~~~~ - -Because this addon is critical to the Mojito framework, all implementations need to provide the following methods: - -- ``getMojitDetails(ctx, mojitType, cb)`` -- ``expandSpec(ctx, spec, cb)`` - - - -getMojitDetails(ctx, mojitType, cb) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. Question: - -.. 1. Need description, spec, and example of ``ctx``, ``mojitType``, ``cb`` and return value. - -Returns a single structure that contains all details needed by the Mojito kernel -The structure is made by aggregating information from all the resources in the mojit. - -**Parameters** - -- ``ctx`` - The context that the application is running in. -- ``mojitType`` - The type of mojito for an instance that is defined in ``application.json``. -- ``cb`` - - -**Return:** - - -.. _instance-ex: - -Example -~~~~~~~ - -.. Question: - -.. 1. Need example. - -.. _intro-routes: - -routes -`````` - -.. Questions: - -.. 1. Is the sugar method ``getRoutes`` in ``store.server.js``? - -.. 2. To write a custom ``routes`` addon, are developers required to override ``getRoutes`` with their own version of the function? - -.. Answers: - -.. 1. - -.. 2. - -.. _routes-desc: - -Description -~~~~~~~~~~~ - -The ``routes`` addon provides access to the routes. Although the addon is -not used by resource store core, it is critical to the server-side Mojito -mojito ships with a default implementation. The resource store has a method -for returning all of the route files in a single merged result. - -**Who might want to customize their own version of the addon?** - -We do not recommend that developers create a customized ``routes`` addon, but for those developers -who want to process the routes or add additional metadata, creating a custom ``routes`` addon might be -the solution. - -.. _routes-reqs: - -Requirements -~~~~~~~~~~~~ - -None. - -.. _routes-ex: - -Example -~~~~~~~ - -YUI.add('addon-rs-routes', function(Y, NAME) { - - var libpath = require('path'), - libycb = require(libpath.join(__dirname, '../../../libs/ycb')); - - function RSAddonRoutes() { - RSAddonRoutes.superclass.constructor.apply(this, arguments); - } - RSAddonRoutes.NS = 'routes'; - RSAddonRoutes.DEPS = ['config']; - RSAddonRoutes.ATTRS = {}; - - Y.extend(RSAddonRoutes, Y.Plugin.Base, { - - initializer: function(config) { - this.rs = config.host; - this.appRoot = config.appRoot; - }, - - - destructor: function() { - // TODO: needed to break cycle so we don't leak memory? - this.rs = null; - }, - - - read: function(env, ctx, cb) { - ctx.runtime = env; - var appConfig = this.rs.getAppConfig(ctx), - routesFiles = appConfig.routesFiles, - p, - path, - fixedPaths = {}, - out = {}, - ress, - r, - res, - path, - routes; - - for (p = 0; p < routesFiles.length; p += 1) { - path = routesFiles[p]; - // relative paths are relative to the application - if ('/' !== path.charAt(1)) { - path = libpath.join(this.appRoot, path); - } - fixedPaths[path] = true; - } - - ress = this.rs.getResources(env, ctx, {type:'config'}); - for (r = 0; r < ress.length; r += 1) { - res = ress[r]; - if (fixedPaths[res.source.fs.fullPath]) { - routes = this.rs.config.readConfigYCB(res.source.fs.fullPath, ctx); - out = Y.merge(out, routes); - } - } - - cb(null, out); - } - - - }); - Y.namespace('mojito.addons.rs'); - Y.mojito.addons.rs.routes = RSAddonRoutes; - -}, '0.0.1', { requires: ['plugin', 'oop']}); .. _url-intro: @@ -888,6 +473,14 @@ The static handler URL can be a rollup URL. The ``url`` addon also provides a method for the static handler middleware to find the filesystem path for a URL. + + +Any property which wants to have control over the static handler URLs of +the resources, including potentially serving resources from a CDN. Such +a property will hopefully use Shaker, so in fact the Shaker team would +need to know how to write a "url" RS addon. Some other properties might +want to do some extra fancy/custom things (besides what Shaker does) so +they might want to write a "url" RS addon. .. _url-reqs: @@ -902,250 +495,22 @@ None. Example ~~~~~~~ -.. _intro-yui: - -yui -``` - -.. _yui-desc: - -Description -~~~~~~~~~~~ - -.. Questions: - -.. 1. Who might want to customize their own version of the addon? -.. 2. Should the following be included? - -.. - - after findResourceByConvention() - - detect ``yui-module`` and ``yui-lang`` resources. - before addResourceVersion() - - if it's a resource implemented as a YUI module, gathers the YUI module metadata about it - on mojitResourceResolved() - - calculates the YUI module dependencies for the controller - - calculates the YUI module dependencies for each binder - on getMojitTypeDetails() - - add dependency information to the mojit's details - -The ``yui`` addon has the following functions: - -- detects which resources are YUI modules and gathers additional metadata. -- defines new mojit-specific resource of type ``yui-module`` that are found in ``autoload/`` or ``yui_modules/``. -- defines new mojit-specific resource of type ``yui-lang`` that are found in ``lang/``. -- precalculates YUI dependencies for mojit controllers and binders. -The built-in ``yui`` addon will generally not need to be overridden with a custom version of the addon. - - -.. _yui-reqs: - -Requirements -~~~~~~~~~~~~ - -None. - -.. _yui-ex: - -Example -~~~~~~~ - -.. code-block:: javascript - - /* - * Copyright (c) 2012, Yahoo! Inc. All rights reserved. - * Copyrights licensed under the New BSD License. - * See the accompanying LICENSE file for terms. - */ - - YUI.add('addon-rs-yui', function(Y, NAME) { - - var libfs = require('fs'), - libpath = require('path'), - libvm = require('vm'); - - function RSAddonYUI() { - RSAddonYUI.superclass.constructor.apply(this, arguments); - } - RSAddonYUI.NS = 'yui'; - RSAddonYUI.ATTRS = {}; - - Y.extend(RSAddonYUI, Y.Plugin.Base, { - - initializer: function(config) { - this.rs = config.host; - this.appRoot = config.appRoot; - this.mojitoRoot = config.mojitoRoot; - this.afterHostMethod('findResourceByConvention', this.findResourceByConvention, this); - this.beforeHostMethod('parseResource', this.parseResource, this); - this.beforeHostMethod('addResourceVersion', this.addResourceVersion, this); - }, - - - destructor: function() { - // TODO: needed to break cycle so we don't leak memory? - this.rs = null; - }, - - - findResourceByConvention: function(source, mojitType) { - var fs = source.fs; - - if (!fs.isFile) { - return; - } - if ('.js' !== fs.ext) { - return; - } - - if (fs.subDirArray.length >= 1 && ('autoload' === fs.subDirArray[0] || 'yui_modules' === fs.subDirArray[0])) { - return new Y.Do.AlterReturn(null, { - type: 'yui-module', - skipSubdirParts: 1 - }); - } - - if (fs.subDirArray.length >= 1 && 'lang' === fs.subDirArray[0]) { - return new Y.Do.AlterReturn(null, { - type: 'yui-lang', - skipSubdirParts: 1 - }); - } - }, - - - parseResource: function(source, type, subtype, mojitType) { - var fs = source.fs, - baseParts, - res; - - if ('yui-lang' === type) { - res = { - source: source, - mojit: mojitType, - type: 'yui-lang', - affinity: 'common', - selector: '*' - }; - if (!res.yui) { - res.yui = {}; - } - if (fs.basename === mojitType) { - res.yui.lang = ''; - } else if (mojitType === fs.basename.substr(0, mojitType.length)) { - res.yui.lang = fs.basename.substr(mojitType.length + 1); - } else { - logger.log('invalid YUI lang file format. skipping ' + fs.fullPath, 'error', NAME); - } - res.name = res.yui.lang; - res.id = [res.type, res.subtype, res.name].join('-'); - return new Y.Do.Halt(null, res); - } - - if ('yui-module' === type) { - baseParts = fs.basename.split('.'), - res = { - source: source, - mojit: mojitType, - type: 'yui-module', - affinity: 'server', - selector: '*' - }; - if (baseParts.length >= 3) { - res.selector = baseParts.pop(); - } - if (baseParts.length >= 2) { - res.affinity = baseParts.pop(); - } - if (baseParts.length !== 1) { - Y.log('invalid yui-module filename. skipping ' + fs.fullPath, 'warn', NAME); - return; - } - this._parseYUIModule(res); - res.name = res.yui.name; - res.id = [res.type, res.subtype, res.name].join('-'); - return new Y.Do.Halt(null, res); - } - }, - - - addResourceVersion: function(res) { - if ('.js' !== res.source.fs.ext) { - return; - } - if (res.yui && res.yui.name) { - // work done already - return; - } - // ASSUMPTION: no app-level resources are YUI modules - if (!res.mojit) { - return; - } - this._parseYUIModule(res); - }, - - - _parseYUIModule: function(res) { - var file, - ctx, - yui = {}; - file = libfs.readFileSync(res.source.fs.fullPath, 'utf8'); - ctx = { - console: { - log: function() {} - }, - window: {}, - document: {}, - YUI: { - add: function(name, fn, version, meta) { - yui.name = name; - yui.version = version; - yui.meta = meta || {}; - } - } - }; - try { - libvm.runInNewContext(file, ctx, res.source.fs.fullPath); - } catch (e) { - yui = null; - Y.log(e.message + '\n' + e.stack, 'error', NAME); - } - if (yui) { - res.yui = Y.merge(res.yui || {}, yui); - } - } - - - }); - Y.namespace('mojito.addons.rs'); - Y.mojito.addons.rs.yui = RSAddonYUI; - - }, '0.0.1', { requires: ['plugin', 'oop']}); - -Creating Custom Resource Store Addons -===================================== +Creating Your Own Resource Store Addons +--------------------------------------- Intro ----- -This section is intended only for those developers who need to override the built-in resource store -addons or create new resource store addons. In general, we recommend that you use the built-in resource -store addons. + General Process --------------- -.. Questions: - -.. Do these steps look accurate? (would like a little more detail) - -.. 1. Create file with metadata object. -.. 2. Install Shaker with npm. -.. 3. Create addon that uses Shaker. +.. Use Drew's skeleton doc Requirements @@ -1165,47 +530,18 @@ Example Intro `````` -In this example, you will learn how to create a resource store addon for -`Shaker `_, a static asset rollup manager for Mojito applications. +In this example, you will learn how to create a resource store addon to do ... -We'll take you through creating the metadata object and the ``shaker`` resource store addon. +We'll take you through creating the metadata object and the ... resource store addon. You should be able to create your own resource store addons afterward and figure out how to customize (and override) one of the built-in resource store addons. Creating Metadata Object ```````````````````````` -.. Questions: - -.. 1. Location and name of file containing ``metadata`` object? - -.. 2. The table of properties of the ``metadata`` object has to be completed first. -.. Answers: - -.. 1. -Installing Shaker -````````````````` - -.. Questions: - -.. 1. Should the ``package.json`` file specify ``shaker`` as a dependency? - -.. 2. Is the instruction below correct and sufficient? - -.. Answers: - -.. 1. - -.. 2. - - -From the application directory of your application, run the following command to install ``shaker`` into the ``node_modules`` directory: - -``$ npm install mojito-shaker`` - Writing Addon ````````````` @@ -1230,10 +566,7 @@ Writing Addon .. 4. -The ``shaker`` addon will listen for changes to the ``staticHandlerURL`` -resource field and then update ``staticHandlerURL`` and then update the ``staticHandlerURL`` so that static assets can come from -a CDN and be part of a multi-mojit rollup. - +The ... addon will ... From 78d10b1792a3f899e83eef120787e08100125560 Mon Sep 17 00:00:00 2001 From: Joe Catera Date: Fri, 6 Jul 2012 18:13:24 -0700 Subject: [PATCH 18/45] Added info from Drew's skeleton docs. Need to edit the section on creating custom RS addons and built-in addons. --- .../topics/mojito_resource_store.rst | 682 +++++++++++------- 1 file changed, 421 insertions(+), 261 deletions(-) diff --git a/docs/dev_guide/topics/mojito_resource_store.rst b/docs/dev_guide/topics/mojito_resource_store.rst index 4cf74223c..6e59c8429 100644 --- a/docs/dev_guide/topics/mojito_resource_store.rst +++ b/docs/dev_guide/topics/mojito_resource_store.rst @@ -9,9 +9,7 @@ Intro ===== The Resource Store (RS) is the Mojito substystem that manages metadata about the files in your Mojito applications. -The Resource Store (RS) manages metadata about the files in the application. Thus, -it is responsible for finding and classifying code and configuration files. - +The RS manages metadata about the files in the application. Thus, it is responsible for finding and classifying code and configuration files. .. _intro-who: @@ -19,115 +17,122 @@ it is responsible for finding and classifying code and configuration files. Who Needs to Know About the Resource Store? ------------------------------------------- -Most Mojito application developers will not need to know much about the resource store other than what it does. Advanced Mojito application developers who -want to track new files types or modify information that the RS tracks through metadata. +Most Mojito application developers will not need to know much about the resource store, but advanced Mojito application developers who +want to have finer grain control over the management of resources +or extend the functionality of the resource store should read this documentation. + +.. track new files types or modify information that the RS tracks through metadata can write their own RS addons. .. _intro-use: How Can the Resource Store Help Developers? ------------------------------------------- -Developers can write addons for the resource store to have finer grain control over the management of resources -or extend the functionality of the resource store. As a developer, you can write custom addons to use AOP -on the resource store, create resource types, and map contexts to selectors. +You can write custom RS addons to use the aspect-oriented features of +the resource store, to create resource types, and to map contexts to selectors. -Yes, if an advanced developer wants to write a Mojito commandline tool -to do interesting things with files/resources in the application. For -example, all of our commandline tools (except `start`) use the resource -store. - -Writing a RS addon lets a dev teach the RS how to track new file types, -augment the information that RS stores about file/code, or augment or -replace the information returned by RS. +For example, you could write your own RS addon so that the Mojito command-line +tool will create files and resources for your application. The Mojito command-line +tool uses the RS for all the commands except ``start``. + +You can also write custom versions of built-in RS addons to modify how the resource store works. You custom addon could track new file types, +augment the information that RS stores about files or code, or augment/replace the information returned by RS. -.. _intro-what: +.. _intro-do: + + + + +.. _rs-resources: + +Resources +========= + +.. _resources-what: What is a Resource? ------------------- -"A Mojito resource can be a unit of code or configuration that Mojito -applications can include and use." +To Mojito +````````` + +The Mojito framework primarely views a **resource** as something useful found on the filesystem. -A Mojito resource can be a unit of code or configuration that Mojito applications can include and use. -At the application level, resources include archetypes, commands, configuration files, and middleware. At the mojit level, -resources include controllers, models, binders, configuration files, and views. Developers can also create their own types of -resources to fit the need of their applications. See `Types of Resources `_ for descriptions of the -built-in resource types. -.. From Drew's doc: -Although, for Mojito, a "resource" is primarily something useful found on the filesystem, -the RS primarily cares about the *metadata* about each file. So, a "resource" in the RS -is an object containing metadata. +To the Resource Store +````````````````````` + +The RS primarily cares about the *metadata* about each resource +The RS uses metadata resources, so it calls the +metadata the "resource". The "resource" is just a JavaScript object containing +metadata. The RS define certain keys with specific meanings. RS addons +can add, remove, or modify those keys/values as they see fit. (For +example, it is the yui RS addon that adds the "yui" key with metadata +about resources that are YUI modules. The RS itself doesn't populate +the "yui" key of each resource.) + + +.. _resources-versions: + +Resource Versions +----------------- Since there can be multiple files which are all conceptually different versions of the -same thing (think `views/index.mu.html` and `views/index.iphone.mu.html`), the RS defines +same thing (think ``views/index.mu.html`` and ``views/index.iphone.mu.html``), the RS defines "resource version" as the metadata about each file and "resource" as the metadata about the file chosen among the possible choices. -The process of choosing which version of a resource to use is called "resolution" (or +The process of choosing which version of a resource to use is called *resolution* (or "resolving the resource"). This act is one of the primary responsibilities of the Resource Store. + See "resolution and priorities" below. -Some resources (and resource versions) are "mojit-level": the resource is scoped to a mojit. -Examples are controllers, views, and binders. -Some resources (and resource versions) are "shared", which means that they are included in *all* -mojits. Most resource types that are "mojit-level" can also be shared. Examples of mojit-level -resource types that can't be shared are controllers, config files (such as `definition.json`), and -YUI language bundles. +Resource Scope +-------------- + +.. _resources-application: + +Application-Level Resources +``````````````````````````` -Some resources are "app-level". These resources are truly global to the application. +Application-level resources are truly global to the application. Some example resource types are middleware, RS addons, architetypes, and commands. (As an implementation detail, the RS still tracks resource versions for these kinds of resources and then resolves those versions down to a chosen resource, even though there's only one version of each resource. More work at server start, but less code to write and debug.) +At the application level, resources include archetypes, commands, configuration files, and middleware. -The RS primarily manages metadata about resources, so it calls the -metadata the "resource". The "resource" is just a JS object containing -metadata. The RS define certain keys with specific meanings. RS addons -can add, remove, or modify those keys/values as they see fit. (For -example, it is the yui RS addon that adds the "yui" key with metadata -about resources that are YUI modules. The RS itself doesn't populate -the "yui" key of each resource.) +.. _resources-mojit: -.. _intro-do: +Mojit-Level Resources +````````````````````` -How Does the Resource Store Work? ----------------------------------- +At the mojit level, resources include controllers, models, binders, configuration files, and views. +These resources are limited in scope to a mojit. -Resource store addons - -The code for the resource store is a `YUI Base `_, which enables plugins to be implemented as `YUI Plugin modules `_. -Being a YUI Base, the resource store also provides an event subsystem and a simple aspect-oriented subsystem (methods ``beforeHostMethod`` and ``afterHostMethod``). +.. _resources-shared: -Mojito addons +Shared Resources +```````````````` -Understanding the workflow of the resource store will give help those who want to customize addons to write code and -help others who don't plan on customizing addons to debug. - -In short, the resource store walks through the application-level, -mojit-level, and ``npm`` module files (in that order) of a Mojito application, determines what type of resource each file is, -creates an instance of the resource, and then registers the instance. - -During this process, the resource store is also doing the following: - -- precalculating ("resolving") which resource versions are used for each version of the mojit. -- keeping track of app-level resources (archetypes, commands, config files, and middleware). -- providing methods for events, including those specialized for AOP. -- explicitly using the addons `selector `_ and `config `_ +Some resources (and resource versions) are *shared*, meaning that they are included in **all** +mojits. Most resource types that are mojit level can also be shared. Examples of mojit-level +resource types that can't be shared are controllers, configuration files (such as ``definition.json``), and +YUI language bundles. -To see the code for the resource store, see `store.server.js `_. +.. _resources-types: +Resource Types +-------------- -Resource Store Addons -===================== +The resource type is defined by the ``type`` property in the metadata for a given resource. +See `Types of Resources `_ for descriptions of the built-in resource types. +Developers can also create their own types of resources to fit the need of their applications. -The resource store uses addons to do much of the work, which you can read about in `Built-In Resource Store Addons `_. -Also, a RS "addon" is implemented using the YUI "plugin" mechanism. -"addon" is the Mojito terminology, and "plugin" is the YUI terminology. .. _resource_store-metadata: @@ -139,48 +144,16 @@ Resource Metadata Intro ----- -The resource store uses metadata to find, load, parse, and create instances of resources. - - -.. _metadata-location: - -Location --------- - -The resource metadata is generated by code -- it has no representation +The resource store uses metadata to find, load, parse, and create instances of resources. The resource metadata is generated by code -- it has no representation on the filesystem. It is generate during `preload()`, either by the RS itself or by RS addons. + .. _metadata-obj: Metadata Object --------------- -.. Questions: - -.. 0. Is the data type string for all of the properties? - -.. 1. Please review and improve descriptions. The twiki and source code didn't offer much info for some. - -.. 2. It would be nice to list default values, but if most properties don't have default values, then I could remove this column. - -.. 3. Need to know what properties are required. - -.. 4. The list of properties was taken from the twiki and the source code. I have added both sets of properties to the table, -.. by I imagine some do not belong. - -.. 5. Need a description for ``subtype`` and examples. - -.. 6. What are the Mojito subsystems that addons can be added to? - -.. 7. Do we have a better description for ``name``? Any syntax convention, default values, or possible values? - -.. 8. What "filesystem details" are given for ``fs``? - -.. 9. What "package details" are given for ``pkg``? - -.. 10. Can you explain what the ``yui`` property does? Is it a Boolean that determines whether a resource is a YUI module or does it give info about the resource that is a YUI module? - .. Please fill in or correct the rows for the 'Required?', 'Default Value', 'Possible Values', and 'Description' columns below. @@ -238,46 +211,6 @@ from the filename. | ``yui`` | string | no | none | | // for resources that are YUI modules ==?? | +------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ -.. - - Not sure where I got the following properties, but I'm reluctant to remove them until - I have confirmation that they are unnecessary. - - +------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ - | ``addonType`` | string | -- | -- | | Specifies the mojito subsystem to which the | - | | | | | | addon should be added and is required if | - | | | | | | type if ``type=addon``. | - +------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ - | ``assetType`` | string | -- | -- | ``css``, ``js``, ``png``, | Specifies the type of asset and is required | - | | | | | ``png``, ``swf`` | if ``type=asset``. | - +------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ - | ``configType`` | string | -- | -- | | Specifies the type of configuration and is | - | | | | | | required if ``type=config``. | - +------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ - | ``fsPath`` | string | -- | none | | The path on the filesystem to the resource. | - | ``viewEngine`` | string | no | none | ``mu``, ``dust`` | Specifies the view engine being used | - | | | | | | and is only used if ``type=view``. | - +------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ - | ``viewOutputFormat`` | string | no | none | ``xml``, ``html`` | Specifies the view engine being used | - | | | | | | and is only used if ``type=view``. | - +------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ - | ``yuiModuleMeta`` | string | no | none | | Specifies the metadata, such dependencies, | - | | | | | | languages, etc., for a YUI 3 module. | - +------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ - | ``yuiModuleName`` | string | no | none | | The name of any resource delivered as a | - | | | | | | YUI 3 module. The ``type`` must be | - | | | | | | ``yui-module``. | - +------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ - | ``yuiModuleVersion`` | string | no | none | | The version of any resource delivered as a | - | | | | | | YUI 3 module. The ``type`` must be | - | | | | | | ``yui-module``. | - +------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ - | ``yuiSortedPaths`` | string | no | none | | For any resource delivered as a YUI3 module,| - | | | | | | this is the list of YUI modules required by | - | | | | | | the module with transitive dependencies | - | | | | | | resolved. The ``type`` must be | - | | | | | | ``yui-module``. | - +------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ It doesn't make sense to have a default value. The "name" is what uniquely identifies the resource within type and subtype. For example, @@ -323,81 +256,209 @@ For "type:archetype" the subtypes refers to the "type" described by Example ------- -.. Questions: - -.. 1. Do we have an example? .. code-block:: javascript { - source: // where the resource came from (not shipped to client) - fs: // filesystem details - pkg: // packaging details - mojit: // which mojit this applies to, if any ("shared" means the resource is available to all mojits) - type: - subtype: // not all types have a subtype - name: // name. common to all versions of the resource - id: // unique ID. common to all versions of the resource. (typically {type}-{subtype}-{name}) - staticHandlerURL: // path used to load the resource onto the client - yui: // for resources that are YUI modules - - // these are only used in the metadata for each resource version. the metadata - // for resolved resources won't have these, since they're intrinsically part of - // the resolved resource. - affinity: // "server", "client", or "common" - selector: - } + "source": { + "fs": { + "fullPath": "/Users/folta/work/yahoo/mojito/github-drewfish/examples/getting-started-guide/part4/paged-yql/mojits/PagedFlickr/views/index.mu.html", + "rootDir": "/Users/folta/work/yahoo/mojito/github-drewfish/examples/getting-started-guide/part4/paged-yql/mojits/PagedFlickr", + "rootType": "mojit", + "subDir": ".", + "subDirArray": [], + "isFile": true, + "ext": ".html", + "basename": "index.mu" + }, + "pkg": { + "name": "paged-yql", + "version": "0.1.0", + "depth": 0 + } + }, + "type": "view", + "name": "index", + "id": "view--index", + "mojit": "PagedFlickr", + "affinity": "common", + "selector": "iphone", + "viewOutputFormat": "html", + "viewEngine": "mu", + "url": "/static/PagedFlickr/views/index.mu.html" + } + + + +.. _resource_store-how: + +How Does the Resource Store Work? +================================= + +Understanding the workflow of the resource store will give help those who want to customize addons to write code and +help others who don't plan on customizing addons to debug. + +In short, the resource store walks through the application-level, +mojit-level, and ``npm`` module files (in that order) of a Mojito application, determines what type of resource each file is, +creates an instance of the resource, and then registers the instance. + +During this process, the resource store is also doing the following: + +- precalculating ("resolving") which resource versions are used for each version of the mojit. +- keeping track of app-level resources (archetypes, commands, config files, and middleware). +- providing methods for events, including those specialized for AOP. +- explicitly using the addons `selector `_ and `config `_ + +To see the code for the resource store, see `store.server.js `_. + + +Walking the Filesystem +---------------------- + +Resource versions are discovered by the RS at server-start time. (Mojito server calls the +`preload()` method of the RS.) + +This is done by walking all the files in the application, excluding the ``node_modules`` directory. + +Then, all files in the packages in `node_modules/` are walked. The packages are walked in +breadth-first fassion, so that "shallower" packages have precedence above "deeper" ones. +(Not all the packages are used, of course, only those that have declared themselves as extensions +to Mojito.) + +(Then, if Mojito wasn't found in `node_modules/`, the globally-installed version of Mojito is walked.) + +After all that, the RS knows about all the resource versions. Then it resolves those versions +into the resources as described below. That still happens as part of `preload()`. + +Resolution and Priorities +------------------------- + +The act of resolving the resource versions is really just resolving the affinities and selectors. + +For example, the application might have the following: + +* `controller.common.js` +* `controller.common.iphone.js` +* `controller.server.js` +* `controller.server.phone.js` + +The order of the selectors is defined by a "POSL": priority-ordered selector list. The POSL depends on +the runtime context. In our example, the POSL for context `{device:browser}` might be `['*']` but for +context `{device:iphone}` might be `['iphone','*']`. + +(We need to use a (prioritized) list of selectors instead of just a "selector that matches the context" +because not all versions might exist for all selectors. In the example above, if +`controller.server.iphone.js` didn't exist we should still do the right thing for context `{device:iphone}`.) + +As well, the choice depends on the affinity. If we're resolving versions for the server, versions with +`affinity:server` will have higher priority than `affinity:common`, and `affinity:client` will be completely +ignored. + +The final consideration for priority is the "source". Mojit-level versions have higher priority than +shared versions. For example, imagine an application with the following: + +* `mojits/Foo/models/bar.common.js` +* `models/bar.common.js` + +In this case the second resource is shared with all mojits. However, the mojit `Foo` has defined its own +version of the same resource (id `model--bar`), and so that should have higher priority than the shared one. + +Finally, there's a relationship between the different types of priority. + +1. The source has highest priority. +1. The selector has next highest priority. +1. The affinity has least highest priority. + +That means that if there exists, for example, both a `controller.server.js` and `controller.common.iphone.js`, +for the server and context `{device:iphone}` the second version will be used, since its selector is a higher +priority match than its affinity. + + +All this is precalculated for each resource, for each possible runtime configuration (client or server, and +every possible runtime context). + +Getting Data from the Resource Store +------------------------------------ + +Besides the standard ways that Mojito uses the resource store, there are generic interfaces to getting +resources and resource versions from the RS. + +* `getResourceVersions(filter)` +* `getResources(env, ctx, filter)` + +The APIs are intentially similar. Both return an array of resources, and the `filter` argument +can be used to restrict the returned resources (or versions). It is an object, all of whose +keys and values must match the returned resources (or versions). Think of it as a "template" +or "partial resource" which all resources must match. For example, a filter of `{type:'view'}` +will return all the views. + +For mojit-level resources or resource versions, specify the mojit name in the filter. For example +filter `{mojit:'Foo'}` will return all resources (or versions) in the `Foo` mojit. +**Note** that, because of the resolution process, the resources returned for filter `{mojit:'Foo'}` +might contain shared resources. + +To get mojit-level resources (or versions) from multiple mojits, you'll have to call +`getResourceVersions()` or `getResources()` for each mojit. You can call `listAllMojits()` to +get the list of all mojits. + + + + +Resource store addons + +The code for the resource store is a `YUI Base `_, which enables plugins to be implemented as `YUI Plugin modules `_. +Being a YUI Base, the resource store also provides an event subsystem and a simple aspect-oriented subsystem (methods ``beforeHostMethod`` and ``afterHostMethod``). + +Mojito addons .. _resource_store-write_addons: -Writing RS Addons -================= -.. Note: Replace code examples with links to Mojito source once the resource store addons have been merged into master. +.. _resource_store-addons: -.. _write_addons-intro: +Resource Store Built-In Addons +============================== Intro ----- Mojito comes with built-in resource store addons that are used by the resource store and the Mojito framework. These resource store addons are required by the resource store and -the Mojito framework, so particular care must be taken when creating custom versions of them. -This chapter takes a look at the built-in resource store addons, so you can better understand their use or -customize your own versions. - -.. Link to API docs +the Mojito framework. In general, so particular care must be taken when creating custom versions of them. + +The RS comes with the following four built-in addons: + +- ``config`` + - registers new resource type ``config`` found in ``.json`` files + - provides API for reading both context and straight-JSON files + - also provides sugar for reading the application's dimensions +- ``selector`` + - decides the priority-ordered list (POSL) to use for a context + - default implementation looks for ``selector`` in ``application.json``. Because ``application.json`` is a context configuration file, the ``selector`` can be contextualized there. +- ``url`` + - calculates the static handler URL for appropriate resources (and resource versions) + - URL is stored in the ``url`` key of the resource + - also calculates the asset URL base for each mojit +- ``yui`` + - registers new resource type ``yui-module`` found in ``autoload`` or ``yui_modules`` + - registers new resource type ``yui-lang`` found in ``lang`` + - calculates the ``yui`` metadata for resource versions which are YUI modules + - when resources are resolved for each version of each mojit, precalculates cooresponding YUI module dependencies + - when Mojito queries the RS for details of a mojit (`getMojitTypeDetails()`) appends the precalculated YUI module dependencies for the controller and binders + - provides methods used by Mojito to configure its YUI instances + .. _resource_store-custom_addons: Creating Custom Versions of Built-In RS Addons ---------------------------------------------- -This section is intended only for developers who need to override the built-in resource store -addons or create new resource store addons. In general, we recommend that you use the built-in resource -store addons. - ->> I think we should, by default, -not- document these. They have API ->> docs, so the users (which remember are advanced devs) can look at that ->> or their source code. The two possible exceptions to that are the ->> "selector" and "url" addons, which we expect some users might want to ->> make replacements for. Their replacements will need to follow the same ->> API, so we should document that API. This documentation is different ->> than the API documentation for the addon itself. That API doc says what ->> that addon implementation -does-, but the RS API docs should outline ->> what the RS -expects- the addon to do. - -"In general, we recommend that ->> you use the built-in versions of the "config" and "url" addons". As ->> mentioned before, we'll have to document the specific requirements for ->> writing a replacement for the "selector" or "url" RS addons. - -That's true for most of the RS addons, but not all, and it's just fine -if they write new addons. So, perhaps "In general, we recommend that -you use the built-in versions of the "config" and "url" addons". As -mentioned before, we'll have to document the specific requirements for -writing a replacement for the "selector" or "url" RS addons. - +We will be examing the ``selector`` and ``url`` addons to help you create custom versions of those addons. +In general, because we do not recommend that you create custom versions of the ``config`` or ``yui`` addons, +we will not be looking at those addons. Also, this documentation explains what the RS expects the addon to do, +so you can create your own version of the addons. To learn what a RS addon does, please refer to the +`ResourceStore.server Class `_ in the API documentation. + .. _intro-selector: @@ -409,12 +470,10 @@ selector Description ~~~~~~~~~~~ -The ``selector`` addon maps contexts to selectors and then returns -a priority-ordered list (POSL) of selectors. - -**Who might want to customize their own version of the addon?** +If you wish to use a different algorithm for to determine the selectors to use, +you can implement your own version of this RS addon. It'll need to go in +``addons/rs/selector.server.js`` in your application. -Developers wanting to use heir own algorithm for creating the POSL or refine the mapping of contexts to selector. .. _selector-reqs: @@ -423,30 +482,27 @@ Requirements Because the ``selector`` addon is used directly by the the resource store, all implementations need to provide the following method: -``getListFromContext(ctx)`` +- ``getListFromContext(ctx)`` +.. _selector-getListFromContext: getListFromContext(ctx) ~~~~~~~~~~~~~~~~~~~~~~~ - -.. Question: - -.. 1. Need description, spec, and example of ``ctx`` and return value. +Returns the priority-ordered selector list (POSL) for the context. **Parameters:** -- ``ctx`` - The context that the application is running in. +- ``ctx `` - The context that the application is running in. **Return:** +```` + .. _selector-ex: Example ~~~~~~~ - - - .. _url-intro: url @@ -457,39 +513,83 @@ url Description ~~~~~~~~~~~ -.. Question: - -.. 1. Who might want to customize their own version of the addon? The ``url`` addon calculates and manages the static handler URLs for resources. The addon is not used by resource store core, but used by the static handler middleware. -Developers should not need to write their own custom version of the ``url`` addon. + +If you wish to use a different algorithm to determine the URLs, you can +implement your own version of this RS addon. It'll need to go in +``addons/rs/url.server.js`` in your application. After the method ``preloadResourceVersions`` sets ``res.url`` to the static handler URL for the resource, the method ``getMojitTypeDetails`` sets the mojit's ``assetsRoot``. The static handler URL can be a rollup URL. - The ``url`` addon also provides a method for the static handler middleware to find the filesystem path for a URL. - - -Any property which wants to have control over the static handler URLs of -the resources, including potentially serving resources from a CDN. Such -a property will hopefully use Shaker, so in fact the Shaker team would -need to know how to write a "url" RS addon. Some other properties might -want to do some extra fancy/custom things (besides what Shaker does) so -they might want to write a "url" RS addon. - .. _url-reqs: Requirements ~~~~~~~~~~~~ +The ``selector`` addon is required to have the following methods (see details for the methods in below sections): + +- ``getPathForURL(url)`` +- ``getSpecURL(id)`` +- ``getURLPaths()`` +- + +Your addon will also be required to do the following: + +- Add the ``url`` metadatum to resource versions; this is where your addon will set the calculated value (using ``beforeHostMethod('addResourceVersion')``). +- Add ``assetsRoot`` to the results of ``getMojitTypeDetails()``, which is done with ``onHostEvent('getMojitTypeDetails')``; ``assetsRoot`` is the common prefix for all assets in the mojit. The built-in addon makes something like ``/static/Foo/assets`` for the ``Foo`` mojit. + +.. _url-getPathForURL: + +getPathForURL(url) +`````````````````` +This method is called by the static handler middleware. Returns the full filesystem path for the URL. + +**Parameters:** + +- ``url `` - The URL that was previously generated. + +**Return:** + +```` + +.. _url-getSpecURL: + +getSpecURL(id) +`````````````` +Returns the URL for the spec. + +**Parameters:** + +- ``id `` - the spec ID. + +**Return:** + +```` + +.. _url-getSpecURL: + +getURLPaths() +````````````` +Returns an object whose keys are all URLs and whose values are the cooresponding filesystem paths. + +**Parameters:** + None. +**Return:** + +```` + + + .. _url-ex: Example @@ -498,75 +598,135 @@ Example - Creating Your Own Resource Store Addons ---------------------------------------- +======================================= Intro ----- +In this section, we will discuss the key methods, events, and give a simple example of a custom RS addon. +You should be able to create your own custom RS addons afterward. +Anatomy of a RS Addon +--------------------- -General Process ---------------- +The resource store addons are implemented using the `YUI Plugin `_ mechanism. In essence, a Mojito addon is a YUI plugin. +The skeleton of the addon will be the same as a YUI Plugin. -.. Use Drew's skeleton doc +Key Methods +~~~~~~~~~~~ +initialize(config) +`````````````````` -Requirements ------------- +**Parameters:** -.. Questions: +- ``config `` - contains the following: + - ``host `` - contains the resource store. + - ``appRoot `` - the directory of the application. + - ``mojitoRoot `` - the directory of the Mojito framework code. + +**Return:** -.. 1. What are the requirements? (configuration, functions, objects, namespaces, etc.) +None. -.. Answers: +preload() +````````` -.. 1. + * addons are loaded during this method, so it's not possible to hook in before this + * during this, `preloadResourceVersions()` and `resolveResourceVersions()` are called + * it *is* possible to hookin afterwards via `afterHostMethod('preload', ...)` -Example -------- +**Parameters:** -Intro -`````` +**Return:** -In this example, you will learn how to create a resource store addon to do ... +preloadResourceVersions() +````````````````````````` + * this is when the RS walks the filesystem + * before this, not much is known, though the static app config is available (via `getStaticAppConfig()`) + * during this, the following host methods happen: `findResourceVersionByConvention()`, `parseResourceVersion()`, and `addResourceVersion()` + * after this + * all the resource versions have been loaded and are available via `getResourceVersions()` + * the RS has a `selectors` object whose keys are all selectors actually in the app. the values are just `true`. -We'll take you through creating the metadata object and the ... resource store addon. -You should be able to create your own resource store addons afterward and figure out how to -customize (and override) one of the built-in resource store addons. +**Parameters:** -Creating Metadata Object -```````````````````````` +**Return:** +findResourceVersionByConvention() +````````````````````````````````` + * called on each directory or file being walked + * used to decide if the path is a resource version + * return value is a bit tricky, so read API docs carefully (and ask questions if not clear) + * typically, hook into this via `afterHostMethod()` to register your own resource version types + * this should work together with your own version of `parseResourceVersion()` +**Parameters:** -Writing Addon -````````````` -.. Questions: +**Return:** + +parseResourceVersion() +`````````````````````` -.. 1. Does the app-level resource store addon go in ``{app_dir}/addons/rs/``? + * called to create an actual resource version + * typically, hook into this via `beforeHostMethod()` to create your own resource versions + * this should work together with your own version of `findResourceVersionByConvention()` -.. 2. Any file naming context for the resource store addon? +**Parameters:** -.. 3. Requirements that users should know for making their own resource store addons? +**Return:** + +addResourceVersion() +```````````````````` -.. 4. Need code and high-level explanation of what's going on as well as a brief breakdown of salient points. + * called to save the resource version into the RS + * typically, if you want to modify/augment an existing resource version, hook into this via `beforeHostMethod()` -.. Answers: +**Parameters:** -.. 1. +**Return:** -.. 2. -.. 3. +resolveResourceVersions() +````````````````````````` -.. 4. + * called to resolve the resource versions down into resources + * during this, the `mojitResourcesResolved` event is called + * after this, all resource versions have been resolved + +**Parameters:** + +**Return:** + +serializeClientStore() +`````````````````````` + +called during runtime as Mojito creates the configuration for the client-side Mojito + +**Parameters:** + +**Return:** + + +Key Events +~~~~~~~~~~ + +mojitResourcesResolved +`````````````````````` +Called when the resources in a mojit are resolved. + +getMojitTypeDetails +``````````````````` +Called during runtime as Mojito creates an "instance" used to dispatch a mojit. + + +Example +------- -The ... addon will ... From aa948e3136cbcd74ed1d26d5193daab26987d973 Mon Sep 17 00:00:00 2001 From: Joe Catera Date: Mon, 9 Jul 2012 19:14:38 -0700 Subject: [PATCH 19/45] Finished added information from skeleton doc and example. --- .../topics/mojito_resource_store.rst | 333 ++++++++++++++---- 1 file changed, 260 insertions(+), 73 deletions(-) diff --git a/docs/dev_guide/topics/mojito_resource_store.rst b/docs/dev_guide/topics/mojito_resource_store.rst index 6e59c8429..2c38942d8 100644 --- a/docs/dev_guide/topics/mojito_resource_store.rst +++ b/docs/dev_guide/topics/mojito_resource_store.rst @@ -39,11 +39,6 @@ You can also write custom versions of built-in RS addons to modify how the resou augment the information that RS stores about files or code, or augment/replace the information returned by RS. -.. _intro-do: - - - - .. _rs-resources: Resources @@ -170,7 +165,7 @@ from the filename. | ``affinity`` | string | -- | -- | ``server``, ``client``, | The affinity of the resource, which | | | | | | ``common`` | indicates where the resource will be used. | +------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ -| ``fs`` | string | yes | none | N/A | // filesystem details ==> ?? | +| ``fs`` | string | yes | none | N/A | | +------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ | ``id`` | string | yes | none | N/A | A unique ID that is common to all versions | | | | | | | of the resource. The ``id`` has the | @@ -183,7 +178,9 @@ from the filename. +------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ | ``name`` | string | yes | none | | The name of the resource that is common to | | | | | | | all versions (i.e., iPhone/Android, etc.) | -| | | | | | of the resource. | +| | | | | | of the resource. Example: the name for | +| | | | | | for the resources ``index.iphone.mu.html`` | +| | | | | | and ``index.mu.html`` is ``index``. | +------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ | `` pkg`` | string | -- | none | | // packaging details ==> what details? | +------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ @@ -193,12 +190,14 @@ from the filename. | | | | | | resource could have a version for iPhones, | | | | | | | Android devices, fallbacks, etc. | +------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ -| `` source`` | string | no | | | Specifies where the resource came from | -| | | | | | (not shipped to client). | +| ``source`` | object | yes | | | Specifies where the resource came from | +| | | | | | (not shipped to client). See `source Object | +| | | | | | `_ for details. | +------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ -| ``subtype`` | string | no | none | ``action``, ``binder``, | | -| | | | | ``command``, ``middleware`` | | -| | | | | ``model``, ``view`` | | +| ``subtype`` | string | no | none | ``action``, ``binder``, | Some resource types have multiple subtypes | +| | | | | ``command``, ``middleware`` | that can be specified with ``subtype``. See | +| | | | | ``model``, ``view`` | `Subtypes `_ for more | +| | | | | | information. | +------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ | ``type`` | string | yes | none | See `Types of Resources `_. | | @@ -208,23 +207,44 @@ from the filename. | | | | | | that can be deployed by reference to the | | | | | | | client. | +------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ -| ``yui`` | string | no | none | | // for resources that are YUI modules ==?? | +| ``yui`` | object | no | none | | // for resources that are YUI modules ==?? | +------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ +.. _src_obj: + +source Object +````````````` + ++------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ +| Property | Data Type | Required? | Default Value | Possible Values | Description | ++========================+===============+===========+===============+===============================+=============================================+ +| ``fs`` | string | yes | none | N/A | // filesystem details ==> ?? | ++------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ +| ``pkg`` | array | yes | none | N/A | // packaging details ==> what details? | ++------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ + +yui Object +`````````` + +The ``yui`` property of the metadata object is created by the ``yui`` resource store addon, and therefore, the ``yui`` property can +be any data type. In general, the ``yui`` property is an object containing metadata about YUI modules. The following table lists +the typical properties that are part of the ``yui`` object. You can think of the ``yui`` object as a container for + the arguments to the ``YUI.add`` method that is used to register reusable YUI modules. -It doesn't make sense to have a default value. The "name" is what -uniquely identifies the resource within type and subtype. For example, -views/index.mu.html might have "type:view", empty subtype, and -"name:index". The name should be the same for all -versions- of the -resource, so for example views/index.iphone.mu.html would have the exact -same type, subtype, and name as views/index.mu.html (only the "selector" -would be different). ++------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ +| Property | Data Type | Required? | Default Value | Possible Values | Description | ++========================+===============+===========+===============+===============================+=============================================+ +| ``name`` | string | yes | none | "scroll" | The name of the YUI module. | ++------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ +| ``meta.requires`` | array | yes | none | ``["scroll","node","cache"]`` | Contains a list of YUI modules required by | +| | | | | | this resource. | ++------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ .. _types_resources: Types of Resources -`````````````````` +------------------ The ``type`` property of the metadata object can have any of the following values: @@ -240,12 +260,15 @@ The ``type`` property of the metadata object can have any of the following value - ``yui-lang`` - a YUI3 language bundle - ``yui-module`` - a YUI3 module (that isn't one of the above) +.. _subtypes_resources: + Subtypes ```````` -Subtype is used for certain types, but not others. For example, an -"type:addon" resource might have "subtype:ac" for AC addons, or -"subtype:view-engine" for view engines, or "subtype:rs" for RS addons. +You can use a subtype to specify types of a ``type``. For example, a +resource of ``type:addon`` might have subtypes, such as ``subtype:ac`` for AC addons, +``subtype:view-engine`` for view engines, or ``subtype:rs`` for RS addons. + For "type:archetype" the subtypes refers to the "type" described by `mojito help create`. So, you could have "subtype:app" or "subtype:mojit". (There might be more in the future!) @@ -290,6 +313,8 @@ Example +.. Note: Drew is thinking of change "viewOutputFormat" and "viewEngine" to go under a "view" sub-object. I'll let you know if I make that change. + .. _resource_store-how: How Does the Resource Store Work? @@ -300,7 +325,7 @@ help others who don't plan on customizing addons to debug. In short, the resource store walks through the application-level, mojit-level, and ``npm`` module files (in that order) of a Mojito application, determines what type of resource each file is, -creates an instance of the resource, and then registers the instance. +creates metadata about the resource, and then registers the resource. During this process, the resource store is also doing the following: @@ -316,19 +341,19 @@ Walking the Filesystem ---------------------- Resource versions are discovered by the RS at server-start time. (Mojito server calls the -`preload()` method of the RS.) +``preload`` method of the RS.) This is done by walking all the files in the application, excluding the ``node_modules`` directory. -Then, all files in the packages in `node_modules/` are walked. The packages are walked in -breadth-first fassion, so that "shallower" packages have precedence above "deeper" ones. +Then, all files in the packages in `node_modules` are walked. The packages are walked in +breadth-first fashion, so that *shallower* packages have precedence above *deeper* ones. (Not all the packages are used, of course, only those that have declared themselves as extensions to Mojito.) -(Then, if Mojito wasn't found in `node_modules/`, the globally-installed version of Mojito is walked.) +(Then, if Mojito wasn't found in ``node_modules``, the globally-installed version of Mojito is walked.) After all that, the RS knows about all the resource versions. Then it resolves those versions -into the resources as described below. That still happens as part of `preload()`. +into the resources as described below. That still happens as part of ``preload``. Resolution and Priorities ------------------------- @@ -337,40 +362,40 @@ The act of resolving the resource versions is really just resolving the affiniti For example, the application might have the following: -* `controller.common.js` -* `controller.common.iphone.js` -* `controller.server.js` -* `controller.server.phone.js` +- ``controller.common.js`` +- ``controller.common.iphone.js`` +- ``controller.server.js`` +- ``controller.server.phone.js`` -The order of the selectors is defined by a "POSL": priority-ordered selector list. The POSL depends on -the runtime context. In our example, the POSL for context `{device:browser}` might be `['*']` but for -context `{device:iphone}` might be `['iphone','*']`. +The order of the selectors is defined by a **priority-ordered selector list (POSL)**. The POSL depends on +the runtime context. In our example, the POSL for context ``{device:browser}`` might be ``['*']`` but for +context ``{device:iphone}`` might be ``['iphone','*']``. (We need to use a (prioritized) list of selectors instead of just a "selector that matches the context" because not all versions might exist for all selectors. In the example above, if -`controller.server.iphone.js` didn't exist we should still do the right thing for context `{device:iphone}`.) +``controller.server.iphone.js`` didn't exist we should still do the right thing for context ``{device:iphone}``.) -As well, the choice depends on the affinity. If we're resolving versions for the server, versions with -`affinity:server` will have higher priority than `affinity:common`, and `affinity:client` will be completely +The choice depends on the **affinity** as well. If we're resolving versions for the server, versions with +``affinity:server`` will have higher priority than ``affinity:common``, and ``affinity:client`` will be completely ignored. -The final consideration for priority is the "source". Mojit-level versions have higher priority than +The final consideration for priority is the **source**. Mojit-level versions have higher priority than shared versions. For example, imagine an application with the following: -* `mojits/Foo/models/bar.common.js` -* `models/bar.common.js` +- ``mojits/Foo/models/bar.common.js`` +- ``models/bar.common.js`` -In this case the second resource is shared with all mojits. However, the mojit `Foo` has defined its own -version of the same resource (id `model--bar`), and so that should have higher priority than the shared one. +In this case, the second resource is shared with all mojits. However, the mojit ``Foo`` has defined its own +version of the same resource (id ``model--bar``), and so that should have higher priority than the shared one. -Finally, there's a relationship between the different types of priority. +Finally, there's a **relationship** between the different types of priority. -1. The source has highest priority. -1. The selector has next highest priority. -1. The affinity has least highest priority. +#. The source has the highest priority. +#. The selector has the next highest priority. +#. The affinity has the least highest priority. -That means that if there exists, for example, both a `controller.server.js` and `controller.common.iphone.js`, -for the server and context `{device:iphone}` the second version will be used, since its selector is a higher +That means that if there exists, for example, both a ``controller.server.js`` and ``controller.common.iphone.js``, +for the server and context ``{device:iphone}``, the second version will be used because its selector is a higher priority match than its affinity. @@ -380,40 +405,30 @@ every possible runtime context). Getting Data from the Resource Store ------------------------------------ -Besides the standard ways that Mojito uses the resource store, there are generic interfaces to getting +Besides the standard ways that Mojito uses the resource store, there are generic interfaces for getting resources and resource versions from the RS. -* `getResourceVersions(filter)` -* `getResources(env, ctx, filter)` +- ``getResourceVersions(filter)`` +- ``getResources(env, ctx, filter)`` -The APIs are intentially similar. Both return an array of resources, and the `filter` argument +The APIs are intentially similar. Both return an array of resources, and the ``filter`` argument can be used to restrict the returned resources (or versions). It is an object, all of whose -keys and values must match the returned resources (or versions). Think of it as a "template" -or "partial resource" which all resources must match. For example, a filter of `{type:'view'}` +keys and values must match the returned resources (or versions). Think of it as a *template* +or *partial resource* that all resources must match. For example, a filter of ``{type:'view'}`` will return all the views. -For mojit-level resources or resource versions, specify the mojit name in the filter. For example -filter `{mojit:'Foo'}` will return all resources (or versions) in the `Foo` mojit. -**Note** that, because of the resolution process, the resources returned for filter `{mojit:'Foo'}` +For mojit-level resources or resource versions, specify the mojit name in the filter. For example, +filter ``{mojit:'Foo'}`` will return all resources (or versions) in the ``Foo`` mojit. + +.. note:: Because of the resolution process, the resources returned for filter ``{mojit:'Foo'}`` might contain shared resources. To get mojit-level resources (or versions) from multiple mojits, you'll have to call -`getResourceVersions()` or `getResources()` for each mojit. You can call `listAllMojits()` to +the method ``getResourceVersions` or ``getResources`` for each mojit. You can call ``listAllMojits`` to get the list of all mojits. - -Resource store addons - -The code for the resource store is a `YUI Base `_, which enables plugins to be implemented as `YUI Plugin modules `_. -Being a YUI Base, the resource store also provides an event subsystem and a simple aspect-oriented subsystem (methods ``beforeHostMethod`` and ``afterHostMethod``). - -Mojito addons - -.. _resource_store-write_addons: - - .. _resource_store-addons: Resource Store Built-In Addons @@ -444,7 +459,7 @@ The RS comes with the following four built-in addons: - registers new resource type ``yui-lang`` found in ``lang`` - calculates the ``yui`` metadata for resource versions which are YUI modules - when resources are resolved for each version of each mojit, precalculates cooresponding YUI module dependencies - - when Mojito queries the RS for details of a mojit (`getMojitTypeDetails()`) appends the precalculated YUI module dependencies for the controller and binders + - when Mojito queries the RS for details of a mojit (``getMojitTypeDetails`` method) appends the precalculated YUI module dependencies for the controller and binders - provides methods used by Mojito to configure its YUI instances @@ -726,10 +741,182 @@ Called during runtime as Mojito creates an "instance" used to dispatch a mojit. Example ------- +RS Addon +```````` + +The following RS addon registers the new resource type ``text`` for text files. +``addons/rs/text.server.js`` +.. code-block:: javascript +YUI.add('addon-rs-text', function(Y, NAME) { + + var libpath = require('path'); + + + function RSAddonText() { + RSAddonText.superclass.constructor.apply(this, arguments); + } + RSAddonText.NS = 'text'; + RSAddonText.ATTRS = {}; + + Y.extend(RSAddonText, Y.Plugin.Base, { + + initializer: function(config) { + this.rs = config.host; + this.appRoot = config.appRoot; + this.mojitoRoot = config.mojitoRoot; + this.afterHostMethod('findResourceVersionByConvention', this.findResourceVersionByConvention, this); + this.beforeHostMethod('parseResourceVersion', this.parseResourceVersion, this); + }, + + + destructor: function() { + // TODO: needed to break cycle so we don't leak memory? + this.rs = null; + }, + + + /** + * Using AOP, this is called after the ResourceStore's version. + * @method findResourceVersionByConvention + * @param source {object} metadata about where the resource is located + * @param mojitType {string} name of mojit to which the resource likely belongs + * @return {object||null} for config file resources, returns metadata signifying that + */ + findResourceVersionByConvention: function(source, mojitType) { + // we only care about files + if (!source.fs.isFile) { + return; + } + + // we only care about txt files + if ('.txt' !== source.fs.ext) { + return; + } + + return new Y.Do.AlterReturn(null, { + type: 'text' + }); + }, + + + /** + * Using AOP, this is called before the ResourceStore's version. + * @method parseResourceVersion + * @param source {object} metadata about where the resource is located + * @param type {string} type of the resource + * @param subtype {string} subtype of the resource + * @param mojitType {string} name of mojit to which the resource likely belongs + * @return {object||null} for config file resources, returns the resource metadata + */ + parseResourceVersion: function(source, type, subtype, mojitType) { + var res; + + if ('text' !== type) { + return; + } + + res = { + source: source, + type: 'text', + affinity: 'server', + selector: '*' + }; + if ('app' !== source.fs.rootType) { + res.mojit = mojitType; + } + res.name = libpath.join(source.fs.subDir, source.fs.basename); + res.id = [res.type, res.subtype, res.name].join('-'); + return new Y.Do.Halt(null, res); + } + }); + Y.namespace('mojito.addons.rs'); + Y.mojito.addons.rs.text = RSAddonText; + }, '0.0.1', { requires: ['plugin', 'oop']}); +Text Addon +`````````` + +The Text Addon provides accessors so that that controller can access resources of type ``text``. + +``addons/ac/text.server.js`` + +.. code-block:: javascript + + + YUI.add('addon-ac-text', function(Y, NAME) { + + var libfs = require('fs'); + + function Addon(command, adapter, ac) { + this._ctx = ac.command.context; + } + Addon.prototype = { + + namespace: 'text', + + setStore: function(store) { + this._store = store; + }, + list: function() { + var r, res, ress, list = []; + ress = this._store.store.getResources('server', this._ctx, {type:'text'}); + for (r = 0; r < ress.length; r += 1) { + res = ress[r]; + list.push(res.name); + } + return list; + }, + read: function(name, cb) { + var ress; + ress = this._store.store.getResources('server', this._ctx, {type:'text', name:name}); + if (!ress || 1 !== ress.length) { + cb(new Error('Unknown text file ' + name)); + } + libfs.readFile(ress[0].source.fs.fullPath, 'utf-8', function(err, body) { + cb(err, body); + }); + } + }; + Y.mojito.addons.ac.text = Addon; + }, '0.1.0', {requires: ['mojito']} + ); + +Controller +`````````` + +``mojits/Viewer/controller.server.js`` + + +.. code-block:: javascript + + YUI.add('Viewer', function(Y, NAME) { + + Y.mojito.controllers[NAME] = { + + init: function(config) { + this.config = config; + }, + + index: function(ac) { + var chosen; // TODO: use form input to choose a text file + if (!chosen) { + var list; + list = ac.text.list(); + chosen = list[0]; + } + ac.assets.addCss('./index.css'); + ac.text.read(chosen, function(err, body) { + if (err) { + return ac.error(err); + } + ac.done({body: body}); + }); + } + }; + }, '1.0.1', {requires: ['mojito', 'addon-ac-text']}); \ No newline at end of file From 55d283c3fb3fb8dbdae4ca9f82212ebb78d49dd9 Mon Sep 17 00:00:00 2001 From: Joe Catera Date: Tue, 10 Jul 2012 12:17:41 -0700 Subject: [PATCH 20/45] Edited doc. --- .../topics/mojito_resource_store.rst | 308 ++++++++++-------- 1 file changed, 168 insertions(+), 140 deletions(-) diff --git a/docs/dev_guide/topics/mojito_resource_store.rst b/docs/dev_guide/topics/mojito_resource_store.rst index 2c38942d8..8a6fdf7c2 100644 --- a/docs/dev_guide/topics/mojito_resource_store.rst +++ b/docs/dev_guide/topics/mojito_resource_store.rst @@ -2,14 +2,20 @@ Resource Store ============== +.. |RS| replace:: Resource Store +.. |RSC| replace:: ResourceStore.server Class +.. _RSC: http://developer.yahoo.com/cocktails/mojito/api/classes/ResourceStore.server.html +.. |YUIPlugin| replace:: YUI Plugin +.. _|YUIPlugin| http://yuilibrary.com/yui/docs/plugin/ -.. _resource_store_intro: +.. _rs-intro: Intro ===== -The Resource Store (RS) is the Mojito substystem that manages metadata about the files in your Mojito applications. -The RS manages metadata about the files in the application. Thus, it is responsible for finding and classifying code and configuration files. +The Resource Store (RS) is the Mojito subsystem that manages metadata about the files in your +Mojito applications. The |RS| manages metadata about the files in the application. Thus, it is +responsible for finding and classifying code and configuration files. .. _intro-who: @@ -17,26 +23,28 @@ The RS manages metadata about the files in the application. Thus, it is responsi Who Needs to Know About the Resource Store? ------------------------------------------- -Most Mojito application developers will not need to know much about the resource store, but advanced Mojito application developers who -want to have finer grain control over the management of resources -or extend the functionality of the resource store should read this documentation. +Most Mojito application developers will not need to know much about the resource store, but +advanced Mojito application developers who want to have finer grain control over the management +of resources or extend the functionality of the resource store should read this documentation. -.. track new files types or modify information that the RS tracks through metadata can write their own RS addons. +.. track new files types or modify information that the |RS| tracks through metadata can write +.. their own |RS| addons. .. _intro-use: How Can the Resource Store Help Developers? ------------------------------------------- -You can write custom RS addons to use the aspect-oriented features of +You can write custom |RS| addons to use the aspect-oriented features of the resource store, to create resource types, and to map contexts to selectors. -For example, you could write your own RS addon so that the Mojito command-line +For example, you could write your own |RS| addon so that the Mojito command-line tool will create files and resources for your application. The Mojito command-line -tool uses the RS for all the commands except ``start``. +tool uses the |RS| for all the commands except ``start``. -You can also write custom versions of built-in RS addons to modify how the resource store works. You custom addon could track new file types, -augment the information that RS stores about files or code, or augment/replace the information returned by RS. +You can also write custom versions of built-in |RS| addons to modify how the resource store works. +You custom addon could track new file types, augment the information that |RS| stores about files or +code, or augment/replace the information returned by the |RS|. .. _rs-resources: @@ -49,24 +57,26 @@ Resources What is a Resource? ------------------- +.. _what-to_mojito: + To Mojito ````````` -The Mojito framework primarely views a **resource** as something useful found on the filesystem. - +The Mojito framework primarily views a **resource** as something useful found on the filesystem. +.. _what-to_rs: To the Resource Store ````````````````````` -The RS primarily cares about the *metadata* about each resource -The RS uses metadata resources, so it calls the +The |RS| primarily cares about the *metadata* about each resource +The |RS| uses metadata resources, so it calls the metadata the "resource". The "resource" is just a JavaScript object containing -metadata. The RS define certain keys with specific meanings. RS addons +metadata. The |RS| define certain keys with specific meanings. |RS| addons can add, remove, or modify those keys/values as they see fit. (For -example, it is the yui RS addon that adds the "yui" key with metadata -about resources that are YUI modules. The RS itself doesn't populate -the "yui" key of each resource.) +example, it is the yui |RS| addon that adds the ``yui`` key with metadata +about resources that are YUI modules. The |RS| itself doesn't populate +the ``yui`` key of each resource.) .. _resources-versions: @@ -74,33 +84,35 @@ the "yui" key of each resource.) Resource Versions ----------------- -Since there can be multiple files which are all conceptually different versions of the -same thing (think ``views/index.mu.html`` and ``views/index.iphone.mu.html``), the RS defines +Because there can be multiple files which are all conceptually different versions of the +same thing (think ``views/index.mu.html`` and ``views/index.iphone.mu.html``), the |RS| defines "resource version" as the metadata about each file and "resource" as the metadata about the file chosen among the possible choices. The process of choosing which version of a resource to use is called *resolution* (or -"resolving the resource"). This act is one of the primary responsibilities of the Resource Store. +"resolving the resource"). This act is one of the primary responsibilities of the |RS|. See "resolution and priorities" below. +.. _resources-scope: Resource Scope -------------- -.. _resources-application: +.. _scope-application: Application-Level Resources ``````````````````````````` Application-level resources are truly global to the application. -Some example resource types are middleware, RS addons, architetypes, and commands. -(As an implementation detail, the RS still tracks resource versions for these kinds of resources +Some example resource types are middleware, |RS| addons, archetypes, and commands. +(As an implementation detail, the |RS| still tracks resource versions for these kinds of resources and then resolves those versions down to a chosen resource, even though there's only one version of each resource. More work at server start, but less code to write and debug.) -At the application level, resources include archetypes, commands, configuration files, and middleware. +At the application level, resources include archetypes, commands, configuration files, and +middleware. -.. _resources-mojit: +.. _scope-mojit: Mojit-Level Resources ````````````````````` @@ -108,15 +120,15 @@ Mojit-Level Resources At the mojit level, resources include controllers, models, binders, configuration files, and views. These resources are limited in scope to a mojit. -.. _resources-shared: +.. _scope-shared: Shared Resources ```````````````` Some resources (and resource versions) are *shared*, meaning that they are included in **all** mojits. Most resource types that are mojit level can also be shared. Examples of mojit-level -resource types that can't be shared are controllers, configuration files (such as ``definition.json``), and -YUI language bundles. +resource types that can't be shared are controllers, configuration files (such as +``definition.json``), and YUI language bundles. .. _resources-types: @@ -124,12 +136,13 @@ Resource Types -------------- The resource type is defined by the ``type`` property in the metadata for a given resource. -See `Types of Resources `_ for descriptions of the built-in resource types. -Developers can also create their own types of resources to fit the need of their applications. +See `Types of Resources `_ for descriptions of the built-in resource +types. Developers can also create their own types of resources to fit the need of their +applications. -.. _resource_store-metadata: +.. _rs-metadata: Resource Metadata ================= @@ -139,9 +152,9 @@ Resource Metadata Intro ----- -The resource store uses metadata to find, load, parse, and create instances of resources. The resource metadata is generated by code -- it has no representation -on the filesystem. It is generate during `preload()`, either by the RS -itself or by RS addons. +The resource store uses metadata to find, load, parse, and create instances of resources. The +resource metadata is generated by code--it has no representation on the filesystem. It is +generate during ``preload``, either by the |RS| itself or by |RS| addons. .. _metadata-obj: @@ -149,15 +162,11 @@ itself or by RS addons. Metadata Object --------------- - - -.. Please fill in or correct the rows for the 'Required?', 'Default Value', 'Possible Values', and 'Description' columns below. - -ome values do have defaults, but it depends on the value of the "type" -key, and/or comes from the filename of the resource being represented. -For example, the "affinity" of views is "common" (since views are used -on both client and server), however the "affinity" for controllers comes -from the filename. +Some values do have defaults, but it depends on the value of the ``type`` +key, and/or comes from the file name of the resource being represented. +For example, the affinity of views is ``common`` (because views are used +on both client and server); however, the affinity for controllers comes +from the file name. +------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ | Property | Data Type | Required? | Default Value | Possible Values | Description | @@ -165,8 +174,6 @@ from the filename. | ``affinity`` | string | -- | -- | ``server``, ``client``, | The affinity of the resource, which | | | | | | ``common`` | indicates where the resource will be used. | +------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ -| ``fs`` | string | yes | none | N/A | | -+------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ | ``id`` | string | yes | none | N/A | A unique ID that is common to all versions | | | | | | | of the resource. The ``id`` has the | | | | | | | following syntax convention: | @@ -182,8 +189,6 @@ from the filename. | | | | | | for the resources ``index.iphone.mu.html`` | | | | | | | and ``index.mu.html`` is ``index``. | +------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ -| `` pkg`` | string | -- | none | | // packaging details ==> what details? | -+------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ | ``selector`` | string | no | "*" | | The version of the resource, not to be | | | | | | | confused revisions that mark the change of | | | | | | | the resource over time. For example, a | @@ -223,13 +228,16 @@ source Object | ``pkg`` | array | yes | none | N/A | // packaging details ==> what details? | +------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ +.. _yui_obj: + yui Object `````````` -The ``yui`` property of the metadata object is created by the ``yui`` resource store addon, and therefore, the ``yui`` property can -be any data type. In general, the ``yui`` property is an object containing metadata about YUI modules. The following table lists -the typical properties that are part of the ``yui`` object. You can think of the ``yui`` object as a container for - the arguments to the ``YUI.add`` method that is used to register reusable YUI modules. +The ``yui`` property of the metadata object is created by the ``yui`` resource store addon, and +therefore, the ``yui`` property can be any data type. In general, the ``yui`` property is an object +containing metadata about YUI modules. The following table liststhe typical properties that are +part of the ``yui`` object. You can think of the ``yui`` object as a container for the arguments to +the ``YUI.add`` method that is used to register reusable YUI modules. +------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ | Property | Data Type | Required? | Default Value | Possible Values | Description | @@ -241,7 +249,7 @@ the typical properties that are part of the ``yui`` object. You can think of the +------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ -.. _types_resources: +.. _metadata-types: Types of Resources ------------------ @@ -260,14 +268,14 @@ The ``type`` property of the metadata object can have any of the following value - ``yui-lang`` - a YUI3 language bundle - ``yui-module`` - a YUI3 module (that isn't one of the above) -.. _subtypes_resources: +.. _types-subtypes: Subtypes ```````` You can use a subtype to specify types of a ``type``. For example, a resource of ``type:addon`` might have subtypes, such as ``subtype:ac`` for AC addons, -``subtype:view-engine`` for view engines, or ``subtype:rs`` for RS addons. +``subtype:view-engine`` for view engines, or ``subtype:rs`` for |RS| addons. For "type:archetype" the subtypes refers to the "type" described by `mojito help create`. So, you could have "subtype:app" or @@ -313,35 +321,37 @@ Example -.. Note: Drew is thinking of change "viewOutputFormat" and "viewEngine" to go under a "view" sub-object. I'll let you know if I make that change. +.. Note: Drew is thinking of change "viewOutputFormat" and "viewEngine" to go under a "view" +.. sub-object. I'll let you know if I make that change. -.. _resource_store-how: +.. _rs-how: How Does the Resource Store Work? ================================= -Understanding the workflow of the resource store will give help those who want to customize addons to write code and -help others who don't plan on customizing addons to debug. +Understanding the workflow of the resource store will give help those who want to customize addons +to write code and help others who don't plan on customizing addons to debug. In short, the resource store walks through the application-level, -mojit-level, and ``npm`` module files (in that order) of a Mojito application, determines what type of resource each file is, -creates metadata about the resource, and then registers the resource. +mojit-level, and ``npm`` module files (in that order) of a Mojito application, determines what type +of resource each file is, creates metadata about the resource, and then registers the resource. During this process, the resource store is also doing the following: -- precalculating ("resolving") which resource versions are used for each version of the mojit. +- pre-calculating ("resolving") which resource versions are used for each version of the mojit. - keeping track of app-level resources (archetypes, commands, config files, and middleware). - providing methods for events, including those specialized for AOP. - explicitly using the addons `selector `_ and `config `_ To see the code for the resource store, see `store.server.js `_. +.. _how-walk_fs: Walking the Filesystem ---------------------- -Resource versions are discovered by the RS at server-start time. (Mojito server calls the -``preload`` method of the RS.) +Resource versions are discovered by the |RS| at server-start time. (Mojito server calls the +``preload`` method of the |RS|.) This is done by walking all the files in the application, excluding the ``node_modules`` directory. @@ -350,11 +360,14 @@ breadth-first fashion, so that *shallower* packages have precedence above *deepe (Not all the packages are used, of course, only those that have declared themselves as extensions to Mojito.) -(Then, if Mojito wasn't found in ``node_modules``, the globally-installed version of Mojito is walked.) +(Then, if Mojito wasn't found in ``node_modules``, the globally-installed version of Mojito is +walked.) -After all that, the RS knows about all the resource versions. Then it resolves those versions +After all that, the |RS| knows about all the resource versions. Then it resolves those versions into the resources as described below. That still happens as part of ``preload``. +.. _how-resolution: + Resolution and Priorities ------------------------- @@ -367,26 +380,28 @@ For example, the application might have the following: - ``controller.server.js`` - ``controller.server.phone.js`` -The order of the selectors is defined by a **priority-ordered selector list (POSL)**. The POSL depends on -the runtime context. In our example, the POSL for context ``{device:browser}`` might be ``['*']`` but for -context ``{device:iphone}`` might be ``['iphone','*']``. +The order of the selectors is defined by a **priority-ordered selector list (POSL)**. The POSL +depends on the runtime context. In our example, the POSL for context ``{device:browser}`` might +be ``['*']`` but for context ``{device:iphone}`` might be ``['iphone','*']``. -(We need to use a (prioritized) list of selectors instead of just a "selector that matches the context" -because not all versions might exist for all selectors. In the example above, if -``controller.server.iphone.js`` didn't exist we should still do the right thing for context ``{device:iphone}``.) +(We need to use a (prioritized) list of selectors instead of just a "selector that matches the +context" because not all versions might exist for all selectors. In the example above, if +``controller.server.iphone.js`` didn't exist we should still do the right thing for context +``{device:iphone}``.) -The choice depends on the **affinity** as well. If we're resolving versions for the server, versions with -``affinity:server`` will have higher priority than ``affinity:common``, and ``affinity:client`` will be completely -ignored. +The choice depends on the **affinity** as well. If we're resolving versions for the server, +versions with ``affinity:server`` will have higher priority than ``affinity:common``, and +``affinity:client`` will be completely ignored. -The final consideration for priority is the **source**. Mojit-level versions have higher priority than -shared versions. For example, imagine an application with the following: +The final consideration for priority is the **source**. Mojit-level versions have higher priority +than shared versions. For example, imagine an application with the following: - ``mojits/Foo/models/bar.common.js`` - ``models/bar.common.js`` -In this case, the second resource is shared with all mojits. However, the mojit ``Foo`` has defined its own -version of the same resource (id ``model--bar``), and so that should have higher priority than the shared one. +In this case, the second resource is shared with all mojits. However, the mojit ``Foo`` has +defined its own version of the same resource (``id: model--bar``), and so that should have higher +priority than the shared one. Finally, there's a **relationship** between the different types of priority. @@ -394,24 +409,27 @@ Finally, there's a **relationship** between the different types of priority. #. The selector has the next highest priority. #. The affinity has the least highest priority. -That means that if there exists, for example, both a ``controller.server.js`` and ``controller.common.iphone.js``, -for the server and context ``{device:iphone}``, the second version will be used because its selector is a higher -priority match than its affinity. +That means that if there exists, for example, both a ``controller.server.js`` and +``controller.common.iphone.js``, for the server and context ``{device:iphone}``, the second version +will be used because its selector is a higher priority match than its affinity. -All this is precalculated for each resource, for each possible runtime configuration (client or server, and +All this is pre-calculated for each resource, for each possible runtime configuration (client or +server, and every possible runtime context). +.. _how-get_data: + Getting Data from the Resource Store ------------------------------------ -Besides the standard ways that Mojito uses the resource store, there are generic interfaces for getting -resources and resource versions from the RS. +Besides the standard ways that Mojito uses the resource store, there are generic interfaces for +getting resources and resource versions from the |RS|. - ``getResourceVersions(filter)`` - ``getResources(env, ctx, filter)`` -The APIs are intentially similar. Both return an array of resources, and the ``filter`` argument +The APIs are intentionally similar. Both return an array of resources, and the ``filter`` argument can be used to restrict the returned resources (or versions). It is an object, all of whose keys and values must match the returned resources (or versions). Think of it as a *template* or *partial resource* that all resources must match. For example, a filter of ``{type:'view'}`` @@ -424,8 +442,8 @@ filter ``{mojit:'Foo'}`` will return all resources (or versions) in the ``Foo`` might contain shared resources. To get mojit-level resources (or versions) from multiple mojits, you'll have to call -the method ``getResourceVersions` or ``getResources`` for each mojit. You can call ``listAllMojits`` to -get the list of all mojits. +the method ``getResourceVersions` or ``getResources`` for each mojit. You can call +``listAllMojits`` to get the list of all mojits. @@ -438,41 +456,46 @@ Intro ----- Mojito comes with built-in resource store addons that are used by the resource store -and the Mojito framework. These resource store addons are required by the resource store and -the Mojito framework. In general, so particular care must be taken when creating custom versions of them. +and the Mojito framework. These resource store addons are required by the |RS| and +the Mojito framework. Thus, particular care must be taken when creating custom versions +of them. -The RS comes with the following four built-in addons: +The |RS| comes with the following four built-in addons: - ``config`` - registers new resource type ``config`` found in ``.json`` files - provides API for reading both context and straight-JSON files - - also provides sugar for reading the application's dimensions + - provides sugar for reading the application's dimensions - ``selector`` - decides the priority-ordered list (POSL) to use for a context - - default implementation looks for ``selector`` in ``application.json``. Because ``application.json`` is a context configuration file, the ``selector`` can be contextualized there. + - looks (default implementation) for ``selector`` in ``application.json``. Because + ``application.json`` is a context configuration file, the ``selector`` can be contextualized + there. - ``url`` - calculates the static handler URL for appropriate resources (and resource versions) - - URL is stored in the ``url`` key of the resource - - also calculates the asset URL base for each mojit + - stores the URL in the ``url`` key of the resource + - calculates the asset URL base for each mojit - ``yui`` - registers new resource type ``yui-module`` found in ``autoload`` or ``yui_modules`` - registers new resource type ``yui-lang`` found in ``lang`` - calculates the ``yui`` metadata for resource versions which are YUI modules - - when resources are resolved for each version of each mojit, precalculates cooresponding YUI module dependencies - - when Mojito queries the RS for details of a mojit (``getMojitTypeDetails`` method) appends the precalculated YUI module dependencies for the controller and binders + - pre-calculates corresponding YUI module dependencies when resources are resolved + for each version of each mojit, + - appends the pre-calculated YUI module dependencies for the controller and binders when + Mojito queries the |RS| for details of a mojit (``getMojitTypeDetails`` method) - provides methods used by Mojito to configure its YUI instances .. _resource_store-custom_addons: -Creating Custom Versions of Built-In RS Addons +Creating Custom Versions of Built-In |RS| Addons ---------------------------------------------- -We will be examing the ``selector`` and ``url`` addons to help you create custom versions of those addons. -In general, because we do not recommend that you create custom versions of the ``config`` or ``yui`` addons, -we will not be looking at those addons. Also, this documentation explains what the RS expects the addon to do, -so you can create your own version of the addons. To learn what a RS addon does, please refer to the -`ResourceStore.server Class `_ in the API documentation. +We will be examining the ``selector`` and ``url`` addons to help you create custom versions of +those addons. We do not recommend that you create custom versions of the +``config`` or ``yui`` addons, so we will not be looking at those addons. Also, this documentation +explains what the |RS| expects the addon to do, so you can create your own version of the addons. +To learn what a |RS| addon does, please refer to the |RSC|_ in the API documentation. .. _intro-selector: @@ -486,7 +509,7 @@ Description ~~~~~~~~~~~ If you wish to use a different algorithm for to determine the selectors to use, -you can implement your own version of this RS addon. It'll need to go in +you can implement your own version of this |RS| addon. It'll need to go in ``addons/rs/selector.server.js`` in your application. @@ -533,7 +556,7 @@ The ``url`` addon calculates and manages the static handler URLs for resources. The addon is not used by resource store core, but used by the static handler middleware. If you wish to use a different algorithm to determine the URLs, you can -implement your own version of this RS addon. It'll need to go in +implement your own version of this |RS| addon. It'll need to go in ``addons/rs/url.server.js`` in your application. After the method ``preloadResourceVersions`` sets ``res.url`` to the static handler URL @@ -549,7 +572,8 @@ filesystem path for a URL. Requirements ~~~~~~~~~~~~ -The ``selector`` addon is required to have the following methods (see details for the methods in below sections): +The ``selector`` addon is required to have the following methods (see details for the methods in +below sections): - ``getPathForURL(url)`` - ``getSpecURL(id)`` @@ -558,14 +582,18 @@ The ``selector`` addon is required to have the following methods (see details fo Your addon will also be required to do the following: -- Add the ``url`` metadatum to resource versions; this is where your addon will set the calculated value (using ``beforeHostMethod('addResourceVersion')``). -- Add ``assetsRoot`` to the results of ``getMojitTypeDetails()``, which is done with ``onHostEvent('getMojitTypeDetails')``; ``assetsRoot`` is the common prefix for all assets in the mojit. The built-in addon makes something like ``/static/Foo/assets`` for the ``Foo`` mojit. +- Add the ``url`` metadatum to resource versions; this is where your addon will set the calculated + value (using ``beforeHostMethod('addResourceVersion')``). +- Add ``assetsRoot`` to the results of ``getMojitTypeDetails()``, which is done with + ``onHostEvent('getMojitTypeDetails')``; ``assetsRoot`` is the common prefix for all assets in the + mojit. The built-in addon makes something like ``/static/Foo/assets`` for the ``Foo`` mojit. .. _url-getPathForURL: getPathForURL(url) `````````````````` -This method is called by the static handler middleware. Returns the full filesystem path for the URL. +This method is called by the static handler middleware. Returns the full filesystem path for the +URL. **Parameters:** @@ -593,7 +621,7 @@ Returns the URL for the spec. getURLPaths() ````````````` -Returns an object whose keys are all URLs and whose values are the cooresponding filesystem paths. +Returns an object whose keys are all URLs and whose values are the corresponding filesystem paths. **Parameters:** @@ -611,22 +639,20 @@ Example ~~~~~~~ - - Creating Your Own Resource Store Addons ======================================= Intro ----- -In this section, we will discuss the key methods, events, and give a simple example of a custom RS addon. -You should be able to create your own custom RS addons afterward. +In this section, we will discuss the key methods, events, and give a simple example of a custom +|RS| addon. You should be able to create your own custom |RS| addons afterward. -Anatomy of a RS Addon +Anatomy of a |RS| Addon --------------------- -The resource store addons are implemented using the `YUI Plugin `_ mechanism. In essence, a Mojito addon is a YUI plugin. -The skeleton of the addon will be the same as a YUI Plugin. +The resource store addons are implemented using the _|YUIPlugin| mechanism. In essence, a Mojito +addon is a YUI plugin, so the skeleton of a |RS| addon will be the same as a YUI Plugin. Key Methods ~~~~~~~~~~~ @@ -637,9 +663,9 @@ initialize(config) **Parameters:** - ``config `` - contains the following: - - ``host `` - contains the resource store. - - ``appRoot `` - the directory of the application. - - ``mojitoRoot `` - the directory of the Mojito framework code. +- ``host `` - contains the resource store. +- ``appRoot `` - the directory of the application. +- ``mojitoRoot `` - the directory of the Mojito framework code. **Return:** @@ -648,9 +674,11 @@ None. preload() ````````` - * addons are loaded during this method, so it's not possible to hook in before this - * during this, `preloadResourceVersions()` and `resolveResourceVersions()` are called - * it *is* possible to hookin afterwards via `afterHostMethod('preload', ...)` +- Addons are loaded during this method, so it's not possible to hook in before ``preload`` is + called. +- During preload, the methods ``preloadResourceVersions`` and ``resolveResourceVersions`` are + called. +- After ``preload`` has been called, you can hook in with ``afterHostMethod('preload', ...)``. **Parameters:** @@ -658,12 +686,12 @@ preload() preloadResourceVersions() ````````````````````````` - * this is when the RS walks the filesystem - * before this, not much is known, though the static app config is available (via `getStaticAppConfig()`) - * during this, the following host methods happen: `findResourceVersionByConvention()`, `parseResourceVersion()`, and `addResourceVersion()` - * after this - * all the resource versions have been loaded and are available via `getResourceVersions()` - * the RS has a `selectors` object whose keys are all selectors actually in the app. the values are just `true`. +- The |RS| walks the filesystem in this method. +- Before ``preloadResourceVersions`` is called, not much is known, though the static application configuration is available using the method ``getStaticAppConfig``. +- Within the ``preloadResourceVersions`` method, the following host methods are called: ``findResourceVersionByConvention``, ``parseResourceVersion``, and ``addResourceVersion`` +- After ``preloadResourceVersions`` has been called: + - All the resource versions have been loaded and are available through the method ``getResourceVersions``. + - The |RS| has ``selectors`` object whose keys are all selectors in the application. The values for the keys are just ``true``. **Parameters:** @@ -697,7 +725,7 @@ parseResourceVersion() addResourceVersion() ```````````````````` - * called to save the resource version into the RS + * called to save the resource version into the |RS| * typically, if you want to modify/augment an existing resource version, hook into this via `beforeHostMethod()` **Parameters:** @@ -741,10 +769,10 @@ Called during runtime as Mojito creates an "instance" used to dispatch a mojit. Example ------- -RS Addon +|RS| Addon ```````` -The following RS addon registers the new resource type ``text`` for text files. +The following |RS| addon registers the new resource type ``text`` for text files. ``addons/rs/text.server.js`` @@ -756,13 +784,13 @@ YUI.add('addon-rs-text', function(Y, NAME) { var libpath = require('path'); - function RSAddonText() { - RSAddonText.superclass.constructor.apply(this, arguments); + function |RS|AddonText() { + |RS|AddonText.superclass.constructor.apply(this, arguments); } - RSAddonText.NS = 'text'; - RSAddonText.ATTRS = {}; + |RS|AddonText.NS = 'text'; + |RS|AddonText.ATT|RS| = {}; - Y.extend(RSAddonText, Y.Plugin.Base, { + Y.extend(|RS|AddonText, Y.Plugin.Base, { initializer: function(config) { this.rs = config.host; @@ -834,7 +862,7 @@ YUI.add('addon-rs-text', function(Y, NAME) { } }); Y.namespace('mojito.addons.rs'); - Y.mojito.addons.rs.text = RSAddonText; + Y.mojito.addons.rs.text = |RS|AddonText; }, '0.0.1', { requires: ['plugin', 'oop']}); From 3156c1efa83cbac2f7ef809850fc62fb775fab2a Mon Sep 17 00:00:00 2001 From: Joe Catera Date: Tue, 10 Jul 2012 16:10:55 -0700 Subject: [PATCH 21/45] Finished first draft of docs. --- .../topics/mojito_resource_store.rst | 251 +++++++++--------- 1 file changed, 132 insertions(+), 119 deletions(-) diff --git a/docs/dev_guide/topics/mojito_resource_store.rst b/docs/dev_guide/topics/mojito_resource_store.rst index 8a6fdf7c2..bc7c124c5 100644 --- a/docs/dev_guide/topics/mojito_resource_store.rst +++ b/docs/dev_guide/topics/mojito_resource_store.rst @@ -10,8 +10,8 @@ Resource Store .. _rs-intro: -Intro -===== +Overview +======== The Resource Store (RS) is the Mojito subsystem that manages metadata about the files in your Mojito applications. The |RS| manages metadata about the files in the application. Thus, it is @@ -69,14 +69,13 @@ The Mojito framework primarily views a **resource** as something useful found on To the Resource Store ````````````````````` -The |RS| primarily cares about the *metadata* about each resource -The |RS| uses metadata resources, so it calls the -metadata the "resource". The "resource" is just a JavaScript object containing -metadata. The |RS| define certain keys with specific meanings. |RS| addons -can add, remove, or modify those keys/values as they see fit. (For -example, it is the yui |RS| addon that adds the ``yui`` key with metadata +The |RS| primarily cares about the *metadata* about each resource, so it calls the +metadata the *resource". To the |RS|, the **resource** is just a JavaScript object containing +metadata. The |RS| defines certain keys with specific meanings. The |RS| addons +can add, remove, or modify those keys/values as they see fit. For +example, the yui |RS| addon adds the ``yui`` key with metadata about resources that are YUI modules. The |RS| itself doesn't populate -the ``yui`` key of each resource.) +the ``yui`` key of each resource. .. _resources-versions: @@ -86,13 +85,14 @@ Resource Versions Because there can be multiple files which are all conceptually different versions of the same thing (think ``views/index.mu.html`` and ``views/index.iphone.mu.html``), the |RS| defines -"resource version" as the metadata about each file and "resource" as the metadata +**resource version** as the metadata about each file and **resource** as the metadata about the file chosen among the possible choices. The process of choosing which version of a resource to use is called *resolution* (or "resolving the resource"). This act is one of the primary responsibilities of the |RS|. -See "resolution and priorities" below. +See `Resolution and Priorities `_ to learn how the |RS| resolves +different versions of the same resource. .. _resources-scope: @@ -343,7 +343,8 @@ During this process, the resource store is also doing the following: - providing methods for events, including those specialized for AOP. - explicitly using the addons `selector `_ and `config `_ -To see the code for the resource store, see `store.server.js `_. +To see the code for the resource store, +see `store.server.js `_. .. _how-walk_fs: @@ -446,7 +447,6 @@ the method ``getResourceVersions` or ``getResources`` for each mojit. You can c ``listAllMojits`` to get the list of all mojits. - .. _resource_store-addons: Resource Store Built-In Addons @@ -632,31 +632,41 @@ None. ```` - .. _url-ex: Example ~~~~~~~ +.. _rs-creating_rs_addons: Creating Your Own Resource Store Addons ======================================= +.. _creating_rs_addons-intro: + Intro ----- In this section, we will discuss the key methods, events, and give a simple example of a custom -|RS| addon. You should be able to create your own custom |RS| addons afterward. +|RS| addon. You should be able to create your own custom |RS| addons afterward. + +.. _creating_rs_addons-anatomy: Anatomy of a |RS| Addon ---------------------- +----------------------- The resource store addons are implemented using the _|YUIPlugin| mechanism. In essence, a Mojito addon is a YUI plugin, so the skeleton of a |RS| addon will be the same as a YUI Plugin. +See the |RCS|_ for the parameters and return values for the |RS| methods. + +.. _anatomy-key_methods: + Key Methods ~~~~~~~~~~~ +.. _key_methods-initialize: + initialize(config) `````````````````` @@ -667,9 +677,7 @@ initialize(config) - ``appRoot `` - the directory of the application. - ``mojitoRoot `` - the directory of the Mojito framework code. -**Return:** - -None. +.. _key_methods-preload: preload() ````````` @@ -680,97 +688,104 @@ preload() called. - After ``preload`` has been called, you can hook in with ``afterHostMethod('preload', ...)``. -**Parameters:** - -**Return:** +.. _key_methods-preloadResourceVersions: preloadResourceVersions() ````````````````````````` -- The |RS| walks the filesystem in this method. -- Before ``preloadResourceVersions`` is called, not much is known, though the static application configuration is available using the method ``getStaticAppConfig``. -- Within the ``preloadResourceVersions`` method, the following host methods are called: ``findResourceVersionByConvention``, ``parseResourceVersion``, and ``addResourceVersion`` -- After ``preloadResourceVersions`` has been called: - - All the resource versions have been loaded and are available through the method ``getResourceVersions``. - - The |RS| has ``selectors`` object whose keys are all selectors in the application. The values for the keys are just ``true``. +The |RS| walks the filesystem in this method. Before ``preloadResourceVersions`` is called, not +much is known, though the static application configuration is available using the +method ``getStaticAppConfig``. -**Parameters:** +Within the ``preloadResourceVersions`` method, the following host methods are called: +- ``findResourceVersionByConvention`` +- ``parseResourceVersion`` +- ``addResourceVersion`` -**Return:** +After ``preloadResourceVersions`` has been called: + - All the resource versions have been loaded and are available through the method + ``getResourceVersions``. + - The |RS| has ``selectors`` object whose keys are all selectors in the application. + The values for the keys are just ``true``. -findResourceVersionByConvention() -````````````````````````````````` - - * called on each directory or file being walked - * used to decide if the path is a resource version - * return value is a bit tricky, so read API docs carefully (and ask questions if not clear) - * typically, hook into this via `afterHostMethod()` to register your own resource version types - * this should work together with your own version of `parseResourceVersion()` -**Parameters:** +.. _key_methods-findResourceVersionByConvention: -**Return:** +findResourceVersionByConvention() +````````````````````````````````` +This method is called on each directory or file being walked and is used to decide if the +path is a resource version. The return value can be a bit confusing, so read API docs carefully +and feel free to post any questions that you have to the +`Yahoo! Mojito Forum `_. + +Typically, you would hook into this method with the ``afterHostMethod()`` method to register your +own resource version types. This method should work together with your +own version of the ``parseResourceVersion`` method. + +.. _key_methods-parseResourceVersion: parseResourceVersion() `````````````````````` - * called to create an actual resource version - * typically, hook into this via `beforeHostMethod()` to create your own resource versions - * this should work together with your own version of `findResourceVersionByConvention()` +This method creates an actual resource version. -**Parameters:** +Typically, you would hook into this method with the `beforeHostMethod()` method to create +your own resource versions. This should work together with your own version +of the ``findResourceVersionByConvention`` method. -**Return:** +.. _key_methods-addResourceVersion: addResourceVersion() ```````````````````` +This method is called to save the resource version into the |RS|. +Typically, if you want to modify/augment an existing resource version, hook into this with the +``beforeHostMethod`` method. - * called to save the resource version into the |RS| - * typically, if you want to modify/augment an existing resource version, hook into this via `beforeHostMethod()` - -**Parameters:** - -**Return:** +.. _key_methods-resolveResourceVersions: resolveResourceVersions() ````````````````````````` - * called to resolve the resource versions down into resources - * during this, the `mojitResourcesResolved` event is called - * after this, all resource versions have been resolved +This method resolves the resource versions into resources. +As a resource version is resolved, the ``mojitResourcesResolved`` event is called +After the method has been executed, all resource versions have been resolved. -**Parameters:** - -**Return:** +.. _key_methods-serializeClientStore: serializeClientStore() `````````````````````` -called during runtime as Mojito creates the configuration for the client-side Mojito +This method is called during runtime as Mojito creates the configuration for the client-side +Mojito. -**Parameters:** -**Return:** - +.. _anatomy-key_events: Key Events ~~~~~~~~~~ +.. _key_events-mojitResourcesResolved: + mojitResourcesResolved `````````````````````` -Called when the resources in a mojit are resolved. +This event is called when the resources in a mojit are resolved. + +.. _key_events-getMojitTypeDetails: getMojitTypeDetails ``````````````````` -Called during runtime as Mojito creates an "instance" used to dispatch a mojit. +This event is called during runtime as Mojito creates an "instance" used to dispatch a mojit. +.. _creating_rs_addons-ex: Example ------- +.. _creating_rs_addons_ex-rs_addon: + |RS| Addon -```````` +`````````` The following |RS| addon registers the new resource type ``text`` for text files. @@ -779,74 +794,69 @@ The following |RS| addon registers the new resource type ``text`` for text files .. code-block:: javascript -YUI.add('addon-rs-text', function(Y, NAME) { - - var libpath = require('path'); - - - function |RS|AddonText() { - |RS|AddonText.superclass.constructor.apply(this, arguments); - } - |RS|AddonText.NS = 'text'; - |RS|AddonText.ATT|RS| = {}; - - Y.extend(|RS|AddonText, Y.Plugin.Base, { - - initializer: function(config) { - this.rs = config.host; - this.appRoot = config.appRoot; - this.mojitoRoot = config.mojitoRoot; - this.afterHostMethod('findResourceVersionByConvention', this.findResourceVersionByConvention, this); - this.beforeHostMethod('parseResourceVersion', this.parseResourceVersion, this); - }, + YUI.add('addon-rs-text', function(Y, NAME) { + var libpath = require('path'); - destructor: function() { - // TODO: needed to break cycle so we don't leak memory? - this.rs = null; - }, + function RSddonText() { + RSAddonText.superclass.constructor.apply(this, arguments); + }, + RSAddonText.NS = 'text'; + RSAddonText.ATT|RS| = {}; + Y.extend(RSAddonText, Y.Plugin.Base, { - /** - * Using AOP, this is called after the ResourceStore's version. - * @method findResourceVersionByConvention - * @param source {object} metadata about where the resource is located - * @param mojitType {string} name of mojit to which the resource likely belongs - * @return {object||null} for config file resources, returns metadata signifying that - */ - findResourceVersionByConvention: function(source, mojitType) { - // we only care about files - if (!source.fs.isFile) { - return; - } + initializer: function(config) { + this.rs = config.host; + this.appRoot = config.appRoot; + this.mojitoRoot = config.mojitoRoot; + this.afterHostMethod('findResourceVersionByConvention', this.findResourceVersionByConvention, this); + this.beforeHostMethod('parseResourceVersion', this.parseResourceVersion, this); + }, - // we only care about txt files - if ('.txt' !== source.fs.ext) { - return; - } + destructor: function() { + // TODO: needed to break cycle so we don't leak memory? + this.rs = null; + }, - return new Y.Do.AlterReturn(null, { - type: 'text' - }); - }, + /** + * Using AOP, this is called after the ResourceStore's version. + * @method findResourceVersionByConvention + * @param source {object} metadata about where the resource is located + * @param mojitType {string} name of mojit to which the resource likely belongs + * @return {object||null} for config file resources, returns metadata signifying that + */ + findResourceVersionByConvention: function(source, mojitType) { + // We only care about files + if (!source.fs.isFile) { + return; + } + // We only care about txt files + if ('.txt' !== source.fs.ext) { + return; + } + + return new Y.Do.AlterReturn(null, { + type: 'text' + }); + }, - /** - * Using AOP, this is called before the ResourceStore's version. - * @method parseResourceVersion - * @param source {object} metadata about where the resource is located - * @param type {string} type of the resource - * @param subtype {string} subtype of the resource - * @param mojitType {string} name of mojit to which the resource likely belongs - * @return {object||null} for config file resources, returns the resource metadata - */ + /** + * Using AOP, this is called before the ResourceStore's version. + * @method parseResourceVersion + * @param source {object} metadata about where the resource is located + * @param type {string} type of the resource + * @param subtype {string} subtype of the resource + * @param mojitType {string} name of mojit to which the resource likely belongs + * @return {object||null} for config file resources, returns the resource metadata + */ parseResourceVersion: function(source, type, subtype, mojitType) { - var res; + var res; if ('text' !== type) { return; } - res = { source: source, type: 'text', @@ -866,6 +876,7 @@ YUI.add('addon-rs-text', function(Y, NAME) { }, '0.0.1', { requires: ['plugin', 'oop']}); +.. _creating_rs_addons_ex-text_addon: Text Addon `````````` @@ -914,6 +925,8 @@ The Text Addon provides accessors so that that controller can access resources o Y.mojito.addons.ac.text = Addon; }, '0.1.0', {requires: ['mojito']} ); + +.. _creating_rs_addons_ex-controller: Controller `````````` From 706e125a642eff5441137492020f75a20a6a520c Mon Sep 17 00:00:00 2001 From: Joe Catera Date: Thu, 12 Jul 2012 08:42:33 -0700 Subject: [PATCH 22/45] Made copy edits, fixed links, and rewrote some sections. --- .../topics/mojito_resource_store.rst | 208 ++++++++++-------- 1 file changed, 122 insertions(+), 86 deletions(-) diff --git a/docs/dev_guide/topics/mojito_resource_store.rst b/docs/dev_guide/topics/mojito_resource_store.rst index bc7c124c5..06f1b930f 100644 --- a/docs/dev_guide/topics/mojito_resource_store.rst +++ b/docs/dev_guide/topics/mojito_resource_store.rst @@ -8,13 +8,21 @@ Resource Store .. |YUIPlugin| replace:: YUI Plugin .. _|YUIPlugin| http://yuilibrary.com/yui/docs/plugin/ + +.. Questions/Needed Info + +.. Formal definition about selectors. +.. Details about ``fs`` and ``pkg`` +.. More complete overview. +.. Have "viewOutputFormat" and "viewEngine" been put under a "view"? + .. _rs-intro: Overview ======== The Resource Store (RS) is the Mojito subsystem that manages metadata about the files in your -Mojito applications. The |RS| manages metadata about the files in the application. Thus, it is +Mojito applications. Thus, it is responsible for finding and classifying code and configuration files. @@ -43,7 +51,7 @@ tool will create files and resources for your application. The Mojito command-li tool uses the |RS| for all the commands except ``start``. You can also write custom versions of built-in |RS| addons to modify how the resource store works. -You custom addon could track new file types, augment the information that |RS| stores about files or +Your custom addon could track new file types, augment the information that the |RS| stores about files or code, or augment/replace the information returned by the |RS|. @@ -69,8 +77,8 @@ The Mojito framework primarily views a **resource** as something useful found on To the Resource Store ````````````````````` -The |RS| primarily cares about the *metadata* about each resource, so it calls the -metadata the *resource". To the |RS|, the **resource** is just a JavaScript object containing +The |RS| primarily cares about the *metadata* about each resource, so it sees the +metadata as the *resource*. To the |RS|, the **resource** is just a JavaScript object containing metadata. The |RS| defines certain keys with specific meanings. The |RS| addons can add, remove, or modify those keys/values as they see fit. For example, the yui |RS| addon adds the ``yui`` key with metadata @@ -84,7 +92,7 @@ Resource Versions ----------------- Because there can be multiple files which are all conceptually different versions of the -same thing (think ``views/index.mu.html`` and ``views/index.iphone.mu.html``), the |RS| defines +same thing (e.g., ``views/index.mu.html`` and ``views/index.iphone.mu.html``), the |RS| defines **resource version** as the metadata about each file and **resource** as the metadata about the file chosen among the possible choices. @@ -105,13 +113,10 @@ Application-Level Resources ``````````````````````````` Application-level resources are truly global to the application. -Some example resource types are middleware, |RS| addons, archetypes, and commands. -(As an implementation detail, the |RS| still tracks resource versions for these kinds of resources -and then resolves those versions down to a chosen resource, even though there's only one version -of each resource. More work at server start, but less code to write and debug.) At the application level, resources include archetypes, commands, configuration files, and middleware. + .. _scope-mojit: Mojit-Level Resources @@ -136,7 +141,7 @@ Resource Types -------------- The resource type is defined by the ``type`` property in the metadata for a given resource. -See `Types of Resources `_ for descriptions of the built-in resource +See `Types of Resources `_ for descriptions of the resource types. Developers can also create their own types of resources to fit the need of their applications. @@ -153,8 +158,8 @@ Intro ----- The resource store uses metadata to find, load, parse, and create instances of resources. The -resource metadata is generated by code--it has no representation on the filesystem. It is -generate during ``preload``, either by the |RS| itself or by |RS| addons. +resource metadata is generated by code--it has no representation on the filesystem. The metadata +is generated by the |RS| or by |RS| addons. .. _metadata-obj: @@ -179,23 +184,23 @@ from the file name. | | | | | | following syntax convention: | | | | | | | ``{type}-{subtype}-{name}`` | +------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ -| `` mojit`` | string | no | none | ``shared`` | The mojit, if any, that uses this resource | +| `` mojit`` | string | no | none | N/A | The mojit, if any, that uses this resource | | | | | | | The value ``"shared"`` means the resource | | | | | | | is available to all mojits. | +------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ -| ``name`` | string | yes | none | | The name of the resource that is common to | +| ``name`` | string | yes | none | N/A | The name of the resource that is common to | | | | | | | all versions (i.e., iPhone/Android, etc.) | | | | | | | of the resource. Example: the name for | | | | | | | for the resources ``index.iphone.mu.html`` | | | | | | | and ``index.mu.html`` is ``index``. | +------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ -| ``selector`` | string | no | "*" | | The version of the resource, not to be | +| ``selector`` | string | no | "*" | N/A | The version of the resource, not to be | | | | | | | confused revisions that mark the change of | | | | | | | the resource over time. For example, a | | | | | | | resource could have a version for iPhones, | | | | | | | Android devices, fallbacks, etc. | +------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ -| ``source`` | object | yes | | | Specifies where the resource came from | +| ``source`` | object | yes | | N/A | Specifies where the resource came from | | | | | | | (not shipped to client). See `source Object | | | | | | | `_ for details. | +------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ @@ -204,15 +209,16 @@ from the file name. | | | | | ``model``, ``view`` | `Subtypes `_ for more | | | | | | | information. | +------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ -| ``type`` | string | yes | none | See `Types of Resources `_. | | +------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ -| ``url`` | string | no | none | | The path used to load the resource | +| ``url`` | string | no | none | N/A | The path used to load the resource | | | | | | | onto the client. Used only for resources | | | | | | | that can be deployed by reference to the | | | | | | | client. | +------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ -| ``yui`` | object | no | none | | // for resources that are YUI modules ==?? | +| ``yui`` | object | no | none | N/A | The metadata about YUI modules. See the | +| | | | | | `yui Object `_ for more details. | +------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ .. _src_obj: @@ -233,16 +239,16 @@ source Object yui Object `````````` -The ``yui`` property of the metadata object is created by the ``yui`` resource store addon, and -therefore, the ``yui`` property can be any data type. In general, the ``yui`` property is an object -containing metadata about YUI modules. The following table liststhe typical properties that are +The ``yui`` property of the metadata object is created by the ``yui`` resource store addon. The +``yui`` property can be any data type, but in general, it is an object +containing metadata about YUI modules. The following table lists the typical properties that are part of the ``yui`` object. You can think of the ``yui`` object as a container for the arguments to the ``YUI.add`` method that is used to register reusable YUI modules. +------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ -| Property | Data Type | Required? | Default Value | Possible Values | Description | +| Property | Data Type | Required? | Default Value | Example Values | Description | +========================+===============+===========+===============+===============================+=============================================+ -| ``name`` | string | yes | none | "scroll" | The name of the YUI module. | +| ``name`` | string | yes | none | ``"scroll"`` | The name of the YUI module. | +------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ | ``meta.requires`` | array | yes | none | ``["scroll","node","cache"]`` | Contains a list of YUI modules required by | | | | | | | this resource. | @@ -277,9 +283,23 @@ You can use a subtype to specify types of a ``type``. For example, a resource of ``type:addon`` might have subtypes, such as ``subtype:ac`` for AC addons, ``subtype:view-engine`` for view engines, or ``subtype:rs`` for |RS| addons. -For "type:archetype" the subtypes refers to the "type" described by -`mojito help create`. So, you could have "subtype:app" or -"subtype:mojit". (There might be more in the future!) +For ``type:archetype``, the subtypes refers to the ``type`` described in the output from +the command ``mojito help create``. So, you could have ``subtype:app``, ``subtype:project``, or +``subtype:mojit``. (There may be more in the future!) + +.. _metatdata-versions: + +Resource Versions +----------------- + +Resources can have many versions that are identified by the ``selector`` property of the +metadata object. The selector is defined by the user and indicates the version of the resource. +For example, developer might decide to use the selector ``selector: iphone`` for the iPhone version +and ``selector: android`` for the Android version of a resource. Using these two selectors, you +could have the following two versions of the ``index`` resource of type ``view``: + +- ``index.iphone.mu.html`` +- ``index.android.mu.html`` .. _metadata-ex: @@ -318,11 +338,7 @@ Example "viewEngine": "mu", "url": "/static/PagedFlickr/views/index.mu.html" } - - - -.. Note: Drew is thinking of change "viewOutputFormat" and "viewEngine" to go under a "view" -.. sub-object. I'll let you know if I make that change. + .. _rs-how: @@ -336,74 +352,93 @@ In short, the resource store walks through the application-level, mojit-level, and ``npm`` module files (in that order) of a Mojito application, determines what type of resource each file is, creates metadata about the resource, and then registers the resource. -During this process, the resource store is also doing the following: +During this process, the resource store also does the following: -- pre-calculating ("resolving") which resource versions are used for each version of the mojit. -- keeping track of app-level resources (archetypes, commands, config files, and middleware). -- providing methods for events, including those specialized for AOP. -- explicitly using the addons `selector `_ and `config `_ +- pre-calculates ("resolving") which resource versions are used for each version of the mojit. +- keeps track of application-level resources (archetypes, commands, config files, and middleware). +- provides methods for events, including those specialized for + `aspect-orient programming (AOP) `_. +- explicitly uses the addons `selector `_ and `config `_ -To see the code for the resource store, -see `store.server.js `_. +In the following sections, we'll look at the process in a little more details. To see the code for +the resource store, see the `store.server.js `_ +file. .. _how-walk_fs: Walking the Filesystem ---------------------- -Resource versions are discovered by the |RS| at server-start time. (Mojito server calls the -``preload`` method of the |RS|.) - -This is done by walking all the files in the application, excluding the ``node_modules`` directory. - -Then, all files in the packages in `node_modules` are walked. The packages are walked in -breadth-first fashion, so that *shallower* packages have precedence above *deeper* ones. -(Not all the packages are used, of course, only those that have declared themselves as extensions -to Mojito.) - -(Then, if Mojito wasn't found in ``node_modules``, the globally-installed version of Mojito is -walked.) +Resource versions are discovered by the |RS| at server-start time. The |RS| method ``preload`` +first walks all the files in the application, excluding the ``node_modules`` directory. Next, all +the files in the packages in `node_modules` are walked. The packages are walked in breadth-first +fashion, so that *shallower* packages have precedence above *deeper* ones. (Not all the packages +are used, of course; only those that have declared themselves as extensions to Mojito.) Finally, +if Mojito wasn't found in ``node_modules``, the globally-installed version of Mojito is walked. After all that, the |RS| knows about all the resource versions. Then it resolves those versions -into the resources as described below. That still happens as part of ``preload``. +into the resources as described in `Resolution and Priorities `_. .. _how-resolution: Resolution and Priorities ------------------------- +The resolving of resource version happens in the |RS| ``preload`` method as well. The act of resolving the resource versions is really just resolving the affinities and selectors. +See `Resource Versions `_ for a brief explanation about how affinities +and selectors determine different versions of a resource. + +.. _resolution-selectors: + +Selectors +````````` + +The order of the selectors is defined by a **priority-ordered selector list (POSL)**. The POSL +depends on the runtime context. -For example, the application might have the following: +Suppose an application has the following resources: - ``controller.common.js`` - ``controller.common.iphone.js`` - ``controller.server.js`` - ``controller.server.phone.js`` -The order of the selectors is defined by a **priority-ordered selector list (POSL)**. The POSL -depends on the runtime context. In our example, the POSL for context ``{device:browser}`` might -be ``['*']`` but for context ``{device:iphone}`` might be ``['iphone','*']``. - -(We need to use a (prioritized) list of selectors instead of just a "selector that matches the +In this application, the POSL for context ``{device:browser}`` might +be ``['*']``, but the POSL for the context ``{device:iphone}`` might be ``['iphone','*']``. +We need to use a (prioritized) list of selectors instead of just a "selector that matches the context" because not all versions might exist for all selectors. In the example above, if -``controller.server.iphone.js`` didn't exist we should still do the right thing for context -``{device:iphone}``.) +``controller.server.iphone.js`` didn't exist, we should still do the right thing for context +``{device:iphone}``. + +.. _resolution-affinities: + +Affinities +``````````` + +The choice of a resource version depends on the **affinity** as well. If we're resolving versions +for the server, versions with ``affinity:server`` will have higher priority than +``affinity:common``, and ``affinity:client`` will be completely ignored. -The choice depends on the **affinity** as well. If we're resolving versions for the server, -versions with ``affinity:server`` will have higher priority than ``affinity:common``, and -``affinity:client`` will be completely ignored. +.. _resolution-sources: -The final consideration for priority is the **source**. Mojit-level versions have higher priority -than shared versions. For example, imagine an application with the following: +Sources +``````` + +The final consideration for priority is the **source**. Mojit-level versions have higher priority +than shared versions. Let's take a different application with the following resources: - ``mojits/Foo/models/bar.common.js`` - ``models/bar.common.js`` -In this case, the second resource is shared with all mojits. However, the mojit ``Foo`` has +In this application, the second resource is shared with all mojits. The mojit ``Foo``, however, has defined its own version of the same resource (``id: model--bar``), and so that should have higher priority than the shared one. +.. _resolution-relationships: + +Relationships +````````````` Finally, there's a **relationship** between the different types of priority. #. The source has the highest priority. @@ -424,15 +459,15 @@ every possible runtime context). Getting Data from the Resource Store ------------------------------------ -Besides the standard ways that Mojito uses the resource store, there are generic interfaces for +Besides the standard ways that Mojito uses the resource store, there are two generic methods for getting resources and resource versions from the |RS|. - ``getResourceVersions(filter)`` - ``getResources(env, ctx, filter)`` The APIs are intentionally similar. Both return an array of resources, and the ``filter`` argument -can be used to restrict the returned resources (or versions). It is an object, all of whose -keys and values must match the returned resources (or versions). Think of it as a *template* +can be used to restrict the returned resources (or versions). The ``filter`` is an object +whose keys and values must match the returned resources (or versions). Think of it as a *template* or *partial resource* that all resources must match. For example, a filter of ``{type:'view'}`` will return all the views. @@ -443,8 +478,8 @@ filter ``{mojit:'Foo'}`` will return all resources (or versions) in the ``Foo`` might contain shared resources. To get mojit-level resources (or versions) from multiple mojits, you'll have to call -the method ``getResourceVersions` or ``getResources`` for each mojit. You can call -``listAllMojits`` to get the list of all mojits. +the method ``getResourceVersions`` or ``getResources`` for each mojit. You can call +``listAllMojits`` to get a list of all mojits. .. _resource_store-addons: @@ -455,7 +490,7 @@ Resource Store Built-In Addons Intro ----- -Mojito comes with built-in resource store addons that are used by the resource store +Mojito comes with built-in resource store addons that are used by the |RS| and the Mojito framework. These resource store addons are required by the |RS| and the Mojito framework. Thus, particular care must be taken when creating custom versions of them. @@ -464,7 +499,7 @@ The |RS| comes with the following four built-in addons: - ``config`` - registers new resource type ``config`` found in ``.json`` files - - provides API for reading both context and straight-JSON files + - provides an API for reading both context and straight-JSON files - provides sugar for reading the application's dimensions - ``selector`` - decides the priority-ordered list (POSL) to use for a context @@ -476,26 +511,27 @@ The |RS| comes with the following four built-in addons: - stores the URL in the ``url`` key of the resource - calculates the asset URL base for each mojit - ``yui`` - - registers new resource type ``yui-module`` found in ``autoload`` or ``yui_modules`` - - registers new resource type ``yui-lang`` found in ``lang`` - - calculates the ``yui`` metadata for resource versions which are YUI modules + - registers new resource type ``yui-module`` found in the directories ``autoload`` + or ``yui_modules`` + - registers new resource type ``yui-lang`` found in the ``lang`` directory + - calculates the ``yui`` metadata for resource versions that are YUI modules - pre-calculates corresponding YUI module dependencies when resources are resolved - for each version of each mojit, + for each version of each mojit - appends the pre-calculated YUI module dependencies for the controller and binders when - Mojito queries the |RS| for details of a mojit (``getMojitTypeDetails`` method) + Mojito queries the |RS| for the details of a mojit (``getMojitTypeDetails`` method) - provides methods used by Mojito to configure its YUI instances .. _resource_store-custom_addons: Creating Custom Versions of Built-In |RS| Addons ----------------------------------------------- +------------------------------------------------ We will be examining the ``selector`` and ``url`` addons to help you create custom versions of those addons. We do not recommend that you create custom versions of the ``config`` or ``yui`` addons, so we will not be looking at those addons. Also, this documentation explains what the |RS| expects the addon to do, so you can create your own version of the addons. -To learn what a |RS| addon does, please refer to the |RSC|_ in the API documentation. +To learn what a |RS| built-in addons do, please refer to the |RSC|_ in the API documentation. .. _intro-selector: @@ -518,7 +554,8 @@ you can implement your own version of this |RS| addon. It'll need to go in Requirements ~~~~~~~~~~~~ -Because the ``selector`` addon is used directly by the the resource store, all implementations need to provide the following method: +Because the ``selector`` addon is used directly by the the resource store, all implementations +need to provide the following method: - ``getListFromContext(ctx)`` @@ -551,7 +588,6 @@ url Description ~~~~~~~~~~~ - The ``url`` addon calculates and manages the static handler URLs for resources. The addon is not used by resource store core, but used by the static handler middleware. @@ -584,7 +620,7 @@ Your addon will also be required to do the following: - Add the ``url`` metadatum to resource versions; this is where your addon will set the calculated value (using ``beforeHostMethod('addResourceVersion')``). -- Add ``assetsRoot`` to the results of ``getMojitTypeDetails()``, which is done with +- Add ``assetsRoot`` to the results of the method ``getMojitTypeDetails`, which is done with ``onHostEvent('getMojitTypeDetails')``; ``assetsRoot`` is the common prefix for all assets in the mojit. The built-in addon makes something like ``/static/Foo/assets`` for the ``Foo`` mojit. @@ -673,9 +709,9 @@ initialize(config) **Parameters:** - ``config `` - contains the following: -- ``host `` - contains the resource store. -- ``appRoot `` - the directory of the application. -- ``mojitoRoot `` - the directory of the Mojito framework code. + - ``host `` - contains the resource store. + - ``appRoot `` - the directory of the application. + - ``mojitoRoot `` - the directory of the Mojito framework code. .. _key_methods-preload: From 4cc21e3a04a6d98e3ae810f803df9cce928fa030 Mon Sep 17 00:00:00 2001 From: Joe Catera Date: Thu, 12 Jul 2012 09:15:48 -0700 Subject: [PATCH 23/45] Made more copy edits. --- .../topics/mojito_resource_store.rst | 65 +++++++++++-------- 1 file changed, 38 insertions(+), 27 deletions(-) diff --git a/docs/dev_guide/topics/mojito_resource_store.rst b/docs/dev_guide/topics/mojito_resource_store.rst index 06f1b930f..b33af3f1d 100644 --- a/docs/dev_guide/topics/mojito_resource_store.rst +++ b/docs/dev_guide/topics/mojito_resource_store.rst @@ -15,6 +15,11 @@ Resource Store .. Details about ``fs`` and ``pkg`` .. More complete overview. .. Have "viewOutputFormat" and "viewEngine" been put under a "view"? +.. Do we have any simple examples for the ``selector`` and ``url`` addons? +.. I'm don't quite understand what "hook in" means in the following sentence: + .. Addons are loaded during this method, so it's not possible to hook in before ``preload`` is +called. +.. Does the ``affinity`` property of the metadata object have a default value? .. _rs-intro: @@ -176,8 +181,19 @@ from the file name. +------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ | Property | Data Type | Required? | Default Value | Possible Values | Description | +========================+===============+===========+===============+=============================+=============================================+ -| ``affinity`` | string | -- | -- | ``server``, ``client``, | The affinity of the resource, which | -| | | | | ``common`` | indicates where the resource will be used. | +| ``type`` | string | yes | none | See `Types of Resources `_. | | ++------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ +| ``subtype`` | string | no | none | ``action``, ``binder``, | Some resource types have multiple subtypes | +| | | | | ``command``, ``middleware`` | that can be specified with ``subtype``. See | +| | | | | ``model``, ``view`` | `Subtypes `_ for more | +| | | | | | information. | ++------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ +| ``name`` | string | yes | none | N/A | The name of the resource that is common to | +| | | | | | all versions (i.e., iPhone/Android, etc.) | +| | | | | | of the resource. Example: the name for | +| | | | | | for the resources ``index.iphone.mu.html`` | +| | | | | | and ``index.mu.html`` is ``index``. | +------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ | ``id`` | string | yes | none | N/A | A unique ID that is common to all versions | | | | | | | of the resource. The ``id`` has the | @@ -188,11 +204,8 @@ from the file name. | | | | | | The value ``"shared"`` means the resource | | | | | | | is available to all mojits. | +------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ -| ``name`` | string | yes | none | N/A | The name of the resource that is common to | -| | | | | | all versions (i.e., iPhone/Android, etc.) | -| | | | | | of the resource. Example: the name for | -| | | | | | for the resources ``index.iphone.mu.html`` | -| | | | | | and ``index.mu.html`` is ``index``. | +| ``affinity`` | string | yes | -- | ``server``, ``client``, | The affinity of the resource, which | +| | | | | ``common`` | indicates where the resource will be used. | +------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ | ``selector`` | string | no | "*" | N/A | The version of the resource, not to be | | | | | | | confused revisions that mark the change of | @@ -200,18 +213,10 @@ from the file name. | | | | | | resource could have a version for iPhones, | | | | | | | Android devices, fallbacks, etc. | +------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ -| ``source`` | object | yes | | N/A | Specifies where the resource came from | +| ``source`` | object | yes | none | N/A | Specifies where the resource came from | | | | | | | (not shipped to client). See `source Object | | | | | | | `_ for details. | +------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ -| ``subtype`` | string | no | none | ``action``, ``binder``, | Some resource types have multiple subtypes | -| | | | | ``command``, ``middleware`` | that can be specified with ``subtype``. See | -| | | | | ``model``, ``view`` | `Subtypes `_ for more | -| | | | | | information. | -+------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ -| ``type`` | string | yes | none | See `Types of Resources `_. | | -+------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ | ``url`` | string | no | none | N/A | The path used to load the resource | | | | | | | onto the client. Used only for resources | | | | | | | that can be deployed by reference to the | @@ -358,7 +363,7 @@ During this process, the resource store also does the following: - keeps track of application-level resources (archetypes, commands, config files, and middleware). - provides methods for events, including those specialized for `aspect-orient programming (AOP) `_. -- explicitly uses the addons `selector `_ and `config `_ +- explicitly uses the addons `selector `_ and `config `_. In the following sections, we'll look at the process in a little more details. To see the code for the resource store, see the `store.server.js `_ @@ -545,8 +550,8 @@ Description ~~~~~~~~~~~ If you wish to use a different algorithm for to determine the selectors to use, -you can implement your own version of this |RS| addon. It'll need to go in -``addons/rs/selector.server.js`` in your application. +you can implement your own version of this |RS| addon. It will need to go in the file +``addons/rs/selector.server.js`` of your application. .. _selector-reqs: @@ -718,11 +723,15 @@ initialize(config) preload() ````````` -- Addons are loaded during this method, so it's not possible to hook in before ``preload`` is - called. -- During preload, the methods ``preloadResourceVersions`` and ``resolveResourceVersions`` are - called. -- After ``preload`` has been called, you can hook in with ``afterHostMethod('preload', ...)``. +Addons are loaded during this method, so it's not possible to hook in before ``preload`` is +called. + +Within the ``preload`` method, the following host methods are called: +- `preloadResourceVersions `_ and +- `resolveResourceVersions `_. + +After ``preload`` has finished executing, you can hook in +with ``afterHostMethod('preload', ...)``. .. _key_methods-preloadResourceVersions: @@ -735,8 +744,8 @@ method ``getStaticAppConfig``. Within the ``preloadResourceVersions`` method, the following host methods are called: - ``findResourceVersionByConvention`` -- ``parseResourceVersion`` -- ``addResourceVersion`` +- `parseResourceVersion `_ +- `addResourceVersion `_ After ``preloadResourceVersions`` has been called: - All the resource versions have been loaded and are available through the method @@ -917,7 +926,9 @@ The following |RS| addon registers the new resource type ``text`` for text files Text Addon `````````` -The Text Addon provides accessors so that that controller can access resources of type ``text``. +The Text Addon provides accessors so that the controller can access resources of type ``text``. +You could use this example addon as a model for writing an addon that allows a controller +to access other resource types such as ``xml`` or ``yaml``. ``addons/ac/text.server.js`` From 96567f290e8464c471cec662479fc0df95164c97 Mon Sep 17 00:00:00 2001 From: Joe Catera Date: Thu, 12 Jul 2012 09:19:27 -0700 Subject: [PATCH 24/45] Moving comments and variables to the end. Seems like the indentation broke the doc. --- .../topics/mojito_resource_store.rst | 40 ++++++++++--------- 1 file changed, 22 insertions(+), 18 deletions(-) diff --git a/docs/dev_guide/topics/mojito_resource_store.rst b/docs/dev_guide/topics/mojito_resource_store.rst index b33af3f1d..cf2756afa 100644 --- a/docs/dev_guide/topics/mojito_resource_store.rst +++ b/docs/dev_guide/topics/mojito_resource_store.rst @@ -2,25 +2,8 @@ Resource Store ============== -.. |RS| replace:: Resource Store -.. |RSC| replace:: ResourceStore.server Class -.. _RSC: http://developer.yahoo.com/cocktails/mojito/api/classes/ResourceStore.server.html -.. |YUIPlugin| replace:: YUI Plugin -.. _|YUIPlugin| http://yuilibrary.com/yui/docs/plugin/ -.. Questions/Needed Info - -.. Formal definition about selectors. -.. Details about ``fs`` and ``pkg`` -.. More complete overview. -.. Have "viewOutputFormat" and "viewEngine" been put under a "view"? -.. Do we have any simple examples for the ``selector`` and ``url`` addons? -.. I'm don't quite understand what "hook in" means in the following sentence: - .. Addons are loaded during this method, so it's not possible to hook in before ``preload`` is -called. -.. Does the ``affinity`` property of the metadata object have a default value? - .. _rs-intro: Overview @@ -1007,4 +990,25 @@ Controller }); } }; - }, '1.0.1', {requires: ['mojito', 'addon-ac-text']}); \ No newline at end of file + }, '1.0.1', {requires: ['mojito', 'addon-ac-text']}); + + + +.. |RS| replace:: Resource Store +.. |RSC| replace:: ResourceStore.server Class +.. _RSC: http://developer.yahoo.com/cocktails/mojito/api/classes/ResourceStore.server.html +.. |YUIPlugin| replace:: YUI Plugin +.. _|YUIPlugin| http://yuilibrary.com/yui/docs/plugin/ + + +.. Questions/Needed Info + +.. Formal definition about selectors. +.. Details about ``fs`` and ``pkg`` +.. More complete overview. +.. Have "viewOutputFormat" and "viewEngine" been put under a "view"? +.. Do we have any simple examples for the ``selector`` and ``url`` addons? +.. I'm don't quite understand what "hook in" means in the following sentence: + .. Addons are loaded during this method, so it's not possible to hook in before ``preload`` is +called. +.. Does the ``affinity`` property of the metadata object have a default value? \ No newline at end of file From a10ffe17a32a730d26d83ad5323d84eb498340dc Mon Sep 17 00:00:00 2001 From: Joe Catera Date: Thu, 12 Jul 2012 09:32:50 -0700 Subject: [PATCH 25/45] Fixing indentation, hopefully. --- docs/dev_guide/topics/mojito_resource_store.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/dev_guide/topics/mojito_resource_store.rst b/docs/dev_guide/topics/mojito_resource_store.rst index cf2756afa..27dbdb70e 100644 --- a/docs/dev_guide/topics/mojito_resource_store.rst +++ b/docs/dev_guide/topics/mojito_resource_store.rst @@ -1009,6 +1009,5 @@ Controller .. Have "viewOutputFormat" and "viewEngine" been put under a "view"? .. Do we have any simple examples for the ``selector`` and ``url`` addons? .. I'm don't quite understand what "hook in" means in the following sentence: - .. Addons are loaded during this method, so it's not possible to hook in before ``preload`` is -called. + .. Addons are loaded during this method, so it's not possible to hook in before ``preload`` is called. .. Does the ``affinity`` property of the metadata object have a default value? \ No newline at end of file From ca9d9ccdf32c2209960178516337db555ac83a09 Mon Sep 17 00:00:00 2001 From: Joe Catera Date: Thu, 12 Jul 2012 14:26:15 -0700 Subject: [PATCH 26/45] Removing comments that might be breaking the file on GitHub, although Sphinx renders the file without an issue. --- .../topics/mojito_resource_store.rst | 21 +------------------ 1 file changed, 1 insertion(+), 20 deletions(-) diff --git a/docs/dev_guide/topics/mojito_resource_store.rst b/docs/dev_guide/topics/mojito_resource_store.rst index 27dbdb70e..589ef9cfa 100644 --- a/docs/dev_guide/topics/mojito_resource_store.rst +++ b/docs/dev_guide/topics/mojito_resource_store.rst @@ -991,23 +991,4 @@ Controller } }; }, '1.0.1', {requires: ['mojito', 'addon-ac-text']}); - - - -.. |RS| replace:: Resource Store -.. |RSC| replace:: ResourceStore.server Class -.. _RSC: http://developer.yahoo.com/cocktails/mojito/api/classes/ResourceStore.server.html -.. |YUIPlugin| replace:: YUI Plugin -.. _|YUIPlugin| http://yuilibrary.com/yui/docs/plugin/ - - -.. Questions/Needed Info - -.. Formal definition about selectors. -.. Details about ``fs`` and ``pkg`` -.. More complete overview. -.. Have "viewOutputFormat" and "viewEngine" been put under a "view"? -.. Do we have any simple examples for the ``selector`` and ``url`` addons? -.. I'm don't quite understand what "hook in" means in the following sentence: - .. Addons are loaded during this method, so it's not possible to hook in before ``preload`` is called. -.. Does the ``affinity`` property of the metadata object have a default value? \ No newline at end of file + \ No newline at end of file From 9036d7c4fc31cbd8d139fe0e7034581bf3a050ee Mon Sep 17 00:00:00 2001 From: Joe Catera Date: Thu, 12 Jul 2012 14:30:46 -0700 Subject: [PATCH 27/45] Changing marker for second-level headings. --- docs/dev_guide/topics/mojito_resource_store.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/dev_guide/topics/mojito_resource_store.rst b/docs/dev_guide/topics/mojito_resource_store.rst index 589ef9cfa..2c309cccf 100644 --- a/docs/dev_guide/topics/mojito_resource_store.rst +++ b/docs/dev_guide/topics/mojito_resource_store.rst @@ -7,7 +7,7 @@ Resource Store .. _rs-intro: Overview -======== +######## The Resource Store (RS) is the Mojito subsystem that manages metadata about the files in your Mojito applications. Thus, it is @@ -46,7 +46,7 @@ code, or augment/replace the information returned by the |RS|. .. _rs-resources: Resources -========= +######### .. _resources-what: @@ -138,7 +138,7 @@ applications. .. _rs-metadata: Resource Metadata -================= +################# .. _metadata-intro: @@ -331,7 +331,7 @@ Example .. _rs-how: How Does the Resource Store Work? -================================= +################################# Understanding the workflow of the resource store will give help those who want to customize addons to write code and help others who don't plan on customizing addons to debug. @@ -473,7 +473,7 @@ the method ``getResourceVersions`` or ``getResources`` for each mojit. You can .. _resource_store-addons: Resource Store Built-In Addons -============================== +############################## Intro ----- @@ -664,7 +664,7 @@ Example .. _rs-creating_rs_addons: Creating Your Own Resource Store Addons -======================================= +####################################### .. _creating_rs_addons-intro: From 3dfaf88e5dc00e3856c48eb06a71a7b17d1e38b6 Mon Sep 17 00:00:00 2001 From: Joe Catera Date: Thu, 12 Jul 2012 15:10:32 -0700 Subject: [PATCH 28/45] Fixed some reST issues. --- .../topics/mojito_resource_store.rst | 86 +++++++++++-------- 1 file changed, 50 insertions(+), 36 deletions(-) diff --git a/docs/dev_guide/topics/mojito_resource_store.rst b/docs/dev_guide/topics/mojito_resource_store.rst index 2c309cccf..1e92c3ade 100644 --- a/docs/dev_guide/topics/mojito_resource_store.rst +++ b/docs/dev_guide/topics/mojito_resource_store.rst @@ -7,7 +7,7 @@ Resource Store .. _rs-intro: Overview -######## +======== The Resource Store (RS) is the Mojito subsystem that manages metadata about the files in your Mojito applications. Thus, it is @@ -46,7 +46,7 @@ code, or augment/replace the information returned by the |RS|. .. _rs-resources: Resources -######### +========= .. _resources-what: @@ -56,14 +56,14 @@ What is a Resource? .. _what-to_mojito: To Mojito -````````` +######### The Mojito framework primarily views a **resource** as something useful found on the filesystem. .. _what-to_rs: To the Resource Store -````````````````````` +##################### The |RS| primarily cares about the *metadata* about each resource, so it sees the metadata as the *resource*. To the |RS|, the **resource** is just a JavaScript object containing @@ -98,7 +98,7 @@ Resource Scope .. _scope-application: Application-Level Resources -``````````````````````````` +########################### Application-level resources are truly global to the application. At the application level, resources include archetypes, commands, configuration files, and @@ -138,7 +138,7 @@ applications. .. _rs-metadata: Resource Metadata -################# +================= .. _metadata-intro: @@ -183,7 +183,7 @@ from the file name. | | | | | | following syntax convention: | | | | | | | ``{type}-{subtype}-{name}`` | +------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ -| `` mojit`` | string | no | none | N/A | The mojit, if any, that uses this resource | +| ``mojit`` | string | no | none | N/A | The mojit, if any, that uses this resource | | | | | | | The value ``"shared"`` means the resource | | | | | | | is available to all mojits. | +------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ @@ -212,7 +212,7 @@ from the file name. .. _src_obj: source Object -````````````` +############# +------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ | Property | Data Type | Required? | Default Value | Possible Values | Description | @@ -225,7 +225,7 @@ source Object .. _yui_obj: yui Object -`````````` +########## The ``yui`` property of the metadata object is created by the ``yui`` resource store addon. The ``yui`` property can be any data type, but in general, it is an object @@ -265,7 +265,7 @@ The ``type`` property of the metadata object can have any of the following value .. _types-subtypes: Subtypes -```````` +######## You can use a subtype to specify types of a ``type``. For example, a resource of ``type:addon`` might have subtypes, such as ``subtype:ac`` for AC addons, @@ -331,7 +331,7 @@ Example .. _rs-how: How Does the Resource Store Work? -################################# +================================= Understanding the workflow of the resource store will give help those who want to customize addons to write code and help others who don't plan on customizing addons to debug. @@ -365,7 +365,7 @@ are used, of course; only those that have declared themselves as extensions to M if Mojito wasn't found in ``node_modules``, the globally-installed version of Mojito is walked. After all that, the |RS| knows about all the resource versions. Then it resolves those versions -into the resources as described in `Resolution and Priorities `_. +into the resources as described in `Resolution and Priorities `_. .. _how-resolution: @@ -380,7 +380,7 @@ and selectors determine different versions of a resource. .. _resolution-selectors: Selectors -````````` +######### The order of the selectors is defined by a **priority-ordered selector list (POSL)**. The POSL depends on the runtime context. @@ -402,7 +402,7 @@ context" because not all versions might exist for all selectors. In the example .. _resolution-affinities: Affinities -``````````` +########## The choice of a resource version depends on the **affinity** as well. If we're resolving versions for the server, versions with ``affinity:server`` will have higher priority than @@ -411,7 +411,7 @@ for the server, versions with ``affinity:server`` will have higher priority than .. _resolution-sources: Sources -``````` +####### The final consideration for priority is the **source**. Mojit-level versions have higher priority than shared versions. Let's take a different application with the following resources: @@ -426,7 +426,8 @@ priority than the shared one. .. _resolution-relationships: Relationships -````````````` +############# + Finally, there's a **relationship** between the different types of priority. #. The source has the highest priority. @@ -463,7 +464,7 @@ For mojit-level resources or resource versions, specify the mojit name in the fi filter ``{mojit:'Foo'}`` will return all resources (or versions) in the ``Foo`` mojit. .. note:: Because of the resolution process, the resources returned for filter ``{mojit:'Foo'}`` -might contain shared resources. + might contain shared resources. To get mojit-level resources (or versions) from multiple mojits, you'll have to call the method ``getResourceVersions`` or ``getResources`` for each mojit. You can call @@ -473,7 +474,7 @@ the method ``getResourceVersions`` or ``getResources`` for each mojit. You can .. _resource_store-addons: Resource Store Built-In Addons -############################## +============================== Intro ----- @@ -525,12 +526,12 @@ To learn what a |RS| built-in addons do, please refer to the |RSC|_ in the API d .. _intro-selector: selector -```````` +######## .. _selector-desc: Description -~~~~~~~~~~~ +``````````` If you wish to use a different algorithm for to determine the selectors to use, you can implement your own version of this |RS| addon. It will need to go in the file @@ -540,7 +541,7 @@ you can implement your own version of this |RS| addon. It will need to go in th .. _selector-reqs: Requirements -~~~~~~~~~~~~ +```````````` Because the ``selector`` addon is used directly by the the resource store, all implementations need to provide the following method: @@ -550,7 +551,8 @@ need to provide the following method: .. _selector-getListFromContext: getListFromContext(ctx) -~~~~~~~~~~~~~~~~~~~~~~~ +``````````````````````` + Returns the priority-ordered selector list (POSL) for the context. **Parameters:** @@ -564,17 +566,17 @@ Returns the priority-ordered selector list (POSL) for the context. .. _selector-ex: Example -~~~~~~~ +``````` .. _url-intro: url -``` +### .. _url-desc: Description -~~~~~~~~~~~ +``````````` The ``url`` addon calculates and manages the static handler URLs for resources. The addon is not used by resource store core, but used by the static handler middleware. @@ -594,7 +596,7 @@ filesystem path for a URL. .. _url-reqs: Requirements -~~~~~~~~~~~~ +```````````` The ``selector`` addon is required to have the following methods (see details for the methods in below sections): @@ -641,7 +643,7 @@ Returns the URL for the spec. ```` -.. _url-getSpecURL: +.. _url-getURLPaths: getURLPaths() ````````````` @@ -659,12 +661,12 @@ None. .. _url-ex: Example -~~~~~~~ +``````` .. _rs-creating_rs_addons: Creating Your Own Resource Store Addons -####################################### +======================================= .. _creating_rs_addons-intro: @@ -682,12 +684,12 @@ Anatomy of a |RS| Addon The resource store addons are implemented using the _|YUIPlugin| mechanism. In essence, a Mojito addon is a YUI plugin, so the skeleton of a |RS| addon will be the same as a YUI Plugin. -See the |RCS|_ for the parameters and return values for the |RS| methods. +See the _|RCS| for the parameters and return values for the |RS| methods. .. _anatomy-key_methods: Key Methods -~~~~~~~~~~~ +########### .. _key_methods-initialize: @@ -741,6 +743,7 @@ After ``preloadResourceVersions`` has been called: findResourceVersionByConvention() ````````````````````````````````` + This method is called on each directory or file being walked and is used to decide if the path is a resource version. The return value can be a bit confusing, so read API docs carefully and feel free to post any questions that you have to the @@ -765,6 +768,7 @@ of the ``findResourceVersionByConvention`` method. addResourceVersion() ```````````````````` + This method is called to save the resource version into the |RS|. Typically, if you want to modify/augment an existing resource version, hook into this with the ``beforeHostMethod`` method. @@ -791,18 +795,20 @@ Mojito. .. _anatomy-key_events: Key Events -~~~~~~~~~~ +########## .. _key_events-mojitResourcesResolved: mojitResourcesResolved `````````````````````` + This event is called when the resources in a mojit are resolved. .. _key_events-getMojitTypeDetails: getMojitTypeDetails ``````````````````` + This event is called during runtime as Mojito creates an "instance" used to dispatch a mojit. .. _creating_rs_addons-ex: @@ -813,7 +819,7 @@ Example .. _creating_rs_addons_ex-rs_addon: |RS| Addon -`````````` +########## The following |RS| addon registers the new resource type ``text`` for text files. @@ -907,7 +913,7 @@ The following |RS| addon registers the new resource type ``text`` for text files .. _creating_rs_addons_ex-text_addon: Text Addon -`````````` +########## The Text Addon provides accessors so that the controller can access resources of type ``text``. You could use this example addon as a model for writing an addon that allows a controller @@ -959,7 +965,7 @@ to access other resource types such as ``xml`` or ``yaml``. .. _creating_rs_addons_ex-controller: Controller -`````````` +########## ``mojits/Viewer/controller.server.js`` @@ -991,4 +997,12 @@ Controller } }; }, '1.0.1', {requires: ['mojito', 'addon-ac-text']}); - \ No newline at end of file + + + +.. |RS| replace:: Resource Store +.. |RSC| replace:: ResourceStore.server Class +.. _RSC: http://developer.yahoo.com/cocktails/mojito/api/classes/ResourceStore.server.html +.. |YUIPlugin| replace:: YUI Plugin +.. _YUIPlugin: http://yuilibrary.com/yui/docs/plugin/ + \ No newline at end of file From 2c3a5d0ccbdb06000fcc4f3aee24cb8f84d2f79c Mon Sep 17 00:00:00 2001 From: Joe Catera Date: Thu, 12 Jul 2012 15:22:08 -0700 Subject: [PATCH 29/45] Trying the 'code' directive as the 'code-block' directive is not rendering on GitHub. --- docs/dev_guide/topics/mojito_resource_store.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/dev_guide/topics/mojito_resource_store.rst b/docs/dev_guide/topics/mojito_resource_store.rst index 1e92c3ade..6d2a3b4f8 100644 --- a/docs/dev_guide/topics/mojito_resource_store.rst +++ b/docs/dev_guide/topics/mojito_resource_store.rst @@ -970,7 +970,7 @@ Controller ``mojits/Viewer/controller.server.js`` -.. code-block:: javascript +.. code:: javascript YUI.add('Viewer', function(Y, NAME) { From b37dc0cd924d504312c5feb2e34b66b4dc7166dc Mon Sep 17 00:00:00 2001 From: Joe Catera Date: Thu, 12 Jul 2012 18:36:58 -0700 Subject: [PATCH 30/45] Made more edits. --- .../topics/mojito_resource_store.rst | 115 +++++++++--------- 1 file changed, 58 insertions(+), 57 deletions(-) diff --git a/docs/dev_guide/topics/mojito_resource_store.rst b/docs/dev_guide/topics/mojito_resource_store.rst index 6d2a3b4f8..705447275 100644 --- a/docs/dev_guide/topics/mojito_resource_store.rst +++ b/docs/dev_guide/topics/mojito_resource_store.rst @@ -87,7 +87,7 @@ about the file chosen among the possible choices. The process of choosing which version of a resource to use is called *resolution* (or "resolving the resource"). This act is one of the primary responsibilities of the |RS|. -See `Resolution and Priorities `_ to learn how the |RS| resolves +See :ref:`Resolution and Priorities ` to learn how the |RS| resolves different versions of the same resource. .. _resources-scope: @@ -129,7 +129,7 @@ Resource Types -------------- The resource type is defined by the ``type`` property in the metadata for a given resource. -See `Types of Resources `_ for descriptions of the resource +See :ref:`Types of Resources ` for descriptions of the resource types. Developers can also create their own types of resources to fit the need of their applications. @@ -161,53 +161,54 @@ For example, the affinity of views is ``common`` (because views are used on both client and server); however, the affinity for controllers comes from the file name. -+------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ -| Property | Data Type | Required? | Default Value | Possible Values | Description | -+========================+===============+===========+===============+=============================+=============================================+ -| ``type`` | string | yes | none | See `Types of Resources `_. | | -+------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ -| ``subtype`` | string | no | none | ``action``, ``binder``, | Some resource types have multiple subtypes | -| | | | | ``command``, ``middleware`` | that can be specified with ``subtype``. See | -| | | | | ``model``, ``view`` | `Subtypes `_ for more | -| | | | | | information. | -+------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ -| ``name`` | string | yes | none | N/A | The name of the resource that is common to | -| | | | | | all versions (i.e., iPhone/Android, etc.) | -| | | | | | of the resource. Example: the name for | -| | | | | | for the resources ``index.iphone.mu.html`` | -| | | | | | and ``index.mu.html`` is ``index``. | -+------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ -| ``id`` | string | yes | none | N/A | A unique ID that is common to all versions | -| | | | | | of the resource. The ``id`` has the | -| | | | | | following syntax convention: | -| | | | | | ``{type}-{subtype}-{name}`` | -+------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ -| ``mojit`` | string | no | none | N/A | The mojit, if any, that uses this resource | -| | | | | | The value ``"shared"`` means the resource | -| | | | | | is available to all mojits. | -+------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ -| ``affinity`` | string | yes | -- | ``server``, ``client``, | The affinity of the resource, which | -| | | | | ``common`` | indicates where the resource will be used. | -+------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ -| ``selector`` | string | no | "*" | N/A | The version of the resource, not to be | -| | | | | | confused revisions that mark the change of | -| | | | | | the resource over time. For example, a | -| | | | | | resource could have a version for iPhones, | -| | | | | | Android devices, fallbacks, etc. | -+------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ -| ``source`` | object | yes | none | N/A | Specifies where the resource came from | -| | | | | | (not shipped to client). See `source Object | -| | | | | | `_ for details. | -+------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ -| ``url`` | string | no | none | N/A | The path used to load the resource | -| | | | | | onto the client. Used only for resources | -| | | | | | that can be deployed by reference to the | -| | | | | | client. | -+------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ -| ``yui`` | object | no | none | N/A | The metadata about YUI modules. See the | -| | | | | | `yui Object `_ for more details. | -+------------------------+---------------+-----------+---------------+-----------------------------+---------------------------------------------+ ++------------------------+---------------+-----------+---------------+------------------------------+---------------------------------------------+ +| Property | Data Type | Required? | Default Value | Possible Values | Description | ++========================+===============+===========+===============+==============================+=============================================+ +| ``type`` | string | yes | none | See :ref:`Types of Resources | Specifies the type of resource. | +| | | | | `. | | ++------------------------+---------------+-----------+---------------+------------------------------+---------------------------------------------+ +| ``subtype`` | string | no | none | ``action``, ``binder``, | Some resource types have multiple subtypes | +| | | | | ``command``, ``middleware`` | that can be specified with ``subtype``. See | +| | | | | ``model``, ``view`` | :ref:`Subtypes ` for | +| | | | | | more information. | ++------------------------+---------------+-----------+---------------+------------------------------+---------------------------------------------+ +| ``name`` | string | yes | none | N/A | The name of the resource that is common to | +| | | | | | all versions (i.e., iPhone/Android, etc.) | +| | | | | | of the resource. Example: the name for | +| | | | | | for the resources ``index.iphone.mu.html`` | +| | | | | | and ``index.mu.html`` is ``index``. | ++------------------------+---------------+-----------+---------------+------------------------------+---------------------------------------------+ +| ``id`` | string | yes | none | N/A | A unique ID that is common to all versions | +| | | | | | of the resource. The ``id`` has the | +| | | | | | following syntax convention: | +| | | | | | ``{type}-{subtype}-{name}`` | ++------------------------+---------------+-----------+---------------+------------------------------+---------------------------------------------+ +| ``mojit`` | string | no | none | N/A | The mojit, if any, that uses this resource | +| | | | | | The value ``"shared"`` means the resource | +| | | | | | is available to all mojits. | ++------------------------+---------------+-----------+---------------+------------------------------+---------------------------------------------+ +| ``affinity`` | string | yes | -- | ``server``, ``client``, | The affinity of the resource, which | +| | | | | ``common`` | indicates where the resource will be used. | ++------------------------+---------------+-----------+---------------+------------------------------+---------------------------------------------+ +| ``selector`` | string | no | "*" | N/A | The version of the resource, not to be | +| | | | | | confused revisions that mark the change of | +| | | | | | the resource over time. For example, a | +| | | | | | resource could have a version for iPhones, | +| | | | | | Android devices, fallbacks, etc. | ++------------------------+---------------+-----------+---------------+------------------------------+---------------------------------------------+ +| ``source`` | object | yes | none | N/A | Specifies where the resource came from | +| | | | | | (not shipped to client). See :ref:`source | +| | | | | | Object ` for details. | ++------------------------+---------------+-----------+---------------+------------------------------+---------------------------------------------+ +| ``url`` | string | no | none | N/A | The path used to load the resource | +| | | | | | onto the client. Used only for resources | +| | | | | | that can be deployed by reference to the | +| | | | | | client. | ++------------------------+---------------+-----------+---------------+------------------------------+---------------------------------------------+ +| ``yui`` | object | no | none | N/A | The metadata about YUI modules. See the | +| | | | | | :ref:`yui Object ` for more | +| | | | | | details. | ++------------------------+---------------+-----------+---------------+------------------------------+---------------------------------------------+ .. _src_obj: @@ -346,7 +347,7 @@ During this process, the resource store also does the following: - keeps track of application-level resources (archetypes, commands, config files, and middleware). - provides methods for events, including those specialized for `aspect-orient programming (AOP) `_. -- explicitly uses the addons `selector `_ and `config `_. +- explicitly uses the addons :ref:`selector ` and :ref:`config `. In the following sections, we'll look at the process in a little more details. To see the code for the resource store, see the `store.server.js `_ @@ -365,7 +366,7 @@ are used, of course; only those that have declared themselves as extensions to M if Mojito wasn't found in ``node_modules``, the globally-installed version of Mojito is walked. After all that, the |RS| knows about all the resource versions. Then it resolves those versions -into the resources as described in `Resolution and Priorities `_. +into the resources as described in :ref:`Resolution and Priorities `. .. _how-resolution: @@ -374,7 +375,7 @@ Resolution and Priorities The resolving of resource version happens in the |RS| ``preload`` method as well. The act of resolving the resource versions is really just resolving the affinities and selectors. -See `Resource Versions `_ for a brief explanation about how affinities +See :ref:`Resource Versions ` for a brief explanation about how affinities and selectors determine different versions of a resource. .. _resolution-selectors: @@ -712,8 +713,8 @@ Addons are loaded during this method, so it's not possible to hook in before ``p called. Within the ``preload`` method, the following host methods are called: -- `preloadResourceVersions `_ and -- `resolveResourceVersions `_. +- :ref:`preloadResourceVersions ` +- :ref:`resolveResourceVersions ` After ``preload`` has finished executing, you can hook in with ``afterHostMethod('preload', ...)``. @@ -729,8 +730,8 @@ method ``getStaticAppConfig``. Within the ``preloadResourceVersions`` method, the following host methods are called: - ``findResourceVersionByConvention`` -- `parseResourceVersion `_ -- `addResourceVersion `_ +- :ref:`parseResourceVersion ` +- :ref:`addResourceVersion ` After ``preloadResourceVersions`` has been called: - All the resource versions have been loaded and are available through the method @@ -970,7 +971,7 @@ Controller ``mojits/Viewer/controller.server.js`` -.. code:: javascript +.. code-block:: javascript YUI.add('Viewer', function(Y, NAME) { From cbcebf4265191ba7bca5e1329f4dba4cb48073f0 Mon Sep 17 00:00:00 2001 From: Joe Catera Date: Fri, 13 Jul 2012 08:21:49 -0700 Subject: [PATCH 31/45] More edits. --- docs/dev_guide/topics/mojito_resource_store.rst | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/dev_guide/topics/mojito_resource_store.rst b/docs/dev_guide/topics/mojito_resource_store.rst index 705447275..0d273151a 100644 --- a/docs/dev_guide/topics/mojito_resource_store.rst +++ b/docs/dev_guide/topics/mojito_resource_store.rst @@ -2,8 +2,6 @@ Resource Store ============== - - .. _rs-intro: Overview From d5661a4cd6c440f1caea6ced82833dc04e4de6f9 Mon Sep 17 00:00:00 2001 From: Joe Catera Date: Fri, 13 Jul 2012 10:02:11 -0700 Subject: [PATCH 32/45] Added tables for 'pkg' and 'fs' objects, expanded on overview, and added intro to what is a resource section. --- .../topics/mojito_resource_store.rst | 191 ++++++++++++------ 1 file changed, 124 insertions(+), 67 deletions(-) diff --git a/docs/dev_guide/topics/mojito_resource_store.rst b/docs/dev_guide/topics/mojito_resource_store.rst index 0d273151a..c05a4c559 100644 --- a/docs/dev_guide/topics/mojito_resource_store.rst +++ b/docs/dev_guide/topics/mojito_resource_store.rst @@ -8,8 +8,10 @@ Overview ======== The Resource Store (RS) is the Mojito subsystem that manages metadata about the files in your -Mojito applications. Thus, it is -responsible for finding and classifying code and configuration files. +Mojito applications. Thus, it is responsible for finding and classifying code and configuration +files. When you start a Mojito application, Mojito can find, track, and resolve versions of files +in your application, such as mojits, configuration files, binders, views, assets, addons, etc., +because of the |RS|. .. _intro-who: @@ -21,8 +23,6 @@ Most Mojito application developers will not need to know much about the resource advanced Mojito application developers who want to have finer grain control over the management of resources or extend the functionality of the resource store should read this documentation. -.. track new files types or modify information that the |RS| tracks through metadata can write -.. their own |RS| addons. .. _intro-use: @@ -30,15 +30,15 @@ How Can the Resource Store Help Developers? ------------------------------------------- You can write custom |RS| addons to use the aspect-oriented features of -the resource store, to create resource types, and to map contexts to selectors. +the resource store to create resource types and to map contexts to selectors. For example, you could write your own |RS| addon so that the Mojito command-line tool will create files and resources for your application. The Mojito command-line tool uses the |RS| for all the commands except ``start``. You can also write custom versions of built-in |RS| addons to modify how the resource store works. -Your custom addon could track new file types, augment the information that the |RS| stores about files or -code, or augment/replace the information returned by the |RS|. +Your custom addon could track new file types, augment the information that the |RS| stores about +files or code, or augment/replace the information returned by the |RS|. .. _rs-resources: @@ -51,6 +51,10 @@ Resources What is a Resource? ------------------- +In Mojito, the meaning of the term **resource** is different depending on the context. +Before we discuss the |RS| in more detail, let's differentiate and define the definition of +**resource** in the contexts of Mojito and the |RS|. + .. _what-to_mojito: To Mojito @@ -106,7 +110,7 @@ middleware. .. _scope-mojit: Mojit-Level Resources -````````````````````` +##################### At the mojit level, resources include controllers, models, binders, configuration files, and views. These resources are limited in scope to a mojit. @@ -114,7 +118,7 @@ These resources are limited in scope to a mojit. .. _scope-shared: Shared Resources -```````````````` +################ Some resources (and resource versions) are *shared*, meaning that they are included in **all** mojits. Most resource types that are mojit level can also be shared. Examples of mojit-level @@ -153,60 +157,67 @@ is generated by the |RS| or by |RS| addons. Metadata Object --------------- -Some values do have defaults, but it depends on the value of the ``type`` -key, and/or comes from the file name of the resource being represented. -For example, the affinity of views is ``common`` (because views are used -on both client and server); however, the affinity for controllers comes -from the file name. - -+------------------------+---------------+-----------+---------------+------------------------------+---------------------------------------------+ -| Property | Data Type | Required? | Default Value | Possible Values | Description | -+========================+===============+===========+===============+==============================+=============================================+ -| ``type`` | string | yes | none | See :ref:`Types of Resources | Specifies the type of resource. | -| | | | | `. | | -+------------------------+---------------+-----------+---------------+------------------------------+---------------------------------------------+ -| ``subtype`` | string | no | none | ``action``, ``binder``, | Some resource types have multiple subtypes | -| | | | | ``command``, ``middleware`` | that can be specified with ``subtype``. See | -| | | | | ``model``, ``view`` | :ref:`Subtypes ` for | -| | | | | | more information. | -+------------------------+---------------+-----------+---------------+------------------------------+---------------------------------------------+ -| ``name`` | string | yes | none | N/A | The name of the resource that is common to | -| | | | | | all versions (i.e., iPhone/Android, etc.) | -| | | | | | of the resource. Example: the name for | -| | | | | | for the resources ``index.iphone.mu.html`` | -| | | | | | and ``index.mu.html`` is ``index``. | -+------------------------+---------------+-----------+---------------+------------------------------+---------------------------------------------+ -| ``id`` | string | yes | none | N/A | A unique ID that is common to all versions | -| | | | | | of the resource. The ``id`` has the | -| | | | | | following syntax convention: | -| | | | | | ``{type}-{subtype}-{name}`` | -+------------------------+---------------+-----------+---------------+------------------------------+---------------------------------------------+ -| ``mojit`` | string | no | none | N/A | The mojit, if any, that uses this resource | -| | | | | | The value ``"shared"`` means the resource | -| | | | | | is available to all mojits. | -+------------------------+---------------+-----------+---------------+------------------------------+---------------------------------------------+ -| ``affinity`` | string | yes | -- | ``server``, ``client``, | The affinity of the resource, which | -| | | | | ``common`` | indicates where the resource will be used. | -+------------------------+---------------+-----------+---------------+------------------------------+---------------------------------------------+ -| ``selector`` | string | no | "*" | N/A | The version of the resource, not to be | -| | | | | | confused revisions that mark the change of | -| | | | | | the resource over time. For example, a | -| | | | | | resource could have a version for iPhones, | -| | | | | | Android devices, fallbacks, etc. | -+------------------------+---------------+-----------+---------------+------------------------------+---------------------------------------------+ -| ``source`` | object | yes | none | N/A | Specifies where the resource came from | -| | | | | | (not shipped to client). See :ref:`source | -| | | | | | Object ` for details. | -+------------------------+---------------+-----------+---------------+------------------------------+---------------------------------------------+ -| ``url`` | string | no | none | N/A | The path used to load the resource | -| | | | | | onto the client. Used only for resources | -| | | | | | that can be deployed by reference to the | -| | | | | | client. | -+------------------------+---------------+-----------+---------------+------------------------------+---------------------------------------------+ -| ``yui`` | object | no | none | N/A | The metadata about YUI modules. See the | -| | | | | | :ref:`yui Object ` for more | -| | | | | | details. | -+------------------------+---------------+-----------+---------------+------------------------------+---------------------------------------------+ + + ++------------------------+---------------+-----------+---------------------+------------------------------+---------------------------------------------+ +| Property | Data Type | Required? | Default Value | Possible Values | Description | ++========================+===============+===========+=====================+==============================+=============================================+ +| ``type`` | string | yes | none | See :ref:`Types of Resources | Specifies the type of resource. | +| | | | | `. | | ++------------------------+---------------+-----------+---------------------+------------------------------+---------------------------------------------+ +| ``subtype`` | string | no | none | ``action``, ``binder``, | Some resource types have multiple subtypes | +| | | | | ``command``, ``middleware`` | that can be specified with ``subtype``. See | +| | | | | ``model``, ``view`` | :ref:`Subtypes ` for | +| | | | | | more information. | ++------------------------+---------------+-----------+---------------------+------------------------------+---------------------------------------------+ +| ``name`` | string | yes | none | N/A | The name of the resource that is common to | +| | | | | | all versions (i.e., iPhone/Android, etc.) | +| | | | | | of the resource. Example: the name for | +| | | | | | for the resources ``index.iphone.mu.html`` | +| | | | | | and ``index.mu.html`` is ``index``. | ++------------------------+---------------+-----------+---------------------+------------------------------+---------------------------------------------+ +| ``id`` | string | yes | none | N/A | A unique ID that is common to all versions | +| | | | | | of the resource. The ``id`` has the | +| | | | | | following syntax convention: | +| | | | | | ``{type}-{subtype}-{name}`` | ++------------------------+---------------+-----------+---------------------+------------------------------+---------------------------------------------+ +| ``mojit`` | string | no | none | N/A | The mojit, if any, that uses this resource | +| | | | | | The value ``"shared"`` means the resource | +| | | | | | is available to all mojits. | ++------------------------+---------------+-----------+---------------------+------------------------------+---------------------------------------------+ +| ``affinity`` | string | yes | See :ref:`Note | ``server``, ``client``, | The affinity of the resource, which | +| | | | About Default | ``common`` | indicates where the resource will be used. | +| | | | Values `. | | | ++------------------------+---------------+-----------+---------------------+------------------------------+---------------------------------------------+ +| ``selector`` | string | no | "*" | N/A | The version of the resource, not to be | +| | | | | | confused revisions that mark the change of | +| | | | | | the resource over time. For example, a | +| | | | | | resource could have a version for iPhones, | +| | | | | | Android devices, fallbacks, etc. | ++------------------------+---------------+-----------+---------------------+------------------------------+---------------------------------------------+ +| ``source`` | object | yes | none | N/A | Specifies where the resource came from | +| | | | | | (not shipped to client). See :ref:`source | +| | | | | | Object ` for details. | ++------------------------+---------------+-----------+---------------------+------------------------------+---------------------------------------------+ +| ``url`` | string | no | none | N/A | The path used to load the resource | +| | | | | | onto the client. Used only for resources | +| | | | | | that can be deployed by reference to the | +| | | | | | client. | ++------------------------+---------------+-----------+---------------------+------------------------------+---------------------------------------------+ +| ``yui`` | object | no | none | N/A | The metadata about YUI modules. See the | +| | | | | | :ref:`yui Object ` for more | +| | | | | | details. | ++------------------------+---------------+-----------+---------------------+------------------------------+---------------------------------------------+ + +.. _def_vals: + +.. admonition:: Note About Default Values + + Some values for the properties of the metata object do have defaults, but it depends on + the value of the ``type`` property and/or comes from the file name of the resource being + represented. For example, the affinity of views is ``common`` (because views are used + on both client and server); however, the affinity for controllers comes + from the file name. .. _src_obj: @@ -216,10 +227,56 @@ source Object +------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ | Property | Data Type | Required? | Default Value | Possible Values | Description | +========================+===============+===========+===============+===============================+=============================================+ -| ``fs`` | string | yes | none | N/A | // filesystem details ==> ?? | +| ``fs`` | string | yes | none | N/A | See :ref:`fs Object `. | ++------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ +| ``pkg`` | array | yes | none | N/A | See :ref:`pkg Object `_. | ++------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ + +.. _fs_obj: + +fs Object +````````` + ++------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ +| Property | Data Type | Required? | Default Value | Possible Values | Description | ++========================+===============+===========+===============+===============================+=============================================+ +| ``basename`` | string | yes | none | N/A | | ++------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ +| ``ext`` | string | yes | none | N/A | | ++------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ +| ``fullPath`` | string | yes | none | N/A | | ++------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ +| ``isFile`` | boolean | yes | none | N/A | | ++------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ +| ``fullPath`` | string | yes | none | N/A | | ++------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ +| ``rootDir`` | string | yes | none | N/A | | ++------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ +| ``rootType`` | string | yes | none | See :ref:`Typs of Resources | | +| | | | | `_.| | | ++------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ +| ``subDir`` | string | yes | none | N/A | | ++------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ +| ``subDirArray`` | array | yes | none | N/A | | ++------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ + + +.. _pkg_obj: + +pkg Object +`````````` + ++------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ +| Property | Data Type | Required? | Default Value | Possible Values | Description | ++========================+===============+===========+===============+===============================+=============================================+ +| ``depth`` | number | yes | none | N/A | | +------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ -| ``pkg`` | array | yes | none | N/A | // packaging details ==> what details? | +| ``name`` | string | yes | none | N/A | | +------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ +| ``version`` | string | yes | none | N/A | | ++------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ + + .. _yui_obj: @@ -258,8 +315,8 @@ The ``type`` property of the metadata object can have any of the following value - ``asset`` - an asset (css, js, image, etc.) - ``addon`` - an addon to the mojito system - ``spec`` - the configuration for a mojit instance -- ``yui-lang`` - a YUI3 language bundle -- ``yui-module`` - a YUI3 module (that isn't one of the above) +- ``yui-lang`` - a YUI 3 language bundle +- ``yui-module`` - a YUI 3 module (that isn't one of the above) .. _types-subtypes: From fa20561ef07814cb069facf8056718adbc5b971a Mon Sep 17 00:00:00 2001 From: Joe Catera Date: Fri, 13 Jul 2012 11:08:21 -0700 Subject: [PATCH 33/45] Fixed reST issues and did more copy editing. --- .../topics/mojito_resource_store.rst | 47 +++++++++++-------- 1 file changed, 27 insertions(+), 20 deletions(-) diff --git a/docs/dev_guide/topics/mojito_resource_store.rst b/docs/dev_guide/topics/mojito_resource_store.rst index c05a4c559..8f7935864 100644 --- a/docs/dev_guide/topics/mojito_resource_store.rst +++ b/docs/dev_guide/topics/mojito_resource_store.rst @@ -131,7 +131,7 @@ Resource Types -------------- The resource type is defined by the ``type`` property in the metadata for a given resource. -See :ref:`Types of Resources ` for descriptions of the resource +See :ref:`Types of Resources ` for descriptions of the resource types. Developers can also create their own types of resources to fit the need of their applications. @@ -229,7 +229,7 @@ source Object +========================+===============+===========+===============+===============================+=============================================+ | ``fs`` | string | yes | none | N/A | See :ref:`fs Object `. | +------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ -| ``pkg`` | array | yes | none | N/A | See :ref:`pkg Object `_. | +| ``pkg`` | array | yes | none | N/A | See :ref:`pkg Object `. | +------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ .. _fs_obj: @@ -252,8 +252,8 @@ fs Object +------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ | ``rootDir`` | string | yes | none | N/A | | +------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ -| ``rootType`` | string | yes | none | See :ref:`Typs of Resources | | -| | | | | `_.| | | +| ``rootType`` | string | yes | none | See :ref:`Types of Resources | | +| | | | | `. | | +------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ | ``subDir`` | string | yes | none | N/A | | +------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ @@ -283,7 +283,7 @@ pkg Object yui Object ########## -The ``yui`` property of the metadata object is created by the ``yui`` resource store addon. The +The ``yui`` property of the metadata object is created by the ``yui``|RS| addon. The ``yui`` property can be any data type, but in general, it is an object containing metadata about YUI modules. The following table lists the typical properties that are part of the ``yui`` object. You can think of the ``yui`` object as a container for the arguments to @@ -390,7 +390,10 @@ How Does the Resource Store Work? ================================= Understanding the workflow of the resource store will give help those who want to customize addons -to write code and help others who don't plan on customizing addons to debug. +to write code and others who don't plan on customizing addons to debug. + +Overview +-------- In short, the resource store walks through the application-level, mojit-level, and ``npm`` module files (in that order) of a Mojito application, determines what type @@ -405,8 +408,7 @@ During this process, the resource store also does the following: - explicitly uses the addons :ref:`selector ` and :ref:`config `. In the following sections, we'll look at the process in a little more details. To see the code for -the resource store, see the `store.server.js `_ -file. +the resource store, see the |SS|_ file. .. _how-walk_fs: @@ -415,9 +417,9 @@ Walking the Filesystem Resource versions are discovered by the |RS| at server-start time. The |RS| method ``preload`` first walks all the files in the application, excluding the ``node_modules`` directory. Next, all -the files in the packages in `node_modules` are walked. The packages are walked in breadth-first -fashion, so that *shallower* packages have precedence above *deeper* ones. (Not all the packages -are used, of course; only those that have declared themselves as extensions to Mojito.) Finally, +the files in the packages in ``node_modules`` are walked. The packages are walked in breadth-first +fashion, so that *shallower* packages have precedence over *deeper* ones. (Not all the packages +are used: only those that have declared themselves as extensions to Mojito.) Finally, if Mojito wasn't found in ``node_modules``, the globally-installed version of Mojito is walked. After all that, the |RS| knows about all the resource versions. Then it resolves those versions @@ -496,8 +498,7 @@ will be used because its selector is a higher priority match than its affinity. All this is pre-calculated for each resource, for each possible runtime configuration (client or -server, and -every possible runtime context). +server, and every possible runtime context). .. _how-get_data: @@ -527,11 +528,13 @@ the method ``getResourceVersions`` or ``getResources`` for each mojit. You can ``listAllMojits`` to get a list of all mojits. -.. _resource_store-addons: +.. _rs-addons: Resource Store Built-In Addons ============================== +.. _addons-intro: + Intro ----- @@ -543,7 +546,7 @@ of them. The |RS| comes with the following four built-in addons: - ``config`` - - registers new resource type ``config`` found in ``.json`` files + - registers new resource type ``config`` found in JSON configuration files - provides an API for reading both context and straight-JSON files - provides sugar for reading the application's dimensions - ``selector`` @@ -567,7 +570,7 @@ The |RS| comes with the following four built-in addons: - provides methods used by Mojito to configure its YUI instances -.. _resource_store-custom_addons: +.. _addons-custom: Creating Custom Versions of Built-In |RS| Addons ------------------------------------------------ @@ -579,7 +582,7 @@ explains what the |RS| expects the addon to do, so you can create your own versi To learn what a |RS| built-in addons do, please refer to the |RSC|_ in the API documentation. -.. _intro-selector: +.. _custom-selector: selector ######## @@ -730,7 +733,8 @@ Intro ----- In this section, we will discuss the key methods, events, and give a simple example of a custom -|RS| addon. You should be able to create your own custom |RS| addons afterward. +|RS| addon. By using the provided example as a model and referring to the |RSC|_ in the API +documentation, you should be able to create your own custom |RS| addons. .. _creating_rs_addons-anatomy: @@ -740,7 +744,7 @@ Anatomy of a |RS| Addon The resource store addons are implemented using the _|YUIPlugin| mechanism. In essence, a Mojito addon is a YUI plugin, so the skeleton of a |RS| addon will be the same as a YUI Plugin. -See the _|RCS| for the parameters and return values for the |RS| methods. +See the |RSC|_ for the parameters and return values for the |RS| methods. .. _anatomy-key_methods: @@ -768,6 +772,7 @@ Addons are loaded during this method, so it's not possible to hook in before ``p called. Within the ``preload`` method, the following host methods are called: + - :ref:`preloadResourceVersions ` - :ref:`resolveResourceVersions ` @@ -784,6 +789,7 @@ much is known, though the static application configuration is available using th method ``getStaticAppConfig``. Within the ``preloadResourceVersions`` method, the following host methods are called: + - ``findResourceVersionByConvention`` - :ref:`parseResourceVersion ` - :ref:`addResourceVersion ` @@ -1061,4 +1067,5 @@ Controller .. _RSC: http://developer.yahoo.com/cocktails/mojito/api/classes/ResourceStore.server.html .. |YUIPlugin| replace:: YUI Plugin .. _YUIPlugin: http://yuilibrary.com/yui/docs/plugin/ - \ No newline at end of file +.. |SS| replace:: server.store.js +.. _SS: https://github.com/yahoo/mojito/blob/develop/source/lib/store.server.js \ No newline at end of file From abb2957e128d846fca6dbeaca2314524d76e5471 Mon Sep 17 00:00:00 2001 From: Joe Catera Date: Fri, 13 Jul 2012 17:46:28 -0700 Subject: [PATCH 34/45] Used the Sphinx domain directives for the API docs. --- .../topics/mojito_resource_store.rst | 224 ++-- .../topics/mojito_resource_store.rst.bak | 1041 +++++++++++++++++ 2 files changed, 1138 insertions(+), 127 deletions(-) create mode 100644 docs/dev_guide/topics/mojito_resource_store.rst.bak diff --git a/docs/dev_guide/topics/mojito_resource_store.rst b/docs/dev_guide/topics/mojito_resource_store.rst index 8f7935864..af2e078a4 100644 --- a/docs/dev_guide/topics/mojito_resource_store.rst +++ b/docs/dev_guide/topics/mojito_resource_store.rst @@ -213,7 +213,7 @@ Metadata Object .. admonition:: Note About Default Values - Some values for the properties of the metata object do have defaults, but it depends on + Some values for the properties of the metadata object do have defaults, but it depends on the value of the ``type`` property and/or comes from the file name of the resource being represented. For example, the affinity of views is ``common`` (because views are used on both client and server); however, the affinity for controllers comes @@ -605,22 +605,20 @@ Requirements Because the ``selector`` addon is used directly by the the resource store, all implementations need to provide the following method: -- ``getListFromContext(ctx)`` +- :js:func:`getListFromContext` -.. _selector-getListFromContext: +.. _selector-methods: -getListFromContext(ctx) -``````````````````````` - -Returns the priority-ordered selector list (POSL) for the context. +Methods +``````` -**Parameters:** +.. js:function:: getListFromContext(ctx) -- ``ctx `` - The context that the application is running in. + Returns the priority-ordered selector list (POSL) for the context. -**Return:** + :param String ctx: The context that the application is running in. + :returns: Array -```` .. _selector-ex: @@ -660,10 +658,9 @@ Requirements The ``selector`` addon is required to have the following methods (see details for the methods in below sections): -- ``getPathForURL(url)`` -- ``getSpecURL(id)`` -- ``getURLPaths()`` -- +- :js:func:`getPathForURL` +- :js:func:`getSpecURL` +- :js:func:`getURLPaths` Your addon will also be required to do the following: @@ -673,48 +670,35 @@ Your addon will also be required to do the following: ``onHostEvent('getMojitTypeDetails')``; ``assetsRoot`` is the common prefix for all assets in the mojit. The built-in addon makes something like ``/static/Foo/assets`` for the ``Foo`` mojit. -.. _url-getPathForURL: - -getPathForURL(url) -`````````````````` -This method is called by the static handler middleware. Returns the full filesystem path for the -URL. - -**Parameters:** - -- ``url `` - The URL that was previously generated. +.. _url-methods: -**Return:** - -```` - -.. _url-getSpecURL: - -getSpecURL(id) -`````````````` -Returns the URL for the spec. +Methods +``````` -**Parameters:** +.. js:function:: getPathForURL(url) -- ``id `` - the spec ID. + This method is called by the static handler middleware. Returns the full filesystem path + for the URL. + + :param String url: The URL that was previously generated. + :returns: String -**Return:** -```` +.. js:function:: getSpecURL(id) -.. _url-getURLPaths: + Returns the URL for the spec. + + :param String id: The spec ID. + :returns: String -getURLPaths() -````````````` -Returns an object whose keys are all URLs and whose values are the corresponding filesystem paths. -**Parameters:** +.. js:function:: getURLPaths() -None. + Returns an object whose keys are all URLs and whose values are the corresponding filesystem + paths. -**Return:** + :returns: Object -```` .. _url-ex: @@ -753,105 +737,91 @@ Key Methods .. _key_methods-initialize: -initialize(config) -`````````````````` +.. js:function:: initialize(config) -**Parameters:** - -- ``config `` - contains the following: - - ``host `` - contains the resource store. - - ``appRoot `` - the directory of the application. - - ``mojitoRoot `` - the directory of the Mojito framework code. + Sets the paths to find the application, mojito, and |RS| files. Within the ``preload`` method, + the following host methods are called: + + - :js:func:`preloadResourceVersions` + - :js:func:`resolveResourceVersions` + + After ``preload`` has finished executing, you can hook in with + ``afterHostMethod('preload', ...)``. + + :param Object config: Contains configuration information with the following properties: + + - .. js:attribute:: config.host + + (*Object*) -- contains the resource store. + - .. js:attribute:: config.appRoot + + (*String*) -- contains the the directory of the application. + + - .. js:attribute:: config.mojitoRoot + + (*String*) -- contains the directory of the Mojito framework code. + :returns: None -.. _key_methods-preload: - -preload() -````````` - -Addons are loaded during this method, so it's not possible to hook in before ``preload`` is -called. - -Within the ``preload`` method, the following host methods are called: +.. js:function:: preload() -- :ref:`preloadResourceVersions ` -- :ref:`resolveResourceVersions ` + Addons are loaded during this method, so it's not possible to hook in before ``preload`` + is called. -After ``preload`` has finished executing, you can hook in -with ``afterHostMethod('preload', ...)``. -.. _key_methods-preloadResourceVersions: +.. js:function:: preloadResourceVersions() -preloadResourceVersions() -````````````````````````` - -The |RS| walks the filesystem in this method. Before ``preloadResourceVersions`` is called, not -much is known, though the static application configuration is available using the -method ``getStaticAppConfig``. - -Within the ``preloadResourceVersions`` method, the following host methods are called: - -- ``findResourceVersionByConvention`` -- :ref:`parseResourceVersion ` -- :ref:`addResourceVersion ` - -After ``preloadResourceVersions`` has been called: - - All the resource versions have been loaded and are available through the method - ``getResourceVersions``. - - The |RS| has ``selectors`` object whose keys are all selectors in the application. - The values for the keys are just ``true``. - - -.. _key_methods-findResourceVersionByConvention: - -findResourceVersionByConvention() -````````````````````````````````` - -This method is called on each directory or file being walked and is used to decide if the -path is a resource version. The return value can be a bit confusing, so read API docs carefully -and feel free to post any questions that you have to the -`Yahoo! Mojito Forum `_. - -Typically, you would hook into this method with the ``afterHostMethod()`` method to register your -own resource version types. This method should work together with your -own version of the ``parseResourceVersion`` method. + The |RS| walks the filesystem in this method. Before ``preloadResourceVersions`` is called, + not much is known, though the static application configuration is available using the + method ``getStaticAppConfig``. -.. _key_methods-parseResourceVersion: - -parseResourceVersion() -`````````````````````` + Within the ``preloadResourceVersions`` method, the following host methods are called: + + - ``findResourceVersionByConvention`` + - :ref:`parseResourceVersion ` + - :ref:`addResourceVersion ` + + After ``preloadResourceVersions`` has been called: + + - All the resource versions have been loaded and are available through the method + ``getResourceVersions``. + - The |RS| has ``selectors`` object whose keys are all selectors in the application. + The values for the keys are just ``true``. -This method creates an actual resource version. -Typically, you would hook into this method with the `beforeHostMethod()` method to create -your own resource versions. This should work together with your own version -of the ``findResourceVersionByConvention`` method. +.. js:function:: findResourceVersionByConvention() -.. _key_methods-addResourceVersion: + This method is called on each directory or file being walked and is used to decide if the + path is a resource version. The return value can be a bit confusing, so read API docs carefully + and feel free to post any questions that you have to the + `Yahoo! Mojito Forum `_. -addResourceVersion() -```````````````````` + Typically, you would hook into this method with the ``afterHostMethod()`` method to register + your own resource version types. This method should work together with your + own version of the ``parseResourceVersion`` method. + +.. js:function:: parseResourceVersion() -This method is called to save the resource version into the |RS|. -Typically, if you want to modify/augment an existing resource version, hook into this with the -``beforeHostMethod`` method. + This method creates an actual resource version. Typically, you would hook into this method + with the ``beforeHostMethod`` method to create your own resource versions. This should work + together with your own version of the :js:func:`findResourceVersionByConvention` method. +.. js:function:: addResourceVersion() -.. _key_methods-resolveResourceVersions: + This method is called to save the resource version into the |RS|. Typically, if you want to + modify/augment an existing resource version, hook into this with the + ``beforeHostMethod`` method. -resolveResourceVersions() -````````````````````````` -This method resolves the resource versions into resources. -As a resource version is resolved, the ``mojitResourcesResolved`` event is called -After the method has been executed, all resource versions have been resolved. - -.. _key_methods-serializeClientStore: +.. js:function:: resolveResourceVersions() -serializeClientStore() -`````````````````````` + This method resolves the resource versions into resources. As a resource version is resolved, + the ``mojitResourcesResolved`` event is called. After the method has been executed, all + resource versions have been resolved. + +.. js:function:: serializeClientStore() -This method is called during runtime as Mojito creates the configuration for the client-side -Mojito. + This method is called during runtime as Mojito creates the configuration for the client-side + Mojito. .. _anatomy-key_events: diff --git a/docs/dev_guide/topics/mojito_resource_store.rst.bak b/docs/dev_guide/topics/mojito_resource_store.rst.bak new file mode 100644 index 000000000..541a181c0 --- /dev/null +++ b/docs/dev_guide/topics/mojito_resource_store.rst.bak @@ -0,0 +1,1041 @@ +============== +Resource Store +============== + +.. _rs-intro: + +Overview +======== + +The Resource Store (RS) is the Mojito subsystem that manages metadata about the files in your +Mojito applications. Thus, it is responsible for finding and classifying code and configuration +files. When you start a Mojito application, Mojito can find, track, and resolve versions of files +in your application, such as mojits, configuration files, binders, views, assets, addons, etc., +because of the |RS|. + + +.. _intro-who: + +Who Needs to Know About the Resource Store? +------------------------------------------- + +Most Mojito application developers will not need to know much about the resource store, but +advanced Mojito application developers who want to have finer grain control over the management +of resources or extend the functionality of the resource store should read this documentation. + + +.. _intro-use: + +How Can the Resource Store Help Developers? +------------------------------------------- + +You can write custom |RS| addons to use the aspect-oriented features of +the resource store to create resource types and to map contexts to selectors. + +For example, you could write your own |RS| addon so that the Mojito command-line +tool will create files and resources for your application. The Mojito command-line +tool uses the |RS| for all the commands except ``start``. + +You can also write custom versions of built-in |RS| addons to modify how the resource store works. +Your custom addon could track new file types, augment the information that the |RS| stores about +files or code, or augment/replace the information returned by the |RS|. + + +.. _rs-resources: + +Resources +========= + +.. _resources-what: + +What is a Resource? +------------------- + +In Mojito, the meaning of the term **resource** is different depending on the context. +Before we discuss the |RS| in more detail, let's differentiate and define the definition of +**resource** in the contexts of Mojito and the |RS|. + +.. _what-to_mojito: + +To Mojito +######### + +The Mojito framework primarily views a **resource** as something useful found on the filesystem. + +.. _what-to_rs: + +To the Resource Store +##################### + +The |RS| primarily cares about the *metadata* about each resource, so it sees the +metadata as the *resource*. To the |RS|, the **resource** is just a JavaScript object containing +metadata. The |RS| defines certain keys with specific meanings. The |RS| addons +can add, remove, or modify those keys/values as they see fit. For +example, the yui |RS| addon adds the ``yui`` key with metadata +about resources that are YUI modules. The |RS| itself doesn't populate +the ``yui`` key of each resource. + + +.. _resources-versions: + +Resource Versions +----------------- + +Because there can be multiple files which are all conceptually different versions of the +same thing (e.g., ``views/index.mu.html`` and ``views/index.iphone.mu.html``), the |RS| defines +**resource version** as the metadata about each file and **resource** as the metadata +about the file chosen among the possible choices. + +The process of choosing which version of a resource to use is called *resolution* (or +"resolving the resource"). This act is one of the primary responsibilities of the |RS|. + +See :ref:`Resolution and Priorities ` to learn how the |RS| resolves +different versions of the same resource. + +.. _resources-scope: + +Resource Scope +-------------- + +.. _scope-application: + +Application-Level Resources +########################### + +Application-level resources are truly global to the application. +At the application level, resources include archetypes, commands, configuration files, and +middleware. + + +.. _scope-mojit: + +Mojit-Level Resources +##################### + +At the mojit level, resources include controllers, models, binders, configuration files, and views. +These resources are limited in scope to a mojit. + +.. _scope-shared: + +Shared Resources +################ + +Some resources (and resource versions) are *shared*, meaning that they are included in **all** +mojits. Most resource types that are mojit level can also be shared. Examples of mojit-level +resource types that can't be shared are controllers, configuration files (such as +``definition.json``), and YUI language bundles. + +.. _resources-types: + +Resource Types +-------------- + +The resource type is defined by the ``type`` property in the metadata for a given resource. +See :ref:`Types of Resources ` for descriptions of the resource +types. Developers can also create their own types of resources to fit the need of their +applications. + + + +.. _rs-metadata: + +Resource Metadata +================= + +.. _metadata-intro: + +Intro +----- + +The resource store uses metadata to find, load, parse, and create instances of resources. The +resource metadata is generated by code--it has no representation on the filesystem. The metadata +is generated by the |RS| or by |RS| addons. + + +.. _metadata-obj: + +Metadata Object +--------------- + + + ++------------------------+---------------+-----------+---------------------+------------------------------+---------------------------------------------+ +| Property | Data Type | Required? | Default Value | Possible Values | Description | ++========================+===============+===========+=====================+==============================+=============================================+ +| ``type`` | string | yes | none | See :ref:`Types of Resources | Specifies the type of resource. | +| | | | | `. | | ++------------------------+---------------+-----------+---------------------+------------------------------+---------------------------------------------+ +| ``subtype`` | string | no | none | ``action``, ``binder``, | Some resource types have multiple subtypes | +| | | | | ``command``, ``middleware`` | that can be specified with ``subtype``. See | +| | | | | ``model``, ``view`` | :ref:`Subtypes ` for | +| | | | | | more information. | ++------------------------+---------------+-----------+---------------------+------------------------------+---------------------------------------------+ +| ``name`` | string | yes | none | N/A | The name of the resource that is common to | +| | | | | | all versions (i.e., iPhone/Android, etc.) | +| | | | | | of the resource. Example: the name for | +| | | | | | for the resources ``index.iphone.mu.html`` | +| | | | | | and ``index.mu.html`` is ``index``. | ++------------------------+---------------+-----------+---------------------+------------------------------+---------------------------------------------+ +| ``id`` | string | yes | none | N/A | A unique ID that is common to all versions | +| | | | | | of the resource. The ``id`` has the | +| | | | | | following syntax convention: | +| | | | | | ``{type}-{subtype}-{name}`` | ++------------------------+---------------+-----------+---------------------+------------------------------+---------------------------------------------+ +| ``mojit`` | string | no | none | N/A | The mojit, if any, that uses this resource | +| | | | | | The value ``"shared"`` means the resource | +| | | | | | is available to all mojits. | ++------------------------+---------------+-----------+---------------------+------------------------------+---------------------------------------------+ +| ``affinity`` | string | yes | See :ref:`Note | ``server``, ``client``, | The affinity of the resource, which | +| | | | About Default | ``common`` | indicates where the resource will be used. | +| | | | Values `. | | | ++------------------------+---------------+-----------+---------------------+------------------------------+---------------------------------------------+ +| ``selector`` | string | no | "*" | N/A | The version of the resource, not to be | +| | | | | | confused revisions that mark the change of | +| | | | | | the resource over time. For example, a | +| | | | | | resource could have a version for iPhones, | +| | | | | | Android devices, fallbacks, etc. | ++------------------------+---------------+-----------+---------------------+------------------------------+---------------------------------------------+ +| ``source`` | object | yes | none | N/A | Specifies where the resource came from | +| | | | | | (not shipped to client). See :ref:`source | +| | | | | | Object ` for details. | ++------------------------+---------------+-----------+---------------------+------------------------------+---------------------------------------------+ +| ``url`` | string | no | none | N/A | The path used to load the resource | +| | | | | | onto the client. Used only for resources | +| | | | | | that can be deployed by reference to the | +| | | | | | client. | ++------------------------+---------------+-----------+---------------------+------------------------------+---------------------------------------------+ +| ``yui`` | object | no | none | N/A | The metadata about YUI modules. See the | +| | | | | | :ref:`yui Object ` for more | +| | | | | | details. | ++------------------------+---------------+-----------+---------------------+------------------------------+---------------------------------------------+ + +.. _def_vals: + +.. admonition:: Note About Default Values + + Some values for the properties of the metata object do have defaults, but it depends on + the value of the ``type`` property and/or comes from the file name of the resource being + represented. For example, the affinity of views is ``common`` (because views are used + on both client and server); however, the affinity for controllers comes + from the file name. + +.. _src_obj: + +source Object +############# + ++------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ +| Property | Data Type | Required? | Default Value | Possible Values | Description | ++========================+===============+===========+===============+===============================+=============================================+ +| ``fs`` | string | yes | none | N/A | See :ref:`fs Object `. | ++------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ +| ``pkg`` | array | yes | none | N/A | See :ref:`pkg Object `. | ++------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ + +.. _fs_obj: + +fs Object +````````` + ++------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ +| Property | Data Type | Required? | Default Value | Possible Values | Description | ++========================+===============+===========+===============+===============================+=============================================+ +| ``basename`` | string | yes | none | N/A | | ++------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ +| ``ext`` | string | yes | none | N/A | | ++------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ +| ``fullPath`` | string | yes | none | N/A | | ++------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ +| ``isFile`` | boolean | yes | none | N/A | | ++------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ +| ``fullPath`` | string | yes | none | N/A | | ++------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ +| ``rootDir`` | string | yes | none | N/A | | ++------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ +| ``rootType`` | string | yes | none | See :ref:`Types of Resources | | +| | | | | `. | | ++------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ +| ``subDir`` | string | yes | none | N/A | | ++------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ +| ``subDirArray`` | array | yes | none | N/A | | ++------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ + + +.. _pkg_obj: + +pkg Object +`````````` + ++------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ +| Property | Data Type | Required? | Default Value | Possible Values | Description | ++========================+===============+===========+===============+===============================+=============================================+ +| ``depth`` | number | yes | none | N/A | | ++------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ +| ``name`` | string | yes | none | N/A | | ++------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ +| ``version`` | string | yes | none | N/A | | ++------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ + + + +.. _yui_obj: + +yui Object +########## + +The ``yui`` property of the metadata object is created by the ``yui`` |RS| addon. The +``yui`` property can be any data type, but in general, it is an object +containing metadata about YUI modules. The following table lists the typical properties that are +part of the ``yui`` object. You can think of the ``yui`` object as a container for the arguments to +the ``YUI.add`` method that is used to register reusable YUI modules. + ++------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ +| Property | Data Type | Required? | Default Value | Example Values | Description | ++========================+===============+===========+===============+===============================+=============================================+ +| ``name`` | string | yes | none | ``"scroll"`` | The name of the YUI module. | ++------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ +| ``meta.requires`` | array | yes | none | ``["scroll","node","cache"]`` | Contains a list of YUI modules required by | +| | | | | | this resource. | ++------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ + + +.. _metadata-types: + +Types of Resources +------------------ + +The ``type`` property of the metadata object can have any of the following values: + +- ``config`` - a piece of configuration, sometimes for another resource +- ``controller`` - the controller for a mojit +- ``model`` - a model for a mojit +- ``view`` - a view for a mojit +- ``binder`` - a binder for a mojit +- ``action`` - an action to augment the controller +- ``asset`` - an asset (css, js, image, etc.) +- ``addon`` - an addon to the mojito system +- ``spec`` - the configuration for a mojit instance +- ``yui-lang`` - a YUI 3 language bundle +- ``yui-module`` - a YUI 3 module (that isn't one of the above) + +.. _types-subtypes: + +Subtypes +######## + +You can use a subtype to specify types of a ``type``. For example, a +resource of ``type:addon`` might have subtypes, such as ``subtype:ac`` for AC addons, +``subtype:view-engine`` for view engines, or ``subtype:rs`` for |RS| addons. + +For ``type:archetype``, the subtypes refers to the ``type`` described in the output from +the command ``mojito help create``. So, you could have ``subtype:app``, ``subtype:project``, or +``subtype:mojit``. (There may be more in the future!) + +.. _metatdata-versions: + +Resource Versions +----------------- + +Resources can have many versions that are identified by the ``selector`` property of the +metadata object. The selector is defined by the user and indicates the version of the resource. +For example, developer might decide to use the selector ``selector: iphone`` for the iPhone version +and ``selector: android`` for the Android version of a resource. Using these two selectors, you +could have the following two versions of the ``index`` resource of type ``view``: + +- ``index.iphone.mu.html`` +- ``index.android.mu.html`` + + +.. _metadata-ex: + +Example +------- + + +.. code-block:: javascript + + { + "source": { + "fs": { + "fullPath": "/Users/folta/work/yahoo/mojito/github-drewfish/examples/getting-started-guide/part4/paged-yql/mojits/PagedFlickr/views/index.mu.html", + "rootDir": "/Users/folta/work/yahoo/mojito/github-drewfish/examples/getting-started-guide/part4/paged-yql/mojits/PagedFlickr", + "rootType": "mojit", + "subDir": ".", + "subDirArray": [], + "isFile": true, + "ext": ".html", + "basename": "index.mu" + }, + "pkg": { + "name": "paged-yql", + "version": "0.1.0", + "depth": 0 + } + }, + "type": "view", + "name": "index", + "id": "view--index", + "mojit": "PagedFlickr", + "affinity": "common", + "selector": "iphone", + "viewOutputFormat": "html", + "viewEngine": "mu", + "url": "/static/PagedFlickr/views/index.mu.html" + } + + +.. _rs-how: + +How Does the Resource Store Work? +================================= + +Understanding the workflow of the resource store will give help those who want to customize addons +to write code and others who don't plan on customizing addons to debug. + +Overview +-------- + +In short, the resource store walks through the application-level, +mojit-level, and ``npm`` module files (in that order) of a Mojito application, determines what type +of resource each file is, creates metadata about the resource, and then registers the resource. + +During this process, the resource store also does the following: + +- pre-calculates ("resolving") which resource versions are used for each version of the mojit. +- keeps track of application-level resources (archetypes, commands, config files, and middleware). +- provides methods for events, including those specialized for + `aspect-orient programming (AOP) `_. +- explicitly uses the addons :ref:`selector ` and :ref:`config `. + +In the following sections, we'll look at the process in a little more details. To see the code for +the resource store, see the |SS|_ file. + +.. _how-walk_fs: + +Walking the Filesystem +---------------------- + +Resource versions are discovered by the |RS| at server-start time. The |RS| method ``preload`` +first walks all the files in the application, excluding the ``node_modules`` directory. Next, all +the files in the packages in ``node_modules`` are walked. The packages are walked in breadth-first +fashion, so that *shallower* packages have precedence over *deeper* ones. (Not all the packages +are used: only those that have declared themselves as extensions to Mojito.) Finally, +if Mojito wasn't found in ``node_modules``, the globally-installed version of Mojito is walked. + +After all that, the |RS| knows about all the resource versions. Then it resolves those versions +into the resources as described in :ref:`Resolution and Priorities `. + +.. _how-resolution: + +Resolution and Priorities +------------------------- + +The resolving of resource version happens in the |RS| ``preload`` method as well. +The act of resolving the resource versions is really just resolving the affinities and selectors. +See :ref:`Resource Versions ` for a brief explanation about how affinities +and selectors determine different versions of a resource. + +.. _resolution-selectors: + +Selectors +######### + +The order of the selectors is defined by a **priority-ordered selector list (POSL)**. The POSL +depends on the runtime context. + +Suppose an application has the following resources: + +- ``controller.common.js`` +- ``controller.common.iphone.js`` +- ``controller.server.js`` +- ``controller.server.phone.js`` + +In this application, the POSL for context ``{device:browser}`` might +be ``['*']``, but the POSL for the context ``{device:iphone}`` might be ``['iphone','*']``. +We need to use a (prioritized) list of selectors instead of just a "selector that matches the +context" because not all versions might exist for all selectors. In the example above, if +``controller.server.iphone.js`` didn't exist, we should still do the right thing for context +``{device:iphone}``. + +.. _resolution-affinities: + +Affinities +########## + +The choice of a resource version depends on the **affinity** as well. If we're resolving versions +for the server, versions with ``affinity:server`` will have higher priority than +``affinity:common``, and ``affinity:client`` will be completely ignored. + +.. _resolution-sources: + +Sources +####### + +The final consideration for priority is the **source**. Mojit-level versions have higher priority +than shared versions. Let's take a different application with the following resources: + +- ``mojits/Foo/models/bar.common.js`` +- ``models/bar.common.js`` + +In this application, the second resource is shared with all mojits. The mojit ``Foo``, however, has +defined its own version of the same resource (``id: model--bar``), and so that should have higher +priority than the shared one. + +.. _resolution-relationships: + +Relationships +############# + +Finally, there's a **relationship** between the different types of priority. + +#. The source has the highest priority. +#. The selector has the next highest priority. +#. The affinity has the least highest priority. + +That means that if there exists, for example, both a ``controller.server.js`` and +``controller.common.iphone.js``, for the server and context ``{device:iphone}``, the second version +will be used because its selector is a higher priority match than its affinity. + + +All this is pre-calculated for each resource, for each possible runtime configuration (client or +server, and every possible runtime context). + +.. _how-get_data: + +Getting Data from the Resource Store +------------------------------------ + +Besides the standard ways that Mojito uses the resource store, there are two generic methods for +getting resources and resource versions from the |RS|. + +- ``getResourceVersions(filter)`` +- ``getResources(env, ctx, filter)`` + +The APIs are intentionally similar. Both return an array of resources, and the ``filter`` argument +can be used to restrict the returned resources (or versions). The ``filter`` is an object +whose keys and values must match the returned resources (or versions). Think of it as a *template* +or *partial resource* that all resources must match. For example, a filter of ``{type:'view'}`` +will return all the views. + +For mojit-level resources or resource versions, specify the mojit name in the filter. For example, +filter ``{mojit:'Foo'}`` will return all resources (or versions) in the ``Foo`` mojit. + +.. note:: Because of the resolution process, the resources returned for filter ``{mojit:'Foo'}`` + might contain shared resources. + +To get mojit-level resources (or versions) from multiple mojits, you'll have to call +the method ``getResourceVersions`` or ``getResources`` for each mojit. You can call +``listAllMojits`` to get a list of all mojits. + + +.. _rs-addons: + +Resource Store Built-In Addons +============================== + +.. _addons-intro: + +Intro +----- + +Mojito comes with built-in resource store addons that are used by the |RS| +and the Mojito framework. These resource store addons are required by the |RS| and +the Mojito framework. Thus, particular care must be taken when creating custom versions +of them. + +The |RS| comes with the following four built-in addons: + +- ``config`` + - registers new resource type ``config`` found in JSON configuration files + - provides an API for reading both context and straight-JSON files + - provides sugar for reading the application's dimensions +- ``selector`` + - decides the priority-ordered list (POSL) to use for a context + - looks (default implementation) for ``selector`` in ``application.json``. Because + ``application.json`` is a context configuration file, the ``selector`` can be contextualized + there. +- ``url`` + - calculates the static handler URL for appropriate resources (and resource versions) + - stores the URL in the ``url`` key of the resource + - calculates the asset URL base for each mojit +- ``yui`` + - registers new resource type ``yui-module`` found in the directories ``autoload`` + or ``yui_modules`` + - registers new resource type ``yui-lang`` found in the ``lang`` directory + - calculates the ``yui`` metadata for resource versions that are YUI modules + - pre-calculates corresponding YUI module dependencies when resources are resolved + for each version of each mojit + - appends the pre-calculated YUI module dependencies for the controller and binders when + Mojito queries the |RS| for the details of a mojit (``getMojitTypeDetails`` method) + - provides methods used by Mojito to configure its YUI instances + + +.. _addons-custom: + +Creating Custom Versions of Built-In |RS| Addons +------------------------------------------------ + +We will be examining the ``selector`` and ``url`` addons to help you create custom versions of +those addons. We do not recommend that you create custom versions of the +``config`` or ``yui`` addons, so we will not be looking at those addons. Also, this documentation +explains what the |RS| expects the addon to do, so you can create your own version of the addons. +To learn what a |RS| built-in addons do, please refer to the |RSC|_ in the API documentation. + + +.. _custom-selector: + +selector +######## + +.. _selector-desc: + +Description +``````````` + +If you wish to use a different algorithm for to determine the selectors to use, +you can implement your own version of this |RS| addon. It will need to go in the file +``addons/rs/selector.server.js`` of your application. + + +.. _selector-reqs: + +Requirements +```````````` + +Because the ``selector`` addon is used directly by the the resource store, all implementations +need to provide the following method: + +- :js:func:`getListFromContext` + +.. _selector-methods: + +Methods +``````` + +.. js:function:: getListFromContext(ctx) + + Returns the priority-ordered selector list (POSL) for the context. + + :param String ctx: The context that the application is running in. + :returns: Array + + +.. _selector-ex: + +Example +``````` + +.. _url-intro: + +url +### + +.. _url-desc: + +Description +``````````` + +The ``url`` addon calculates and manages the static handler URLs for resources. +The addon is not used by resource store core, but used by the static handler middleware. + +If you wish to use a different algorithm to determine the URLs, you can +implement your own version of this |RS| addon. It'll need to go in +``addons/rs/url.server.js`` in your application. + +After the method ``preloadResourceVersions`` sets ``res.url`` to the static handler URL +for the resource, the method ``getMojitTypeDetails`` sets the mojit's ``assetsRoot``. +The static handler URL can be a rollup URL. + +The ``url`` addon also provides a method for the static handler middleware to find the +filesystem path for a URL. + + +.. _url-reqs: + +Requirements +```````````` + +The ``selector`` addon is required to have the following methods (see details for the methods in +below sections): + +- :js:func:`getPathForURL` +- :js:func:`getSpecURL` +- :js:func:`getURLPaths` + +Your addon will also be required to do the following: + +- Add the ``url`` metadatum to resource versions; this is where your addon will set the calculated + value (using ``beforeHostMethod('addResourceVersion')``). +- Add ``assetsRoot`` to the results of the method ``getMojitTypeDetails`, which is done with + ``onHostEvent('getMojitTypeDetails')``; ``assetsRoot`` is the common prefix for all assets in the + mojit. The built-in addon makes something like ``/static/Foo/assets`` for the ``Foo`` mojit. + +.. _url-methods: + +Methods +``````` + +.. js:function:: getPathForURL(url) + + This method is called by the static handler middleware. Returns the full filesystem path + for the URL. + + :param String url: The URL that was previously generated. + :returns: String + + +.. js:function:: getSpecURL(id) + + Returns the URL for the spec. + + :param String id: The spec ID. + :returns: String + + +.. js:function:: getURLPaths() + + Returns an object whose keys are all URLs and whose values are the corresponding filesystem + paths. + + :returns: Object + + + +.. _url-ex: + +Example +``````` + +.. _rs-creating_rs_addons: + +Creating Your Own Resource Store Addons +======================================= + +.. _creating_rs_addons-intro: + +Intro +----- + +In this section, we will discuss the key methods, events, and give a simple example of a custom +|RS| addon. By using the provided example as a model and referring to the |RSC|_ in the API +documentation, you should be able to create your own custom |RS| addons. + +.. _creating_rs_addons-anatomy: + +Anatomy of a |RS| Addon +----------------------- + +The resource store addons are implemented using the _|YUIPlugin| mechanism. In essence, a Mojito +addon is a YUI plugin, so the skeleton of a |RS| addon will be the same as a YUI Plugin. + +See the |RSC|_ for the parameters and return values for the |RS| methods. + +.. _anatomy-key_methods: + +Key Methods +########### + +.. _key_methods-initialize: + +.. js:function:: initialize(config) + + Sets the paths to find the application, mojito, and |RS| files. Within the ``preload`` method, + the following host methods are called: + + - :js:func:`preloadResourceVersions` + - :js:func:`resolveResourceVersions` + + After ``preload`` has finished executing, you can hook in with + ``afterHostMethod('preload', ...)``. + + :param Object config: Contains configuration information with the following properties: + + - .. js:attribute:: config.host + + (*Object*) -- contains the resource store. + - .. js:attribute:: config.appRoot + + (*String*) -- contains the the directory of the application. + + - .. js:attribute:: config.mojitoRoot + + (*String*) -- contains the directory of the Mojito framework code. + :returns: None + +.. js:function:: preload() + + Addons are loaded during this method, so it's not possible to hook in before ``preload`` + is called. + + +.. js:function:: preloadResourceVersions() + + The |RS| walks the filesystem in this method. Before ``preloadResourceVersions`` is called, + not much is known, though the static application configuration is available using the + method ``getStaticAppConfig``. + + Within the ``preloadResourceVersions`` method, the following host methods are called: + + - ``findResourceVersionByConvention`` + - :ref:`parseResourceVersion ` + - :ref:`addResourceVersion ` + + After ``preloadResourceVersions`` has been called: + + - All the resource versions have been loaded and are available through the method + ``getResourceVersions``. + - The |RS| has ``selectors`` object whose keys are all selectors in the application. + The values for the keys are just ``true``. + + +.. js:function:: findResourceVersionByConvention() + + This method is called on each directory or file being walked and is used to decide if the + path is a resource version. The return value can be a bit confusing, so read API docs carefully + and feel free to post any questions that you have to the + `Yahoo! Mojito Forum `_. + + Typically, you would hook into this method with the ``afterHostMethod()`` method to register + your own resource version types. This method should work together with your + own version of the ``parseResourceVersion`` method. + +.. js:function:: parseResourceVersion() + + This method creates an actual resource version. Typically, you would hook into this method + with the ``beforeHostMethod`` method to create your own resource versions. This should work + together with your own version of the :js:func:`findResourceVersionByConvention` method. + +.. js:function:: addResourceVersion() + + This method is called to save the resource version into the |RS|. Typically, if you want to + modify/augment an existing resource version, hook into this with the + ``beforeHostMethod`` method. + + +.. js:function:: resolveResourceVersions() + + This method resolves the resource versions into resources. As a resource version is resolved, + the ``mojitResourcesResolved`` event is called. After the method has been executed, all + resource versions have been resolved. + +.. js:function:: serializeClientStore() + + This method is called during runtime as Mojito creates the configuration for the client-side + Mojito. + + +.. _anatomy-key_events: + +Key Events +########## + +.. _key_events-mojitResourcesResolved: + +mojitResourcesResolved +`````````````````````` + +This event is called when the resources in a mojit are resolved. + +.. _key_events-getMojitTypeDetails: + +getMojitTypeDetails +``````````````````` + +This event is called during runtime as Mojito creates an "instance" used to dispatch a mojit. + +.. _creating_rs_addons-ex: + +Example +------- + +.. _creating_rs_addons_ex-rs_addon: + +|RS| Addon +########## + +The following |RS| addon registers the new resource type ``text`` for text files. + +``addons/rs/text.server.js`` + +.. code-block:: javascript + + + YUI.add('addon-rs-text', function(Y, NAME) { + + var libpath = require('path'); + + function RSddonText() { + RSAddonText.superclass.constructor.apply(this, arguments); + }, + RSAddonText.NS = 'text'; + RSAddonText.ATT|RS| = {}; + + Y.extend(RSAddonText, Y.Plugin.Base, { + + initializer: function(config) { + this.rs = config.host; + this.appRoot = config.appRoot; + this.mojitoRoot = config.mojitoRoot; + this.afterHostMethod('findResourceVersionByConvention', this.findResourceVersionByConvention, this); + this.beforeHostMethod('parseResourceVersion', this.parseResourceVersion, this); + }, + + destructor: function() { + // TODO: needed to break cycle so we don't leak memory? + this.rs = null; + }, + + /** + * Using AOP, this is called after the ResourceStore's version. + * @method findResourceVersionByConvention + * @param source {object} metadata about where the resource is located + * @param mojitType {string} name of mojit to which the resource likely belongs + * @return {object||null} for config file resources, returns metadata signifying that + */ + findResourceVersionByConvention: function(source, mojitType) { + // We only care about files + if (!source.fs.isFile) { + return; + } + + // We only care about txt files + if ('.txt' !== source.fs.ext) { + return; + } + + return new Y.Do.AlterReturn(null, { + type: 'text' + }); + }, + + /** + * Using AOP, this is called before the ResourceStore's version. + * @method parseResourceVersion + * @param source {object} metadata about where the resource is located + * @param type {string} type of the resource + * @param subtype {string} subtype of the resource + * @param mojitType {string} name of mojit to which the resource likely belongs + * @return {object||null} for config file resources, returns the resource metadata + */ + parseResourceVersion: function(source, type, subtype, mojitType) { + var res; + + if ('text' !== type) { + return; + } + res = { + source: source, + type: 'text', + affinity: 'server', + selector: '*' + }; + if ('app' !== source.fs.rootType) { + res.mojit = mojitType; + } + res.name = libpath.join(source.fs.subDir, source.fs.basename); + res.id = [res.type, res.subtype, res.name].join('-'); + return new Y.Do.Halt(null, res); + } + }); + Y.namespace('mojito.addons.rs'); + Y.mojito.addons.rs.text = |RS|AddonText; + + }, '0.0.1', { requires: ['plugin', 'oop']}); + +.. _creating_rs_addons_ex-text_addon: + +Text Addon +########## + +The Text Addon provides accessors so that the controller can access resources of type ``text``. +You could use this example addon as a model for writing an addon that allows a controller +to access other resource types such as ``xml`` or ``yaml``. + +``addons/ac/text.server.js`` + +.. code-block:: javascript + + + YUI.add('addon-ac-text', function(Y, NAME) { + + var libfs = require('fs'); + + function Addon(command, adapter, ac) { + this._ctx = ac.command.context; + } + Addon.prototype = { + + namespace: 'text', + + setStore: function(store) { + this._store = store; + }, + list: function() { + var r, res, ress, list = []; + ress = this._store.store.getResources('server', this._ctx, {type:'text'}); + for (r = 0; r < ress.length; r += 1) { + res = ress[r]; + list.push(res.name); + } + return list; + }, + read: function(name, cb) { + var ress; + ress = this._store.store.getResources('server', this._ctx, {type:'text', name:name}); + if (!ress || 1 !== ress.length) { + cb(new Error('Unknown text file ' + name)); + } + libfs.readFile(ress[0].source.fs.fullPath, 'utf-8', function(err, body) { + cb(err, body); + }); + } + }; + Y.mojito.addons.ac.text = Addon; + }, '0.1.0', {requires: ['mojito']} + ); + +.. _creating_rs_addons_ex-controller: + +Controller +########## + +``mojits/Viewer/controller.server.js`` + + +.. code-block:: javascript + + YUI.add('Viewer', function(Y, NAME) { + + Y.mojito.controllers[NAME] = { + + init: function(config) { + this.config = config; + }, + + index: function(ac) { + var chosen; // TODO: use form input to choose a text file + if (!chosen) { + var list; + list = ac.text.list(); + chosen = list[0]; + } + ac.assets.addCss('./index.css'); + ac.text.read(chosen, function(err, body) { + if (err) { + return ac.error(err); + } + ac.done({body: body}); + }); + } + }; + }, '1.0.1', {requires: ['mojito', 'addon-ac-text']}); + + + +.. |RS| replace:: Resource Store +.. |RSC| replace:: ResourceStore.server Class +.. _RSC: http://developer.yahoo.com/cocktails/mojito/api/classes/ResourceStore.server.html +.. |YUIPlugin| replace:: YUI Plugin +.. _YUIPlugin: http://yuilibrary.com/yui/docs/plugin/ +.. |SS| replace:: server.store.js +.. _SS: https://github.com/yahoo/mojito/blob/develop/source/lib/store.server.js \ No newline at end of file From dfad6debdc1a264f035d7a81f6f8179ef44f0bea Mon Sep 17 00:00:00 2001 From: Joe Catera Date: Mon, 16 Jul 2012 13:55:52 -0700 Subject: [PATCH 35/45] Modified a method name and added a new method. --- docs/dev_guide/topics/mojito_resource_store.rst.bak | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/dev_guide/topics/mojito_resource_store.rst.bak b/docs/dev_guide/topics/mojito_resource_store.rst.bak index 541a181c0..04ef48486 100644 --- a/docs/dev_guide/topics/mojito_resource_store.rst.bak +++ b/docs/dev_guide/topics/mojito_resource_store.rst.bak @@ -605,14 +605,14 @@ Requirements Because the ``selector`` addon is used directly by the the resource store, all implementations need to provide the following method: -- :js:func:`getListFromContext` +- :js:func:`getPOSLFromContext(ctx)` .. _selector-methods: Methods ``````` -.. js:function:: getListFromContext(ctx) +.. js:function:: getPOSLFromContext(ctx) Returns the priority-ordered selector list (POSL) for the context. @@ -620,6 +620,10 @@ Methods :returns: Array +.. js:function:: getAllPOSLs() + + Returns all POSLs in the application. + .. _selector-ex: Example From 41dc9b04fae586c3fda25962222bf32aa9aaaf24 Mon Sep 17 00:00:00 2001 From: Joe Catera Date: Thu, 26 Jul 2012 09:31:20 -0700 Subject: [PATCH 36/45] Removing backup file. --- .../topics/mojito_resource_store.rst.bak | 1045 ----------------- 1 file changed, 1045 deletions(-) delete mode 100644 docs/dev_guide/topics/mojito_resource_store.rst.bak diff --git a/docs/dev_guide/topics/mojito_resource_store.rst.bak b/docs/dev_guide/topics/mojito_resource_store.rst.bak deleted file mode 100644 index 04ef48486..000000000 --- a/docs/dev_guide/topics/mojito_resource_store.rst.bak +++ /dev/null @@ -1,1045 +0,0 @@ -============== -Resource Store -============== - -.. _rs-intro: - -Overview -======== - -The Resource Store (RS) is the Mojito subsystem that manages metadata about the files in your -Mojito applications. Thus, it is responsible for finding and classifying code and configuration -files. When you start a Mojito application, Mojito can find, track, and resolve versions of files -in your application, such as mojits, configuration files, binders, views, assets, addons, etc., -because of the |RS|. - - -.. _intro-who: - -Who Needs to Know About the Resource Store? -------------------------------------------- - -Most Mojito application developers will not need to know much about the resource store, but -advanced Mojito application developers who want to have finer grain control over the management -of resources or extend the functionality of the resource store should read this documentation. - - -.. _intro-use: - -How Can the Resource Store Help Developers? -------------------------------------------- - -You can write custom |RS| addons to use the aspect-oriented features of -the resource store to create resource types and to map contexts to selectors. - -For example, you could write your own |RS| addon so that the Mojito command-line -tool will create files and resources for your application. The Mojito command-line -tool uses the |RS| for all the commands except ``start``. - -You can also write custom versions of built-in |RS| addons to modify how the resource store works. -Your custom addon could track new file types, augment the information that the |RS| stores about -files or code, or augment/replace the information returned by the |RS|. - - -.. _rs-resources: - -Resources -========= - -.. _resources-what: - -What is a Resource? -------------------- - -In Mojito, the meaning of the term **resource** is different depending on the context. -Before we discuss the |RS| in more detail, let's differentiate and define the definition of -**resource** in the contexts of Mojito and the |RS|. - -.. _what-to_mojito: - -To Mojito -######### - -The Mojito framework primarily views a **resource** as something useful found on the filesystem. - -.. _what-to_rs: - -To the Resource Store -##################### - -The |RS| primarily cares about the *metadata* about each resource, so it sees the -metadata as the *resource*. To the |RS|, the **resource** is just a JavaScript object containing -metadata. The |RS| defines certain keys with specific meanings. The |RS| addons -can add, remove, or modify those keys/values as they see fit. For -example, the yui |RS| addon adds the ``yui`` key with metadata -about resources that are YUI modules. The |RS| itself doesn't populate -the ``yui`` key of each resource. - - -.. _resources-versions: - -Resource Versions ------------------ - -Because there can be multiple files which are all conceptually different versions of the -same thing (e.g., ``views/index.mu.html`` and ``views/index.iphone.mu.html``), the |RS| defines -**resource version** as the metadata about each file and **resource** as the metadata -about the file chosen among the possible choices. - -The process of choosing which version of a resource to use is called *resolution* (or -"resolving the resource"). This act is one of the primary responsibilities of the |RS|. - -See :ref:`Resolution and Priorities ` to learn how the |RS| resolves -different versions of the same resource. - -.. _resources-scope: - -Resource Scope --------------- - -.. _scope-application: - -Application-Level Resources -########################### - -Application-level resources are truly global to the application. -At the application level, resources include archetypes, commands, configuration files, and -middleware. - - -.. _scope-mojit: - -Mojit-Level Resources -##################### - -At the mojit level, resources include controllers, models, binders, configuration files, and views. -These resources are limited in scope to a mojit. - -.. _scope-shared: - -Shared Resources -################ - -Some resources (and resource versions) are *shared*, meaning that they are included in **all** -mojits. Most resource types that are mojit level can also be shared. Examples of mojit-level -resource types that can't be shared are controllers, configuration files (such as -``definition.json``), and YUI language bundles. - -.. _resources-types: - -Resource Types --------------- - -The resource type is defined by the ``type`` property in the metadata for a given resource. -See :ref:`Types of Resources ` for descriptions of the resource -types. Developers can also create their own types of resources to fit the need of their -applications. - - - -.. _rs-metadata: - -Resource Metadata -================= - -.. _metadata-intro: - -Intro ------ - -The resource store uses metadata to find, load, parse, and create instances of resources. The -resource metadata is generated by code--it has no representation on the filesystem. The metadata -is generated by the |RS| or by |RS| addons. - - -.. _metadata-obj: - -Metadata Object ---------------- - - - -+------------------------+---------------+-----------+---------------------+------------------------------+---------------------------------------------+ -| Property | Data Type | Required? | Default Value | Possible Values | Description | -+========================+===============+===========+=====================+==============================+=============================================+ -| ``type`` | string | yes | none | See :ref:`Types of Resources | Specifies the type of resource. | -| | | | | `. | | -+------------------------+---------------+-----------+---------------------+------------------------------+---------------------------------------------+ -| ``subtype`` | string | no | none | ``action``, ``binder``, | Some resource types have multiple subtypes | -| | | | | ``command``, ``middleware`` | that can be specified with ``subtype``. See | -| | | | | ``model``, ``view`` | :ref:`Subtypes ` for | -| | | | | | more information. | -+------------------------+---------------+-----------+---------------------+------------------------------+---------------------------------------------+ -| ``name`` | string | yes | none | N/A | The name of the resource that is common to | -| | | | | | all versions (i.e., iPhone/Android, etc.) | -| | | | | | of the resource. Example: the name for | -| | | | | | for the resources ``index.iphone.mu.html`` | -| | | | | | and ``index.mu.html`` is ``index``. | -+------------------------+---------------+-----------+---------------------+------------------------------+---------------------------------------------+ -| ``id`` | string | yes | none | N/A | A unique ID that is common to all versions | -| | | | | | of the resource. The ``id`` has the | -| | | | | | following syntax convention: | -| | | | | | ``{type}-{subtype}-{name}`` | -+------------------------+---------------+-----------+---------------------+------------------------------+---------------------------------------------+ -| ``mojit`` | string | no | none | N/A | The mojit, if any, that uses this resource | -| | | | | | The value ``"shared"`` means the resource | -| | | | | | is available to all mojits. | -+------------------------+---------------+-----------+---------------------+------------------------------+---------------------------------------------+ -| ``affinity`` | string | yes | See :ref:`Note | ``server``, ``client``, | The affinity of the resource, which | -| | | | About Default | ``common`` | indicates where the resource will be used. | -| | | | Values `. | | | -+------------------------+---------------+-----------+---------------------+------------------------------+---------------------------------------------+ -| ``selector`` | string | no | "*" | N/A | The version of the resource, not to be | -| | | | | | confused revisions that mark the change of | -| | | | | | the resource over time. For example, a | -| | | | | | resource could have a version for iPhones, | -| | | | | | Android devices, fallbacks, etc. | -+------------------------+---------------+-----------+---------------------+------------------------------+---------------------------------------------+ -| ``source`` | object | yes | none | N/A | Specifies where the resource came from | -| | | | | | (not shipped to client). See :ref:`source | -| | | | | | Object ` for details. | -+------------------------+---------------+-----------+---------------------+------------------------------+---------------------------------------------+ -| ``url`` | string | no | none | N/A | The path used to load the resource | -| | | | | | onto the client. Used only for resources | -| | | | | | that can be deployed by reference to the | -| | | | | | client. | -+------------------------+---------------+-----------+---------------------+------------------------------+---------------------------------------------+ -| ``yui`` | object | no | none | N/A | The metadata about YUI modules. See the | -| | | | | | :ref:`yui Object ` for more | -| | | | | | details. | -+------------------------+---------------+-----------+---------------------+------------------------------+---------------------------------------------+ - -.. _def_vals: - -.. admonition:: Note About Default Values - - Some values for the properties of the metata object do have defaults, but it depends on - the value of the ``type`` property and/or comes from the file name of the resource being - represented. For example, the affinity of views is ``common`` (because views are used - on both client and server); however, the affinity for controllers comes - from the file name. - -.. _src_obj: - -source Object -############# - -+------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ -| Property | Data Type | Required? | Default Value | Possible Values | Description | -+========================+===============+===========+===============+===============================+=============================================+ -| ``fs`` | string | yes | none | N/A | See :ref:`fs Object `. | -+------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ -| ``pkg`` | array | yes | none | N/A | See :ref:`pkg Object `. | -+------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ - -.. _fs_obj: - -fs Object -````````` - -+------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ -| Property | Data Type | Required? | Default Value | Possible Values | Description | -+========================+===============+===========+===============+===============================+=============================================+ -| ``basename`` | string | yes | none | N/A | | -+------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ -| ``ext`` | string | yes | none | N/A | | -+------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ -| ``fullPath`` | string | yes | none | N/A | | -+------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ -| ``isFile`` | boolean | yes | none | N/A | | -+------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ -| ``fullPath`` | string | yes | none | N/A | | -+------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ -| ``rootDir`` | string | yes | none | N/A | | -+------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ -| ``rootType`` | string | yes | none | See :ref:`Types of Resources | | -| | | | | `. | | -+------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ -| ``subDir`` | string | yes | none | N/A | | -+------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ -| ``subDirArray`` | array | yes | none | N/A | | -+------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ - - -.. _pkg_obj: - -pkg Object -`````````` - -+------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ -| Property | Data Type | Required? | Default Value | Possible Values | Description | -+========================+===============+===========+===============+===============================+=============================================+ -| ``depth`` | number | yes | none | N/A | | -+------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ -| ``name`` | string | yes | none | N/A | | -+------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ -| ``version`` | string | yes | none | N/A | | -+------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ - - - -.. _yui_obj: - -yui Object -########## - -The ``yui`` property of the metadata object is created by the ``yui`` |RS| addon. The -``yui`` property can be any data type, but in general, it is an object -containing metadata about YUI modules. The following table lists the typical properties that are -part of the ``yui`` object. You can think of the ``yui`` object as a container for the arguments to -the ``YUI.add`` method that is used to register reusable YUI modules. - -+------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ -| Property | Data Type | Required? | Default Value | Example Values | Description | -+========================+===============+===========+===============+===============================+=============================================+ -| ``name`` | string | yes | none | ``"scroll"`` | The name of the YUI module. | -+------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ -| ``meta.requires`` | array | yes | none | ``["scroll","node","cache"]`` | Contains a list of YUI modules required by | -| | | | | | this resource. | -+------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ - - -.. _metadata-types: - -Types of Resources ------------------- - -The ``type`` property of the metadata object can have any of the following values: - -- ``config`` - a piece of configuration, sometimes for another resource -- ``controller`` - the controller for a mojit -- ``model`` - a model for a mojit -- ``view`` - a view for a mojit -- ``binder`` - a binder for a mojit -- ``action`` - an action to augment the controller -- ``asset`` - an asset (css, js, image, etc.) -- ``addon`` - an addon to the mojito system -- ``spec`` - the configuration for a mojit instance -- ``yui-lang`` - a YUI 3 language bundle -- ``yui-module`` - a YUI 3 module (that isn't one of the above) - -.. _types-subtypes: - -Subtypes -######## - -You can use a subtype to specify types of a ``type``. For example, a -resource of ``type:addon`` might have subtypes, such as ``subtype:ac`` for AC addons, -``subtype:view-engine`` for view engines, or ``subtype:rs`` for |RS| addons. - -For ``type:archetype``, the subtypes refers to the ``type`` described in the output from -the command ``mojito help create``. So, you could have ``subtype:app``, ``subtype:project``, or -``subtype:mojit``. (There may be more in the future!) - -.. _metatdata-versions: - -Resource Versions ------------------ - -Resources can have many versions that are identified by the ``selector`` property of the -metadata object. The selector is defined by the user and indicates the version of the resource. -For example, developer might decide to use the selector ``selector: iphone`` for the iPhone version -and ``selector: android`` for the Android version of a resource. Using these two selectors, you -could have the following two versions of the ``index`` resource of type ``view``: - -- ``index.iphone.mu.html`` -- ``index.android.mu.html`` - - -.. _metadata-ex: - -Example -------- - - -.. code-block:: javascript - - { - "source": { - "fs": { - "fullPath": "/Users/folta/work/yahoo/mojito/github-drewfish/examples/getting-started-guide/part4/paged-yql/mojits/PagedFlickr/views/index.mu.html", - "rootDir": "/Users/folta/work/yahoo/mojito/github-drewfish/examples/getting-started-guide/part4/paged-yql/mojits/PagedFlickr", - "rootType": "mojit", - "subDir": ".", - "subDirArray": [], - "isFile": true, - "ext": ".html", - "basename": "index.mu" - }, - "pkg": { - "name": "paged-yql", - "version": "0.1.0", - "depth": 0 - } - }, - "type": "view", - "name": "index", - "id": "view--index", - "mojit": "PagedFlickr", - "affinity": "common", - "selector": "iphone", - "viewOutputFormat": "html", - "viewEngine": "mu", - "url": "/static/PagedFlickr/views/index.mu.html" - } - - -.. _rs-how: - -How Does the Resource Store Work? -================================= - -Understanding the workflow of the resource store will give help those who want to customize addons -to write code and others who don't plan on customizing addons to debug. - -Overview --------- - -In short, the resource store walks through the application-level, -mojit-level, and ``npm`` module files (in that order) of a Mojito application, determines what type -of resource each file is, creates metadata about the resource, and then registers the resource. - -During this process, the resource store also does the following: - -- pre-calculates ("resolving") which resource versions are used for each version of the mojit. -- keeps track of application-level resources (archetypes, commands, config files, and middleware). -- provides methods for events, including those specialized for - `aspect-orient programming (AOP) `_. -- explicitly uses the addons :ref:`selector ` and :ref:`config `. - -In the following sections, we'll look at the process in a little more details. To see the code for -the resource store, see the |SS|_ file. - -.. _how-walk_fs: - -Walking the Filesystem ----------------------- - -Resource versions are discovered by the |RS| at server-start time. The |RS| method ``preload`` -first walks all the files in the application, excluding the ``node_modules`` directory. Next, all -the files in the packages in ``node_modules`` are walked. The packages are walked in breadth-first -fashion, so that *shallower* packages have precedence over *deeper* ones. (Not all the packages -are used: only those that have declared themselves as extensions to Mojito.) Finally, -if Mojito wasn't found in ``node_modules``, the globally-installed version of Mojito is walked. - -After all that, the |RS| knows about all the resource versions. Then it resolves those versions -into the resources as described in :ref:`Resolution and Priorities `. - -.. _how-resolution: - -Resolution and Priorities -------------------------- - -The resolving of resource version happens in the |RS| ``preload`` method as well. -The act of resolving the resource versions is really just resolving the affinities and selectors. -See :ref:`Resource Versions ` for a brief explanation about how affinities -and selectors determine different versions of a resource. - -.. _resolution-selectors: - -Selectors -######### - -The order of the selectors is defined by a **priority-ordered selector list (POSL)**. The POSL -depends on the runtime context. - -Suppose an application has the following resources: - -- ``controller.common.js`` -- ``controller.common.iphone.js`` -- ``controller.server.js`` -- ``controller.server.phone.js`` - -In this application, the POSL for context ``{device:browser}`` might -be ``['*']``, but the POSL for the context ``{device:iphone}`` might be ``['iphone','*']``. -We need to use a (prioritized) list of selectors instead of just a "selector that matches the -context" because not all versions might exist for all selectors. In the example above, if -``controller.server.iphone.js`` didn't exist, we should still do the right thing for context -``{device:iphone}``. - -.. _resolution-affinities: - -Affinities -########## - -The choice of a resource version depends on the **affinity** as well. If we're resolving versions -for the server, versions with ``affinity:server`` will have higher priority than -``affinity:common``, and ``affinity:client`` will be completely ignored. - -.. _resolution-sources: - -Sources -####### - -The final consideration for priority is the **source**. Mojit-level versions have higher priority -than shared versions. Let's take a different application with the following resources: - -- ``mojits/Foo/models/bar.common.js`` -- ``models/bar.common.js`` - -In this application, the second resource is shared with all mojits. The mojit ``Foo``, however, has -defined its own version of the same resource (``id: model--bar``), and so that should have higher -priority than the shared one. - -.. _resolution-relationships: - -Relationships -############# - -Finally, there's a **relationship** between the different types of priority. - -#. The source has the highest priority. -#. The selector has the next highest priority. -#. The affinity has the least highest priority. - -That means that if there exists, for example, both a ``controller.server.js`` and -``controller.common.iphone.js``, for the server and context ``{device:iphone}``, the second version -will be used because its selector is a higher priority match than its affinity. - - -All this is pre-calculated for each resource, for each possible runtime configuration (client or -server, and every possible runtime context). - -.. _how-get_data: - -Getting Data from the Resource Store ------------------------------------- - -Besides the standard ways that Mojito uses the resource store, there are two generic methods for -getting resources and resource versions from the |RS|. - -- ``getResourceVersions(filter)`` -- ``getResources(env, ctx, filter)`` - -The APIs are intentionally similar. Both return an array of resources, and the ``filter`` argument -can be used to restrict the returned resources (or versions). The ``filter`` is an object -whose keys and values must match the returned resources (or versions). Think of it as a *template* -or *partial resource* that all resources must match. For example, a filter of ``{type:'view'}`` -will return all the views. - -For mojit-level resources or resource versions, specify the mojit name in the filter. For example, -filter ``{mojit:'Foo'}`` will return all resources (or versions) in the ``Foo`` mojit. - -.. note:: Because of the resolution process, the resources returned for filter ``{mojit:'Foo'}`` - might contain shared resources. - -To get mojit-level resources (or versions) from multiple mojits, you'll have to call -the method ``getResourceVersions`` or ``getResources`` for each mojit. You can call -``listAllMojits`` to get a list of all mojits. - - -.. _rs-addons: - -Resource Store Built-In Addons -============================== - -.. _addons-intro: - -Intro ------ - -Mojito comes with built-in resource store addons that are used by the |RS| -and the Mojito framework. These resource store addons are required by the |RS| and -the Mojito framework. Thus, particular care must be taken when creating custom versions -of them. - -The |RS| comes with the following four built-in addons: - -- ``config`` - - registers new resource type ``config`` found in JSON configuration files - - provides an API for reading both context and straight-JSON files - - provides sugar for reading the application's dimensions -- ``selector`` - - decides the priority-ordered list (POSL) to use for a context - - looks (default implementation) for ``selector`` in ``application.json``. Because - ``application.json`` is a context configuration file, the ``selector`` can be contextualized - there. -- ``url`` - - calculates the static handler URL for appropriate resources (and resource versions) - - stores the URL in the ``url`` key of the resource - - calculates the asset URL base for each mojit -- ``yui`` - - registers new resource type ``yui-module`` found in the directories ``autoload`` - or ``yui_modules`` - - registers new resource type ``yui-lang`` found in the ``lang`` directory - - calculates the ``yui`` metadata for resource versions that are YUI modules - - pre-calculates corresponding YUI module dependencies when resources are resolved - for each version of each mojit - - appends the pre-calculated YUI module dependencies for the controller and binders when - Mojito queries the |RS| for the details of a mojit (``getMojitTypeDetails`` method) - - provides methods used by Mojito to configure its YUI instances - - -.. _addons-custom: - -Creating Custom Versions of Built-In |RS| Addons ------------------------------------------------- - -We will be examining the ``selector`` and ``url`` addons to help you create custom versions of -those addons. We do not recommend that you create custom versions of the -``config`` or ``yui`` addons, so we will not be looking at those addons. Also, this documentation -explains what the |RS| expects the addon to do, so you can create your own version of the addons. -To learn what a |RS| built-in addons do, please refer to the |RSC|_ in the API documentation. - - -.. _custom-selector: - -selector -######## - -.. _selector-desc: - -Description -``````````` - -If you wish to use a different algorithm for to determine the selectors to use, -you can implement your own version of this |RS| addon. It will need to go in the file -``addons/rs/selector.server.js`` of your application. - - -.. _selector-reqs: - -Requirements -```````````` - -Because the ``selector`` addon is used directly by the the resource store, all implementations -need to provide the following method: - -- :js:func:`getPOSLFromContext(ctx)` - -.. _selector-methods: - -Methods -``````` - -.. js:function:: getPOSLFromContext(ctx) - - Returns the priority-ordered selector list (POSL) for the context. - - :param String ctx: The context that the application is running in. - :returns: Array - - -.. js:function:: getAllPOSLs() - - Returns all POSLs in the application. - -.. _selector-ex: - -Example -``````` - -.. _url-intro: - -url -### - -.. _url-desc: - -Description -``````````` - -The ``url`` addon calculates and manages the static handler URLs for resources. -The addon is not used by resource store core, but used by the static handler middleware. - -If you wish to use a different algorithm to determine the URLs, you can -implement your own version of this |RS| addon. It'll need to go in -``addons/rs/url.server.js`` in your application. - -After the method ``preloadResourceVersions`` sets ``res.url`` to the static handler URL -for the resource, the method ``getMojitTypeDetails`` sets the mojit's ``assetsRoot``. -The static handler URL can be a rollup URL. - -The ``url`` addon also provides a method for the static handler middleware to find the -filesystem path for a URL. - - -.. _url-reqs: - -Requirements -```````````` - -The ``selector`` addon is required to have the following methods (see details for the methods in -below sections): - -- :js:func:`getPathForURL` -- :js:func:`getSpecURL` -- :js:func:`getURLPaths` - -Your addon will also be required to do the following: - -- Add the ``url`` metadatum to resource versions; this is where your addon will set the calculated - value (using ``beforeHostMethod('addResourceVersion')``). -- Add ``assetsRoot`` to the results of the method ``getMojitTypeDetails`, which is done with - ``onHostEvent('getMojitTypeDetails')``; ``assetsRoot`` is the common prefix for all assets in the - mojit. The built-in addon makes something like ``/static/Foo/assets`` for the ``Foo`` mojit. - -.. _url-methods: - -Methods -``````` - -.. js:function:: getPathForURL(url) - - This method is called by the static handler middleware. Returns the full filesystem path - for the URL. - - :param String url: The URL that was previously generated. - :returns: String - - -.. js:function:: getSpecURL(id) - - Returns the URL for the spec. - - :param String id: The spec ID. - :returns: String - - -.. js:function:: getURLPaths() - - Returns an object whose keys are all URLs and whose values are the corresponding filesystem - paths. - - :returns: Object - - - -.. _url-ex: - -Example -``````` - -.. _rs-creating_rs_addons: - -Creating Your Own Resource Store Addons -======================================= - -.. _creating_rs_addons-intro: - -Intro ------ - -In this section, we will discuss the key methods, events, and give a simple example of a custom -|RS| addon. By using the provided example as a model and referring to the |RSC|_ in the API -documentation, you should be able to create your own custom |RS| addons. - -.. _creating_rs_addons-anatomy: - -Anatomy of a |RS| Addon ------------------------ - -The resource store addons are implemented using the _|YUIPlugin| mechanism. In essence, a Mojito -addon is a YUI plugin, so the skeleton of a |RS| addon will be the same as a YUI Plugin. - -See the |RSC|_ for the parameters and return values for the |RS| methods. - -.. _anatomy-key_methods: - -Key Methods -########### - -.. _key_methods-initialize: - -.. js:function:: initialize(config) - - Sets the paths to find the application, mojito, and |RS| files. Within the ``preload`` method, - the following host methods are called: - - - :js:func:`preloadResourceVersions` - - :js:func:`resolveResourceVersions` - - After ``preload`` has finished executing, you can hook in with - ``afterHostMethod('preload', ...)``. - - :param Object config: Contains configuration information with the following properties: - - - .. js:attribute:: config.host - - (*Object*) -- contains the resource store. - - .. js:attribute:: config.appRoot - - (*String*) -- contains the the directory of the application. - - - .. js:attribute:: config.mojitoRoot - - (*String*) -- contains the directory of the Mojito framework code. - :returns: None - -.. js:function:: preload() - - Addons are loaded during this method, so it's not possible to hook in before ``preload`` - is called. - - -.. js:function:: preloadResourceVersions() - - The |RS| walks the filesystem in this method. Before ``preloadResourceVersions`` is called, - not much is known, though the static application configuration is available using the - method ``getStaticAppConfig``. - - Within the ``preloadResourceVersions`` method, the following host methods are called: - - - ``findResourceVersionByConvention`` - - :ref:`parseResourceVersion ` - - :ref:`addResourceVersion ` - - After ``preloadResourceVersions`` has been called: - - - All the resource versions have been loaded and are available through the method - ``getResourceVersions``. - - The |RS| has ``selectors`` object whose keys are all selectors in the application. - The values for the keys are just ``true``. - - -.. js:function:: findResourceVersionByConvention() - - This method is called on each directory or file being walked and is used to decide if the - path is a resource version. The return value can be a bit confusing, so read API docs carefully - and feel free to post any questions that you have to the - `Yahoo! Mojito Forum `_. - - Typically, you would hook into this method with the ``afterHostMethod()`` method to register - your own resource version types. This method should work together with your - own version of the ``parseResourceVersion`` method. - -.. js:function:: parseResourceVersion() - - This method creates an actual resource version. Typically, you would hook into this method - with the ``beforeHostMethod`` method to create your own resource versions. This should work - together with your own version of the :js:func:`findResourceVersionByConvention` method. - -.. js:function:: addResourceVersion() - - This method is called to save the resource version into the |RS|. Typically, if you want to - modify/augment an existing resource version, hook into this with the - ``beforeHostMethod`` method. - - -.. js:function:: resolveResourceVersions() - - This method resolves the resource versions into resources. As a resource version is resolved, - the ``mojitResourcesResolved`` event is called. After the method has been executed, all - resource versions have been resolved. - -.. js:function:: serializeClientStore() - - This method is called during runtime as Mojito creates the configuration for the client-side - Mojito. - - -.. _anatomy-key_events: - -Key Events -########## - -.. _key_events-mojitResourcesResolved: - -mojitResourcesResolved -`````````````````````` - -This event is called when the resources in a mojit are resolved. - -.. _key_events-getMojitTypeDetails: - -getMojitTypeDetails -``````````````````` - -This event is called during runtime as Mojito creates an "instance" used to dispatch a mojit. - -.. _creating_rs_addons-ex: - -Example -------- - -.. _creating_rs_addons_ex-rs_addon: - -|RS| Addon -########## - -The following |RS| addon registers the new resource type ``text`` for text files. - -``addons/rs/text.server.js`` - -.. code-block:: javascript - - - YUI.add('addon-rs-text', function(Y, NAME) { - - var libpath = require('path'); - - function RSddonText() { - RSAddonText.superclass.constructor.apply(this, arguments); - }, - RSAddonText.NS = 'text'; - RSAddonText.ATT|RS| = {}; - - Y.extend(RSAddonText, Y.Plugin.Base, { - - initializer: function(config) { - this.rs = config.host; - this.appRoot = config.appRoot; - this.mojitoRoot = config.mojitoRoot; - this.afterHostMethod('findResourceVersionByConvention', this.findResourceVersionByConvention, this); - this.beforeHostMethod('parseResourceVersion', this.parseResourceVersion, this); - }, - - destructor: function() { - // TODO: needed to break cycle so we don't leak memory? - this.rs = null; - }, - - /** - * Using AOP, this is called after the ResourceStore's version. - * @method findResourceVersionByConvention - * @param source {object} metadata about where the resource is located - * @param mojitType {string} name of mojit to which the resource likely belongs - * @return {object||null} for config file resources, returns metadata signifying that - */ - findResourceVersionByConvention: function(source, mojitType) { - // We only care about files - if (!source.fs.isFile) { - return; - } - - // We only care about txt files - if ('.txt' !== source.fs.ext) { - return; - } - - return new Y.Do.AlterReturn(null, { - type: 'text' - }); - }, - - /** - * Using AOP, this is called before the ResourceStore's version. - * @method parseResourceVersion - * @param source {object} metadata about where the resource is located - * @param type {string} type of the resource - * @param subtype {string} subtype of the resource - * @param mojitType {string} name of mojit to which the resource likely belongs - * @return {object||null} for config file resources, returns the resource metadata - */ - parseResourceVersion: function(source, type, subtype, mojitType) { - var res; - - if ('text' !== type) { - return; - } - res = { - source: source, - type: 'text', - affinity: 'server', - selector: '*' - }; - if ('app' !== source.fs.rootType) { - res.mojit = mojitType; - } - res.name = libpath.join(source.fs.subDir, source.fs.basename); - res.id = [res.type, res.subtype, res.name].join('-'); - return new Y.Do.Halt(null, res); - } - }); - Y.namespace('mojito.addons.rs'); - Y.mojito.addons.rs.text = |RS|AddonText; - - }, '0.0.1', { requires: ['plugin', 'oop']}); - -.. _creating_rs_addons_ex-text_addon: - -Text Addon -########## - -The Text Addon provides accessors so that the controller can access resources of type ``text``. -You could use this example addon as a model for writing an addon that allows a controller -to access other resource types such as ``xml`` or ``yaml``. - -``addons/ac/text.server.js`` - -.. code-block:: javascript - - - YUI.add('addon-ac-text', function(Y, NAME) { - - var libfs = require('fs'); - - function Addon(command, adapter, ac) { - this._ctx = ac.command.context; - } - Addon.prototype = { - - namespace: 'text', - - setStore: function(store) { - this._store = store; - }, - list: function() { - var r, res, ress, list = []; - ress = this._store.store.getResources('server', this._ctx, {type:'text'}); - for (r = 0; r < ress.length; r += 1) { - res = ress[r]; - list.push(res.name); - } - return list; - }, - read: function(name, cb) { - var ress; - ress = this._store.store.getResources('server', this._ctx, {type:'text', name:name}); - if (!ress || 1 !== ress.length) { - cb(new Error('Unknown text file ' + name)); - } - libfs.readFile(ress[0].source.fs.fullPath, 'utf-8', function(err, body) { - cb(err, body); - }); - } - }; - Y.mojito.addons.ac.text = Addon; - }, '0.1.0', {requires: ['mojito']} - ); - -.. _creating_rs_addons_ex-controller: - -Controller -########## - -``mojits/Viewer/controller.server.js`` - - -.. code-block:: javascript - - YUI.add('Viewer', function(Y, NAME) { - - Y.mojito.controllers[NAME] = { - - init: function(config) { - this.config = config; - }, - - index: function(ac) { - var chosen; // TODO: use form input to choose a text file - if (!chosen) { - var list; - list = ac.text.list(); - chosen = list[0]; - } - ac.assets.addCss('./index.css'); - ac.text.read(chosen, function(err, body) { - if (err) { - return ac.error(err); - } - ac.done({body: body}); - }); - } - }; - }, '1.0.1', {requires: ['mojito', 'addon-ac-text']}); - - - -.. |RS| replace:: Resource Store -.. |RSC| replace:: ResourceStore.server Class -.. _RSC: http://developer.yahoo.com/cocktails/mojito/api/classes/ResourceStore.server.html -.. |YUIPlugin| replace:: YUI Plugin -.. _YUIPlugin: http://yuilibrary.com/yui/docs/plugin/ -.. |SS| replace:: server.store.js -.. _SS: https://github.com/yahoo/mojito/blob/develop/source/lib/store.server.js \ No newline at end of file From b151fd608f09be19e5ee6cb170f63869f91f0237 Mon Sep 17 00:00:00 2001 From: Joe Catera Date: Thu, 26 Jul 2012 10:11:04 -0700 Subject: [PATCH 37/45] Updated the resource store doc, removed backup. --- docs/dev_guide/topics/mojito_resource_store.rst | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/docs/dev_guide/topics/mojito_resource_store.rst b/docs/dev_guide/topics/mojito_resource_store.rst index af2e078a4..04ef48486 100644 --- a/docs/dev_guide/topics/mojito_resource_store.rst +++ b/docs/dev_guide/topics/mojito_resource_store.rst @@ -213,7 +213,7 @@ Metadata Object .. admonition:: Note About Default Values - Some values for the properties of the metadata object do have defaults, but it depends on + Some values for the properties of the metata object do have defaults, but it depends on the value of the ``type`` property and/or comes from the file name of the resource being represented. For example, the affinity of views is ``common`` (because views are used on both client and server); however, the affinity for controllers comes @@ -283,7 +283,7 @@ pkg Object yui Object ########## -The ``yui`` property of the metadata object is created by the ``yui``|RS| addon. The +The ``yui`` property of the metadata object is created by the ``yui`` |RS| addon. The ``yui`` property can be any data type, but in general, it is an object containing metadata about YUI modules. The following table lists the typical properties that are part of the ``yui`` object. You can think of the ``yui`` object as a container for the arguments to @@ -605,14 +605,14 @@ Requirements Because the ``selector`` addon is used directly by the the resource store, all implementations need to provide the following method: -- :js:func:`getListFromContext` +- :js:func:`getPOSLFromContext(ctx)` .. _selector-methods: Methods ``````` -.. js:function:: getListFromContext(ctx) +.. js:function:: getPOSLFromContext(ctx) Returns the priority-ordered selector list (POSL) for the context. @@ -620,6 +620,10 @@ Methods :returns: Array +.. js:function:: getAllPOSLs() + + Returns all POSLs in the application. + .. _selector-ex: Example From 844dd0581480c991d36692f89471a6041fd7c31b Mon Sep 17 00:00:00 2001 From: Joe Catera Date: Thu, 26 Jul 2012 11:43:36 -0700 Subject: [PATCH 38/45] Made edits suggested by Drew. --- .../topics/mojito_resource_store.rst | 171 +++++++++++------- 1 file changed, 104 insertions(+), 67 deletions(-) diff --git a/docs/dev_guide/topics/mojito_resource_store.rst b/docs/dev_guide/topics/mojito_resource_store.rst index 04ef48486..e1ce2fe23 100644 --- a/docs/dev_guide/topics/mojito_resource_store.rst +++ b/docs/dev_guide/topics/mojito_resource_store.rst @@ -16,12 +16,11 @@ because of the |RS|. .. _intro-who: -Who Needs to Know About the Resource Store? -------------------------------------------- +Intended Audience +----------------- -Most Mojito application developers will not need to know much about the resource store, but -advanced Mojito application developers who want to have finer grain control over the management -of resources or extend the functionality of the resource store should read this documentation. +Only advanced Mojito application developers needing finer grain control over the management +of resources or to extend the functionality of the resource store should read this documentation. .. _intro-use: @@ -29,16 +28,34 @@ of resources or extend the functionality of the resource store should read this How Can the Resource Store Help Developers? ------------------------------------------- -You can write custom |RS| addons to use the aspect-oriented features of -the resource store to create resource types and to map contexts to selectors. +Reflection +########## + +The |RS| API has methods that can be used (as-is, no addons +required) to query for details about an application. + +.. I'd rather provide examples of API methods than mention that +.. ``mojito compile`` and ``mojito gv`` use the public API or +.. at least say what methods are used when those commands are run. -For example, you could write your own |RS| addon so that the Mojito command-line -tool will create files and resources for your application. The Mojito command-line -tool uses the |RS| for all the commands except ``start``. +Define/Register New Resource Types +################################## + +You can write custom |RS| addons using the aspect-oriented features of +the |RS| to define resource types and to map contexts to selectors. +The |RS| has aspect-oriented features because it is implemented as a +`Y.Base `_, and the |RS| addons +are implemented as `Y.Plugin `_. + +For example, you could write your own |RS| addon so that the Mojito command-line tool +will register files and resources for your application. + +Extend/Modify Functionality of the |RS| +####################################### You can also write custom versions of built-in |RS| addons to modify how the resource store works. Your custom addon could track new file types, augment the information that the |RS| stores about -files or code, or augment/replace the information returned by the |RS|. +files or code, or augment/replace the information returned by the |RS|. .. _rs-resources: @@ -156,58 +173,59 @@ is generated by the |RS| or by |RS| addons. Metadata Object --------------- - -+------------------------+---------------+-----------+---------------------+------------------------------+---------------------------------------------+ -| Property | Data Type | Required? | Default Value | Possible Values | Description | -+========================+===============+===========+=====================+==============================+=============================================+ -| ``type`` | string | yes | none | See :ref:`Types of Resources | Specifies the type of resource. | -| | | | | `. | | -+------------------------+---------------+-----------+---------------------+------------------------------+---------------------------------------------+ -| ``subtype`` | string | no | none | ``action``, ``binder``, | Some resource types have multiple subtypes | -| | | | | ``command``, ``middleware`` | that can be specified with ``subtype``. See | -| | | | | ``model``, ``view`` | :ref:`Subtypes ` for | -| | | | | | more information. | -+------------------------+---------------+-----------+---------------------+------------------------------+---------------------------------------------+ -| ``name`` | string | yes | none | N/A | The name of the resource that is common to | -| | | | | | all versions (i.e., iPhone/Android, etc.) | -| | | | | | of the resource. Example: the name for | -| | | | | | for the resources ``index.iphone.mu.html`` | -| | | | | | and ``index.mu.html`` is ``index``. | -+------------------------+---------------+-----------+---------------------+------------------------------+---------------------------------------------+ -| ``id`` | string | yes | none | N/A | A unique ID that is common to all versions | -| | | | | | of the resource. The ``id`` has the | -| | | | | | following syntax convention: | -| | | | | | ``{type}-{subtype}-{name}`` | -+------------------------+---------------+-----------+---------------------+------------------------------+---------------------------------------------+ -| ``mojit`` | string | no | none | N/A | The mojit, if any, that uses this resource | -| | | | | | The value ``"shared"`` means the resource | -| | | | | | is available to all mojits. | -+------------------------+---------------+-----------+---------------------+------------------------------+---------------------------------------------+ -| ``affinity`` | string | yes | See :ref:`Note | ``server``, ``client``, | The affinity of the resource, which | -| | | | About Default | ``common`` | indicates where the resource will be used. | -| | | | Values `. | | | -+------------------------+---------------+-----------+---------------------+------------------------------+---------------------------------------------+ -| ``selector`` | string | no | "*" | N/A | The version of the resource, not to be | -| | | | | | confused revisions that mark the change of | -| | | | | | the resource over time. For example, a | -| | | | | | resource could have a version for iPhones, | -| | | | | | Android devices, fallbacks, etc. | -+------------------------+---------------+-----------+---------------------+------------------------------+---------------------------------------------+ -| ``source`` | object | yes | none | N/A | Specifies where the resource came from | -| | | | | | (not shipped to client). See :ref:`source | -| | | | | | Object ` for details. | -+------------------------+---------------+-----------+---------------------+------------------------------+---------------------------------------------+ -| ``url`` | string | no | none | N/A | The path used to load the resource | -| | | | | | onto the client. Used only for resources | -| | | | | | that can be deployed by reference to the | -| | | | | | client. | -+------------------------+---------------+-----------+---------------------+------------------------------+---------------------------------------------+ -| ``yui`` | object | no | none | N/A | The metadata about YUI modules. See the | -| | | | | | :ref:`yui Object ` for more | -| | | | | | details. | -+------------------------+---------------+-----------+---------------------+------------------------------+---------------------------------------------+ ++------------------------+---------------+-----------+---------------------+-----------------------------------+------------------------------------------------+ +| Property | Data Type | Required? | Default Value | Possible Values | Description | ++========================+===============+===========+=====================+===================================+================================================+ +| ``type`` | string | yes | none | See :ref:`Types of Resources | Specifies the type of resource. | +| | | | | `. | | ++------------------------+---------------+-----------+---------------------+-----------------------------------+------------------------------------------------+ +| ``subtype`` | string | no | none | See the section | Some resource types have multiple subtypes | +| | | | | :ref:`Subtypes ` | that can be specified with ``subtype``. See | +| | | | | | :ref:`Subtypes ` for | +| | | | | | more information. | ++------------------------+---------------+-----------+---------------------+-----------------------------------+------------------------------------------------+ +| ``name`` | string | yes | none | N/A | The name of the resource that is common to | +| | | | | | all versions (i.e., iPhone/Android, etc.) | +| | | | | | of the resource. Example: the name for | +| | | | | | for the resources ``index.iphone.mu.html`` | +| | | | | | and ``index.mu.html`` is ``index``. | ++------------------------+---------------+-----------+---------------------+-----------------------------------+------------------------------------------------+ +| ``id`` | string | yes | none | N/A | A unique ID that is common to all versions | +| | | | | | of the resource. The ``id`` has the | +| | | | | | following syntax convention: | +| | | | | | ``{type}-{subtype}-{name}`` | ++------------------------+---------------+-----------+---------------------+-----------------------------------+------------------------------------------------+ +| ``mojit`` | string | no | none | N/A | The mojit, if any, that uses this resource | +| | | | | | The value ``"shared"`` means the resource | +| | | | | | is available to all mojits. | ++------------------------+---------------+-----------+---------------------+-----------------------------------+------------------------------------------------+ +| ``affinity`` | string | yes | See :ref:`Note | ``server``, ``client``, | The affinity of the resource, which | +| | | | About Default | ``common`` | indicates where the resource will be used. | +| | | | Values `. | | | ++------------------------+---------------+-----------+---------------------+-----------------------------------+------------------------------------------------+ +| ``selector`` | string | no | "*" | N/A | The version of the resource. For example, a | +| | | | | | resource could have a version for iPhones, | +| | | | | | Android devices, fallbacks, etc. (This concept | +| | | | | | of version should not to be confused code | +| | | | | | revisions, which mark the change of something | +| | | | | | over time.) For more info, see | +| | | | | | :ref:`selector Property `. | ++------------------------+---------------+-----------+---------------------+-----------------------------------+------------------------------------------------+ +| ``source`` | object | yes | none | N/A | Specifies where the resource came from. | +| | | | | | See :ref:`source Object ` for | +| | | | | | details. | ++------------------------+---------------+-----------+---------------------+-----------------------------------+------------------------------------------------+ +| ``url`` | string | no | none | N/A | The path used to load the resource | +| | | | | | onto the client. Used only for resources | +| | | | | | that can be deployed by reference to the | +| | | | | | client. | ++------------------------+---------------+-----------+---------------------+-----------------------------------+------------------------------------------------+ +| ``yui`` | object | no | none | N/A | The metadata about YUI modules. See the | +| | | | | | :ref:`yui Object ` for more | +| | | | | | details. | ++------------------------+---------------+-----------+---------------------+-----------------------------------+------------------------------------------------+ .. _def_vals: @@ -217,7 +235,25 @@ Metadata Object the value of the ``type`` property and/or comes from the file name of the resource being represented. For example, the affinity of views is ``common`` (because views are used on both client and server); however, the affinity for controllers comes - from the file name. + from the file name, so there is no default. + +.. _sel_prop: + +selector Property +################# + +The **selector** is an arbitrary user-defined string, which is used to +*select* which version of each resource to use. The value of the ``selector`` +property is a string that must not have a period (``'.'``) or slash (``'/'``) in it. +In practice, it's suggested to use alphanumeric and hyphen ('-') characters only. + +The selector is defined in the ``application.json``, with the ``selector`` property. +Only one selector can be used in each configuration object identified by the +``setting`` property, which defines the context. + +The specified selectors must match the selector found in the +resource file names. So, for example, the view ``views/index.iphone.mu.html`` has +the selector ``iphone``. .. _src_obj: @@ -227,11 +263,12 @@ source Object +------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ | Property | Data Type | Required? | Default Value | Possible Values | Description | +========================+===============+===========+===============+===============================+=============================================+ -| ``fs`` | string | yes | none | N/A | See :ref:`fs Object `. | +| ``fs`` | object | yes | none | N/A | See :ref:`fs Object `. | +------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ -| ``pkg`` | array | yes | none | N/A | See :ref:`pkg Object `. | +| ``pkg`` | object | yes | none | N/A | See :ref:`pkg Object `. | +------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ + .. _fs_obj: fs Object @@ -294,7 +331,7 @@ the ``YUI.add`` method that is used to register reusable YUI modules. +========================+===============+===========+===============+===============================+=============================================+ | ``name`` | string | yes | none | ``"scroll"`` | The name of the YUI module. | +------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ -| ``meta.requires`` | array | yes | none | ``["scroll","node","cache"]`` | Contains a list of YUI modules required by | +| ``meta`` | array | yes | none | ``["scroll","node","cache"]`` | Contains a list of YUI modules required by | | | | | | | this resource. | +------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ @@ -749,7 +786,7 @@ Key Methods - :js:func:`preloadResourceVersions` - :js:func:`resolveResourceVersions` - After ``preload`` has finished executing, you can hook in with + After ``preload`` has finished executing, you can call with ``afterHostMethod('preload', ...)``. :param Object config: Contains configuration information with the following properties: @@ -768,7 +805,7 @@ Key Methods .. js:function:: preload() - Addons are loaded during this method, so it's not possible to hook in before ``preload`` + Addons are loaded during this method, so it's not possible to call before ``preload`` is called. From d78f1f36c6d46d1ce674ea6c168f16e7d8bdb29a Mon Sep 17 00:00:00 2001 From: Joe Catera Date: Thu, 26 Jul 2012 17:04:01 -0700 Subject: [PATCH 39/45] Made more edits based on an engineer's feedback. --- .../topics/mojito_resource_store.rst | 373 ++++++++---------- 1 file changed, 165 insertions(+), 208 deletions(-) diff --git a/docs/dev_guide/topics/mojito_resource_store.rst b/docs/dev_guide/topics/mojito_resource_store.rst index e1ce2fe23..2e0a786db 100644 --- a/docs/dev_guide/topics/mojito_resource_store.rst +++ b/docs/dev_guide/topics/mojito_resource_store.rst @@ -322,9 +322,11 @@ yui Object The ``yui`` property of the metadata object is created by the ``yui`` |RS| addon. The ``yui`` property can be any data type, but in general, it is an object -containing metadata about YUI modules. The following table lists the typical properties that are -part of the ``yui`` object. You can think of the ``yui`` object as a container for the arguments to -the ``YUI.add`` method that is used to register reusable YUI modules. +containing metadata about YUI modules. You can think of the ``yui`` object as a container for the +arguments to the ``YUI.add`` method that is used to register reusable YUI modules. + +The following table lists the typical properties that are +part of the ``yui`` object. +------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ | Property | Data Type | Required? | Default Value | Example Values | Description | @@ -348,7 +350,6 @@ The ``type`` property of the metadata object can have any of the following value - ``model`` - a model for a mojit - ``view`` - a view for a mojit - ``binder`` - a binder for a mojit -- ``action`` - an action to augment the controller - ``asset`` - an asset (css, js, image, etc.) - ``addon`` - an addon to the mojito system - ``spec`` - the configuration for a mojit instance @@ -365,7 +366,7 @@ resource of ``type:addon`` might have subtypes, such as ``subtype:ac`` for AC ad ``subtype:view-engine`` for view engines, or ``subtype:rs`` for |RS| addons. For ``type:archetype``, the subtypes refers to the ``type`` described in the output from -the command ``mojito help create``. So, you could have ``subtype:app``, ``subtype:project``, or +the command ``mojito help create``. So, you could have ``subtype:app``, or ``subtype:mojit``. (There may be more in the future!) .. _metatdata-versions: @@ -374,10 +375,12 @@ Resource Versions ----------------- Resources can have many versions that are identified by the ``selector`` property of the -metadata object. The selector is defined by the user and indicates the version of the resource. -For example, developer might decide to use the selector ``selector: iphone`` for the iPhone version -and ``selector: android`` for the Android version of a resource. Using these two selectors, you -could have the following two versions of the ``index`` resource of type ``view``: +metadata object and the affinity. The selector is defined by the user and indicates the version of +the resource and the affinity is defined by the resource itself. + +For example, developer might decide to use the selector ``selector: iphone`` for the +iPhone version and ``selector: android`` for the Android version of a resource. Using these two +selectors, you could have the following two versions of the ``index`` resource of type ``view``: - ``index.iphone.mu.html`` - ``index.android.mu.html`` @@ -394,8 +397,8 @@ Example { "source": { "fs": { - "fullPath": "/Users/folta/work/yahoo/mojito/github-drewfish/examples/getting-started-guide/part4/paged-yql/mojits/PagedFlickr/views/index.mu.html", - "rootDir": "/Users/folta/work/yahoo/mojito/github-drewfish/examples/getting-started-guide/part4/paged-yql/mojits/PagedFlickr", + "fullPath": /"home/me/github-mojito/examples/getting-started-guide/part4/paged-yql/mojits/PagedFlickr/views/index.mu.html", + "rootDir": "/home/me/github-mojito/yahoo/mojito/github-drewfish/examples/getting-started-guide/part4/paged-yql/mojits/PagedFlickr", "rootType": "mojit", "subDir": ".", "subDirArray": [], @@ -426,8 +429,8 @@ Example How Does the Resource Store Work? ================================= -Understanding the workflow of the resource store will give help those who want to customize addons -to write code and others who don't plan on customizing addons to debug. +Understanding the |RS| will allow you to customize addons and debug your application. + Overview -------- @@ -438,9 +441,9 @@ of resource each file is, creates metadata about the resource, and then register During this process, the resource store also does the following: -- pre-calculates ("resolving") which resource versions are used for each version of the mojit. -- keeps track of application-level resources (archetypes, commands, config files, and middleware). -- provides methods for events, including those specialized for +- pre-calculates ("resolves") which resource versions are used for each version of the mojit. +- also keeps track of application-level resources (archetypes, commands, config files, and middleware). +- provides methods and events, including those specialized for `aspect-orient programming (AOP) `_. - explicitly uses the addons :ref:`selector ` and :ref:`config `. @@ -535,7 +538,7 @@ will be used because its selector is a higher priority match than its affinity. All this is pre-calculated for each resource, for each possible runtime configuration (client or -server, and every possible runtime context). +server, and every appropriate runtime context). .. _how-get_data: @@ -565,188 +568,6 @@ the method ``getResourceVersions`` or ``getResources`` for each mojit. You can ``listAllMojits`` to get a list of all mojits. -.. _rs-addons: - -Resource Store Built-In Addons -============================== - -.. _addons-intro: - -Intro ------ - -Mojito comes with built-in resource store addons that are used by the |RS| -and the Mojito framework. These resource store addons are required by the |RS| and -the Mojito framework. Thus, particular care must be taken when creating custom versions -of them. - -The |RS| comes with the following four built-in addons: - -- ``config`` - - registers new resource type ``config`` found in JSON configuration files - - provides an API for reading both context and straight-JSON files - - provides sugar for reading the application's dimensions -- ``selector`` - - decides the priority-ordered list (POSL) to use for a context - - looks (default implementation) for ``selector`` in ``application.json``. Because - ``application.json`` is a context configuration file, the ``selector`` can be contextualized - there. -- ``url`` - - calculates the static handler URL for appropriate resources (and resource versions) - - stores the URL in the ``url`` key of the resource - - calculates the asset URL base for each mojit -- ``yui`` - - registers new resource type ``yui-module`` found in the directories ``autoload`` - or ``yui_modules`` - - registers new resource type ``yui-lang`` found in the ``lang`` directory - - calculates the ``yui`` metadata for resource versions that are YUI modules - - pre-calculates corresponding YUI module dependencies when resources are resolved - for each version of each mojit - - appends the pre-calculated YUI module dependencies for the controller and binders when - Mojito queries the |RS| for the details of a mojit (``getMojitTypeDetails`` method) - - provides methods used by Mojito to configure its YUI instances - - -.. _addons-custom: - -Creating Custom Versions of Built-In |RS| Addons ------------------------------------------------- - -We will be examining the ``selector`` and ``url`` addons to help you create custom versions of -those addons. We do not recommend that you create custom versions of the -``config`` or ``yui`` addons, so we will not be looking at those addons. Also, this documentation -explains what the |RS| expects the addon to do, so you can create your own version of the addons. -To learn what a |RS| built-in addons do, please refer to the |RSC|_ in the API documentation. - - -.. _custom-selector: - -selector -######## - -.. _selector-desc: - -Description -``````````` - -If you wish to use a different algorithm for to determine the selectors to use, -you can implement your own version of this |RS| addon. It will need to go in the file -``addons/rs/selector.server.js`` of your application. - - -.. _selector-reqs: - -Requirements -```````````` - -Because the ``selector`` addon is used directly by the the resource store, all implementations -need to provide the following method: - -- :js:func:`getPOSLFromContext(ctx)` - -.. _selector-methods: - -Methods -``````` - -.. js:function:: getPOSLFromContext(ctx) - - Returns the priority-ordered selector list (POSL) for the context. - - :param String ctx: The context that the application is running in. - :returns: Array - - -.. js:function:: getAllPOSLs() - - Returns all POSLs in the application. - -.. _selector-ex: - -Example -``````` - -.. _url-intro: - -url -### - -.. _url-desc: - -Description -``````````` - -The ``url`` addon calculates and manages the static handler URLs for resources. -The addon is not used by resource store core, but used by the static handler middleware. - -If you wish to use a different algorithm to determine the URLs, you can -implement your own version of this |RS| addon. It'll need to go in -``addons/rs/url.server.js`` in your application. - -After the method ``preloadResourceVersions`` sets ``res.url`` to the static handler URL -for the resource, the method ``getMojitTypeDetails`` sets the mojit's ``assetsRoot``. -The static handler URL can be a rollup URL. - -The ``url`` addon also provides a method for the static handler middleware to find the -filesystem path for a URL. - - -.. _url-reqs: - -Requirements -```````````` - -The ``selector`` addon is required to have the following methods (see details for the methods in -below sections): - -- :js:func:`getPathForURL` -- :js:func:`getSpecURL` -- :js:func:`getURLPaths` - -Your addon will also be required to do the following: - -- Add the ``url`` metadatum to resource versions; this is where your addon will set the calculated - value (using ``beforeHostMethod('addResourceVersion')``). -- Add ``assetsRoot`` to the results of the method ``getMojitTypeDetails`, which is done with - ``onHostEvent('getMojitTypeDetails')``; ``assetsRoot`` is the common prefix for all assets in the - mojit. The built-in addon makes something like ``/static/Foo/assets`` for the ``Foo`` mojit. - -.. _url-methods: - -Methods -``````` - -.. js:function:: getPathForURL(url) - - This method is called by the static handler middleware. Returns the full filesystem path - for the URL. - - :param String url: The URL that was previously generated. - :returns: String - - -.. js:function:: getSpecURL(id) - - Returns the URL for the spec. - - :param String id: The spec ID. - :returns: String - - -.. js:function:: getURLPaths() - - Returns an object whose keys are all URLs and whose values are the corresponding filesystem - paths. - - :returns: Object - - - -.. _url-ex: - -Example -``````` - .. _rs-creating_rs_addons: Creating Your Own Resource Store Addons @@ -780,8 +601,10 @@ Key Methods .. js:function:: initialize(config) - Sets the paths to find the application, mojito, and |RS| files. Within the ``preload`` method, - the following host methods are called: + This method sets the paths to find the application, Mojito, and |RS| files. Addons should hook + into |RS| methods (using AOP) or events fired by the |RS| in this method. + + The following host methods are called: - :js:func:`preloadResourceVersions` - :js:func:`resolveResourceVersions` @@ -791,9 +614,6 @@ Key Methods :param Object config: Contains configuration information with the following properties: - - .. js:attribute:: config.host - - (*Object*) -- contains the resource store. - .. js:attribute:: config.appRoot (*String*) -- contains the the directory of the application. @@ -864,7 +684,12 @@ Key Methods This method is called during runtime as Mojito creates the configuration for the client-side Mojito. +Accessing the Resource Store +```````````````````````````` +To access the |RS|, you call ``this.get('host')``. The method returns an object containing the +|RS|. + .. _anatomy-key_events: Key Events @@ -914,7 +739,6 @@ The following |RS| addon registers the new resource type ``text`` for text files Y.extend(RSAddonText, Y.Plugin.Base, { initializer: function(config) { - this.rs = config.host; this.appRoot = config.appRoot; this.mojitoRoot = config.mojitoRoot; this.afterHostMethod('findResourceVersionByConvention', this.findResourceVersionByConvention, this); @@ -923,7 +747,6 @@ The following |RS| addon registers the new resource type ``text`` for text files destructor: function() { // TODO: needed to break cycle so we don't leak memory? - this.rs = null; }, /** @@ -985,8 +808,8 @@ The following |RS| addon registers the new resource type ``text`` for text files .. _creating_rs_addons_ex-text_addon: -Text Addon -########## +Text ActionContext Addon +######################## The Text Addon provides accessors so that the controller can access resources of type ``text``. You could use this example addon as a model for writing an addon that allows a controller @@ -1071,6 +894,140 @@ Controller }; }, '1.0.1', {requires: ['mojito', 'addon-ac-text']}); + +.. _rs-addons: + +Resource Store Built-In Addons +============================== + +.. _addons-intro: + +Intro +----- + +Mojito comes with built-in resource store addons that are used by the |RS| +and the Mojito framework. These resource store addons are required by the |RS| and +the Mojito framework. Thus, particular care must be taken when creating custom versions +of them. + +The |RS| comes with the following four built-in addons: + +- ``config`` + - registers new resource type ``config`` found in JSON configuration files + - provides an API for reading both context and straight-JSON files + - provides sugar for reading the application's dimensions +- ``selector`` + - decides the priority-ordered list (POSL) to use for a context + - looks for ``selector`` in ``application.json``. Because + ``application.json`` is a context configuration file, the ``selector`` can be contextualized + there. +- ``url`` + - calculates the static handler URL for appropriate resources (and resource versions) + - stores the URL in the ``url`` key of the resource + - calculates the asset URL base for each mojit +- ``yui`` + - registers new resource type ``yui-module`` found in the directories ``autoload`` + or ``yui_modules`` + - registers new resource type ``yui-lang`` found in the ``lang`` directory + - calculates the ``yui`` metadata for resource versions that are YUI modules + - pre-calculates corresponding YUI module dependencies when resources are resolved + for each version of each mojit + - appends the pre-calculated YUI module dependencies for the controller and binders when + Mojito queries the |RS| for the details of a mojit (``getMojitTypeDetails`` method) + - provides methods used by Mojito to configure its YUI instances + + +.. _addons-custom: + +Creating Custom Versions of Built-In |RS| Addons +------------------------------------------------ + +We will be examining the ``selector`` and ``url`` addons to help you create custom versions of +those addons. We do not recommend that you create custom versions of the +``config`` or ``yui`` addons, so we will not be looking at those addons. Also, this documentation +explains what the |RS| expects the addon to do, so you can create your own version of the addons. +To learn what a |RS| built-in addons do, please refer to the |RSC|_ in the API documentation. + + +.. _custom-selector: + +selector +######## + +.. _selector-desc: + +Description +``````````` + +If you wish to use a different algorithm for to determine the selectors to use, +you can implement your own version of this |RS| addon. It will need to go in the file +``addons/rs/selector.server.js`` of your application. + + +.. _selector-reqs: + +Requirements +```````````` + +Because the ``selector`` addon is used directly by the the resource store, all implementations +need to provide the following method: + +- :js:func:`getPOSLFromContext(ctx)` + +.. _selector-methods: + +Methods +``````` + +.. js:function:: getPOSLFromContext(ctx) + + Returns the priority-ordered selector list (POSL) for the context. + + :param String ctx: The context that the application is running in. + :returns: Array + + +.. js:function:: getAllPOSLs() + + Returns all POSLs in the application. + + +.. _url-intro: + +url +### + +.. _url-desc: + +Description +``````````` + +The ``url`` addon calculates and manages the static handler URLs for resources. +The addon is not used by resource store core, but used by the static handler middleware. + +If you wish to use a different algorithm to determine the URLs, you can +implement your own version of this |RS| addon. It'll need to go in +``addons/rs/url.server.js`` in your application. + +After the method ``preloadResourceVersions`` sets ``res.url`` to the static handler URL +for the resource, the method ``getMojitTypeDetails`` sets the mojit's ``assetsRoot``. +The static handler URL can be a rollup URL. + + +.. _url-reqs: + +Requirements +```````````` + +Your addon is required to do the following: + +- Set the ``url`` property in the resource ``metadata`` object. + + + + + + .. |RS| replace:: Resource Store From f5cd9e8217a66c40b73b98d72536b8c4bec569d5 Mon Sep 17 00:00:00 2001 From: Joe Catera Date: Thu, 26 Jul 2012 18:53:04 -0700 Subject: [PATCH 40/45] Corrected meta object table. --- .../topics/mojito_resource_store.rst | 216 ++++++++++-------- 1 file changed, 120 insertions(+), 96 deletions(-) diff --git a/docs/dev_guide/topics/mojito_resource_store.rst b/docs/dev_guide/topics/mojito_resource_store.rst index 2e0a786db..26f277bfe 100644 --- a/docs/dev_guide/topics/mojito_resource_store.rst +++ b/docs/dev_guide/topics/mojito_resource_store.rst @@ -53,9 +53,9 @@ will register files and resources for your application. Extend/Modify Functionality of the |RS| ####################################### -You can also write custom versions of built-in |RS| addons to modify how the resource store works. -Your custom addon could track new file types, augment the information that the |RS| stores about -files or code, or augment/replace the information returned by the |RS|. +You can also write addons or create custom versions of built-in |RS| addons to modify +how the resource store works. Your addon could track new file types, augment the information +that the |RS| stores about files or code, or augment/replace the information returned by the |RS|. .. _rs-resources: @@ -87,10 +87,10 @@ To the Resource Store The |RS| primarily cares about the *metadata* about each resource, so it sees the metadata as the *resource*. To the |RS|, the **resource** is just a JavaScript object containing metadata. The |RS| defines certain keys with specific meanings. The |RS| addons -can add, remove, or modify those keys/values as they see fit. For -example, the yui |RS| addon adds the ``yui`` key with metadata -about resources that are YUI modules. The |RS| itself doesn't populate -the ``yui`` key of each resource. +can add, remove, or modify those keys/values as they see fit. +For example, the YUI |RS| addon adds, for resources that are YUI modules, the ``yui`` +property with metadata about the YUI module aspect of the resource. +The |RS| itself, however, doesn't populate the ``yui`` key of each resource. .. _resources-versions: @@ -164,9 +164,9 @@ Resource Metadata Intro ----- -The resource store uses metadata to find, load, parse, and create instances of resources. The -resource metadata is generated by code--it has no representation on the filesystem. The metadata -is generated by the |RS| or by |RS| addons. +The RS uses metadata to track information about each resource. This metadata is used by the rest of +Mojito to find, load, and parse the resources. The metadata is generated by the |RS| or by |RS| +addons--it has no representation on the filesystem. .. _metadata-obj: @@ -175,57 +175,61 @@ Metadata Object --------------- -+------------------------+---------------+-----------+---------------------+-----------------------------------+------------------------------------------------+ -| Property | Data Type | Required? | Default Value | Possible Values | Description | -+========================+===============+===========+=====================+===================================+================================================+ -| ``type`` | string | yes | none | See :ref:`Types of Resources | Specifies the type of resource. | -| | | | | `. | | -+------------------------+---------------+-----------+---------------------+-----------------------------------+------------------------------------------------+ -| ``subtype`` | string | no | none | See the section | Some resource types have multiple subtypes | -| | | | | :ref:`Subtypes ` | that can be specified with ``subtype``. See | -| | | | | | :ref:`Subtypes ` for | -| | | | | | more information. | -+------------------------+---------------+-----------+---------------------+-----------------------------------+------------------------------------------------+ -| ``name`` | string | yes | none | N/A | The name of the resource that is common to | -| | | | | | all versions (i.e., iPhone/Android, etc.) | -| | | | | | of the resource. Example: the name for | -| | | | | | for the resources ``index.iphone.mu.html`` | -| | | | | | and ``index.mu.html`` is ``index``. | -+------------------------+---------------+-----------+---------------------+-----------------------------------+------------------------------------------------+ -| ``id`` | string | yes | none | N/A | A unique ID that is common to all versions | -| | | | | | of the resource. The ``id`` has the | -| | | | | | following syntax convention: | -| | | | | | ``{type}-{subtype}-{name}`` | -+------------------------+---------------+-----------+---------------------+-----------------------------------+------------------------------------------------+ -| ``mojit`` | string | no | none | N/A | The mojit, if any, that uses this resource | -| | | | | | The value ``"shared"`` means the resource | -| | | | | | is available to all mojits. | -+------------------------+---------------+-----------+---------------------+-----------------------------------+------------------------------------------------+ -| ``affinity`` | string | yes | See :ref:`Note | ``server``, ``client``, | The affinity of the resource, which | -| | | | About Default | ``common`` | indicates where the resource will be used. | -| | | | Values `. | | | -+------------------------+---------------+-----------+---------------------+-----------------------------------+------------------------------------------------+ -| ``selector`` | string | no | "*" | N/A | The version of the resource. For example, a | -| | | | | | resource could have a version for iPhones, | -| | | | | | Android devices, fallbacks, etc. (This concept | -| | | | | | of version should not to be confused code | -| | | | | | revisions, which mark the change of something | -| | | | | | over time.) For more info, see | -| | | | | | :ref:`selector Property `. | -+------------------------+---------------+-----------+---------------------+-----------------------------------+------------------------------------------------+ -| ``source`` | object | yes | none | N/A | Specifies where the resource came from. | -| | | | | | See :ref:`source Object ` for | -| | | | | | details. | -+------------------------+---------------+-----------+---------------------+-----------------------------------+------------------------------------------------+ -| ``url`` | string | no | none | N/A | The path used to load the resource | -| | | | | | onto the client. Used only for resources | -| | | | | | that can be deployed by reference to the | -| | | | | | client. | -+------------------------+---------------+-----------+---------------------+-----------------------------------+------------------------------------------------+ -| ``yui`` | object | no | none | N/A | The metadata about YUI modules. See the | -| | | | | | :ref:`yui Object ` for more | -| | | | | | details. | -+------------------------+---------------+-----------+---------------------+-----------------------------------+------------------------------------------------+ ++---------------------------+---------------+-----------+---------------------+-----------------------------------+------------------------------------------------+ +| Property | Data Type | Required? | Default Value | Possible Values | Description | ++===========================+===============+===========+=====================+===================================+================================================+ +| ``type`` | string | yes | none | See :ref:`Types of Resources | Specifies the type of resource. | +| | | | | `. | | ++---------------------------+---------------+-----------+---------------------+-----------------------------------+------------------------------------------------+ +| ``subtype`` | string | no | none | See the section | Some resource types have multiple subtypes | +| | | | | :ref:`Subtypes ` | that can be specified with ``subtype``. See | +| | | | | | :ref:`Subtypes ` for | +| | | | | | more information. | ++---------------------------+---------------+-----------+---------------------+-----------------------------------+------------------------------------------------+ +| ``name`` | string | yes | none | N/A | The name of the resource that is common to | +| | | | | | all versions (i.e., iPhone/Android, etc.) | +| | | | | | of the resource. Example: the name for | +| | | | | | for the resources ``index.iphone.mu.html`` | +| | | | | | and ``index.mu.html`` is ``index``. | ++---------------------------+---------------+-----------+---------------------+-----------------------------------+------------------------------------------------+ +| ``id`` | string | yes | none | N/A | A unique ID that is common to all versions | +| | | | | | of the resource. The ``id`` has the | +| | | | | | following syntax convention: | +| | | | | | ``{type}-{subtype}-{name}`` | ++---------------------------+---------------+-----------+---------------------+-----------------------------------+------------------------------------------------+ +| ``mojit`` | string | no | none | N/A | The mojit, if any, that uses this resource | +| | | | | | The value ``"shared"`` means the resource | +| | | | | | is available to all mojits. | ++---------------------------+---------------+-----------+---------------------+-----------------------------------+------------------------------------------------+ +| ``affinity`` | string | yes | See :ref:`Note | ``server``, ``client``, | The affinity of the resource, which | +| | | | About Default | ``common`` | indicates where the resource will be used. | +| | | | Values `. | | | ++---------------------------+---------------+-----------+---------------------+-----------------------------------+------------------------------------------------+ +| ``selector`` | string | no | "*" | N/A | The version of the resource. For example, a | +| | | | | | resource could have a version for iPhones, | +| | | | | | Android devices, fallbacks, etc. (This concept | +| | | | | | of version should not to be confused code | +| | | | | | revisions, which mark the change of something | +| | | | | | over time.) For more info, see | +| | | | | | :ref:`selector Property `. | ++---------------------------+---------------+-----------+---------------------+-----------------------------------+------------------------------------------------+ +| :ref:`source ` | object | yes | none | N/A | Specifies where the resource came from. | +| | | | | | See :ref:`source Object ` for | +| | | | | | details. | ++---------------------------+---------------+-----------+---------------------+-----------------------------------+------------------------------------------------+ +| ``url`` | string | no | none | N/A | The path used to load the resource | +| | | | | | onto the client. Used only for resources | +| | | | | | that can be deployed by reference to the | +| | | | | | client. | ++---------------------------+---------------+-----------+---------------------+-----------------------------------+------------------------------------------------+ +| :ref:`view ` | object | yes | none | N/A | Specifies the output format such as HTML, XML, | +| | | | | | JSON, etc., and the engine that renders the | +| | | | | | view template into the output format. Some | ++---------------------------+---------------+-----------+---------------------+-----------------------------------+------------------------------------------------+ +| :ref:`yui ` | object | no | none | N/A | The metadata about YUI modules. See the | +| | | | | | :ref:`yui Object ` for more | +| | | | | | details. | ++---------------------------+---------------+-----------+---------------------+-----------------------------------+------------------------------------------------+ .. _def_vals: @@ -263,9 +267,11 @@ source Object +------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ | Property | Data Type | Required? | Default Value | Possible Values | Description | +========================+===============+===========+===============+===============================+=============================================+ -| ``fs`` | object | yes | none | N/A | See :ref:`fs Object `. | +| ``fs`` | object | yes | none | N/A | Contains the filesystem details of a | +| | | | | | resource. See :ref:`fs Object `. | +------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ -| ``pkg`` | object | yes | none | N/A | See :ref:`pkg Object `. | +| ``pkg`` | object | yes | none | N/A | Contains the ``npm``package details of a | +| | | | | | resource. See :ref:`pkg Object `. | +------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ @@ -274,28 +280,26 @@ source Object fs Object ````````` -+------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ -| Property | Data Type | Required? | Default Value | Possible Values | Description | -+========================+===============+===========+===============+===============================+=============================================+ -| ``basename`` | string | yes | none | N/A | | -+------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ -| ``ext`` | string | yes | none | N/A | | -+------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ -| ``fullPath`` | string | yes | none | N/A | | -+------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ -| ``isFile`` | boolean | yes | none | N/A | | -+------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ -| ``fullPath`` | string | yes | none | N/A | | -+------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ -| ``rootDir`` | string | yes | none | N/A | | -+------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ -| ``rootType`` | string | yes | none | See :ref:`Types of Resources | | -| | | | | `. | | -+------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ -| ``subDir`` | string | yes | none | N/A | | -+------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ -| ``subDirArray`` | array | yes | none | N/A | | -+------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ ++------------------------+---------------+-----------+---------------+-------------------------------+ +| Property | Data Type | Required? | Default Value | Possible Values | ++========================+===============+===========+===============+===============================+ +| ``basename`` | string | yes | none | N/A | ++------------------------+---------------+-----------+---------------+-------------------------------+ +| ``ext`` | string | yes | none | N/A | ++------------------------+---------------+-----------+---------------+-------------------------------+ +| ``fullPath`` | string | yes | none | N/A | ++------------------------+---------------+-----------+---------------+-------------------------------+ +| ``isFile`` | boolean | yes | none | N/A | ++------------------------+---------------+-----------+---------------+-------------------------------+ +| ``rootDir`` | string | yes | none | N/A | ++------------------------+---------------+-----------+---------------+-------------------------------+ +| ``rootType`` | string | yes | none | See :ref:`Types of Resources | +| | | | | `. | ++------------------------+---------------+-----------+---------------+-------------------------------+ +| ``subDir`` | string | yes | none | N/A | ++------------------------+---------------+-----------+---------------+-------------------------------+ +| ``subDirArray`` | array | yes | none | N/A | ++------------------------+---------------+-----------+---------------+-------------------------------+ .. _pkg_obj: @@ -303,17 +307,35 @@ fs Object pkg Object `````````` -+------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ -| Property | Data Type | Required? | Default Value | Possible Values | Description | -+========================+===============+===========+===============+===============================+=============================================+ -| ``depth`` | number | yes | none | N/A | | -+------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ -| ``name`` | string | yes | none | N/A | | -+------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ -| ``version`` | string | yes | none | N/A | | -+------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ ++------------------------+---------------+-----------+---------------+-------------------------------+----------------------------------------------+ +| Property | Data Type | Required? | Default Value | Possible Values | Description | ++========================+===============+===========+===============+===============================+==============================================+ +| ``depth`` | number | yes | none | N/A | The depth in ``npm`` dependencies in the | +| | | | | | ``node_modules`` directory where the package | +| | | | | | is found. | ++------------------------+---------------+-----------+---------------+-------------------------------+----------------------------------------------+ +| ``name`` | string | yes | none | N/A | The name of the package in which the | +| | | | | | resource is found. | ++------------------------+---------------+-----------+---------------+-------------------------------+----------------------------------------------+ +| ``version`` | string | yes | none | N/A | The version of the package. | ++------------------------+---------------+-----------+---------------+-------------------------------+----------------------------------------------+ + +.. _view_obj: +view Object +########### + ++------------------------+---------------+-----------+---------------+-------------------------------+-----------------------------------------------+ +| Property | Data Type | Required? | Default Value | Possible Values | Description | ++========================+===============+===========+===============+===============================+===============================================+ +| ``engine`` | string | yes | none | N/A | The engine that renders the view template. | +| | | | | | Two examples of rendering engines are | +| | | | | | Mustache and Handlebars. | ++------------------------+---------------+-----------+---------------+-------------------------------+-----------------------------------------------+ +| ``outputFormat`` | string | yes | none | N/A | The output format that a view template is | +| | | | | | rendered into, such as HTML, XML, and JSON. | ++------------------------+---------------+-----------+---------------+-------------------------------+-----------------------------------------------+ .. _yui_obj: @@ -418,8 +440,10 @@ Example "mojit": "PagedFlickr", "affinity": "common", "selector": "iphone", - "viewOutputFormat": "html", - "viewEngine": "mu", + "view": { + "outputFormat": "html", + "engine": "mu" + }, "url": "/static/PagedFlickr/views/index.mu.html" } From c531c0fcb421032ac8c64b28d188fc784b5f2a87 Mon Sep 17 00:00:00 2001 From: Joe Catera Date: Tue, 31 Jul 2012 09:20:44 -0700 Subject: [PATCH 41/45] Adding edits suggested by Drew. --- .../topics/mojito_resource_store.rst | 197 +++++++++--------- 1 file changed, 104 insertions(+), 93 deletions(-) diff --git a/docs/dev_guide/topics/mojito_resource_store.rst b/docs/dev_guide/topics/mojito_resource_store.rst index 26f277bfe..11b28b756 100644 --- a/docs/dev_guide/topics/mojito_resource_store.rst +++ b/docs/dev_guide/topics/mojito_resource_store.rst @@ -32,18 +32,17 @@ Reflection ########## The |RS| API has methods that can be used (as-is, no addons -required) to query for details about an application. +required) to query for details about an application. When you run the commands +``mojito compile`` and ``mojito gv`` use the |RS| API methods +``getResources`` and ``getResourceVersions``. + -.. I'd rather provide examples of API methods than mention that -.. ``mojito compile`` and ``mojito gv`` use the public API or -.. at least say what methods are used when those commands are run. Define/Register New Resource Types ################################## You can write custom |RS| addons using the aspect-oriented features of -the |RS| to define resource types and to map contexts to selectors. -The |RS| has aspect-oriented features because it is implemented as a +the |RS| to define resource types. The |RS| has aspect-oriented features because it extends `Y.Base `_, and the |RS| addons are implemented as `Y.Plugin `_. @@ -54,8 +53,9 @@ Extend/Modify Functionality of the |RS| ####################################### You can also write addons or create custom versions of built-in |RS| addons to modify -how the resource store works. Your addon could track new file types, augment the information -that the |RS| stores about files or code, or augment/replace the information returned by the |RS|. +how the resource store works. Your addon could map contexts to +:ref:`selectors `, track new file types, augment the information that the +|RS| stores about files or code, or augment/replace the information returned by the |RS|. .. _rs-resources: @@ -175,61 +175,61 @@ Metadata Object --------------- -+---------------------------+---------------+-----------+---------------------+-----------------------------------+------------------------------------------------+ -| Property | Data Type | Required? | Default Value | Possible Values | Description | -+===========================+===============+===========+=====================+===================================+================================================+ -| ``type`` | string | yes | none | See :ref:`Types of Resources | Specifies the type of resource. | -| | | | | `. | | -+---------------------------+---------------+-----------+---------------------+-----------------------------------+------------------------------------------------+ -| ``subtype`` | string | no | none | See the section | Some resource types have multiple subtypes | -| | | | | :ref:`Subtypes ` | that can be specified with ``subtype``. See | -| | | | | | :ref:`Subtypes ` for | -| | | | | | more information. | -+---------------------------+---------------+-----------+---------------------+-----------------------------------+------------------------------------------------+ -| ``name`` | string | yes | none | N/A | The name of the resource that is common to | -| | | | | | all versions (i.e., iPhone/Android, etc.) | -| | | | | | of the resource. Example: the name for | -| | | | | | for the resources ``index.iphone.mu.html`` | -| | | | | | and ``index.mu.html`` is ``index``. | -+---------------------------+---------------+-----------+---------------------+-----------------------------------+------------------------------------------------+ -| ``id`` | string | yes | none | N/A | A unique ID that is common to all versions | -| | | | | | of the resource. The ``id`` has the | -| | | | | | following syntax convention: | -| | | | | | ``{type}-{subtype}-{name}`` | -+---------------------------+---------------+-----------+---------------------+-----------------------------------+------------------------------------------------+ -| ``mojit`` | string | no | none | N/A | The mojit, if any, that uses this resource | -| | | | | | The value ``"shared"`` means the resource | -| | | | | | is available to all mojits. | -+---------------------------+---------------+-----------+---------------------+-----------------------------------+------------------------------------------------+ -| ``affinity`` | string | yes | See :ref:`Note | ``server``, ``client``, | The affinity of the resource, which | -| | | | About Default | ``common`` | indicates where the resource will be used. | -| | | | Values `. | | | -+---------------------------+---------------+-----------+---------------------+-----------------------------------+------------------------------------------------+ -| ``selector`` | string | no | "*" | N/A | The version of the resource. For example, a | -| | | | | | resource could have a version for iPhones, | -| | | | | | Android devices, fallbacks, etc. (This concept | -| | | | | | of version should not to be confused code | -| | | | | | revisions, which mark the change of something | -| | | | | | over time.) For more info, see | -| | | | | | :ref:`selector Property `. | -+---------------------------+---------------+-----------+---------------------+-----------------------------------+------------------------------------------------+ -| :ref:`source ` | object | yes | none | N/A | Specifies where the resource came from. | -| | | | | | See :ref:`source Object ` for | -| | | | | | details. | -+---------------------------+---------------+-----------+---------------------+-----------------------------------+------------------------------------------------+ -| ``url`` | string | no | none | N/A | The path used to load the resource | -| | | | | | onto the client. Used only for resources | -| | | | | | that can be deployed by reference to the | -| | | | | | client. | -+---------------------------+---------------+-----------+---------------------+-----------------------------------+------------------------------------------------+ -| :ref:`view ` | object | yes | none | N/A | Specifies the output format such as HTML, XML, | -| | | | | | JSON, etc., and the engine that renders the | -| | | | | | view template into the output format. Some | -+---------------------------+---------------+-----------+---------------------+-----------------------------------+------------------------------------------------+ -| :ref:`yui ` | object | no | none | N/A | The metadata about YUI modules. See the | -| | | | | | :ref:`yui Object ` for more | -| | | | | | details. | -+---------------------------+---------------+-----------+---------------------+-----------------------------------+------------------------------------------------+ ++---------------------------+---------------+---------------+---------------------+-----------------------------------+------------------------------------------------+ +| Property | Data Type | Required? | Default Value | Possible Values | Description | ++===========================+===============+===============+=====================+===================================+================================================+ +| ``type`` | string | yes | none | See :ref:`Types of Resources | Specifies the type of resource. | +| | | | | `. | | ++---------------------------+---------------+---------------+---------------------+-----------------------------------+------------------------------------------------+ +| ``subtype`` | string | no | none | See the section | Some resource types have multiple subtypes | +| | | | | :ref:`Subtypes ` | that can be specified with ``subtype``. See | +| | | | | | :ref:`Subtypes ` for | +| | | | | | more information. | ++---------------------------+---------------+---------------+---------------------+-----------------------------------+------------------------------------------------+ +| ``name`` | string | yes | none | N/A | The name of the resource that is common to | +| | | | | | all versions (i.e., iPhone/Android, etc.) | +| | | | | | of the resource. Example: the name for | +| | | | | | for the resources ``index.iphone.mu.html`` | +| | | | | | and ``index.mu.html`` is ``index``. | ++---------------------------+---------------+---------------+---------------------+-----------------------------------+------------------------------------------------+ +| ``id`` | string | yes | none | N/A | A unique ID that is common to all versions | +| | | | | | of the resource. The ``id`` has the | +| | | | | | following syntax convention: | +| | | | | | ``{type}-{subtype}-{name}`` | ++---------------------------+---------------+---------------+---------------------+-----------------------------------+------------------------------------------------+ +| ``mojit`` | string | no | none | N/A | The mojit, if any, that uses this resource | +| | | | | | The value ``"shared"`` means the resource | +| | | | | | is available to all mojits. | ++---------------------------+---------------+---------------+---------------------+-----------------------------------+------------------------------------------------+ +| ``affinity`` | string | yes | See :ref:`Note | ``server``, ``client``, | The affinity of the resource, which | +| | | | About Default | ``common`` | indicates where the resource will be used. | +| | | | Values `. | | | ++---------------------------+---------------+---------------+---------------------+-----------------------------------+------------------------------------------------+ +| ``selector`` | string | no | "*" | N/A | The version of the resource. For example, a | +| | | | | | resource could have a version for iPhones, | +| | | | | | Android devices, fallbacks, etc. (This concept | +| | | | | | of version should not to be confused code | +| | | | | | revisions, which mark the change of something | +| | | | | | over time.) For more info, see | +| | | | | | :ref:`selector Property `. | ++---------------------------+---------------+---------------+---------------------+-----------------------------------+------------------------------------------------+ +| :ref:`source ` | object | yes | none | N/A | Specifies where the resource came from. | +| | | | | | See :ref:`source Object ` for | +| | | | | | details. | ++---------------------------+---------------+---------------+---------------------+-----------------------------------+------------------------------------------------+ +| ``url`` | string | no | none | N/A | The path used to load the resource | +| | | | | | onto the client. Used only for resources | +| | | | | | that can be deployed by reference to the | +| | | | | | client. | ++---------------------------+---------------+---------------+---------------------+-----------------------------------+------------------------------------------------+ +| :ref:`view ` | object | yes, if | none | N/A | Specifies the output format such as HTML, XML, | +| | | ``type:view`` | | | JSON, etc., and the engine that renders the | +| | | | | | view template into the output format. | ++---------------------------+---------------+---------------+---------------------+-----------------------------------+------------------------------------------------+ +| :ref:`yui ` | object | no | none | N/A | The metadata about YUI modules. See the | +| | | | | | :ref:`yui Object ` for more | +| | | | | | details. | ++---------------------------+---------------+---------------+---------------------+-----------------------------------+------------------------------------------------+ .. _def_vals: @@ -241,23 +241,7 @@ Metadata Object on both client and server); however, the affinity for controllers comes from the file name, so there is no default. -.. _sel_prop: -selector Property -################# - -The **selector** is an arbitrary user-defined string, which is used to -*select* which version of each resource to use. The value of the ``selector`` -property is a string that must not have a period (``'.'``) or slash (``'/'``) in it. -In practice, it's suggested to use alphanumeric and hyphen ('-') characters only. - -The selector is defined in the ``application.json``, with the ``selector`` property. -Only one selector can be used in each configuration object identified by the -``setting`` property, which defines the context. - -The specified selectors must match the selector found in the -resource file names. So, for example, the view ``views/index.iphone.mu.html`` has -the selector ``iphone``. .. _src_obj: @@ -342,7 +326,7 @@ view Object yui Object ########## -The ``yui`` property of the metadata object is created by the ``yui`` |RS| addon. The +The ``yui`` property of the ``metadata`` object is created by the ``yui`` |RS| addon. The ``yui`` property can be any data type, but in general, it is an object containing metadata about YUI modules. You can think of the ``yui`` object as a container for the arguments to the ``YUI.add`` method that is used to register reusable YUI modules. @@ -350,14 +334,18 @@ arguments to the ``YUI.add`` method that is used to register reusable YUI module The following table lists the typical properties that are part of the ``yui`` object. -+------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ -| Property | Data Type | Required? | Default Value | Example Values | Description | -+========================+===============+===========+===============+===============================+=============================================+ -| ``name`` | string | yes | none | ``"scroll"`` | The name of the YUI module. | -+------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ -| ``meta`` | array | yes | none | ``["scroll","node","cache"]`` | Contains a list of YUI modules required by | -| | | | | | this resource. | -+------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ ++------------------------+---------------+-----------+---------------+-------------------------------+------------------------------------------------+ +| Property | Data Type | Required? | Default Value | Example Values | Description | ++========================+===============+===========+===============+===============================+================================================+ +| ``name`` | string | yes | none | ``"scroll"`` | The name of the YUI module. | ++------------------------+---------------+-----------+---------------+-------------------------------+------------------------------------------------+ +| ``meta`` | array | yes | none | ``["scroll","node","cache"]`` | Contains a list of YUI modules required by | +| | | | | | this resource. The ``meta`` object contains | +| | | | | | the same properties as the ``details`` | +| | | | | | object that is passed to the `YUI add method < | +| | | | | | http://yuilibrary.com/yui/docs/api/classes/YUI | +| | | | | | .html#method_add>`_. | ++------------------------+---------------+-----------+---------------+-------------------------------+------------------------------------------------+ .. _metadata-types: @@ -365,7 +353,7 @@ part of the ``yui`` object. Types of Resources ------------------ -The ``type`` property of the metadata object can have any of the following values: +The ``type`` property of the ``metadata`` object can have any of the following values: - ``config`` - a piece of configuration, sometimes for another resource - ``controller`` - the controller for a mojit @@ -391,14 +379,36 @@ For ``type:archetype``, the subtypes refers to the ``type`` described in the out the command ``mojito help create``. So, you could have ``subtype:app``, or ``subtype:mojit``. (There may be more in the future!) + +.. _sel_prop: + +selector Property +----------------- + +The **selector** is an arbitrary user-defined string, which is used to +*select* which version of each resource to use. The selector is defined in the +``application.json``, with the ``selector`` property. + +The value of the ``selector`` property is a string that must not have a +period (``'.'``) or slash (``'/'``) in it. In practice, it's suggested to use alphanumeric and +hyphen ('-') characters only. + +Only one selector can be used in each configuration object identified by the +``setting`` property, which defines the context. + +The specified selectors must match the selector found in the +resource file names. So, for example, the view ``views/index.iphone.mu.html`` has +the selector ``iphone``. + + .. _metatdata-versions: Resource Versions ----------------- -Resources can have many versions that are identified by the ``selector`` property of the -metadata object and the affinity. The selector is defined by the user and indicates the version of -the resource and the affinity is defined by the resource itself. +Resources can have many versions that are identified by the +:ref:`selector property ` and the affinity. The selector is defined by the user and +indicates the version of the resource and the affinity is defined by the resource itself. For example, developer might decide to use the selector ``selector: iphone`` for the iPhone version and ``selector: android`` for the Android version of a resource. Using these two @@ -466,7 +476,8 @@ of resource each file is, creates metadata about the resource, and then register During this process, the resource store also does the following: - pre-calculates ("resolves") which resource versions are used for each version of the mojit. -- also keeps track of application-level resources (archetypes, commands, config files, and middleware). +- also keeps track of application-level resources (archetypes, commands, config files, + and middleware). - provides methods and events, including those specialized for `aspect-orient programming (AOP) `_. - explicitly uses the addons :ref:`selector ` and :ref:`config `. From 6374c7290f6e6c3d917b7855538cd8c181a3d234 Mon Sep 17 00:00:00 2001 From: Joe Catera Date: Tue, 31 Jul 2012 11:19:21 -0700 Subject: [PATCH 42/45] Made more edits. --- .../topics/mojito_resource_store.rst | 31 ++++++++++++------- 1 file changed, 20 insertions(+), 11 deletions(-) diff --git a/docs/dev_guide/topics/mojito_resource_store.rst b/docs/dev_guide/topics/mojito_resource_store.rst index 11b28b756..6cbdc776a 100644 --- a/docs/dev_guide/topics/mojito_resource_store.rst +++ b/docs/dev_guide/topics/mojito_resource_store.rst @@ -22,6 +22,11 @@ Intended Audience Only advanced Mojito application developers needing finer grain control over the management of resources or to extend the functionality of the resource store should read this documentation. +Prerequisites +------------- + +- Understanding of ``aspect-orient programming (AOP) `_. +- Experience using _YUIPlugin. .. _intro-use: @@ -42,9 +47,9 @@ Define/Register New Resource Types ################################## You can write custom |RS| addons using the aspect-oriented features of -the |RS| to define resource types. The |RS| has aspect-oriented features because it extends -`Y.Base `_, and the |RS| addons -are implemented as `Y.Plugin `_. +the |RS| to define resource types. The |RS| has aspect-oriented features because it is +implemented as an extension of `Y.Base `_, and the +|RS| addons are implemented as `YUI Plugins `_. For example, you could write your own |RS| addon so that the Mojito command-line tool will register files and resources for your application. @@ -313,12 +318,16 @@ view Object +------------------------+---------------+-----------+---------------+-------------------------------+-----------------------------------------------+ | Property | Data Type | Required? | Default Value | Possible Values | Description | +========================+===============+===========+===============+===============================+===============================================+ -| ``engine`` | string | yes | none | N/A | The engine that renders the view template. | -| | | | | | Two examples of rendering engines are | -| | | | | | Mustache and Handlebars. | +| ``engine`` | string | yes | none | Any view engine found | The engine that renders the view template. | +| | | | | in ``addons/view-engines/`` | Two examples of rendering engines are | +| | | | | of the application. | Mustache and Handlebars. | +------------------------+---------------+-----------+---------------+-------------------------------+-----------------------------------------------+ | ``outputFormat`` | string | yes | none | N/A | The output format that a view template is | | | | | | | rendered into, such as HTML, XML, and JSON. | +| | | | | | The ``outputFormat`` matches the file | +| | | | | | extension of the view template. For example, | +| | | | | | the output format for ``index.mu.html`` would | +| | | | | | be HTML. | +------------------------+---------------+-----------+---------------+-------------------------------+-----------------------------------------------+ .. _yui_obj: @@ -463,7 +472,8 @@ Example How Does the Resource Store Work? ================================= -Understanding the |RS| will allow you to customize addons and debug your application. +Understanding the |RS| will allow you to debug your +application and write |RS| addons to customize how it works. Overview @@ -478,8 +488,7 @@ During this process, the resource store also does the following: - pre-calculates ("resolves") which resource versions are used for each version of the mojit. - also keeps track of application-level resources (archetypes, commands, config files, and middleware). -- provides methods and events, including those specialized for - `aspect-orient programming (AOP) `_. +- provides methods and events, including those specialized for AOP. - explicitly uses the addons :ref:`selector ` and :ref:`config `. In the following sections, we'll look at the process in a little more details. To see the code for @@ -722,7 +731,7 @@ Key Methods Accessing the Resource Store ```````````````````````````` -To access the |RS|, you call ``this.get('host')``. The method returns an object containing the +To access the |RS|, you call ``this.get('host')``. The method returns the |RS|. .. _anatomy-key_events: @@ -949,7 +958,7 @@ The |RS| comes with the following four built-in addons: - ``config`` - registers new resource type ``config`` found in JSON configuration files - - provides an API for reading both context and straight-JSON files + - provides an API for reading both contextualized and straight-JSON files - provides sugar for reading the application's dimensions - ``selector`` - decides the priority-ordered list (POSL) to use for a context From 008822c0ce4d5383a1dafcb5399ec10a10934d70 Mon Sep 17 00:00:00 2001 From: Joe Catera Date: Wed, 1 Aug 2012 11:36:29 -0700 Subject: [PATCH 43/45] Copy edited and fixed some reST formatting errors. --- .../topics/mojito_resource_store.rst | 80 +++++++++---------- 1 file changed, 38 insertions(+), 42 deletions(-) diff --git a/docs/dev_guide/topics/mojito_resource_store.rst b/docs/dev_guide/topics/mojito_resource_store.rst index 6cbdc776a..a6c66888d 100644 --- a/docs/dev_guide/topics/mojito_resource_store.rst +++ b/docs/dev_guide/topics/mojito_resource_store.rst @@ -25,8 +25,8 @@ of resources or to extend the functionality of the resource store should read th Prerequisites ------------- -- Understanding of ``aspect-orient programming (AOP) `_. -- Experience using _YUIPlugin. +- Understanding of `aspect-orient programming (AOP) `_. +- Experience using |YUIPlugin|_. .. _intro-use: @@ -37,9 +37,9 @@ Reflection ########## The |RS| API has methods that can be used (as-is, no addons -required) to query for details about an application. When you run the commands -``mojito compile`` and ``mojito gv`` use the |RS| API methods -``getResources`` and ``getResourceVersions``. +required) to query for details about an application. For example, whe you run the commands +``mojito compile`` and ``mojito gv``, the |RS| API methods ``getResources`` and +``getResourceVersions`` are called to get information about your application. @@ -259,7 +259,7 @@ source Object | ``fs`` | object | yes | none | N/A | Contains the filesystem details of a | | | | | | | resource. See :ref:`fs Object `. | +------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ -| ``pkg`` | object | yes | none | N/A | Contains the ``npm``package details of a | +| ``pkg`` | object | yes | none | N/A | Contains the ``npm`` package details of a | | | | | | | resource. See :ref:`pkg Object `. | +------------------------+---------------+-----------+---------------+-------------------------------+---------------------------------------------+ @@ -350,10 +350,10 @@ part of the ``yui`` object. +------------------------+---------------+-----------+---------------+-------------------------------+------------------------------------------------+ | ``meta`` | array | yes | none | ``["scroll","node","cache"]`` | Contains a list of YUI modules required by | | | | | | | this resource. The ``meta`` object contains | -| | | | | | the same properties as the ``details`` | -| | | | | | object that is passed to the `YUI add method < | -| | | | | | http://yuilibrary.com/yui/docs/api/classes/YUI | -| | | | | | .html#method_add>`_. | +| | | | | | the same properties as the ``details`` object | +| | | | | | that is passed to the `YUI add method `_. | +------------------------+---------------+-----------+---------------+-------------------------------+------------------------------------------------+ @@ -396,7 +396,7 @@ selector Property The **selector** is an arbitrary user-defined string, which is used to *select* which version of each resource to use. The selector is defined in the -``application.json``, with the ``selector`` property. +``application.json`` with the ``selector`` property. The value of the ``selector`` property is a string that must not have a period (``'.'``) or slash (``'/'``) in it. In practice, it's suggested to use alphanumeric and @@ -517,15 +517,24 @@ Resolution and Priorities The resolving of resource version happens in the |RS| ``preload`` method as well. The act of resolving the resource versions is really just resolving the affinities and selectors. See :ref:`Resource Versions ` for a brief explanation about how affinities -and selectors determine different versions of a resource. +and selectors determine different versions of a resource. The following sections discuss what the +|RS| uses to resolve versions and create a **priority-ordered selector list (POSL)**. + +.. _resolution-affinities: + +Affinities +########## + +The choice of a resource version depends on the **affinity** as well. If we're resolving versions +for the server, versions with ``affinity:server`` will have higher priority than +``affinity:common``, and ``affinity:client`` will be completely ignored. .. _resolution-selectors: Selectors ######### -The order of the selectors is defined by a **priority-ordered selector list (POSL)**. The POSL -depends on the runtime context. +The order of the selectors is defined by a POSL, which depends on the runtime context. Suppose an application has the following resources: @@ -541,15 +550,6 @@ context" because not all versions might exist for all selectors. In the example ``controller.server.iphone.js`` didn't exist, we should still do the right thing for context ``{device:iphone}``. -.. _resolution-affinities: - -Affinities -########## - -The choice of a resource version depends on the **affinity** as well. If we're resolving versions -for the server, versions with ``affinity:server`` will have higher priority than -``affinity:common``, and ``affinity:client`` will be completely ignored. - .. _resolution-sources: Sources @@ -581,7 +581,7 @@ That means that if there exists, for example, both a ``controller.server.js`` an will be used because its selector is a higher priority match than its affinity. -All this is pre-calculated for each resource, for each possible runtime configuration (client or +All this is pre-calculated for each resource and for each possible runtime configuration (client or server, and every appropriate runtime context). .. _how-get_data: @@ -631,7 +631,7 @@ documentation, you should be able to create your own custom |RS| addons. Anatomy of a |RS| Addon ----------------------- -The resource store addons are implemented using the _|YUIPlugin| mechanism. In essence, a Mojito +The resource store addons are implemented using the |YUIPlugin|_ mechanism. In essence, a Mojito addon is a YUI plugin, so the skeleton of a |RS| addon will be the same as a YUI Plugin. See the |RSC|_ for the parameters and return values for the |RS| methods. @@ -653,7 +653,7 @@ Key Methods - :js:func:`preloadResourceVersions` - :js:func:`resolveResourceVersions` - After ``preload`` has finished executing, you can call with + After ``preload`` has finished executing, you can call ``afterHostMethod('preload', ...)``. :param Object config: Contains configuration information with the following properties: @@ -696,11 +696,11 @@ Key Methods .. js:function:: findResourceVersionByConvention() This method is called on each directory or file being walked and is used to decide if the - path is a resource version. The return value can be a bit confusing, so read API docs carefully - and feel free to post any questions that you have to the + path is a resource version. The return value can be a bit confusing, so read the API + documentation carefully and feel free to post any questions that you have to the `Yahoo! Mojito Forum `_. - Typically, you would hook into this method with the ``afterHostMethod()`` method to register + Typically, you would hook into this method with the ``afterHostMethod`` method to register your own resource version types. This method should work together with your own version of the ``parseResourceVersion`` method. @@ -751,7 +751,7 @@ This event is called when the resources in a mojit are resolved. getMojitTypeDetails ``````````````````` -This event is called during runtime as Mojito creates an "instance" used to dispatch a mojit. +This event is called during runtime as Mojito creates an *instance* used to dispatch a mojit. .. _creating_rs_addons-ex: @@ -959,12 +959,12 @@ The |RS| comes with the following four built-in addons: - ``config`` - registers new resource type ``config`` found in JSON configuration files - provides an API for reading both contextualized and straight-JSON files - - provides sugar for reading the application's dimensions + - provides sugar for reading an application's dimensions - ``selector`` - decides the priority-ordered list (POSL) to use for a context - looks for ``selector`` in ``application.json``. Because - ``application.json`` is a context configuration file, the ``selector`` can be contextualized - there. + ``application.json`` is a context configuration file, the ``selector`` can + be contextualized there. - ``url`` - calculates the static handler URL for appropriate resources (and resource versions) - stores the URL in the ``url`` key of the resource @@ -990,7 +990,7 @@ We will be examining the ``selector`` and ``url`` addons to help you create cust those addons. We do not recommend that you create custom versions of the ``config`` or ``yui`` addons, so we will not be looking at those addons. Also, this documentation explains what the |RS| expects the addon to do, so you can create your own version of the addons. -To learn what a |RS| built-in addons do, please refer to the |RSC|_ in the API documentation. +To learn what the |RS| built-in addons do, please refer to the |RSC|_ in the API documentation. .. _custom-selector: @@ -1004,8 +1004,8 @@ Description ``````````` If you wish to use a different algorithm for to determine the selectors to use, -you can implement your own version of this |RS| addon. It will need to go in the file -``addons/rs/selector.server.js`` of your application. +you can implement your own version of this |RS| addon in the +``addons/rs/selector.server.js`` file of your application. .. _selector-reqs: @@ -1050,8 +1050,8 @@ The ``url`` addon calculates and manages the static handler URLs for resources. The addon is not used by resource store core, but used by the static handler middleware. If you wish to use a different algorithm to determine the URLs, you can -implement your own version of this |RS| addon. It'll need to go in -``addons/rs/url.server.js`` in your application. +implement your own version of this |RS| addon in the +``addons/rs/url.server.js`` file of your application. After the method ``preloadResourceVersions`` sets ``res.url`` to the static handler URL for the resource, the method ``getMojitTypeDetails`` sets the mojit's ``assetsRoot``. @@ -1068,10 +1068,6 @@ Your addon is required to do the following: - Set the ``url`` property in the resource ``metadata`` object. - - - - .. |RS| replace:: Resource Store From bd2a299f6a485ac459ea9954a31e5c19ff36c677 Mon Sep 17 00:00:00 2001 From: Joe Catera Date: Thu, 2 Aug 2012 12:13:15 -0700 Subject: [PATCH 44/45] Added a prerequisite and made a couple of edits. --- .../topics/mojito_resource_store.rst | 33 +++++++++++-------- 1 file changed, 20 insertions(+), 13 deletions(-) diff --git a/docs/dev_guide/topics/mojito_resource_store.rst b/docs/dev_guide/topics/mojito_resource_store.rst index a6c66888d..adf98ef7c 100644 --- a/docs/dev_guide/topics/mojito_resource_store.rst +++ b/docs/dev_guide/topics/mojito_resource_store.rst @@ -25,8 +25,12 @@ of resources or to extend the functionality of the resource store should read th Prerequisites ------------- -- Understanding of `aspect-orient programming (AOP) `_. -- Experience using |YUIPlugin|_. +In addition to being an advanced Mojito user, you should also understand the following before +using the |RS|: + +- |YUIPlugin|_ +- `Mojito addons <../topics/mojito_extensions.html#addons>`_ +- `aspect-orient programming (AOP) `_. .. _intro-use: @@ -37,7 +41,7 @@ Reflection ########## The |RS| API has methods that can be used (as-is, no addons -required) to query for details about an application. For example, whe you run the commands +required) to query for details about an application. For example, when you run the commands ``mojito compile`` and ``mojito gv``, the |RS| API methods ``getResources`` and ``getResourceVersions`` are called to get information about your application. @@ -75,7 +79,7 @@ What is a Resource? In Mojito, the meaning of the term **resource** is different depending on the context. Before we discuss the |RS| in more detail, let's differentiate and define the definition of -**resource** in the contexts of Mojito and the |RS|. +resource in the contexts of Mojito and the |RS|. .. _what-to_mojito: @@ -105,7 +109,7 @@ Resource Versions Because there can be multiple files which are all conceptually different versions of the same thing (e.g., ``views/index.mu.html`` and ``views/index.iphone.mu.html``), the |RS| defines -**resource version** as the metadata about each file and **resource** as the metadata +**resource version** as the metadata about each file and resource as the metadata about the file chosen among the possible choices. The process of choosing which version of a resource to use is called *resolution* (or @@ -171,7 +175,7 @@ Intro The RS uses metadata to track information about each resource. This metadata is used by the rest of Mojito to find, load, and parse the resources. The metadata is generated by the |RS| or by |RS| -addons--it has no representation on the filesystem. +addons |---| it has no representation on the filesystem. .. _metadata-obj: @@ -240,7 +244,7 @@ Metadata Object .. admonition:: Note About Default Values - Some values for the properties of the metata object do have defaults, but it depends on + Some values for the properties of the metadata object do have defaults, but it depends on the value of the ``type`` property and/or comes from the file name of the resource being represented. For example, the affinity of views is ``common`` (because views are used on both client and server); however, the affinity for controllers comes @@ -385,7 +389,7 @@ resource of ``type:addon`` might have subtypes, such as ``subtype:ac`` for AC ad ``subtype:view-engine`` for view engines, or ``subtype:rs`` for |RS| addons. For ``type:archetype``, the subtypes refers to the ``type`` described in the output from -the command ``mojito help create``. So, you could have ``subtype:app``, or +the command ``mojito help create``. So, you could have ``subtype:app`` or ``subtype:mojit``. (There may be more in the future!) @@ -525,7 +529,7 @@ and selectors determine different versions of a resource. The following sections Affinities ########## -The choice of a resource version depends on the **affinity** as well. If we're resolving versions +The choice of a resource version depends on the affinity. If we're resolving versions for the server, versions with ``affinity:server`` will have higher priority than ``affinity:common``, and ``affinity:client`` will be completely ignored. @@ -555,7 +559,7 @@ context" because not all versions might exist for all selectors. In the example Sources ####### -The final consideration for priority is the **source**. Mojit-level versions have higher priority +The final consideration for priority is the source. Mojit-level versions have higher priority than shared versions. Let's take a different application with the following resources: - ``mojits/Foo/models/bar.common.js`` @@ -570,7 +574,7 @@ priority than the shared one. Relationships ############# -Finally, there's a **relationship** between the different types of priority. +Finally, there's a relationship between the different types of priority. #. The source has the highest priority. #. The selector has the next highest priority. @@ -669,7 +673,7 @@ Key Methods .. js:function:: preload() - Addons are loaded during this method, so it's not possible to call before ``preload`` + Addons are loaded during this method, so they cannot be called before ``preload`` is called. @@ -1076,4 +1080,7 @@ Your addon is required to do the following: .. |YUIPlugin| replace:: YUI Plugin .. _YUIPlugin: http://yuilibrary.com/yui/docs/plugin/ .. |SS| replace:: server.store.js -.. _SS: https://github.com/yahoo/mojito/blob/develop/source/lib/store.server.js \ No newline at end of file +.. _SS: https://github.com/yahoo/mojito/blob/develop/source/lib/store.server.js +.. |--| unicode:: U+2013 .. en dash +.. |---| unicode:: U+2014 .. em dash + :trim: \ No newline at end of file From aed2b0ed3d151908c1b023a3a808638c437b3ae1 Mon Sep 17 00:00:00 2001 From: Joe Catera Date: Thu, 2 Aug 2012 12:14:16 -0700 Subject: [PATCH 45/45] Added resource store doc to index. --- docs/dev_guide/topics/index.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/dev_guide/topics/index.rst b/docs/dev_guide/topics/index.rst index b7a4bd82f..b9a4381d2 100644 --- a/docs/dev_guide/topics/index.rst +++ b/docs/dev_guide/topics/index.rst @@ -22,3 +22,4 @@ Table of Contents mojito_extensions mojito_using_contexts mojito_npm + mojito_resource_store