-
Notifications
You must be signed in to change notification settings - Fork 0
Packages
This document explains how Maqetta can use the Packages specification to identify the various resources needed by the application.
- Use package.json to describe a library and point to Maqetta required resources (i.e. widget metadata).
- Allow Maqetta resources to reside in a package separate from the main library code (i.e. one package for Dijit, another package for widget metadata).
Here's a sample package.json file, using the one from the Dijit package as a starting point:
{
"name": "dijit",
"version": "1.7",
"main": "main",
"dependencies": {
"dojo": "current"
},
"description": "Dijit provides a complete collection of user interface controls based on Dojo, giving you the power to create web applications that are highly optimized for usability, performance, internationalization, accessibility, but above all deliver an incredible user experience.",
"licenses": [
{
"type": "AFLv2.1",
"url": "http://trac.dojotoolkit.org/browser/dojo/trunk/LICENSE#L43"
},
{
"type": "BSD",
"url": "http://trac.dojotoolkit.org/browser/dojo/trunk/LICENSE#L13"
}
],
"bugs": "http://bugs.dojotoolkit.org/",
"keywords": ["JavaScript", "Dojo", "Widget"],
"homepage": "http://dojotoolkit.org/",
"dojoBuild": "dijit.profile.js",
"overlays": {
"oam": {
"directories": {
"metadata": "metadata/library"
}
},
"maqetta": {
"directories": {
"theme_metadata": "metadata/themes"
},
"scripts": {
"widget_metadata": "metadata/widgets.json",
"library": "metadata/library.js"
}
}
}
}
Many of these elements are explained in the Packages Specification. What follows is an explanation of the Maqetta additions. Note, as per the Packages spec, any directories or files are relative to package.json.
overlays.oam.directories.metadata
- A directory of OAM files. The directory tree structure should match that of the library code files. For example, given a Dijit widget located at dijit/form/Button.js, the matching OAM file would reside at [overlays.oam.directories.metadata]/dijit/form/Button_oam.json.
overlays.maqetta.directories.theme_metadata
- A directory containing theme files.
overlays.maqetta.scripts.widget_metadata
- A JSON file which provides Maqetta-specific metadata for widgets.
overlays.maqetta.scripts.library
- A JavaScript file providing callbacks ("helper functions") which operate at the library level (as opposed to being widget-specific). The callback functions are used to extend the default functionality of Maqetta and to provide detailed library information.
It is possible that a library package may not contain all of the resources that Maqetta requires. For example, a library package may be available from a repository (i.e. Dojo Foundation Packages Repository), but the metadata package could be provided elsewhere. For that reason, we should support metadata-only packages, which depend on the library package.
This is easily achieved by using Packages' dependencies element. For example, given this (partial) package.json from a library package:
{
"name": "library",
"version": "1.0"
"directories": {
"lib": "library"
}
}
we can construct a metadata-only package like so:
{
"name": "library-maq",
"dependencies": {
"library": "1.0"
},
"overlays": {
"oam": {
"directories": {
"metadata": "metadata/library"
}
},
"maqetta": {
"directories": {
"theme_metadata": "metadata/themes"
},
"scripts": {
"widget_metadata": "metadata/widgets.json",
"library": "metadata/library.js"
}
}
}
}
An older wiki page (Library Packages) goes into a bit more detail.
Maqetta locates library files using the widget metadata (overlays.maqetta.scripts.widget_metadata). When writing the widget metadata files, if you are referring to a library file, you should specify a URL relative to the metadata file. Whether the package is complete or the metadata is split from the library code, the metadata file should be written the same. For example:
package layout:
+ package.json
+ awesomeLib/
+-- main.js
+-- awesome.js
+ metadata
+-- awesomeLib/
+-- main_oam.json
+-- awesome_oam.json
package.json:
{
"name": "awesomeLib",
"overlays": {
"oam": {
"directories": {
"metadata": "metadata/awesomeLib"
}
}
}
}
metadata/awesomeLib/awesome_oam.json:
{
...
"require": [
{
"type": "javascript",
"src": "awesome.js",
"$library": "awesomeLib"
}
],
"library": {
"awesomeLib": {
"src": "../../awesomeLib"
}
},
...
}
In this case, since the require statement for awesome.js has a $library property, the full URL for the resource is a combination of the sources from library and require -- ../../awesomeLib/awesome.js.
The Packages spec already specified a good system for dependencies, which we can leverage for specifying a dependency between widget libraries.
There remains the question of how Maqetta makes use of that information. If library Show depends on library Stage, then when Maqetta adds a Show widget to the page, it should first add the main JS file from Stage, if necessary.
According to the Packages spec, a package.json file should specify one of main or directories.lib. If main, which points to a JS file, then that may satisfy our requirements -- Maqetta would add the main file of a library dependency.
If package.json specifies directories.lib, then it isn't straight forward to figure out what Maqetta should add in this case. Also, in Maqetta, we may not wish to load the main file of one library when loading widgets of a dependent one (although I assume the latter case would be rare).
Proposal:
In the case where the library and metadata are in different packages and the library's package.json only specifies
directories.lib, then the metadata package will need to specifymain.
Maqetta needs to know the base directory for the library code files, in order to do proper URL mapping from within the user's workspace.
The Packages specification states that the package.json file must specify either main or directories.lib. The latter gives us exactly what we need in this case. But what do we do with main?
Proposal:
In the case where the library and metadata are in different packages and the library's package.json only specifies
main, then the metadata package will need to specifydirectories.lib.
The Packages 1.0 Spec says,
Package managers and loaders should ignore unknown fields in the package descriptor file.
The UncommonJS Packages spec states,
Any properties of
package.jsonnot specified here must occur under an "overlays" mapping.
For that reason, I have chosen to specify the OAM and Maqetta metadata information inside of overlays properties.
The
dependencieselement was indeed meant to allow a "choice" of dependencies, and the order was explicit, even though the dependencies choice is specified as an object hash (instead of array). Thinking went that most implimentations keep object order (even though not in spec) and that ES5 did spec object hash order.
Library Packages - An older wiki page which details how to define package dependencies when the library code and metadata are contained in separate packages.