Creating Skeletons

Expansive skeletons are integrated packages that provide starting points for web sites or web applications for specific environments. Skeletons often include starter web pages, layouts, partial pages, stylesheets, scripts and other required packages — everything a user needs to start using a given environment. For example: the exp-semantic-skeleton is an ideal starter when creating a web site using the Semantic-UI client library.

Packaged for Delivery

Skeletons are packaged as a single Pak package and are installed by a simple pak install command. However skeletons may depend on other packages, plugins or skeletons. This flexibility of Expansive skeletons is provided by the Pak package manager and its ability reference and manage dependent packages. Please read the following as background to understand the capabilities of Pak and packages.

• Creating Packages, and
• Publishing Packages

Note that skeletons are used to start web sites or applications instead of the user running expansive init. Skeletons are not installed into existing web sites or applications.

Initializing a Skeleton

To get started building a skeleton, create a directory with the same name as the name of your skeleton. By convention, the name should use a -skeleton suffix. Then run expansive init in that directory. For example:

This will create the following files and directories:

Package Dependencies

A skeleton may provide everything itself, or it may build upon other skeletons or packages. These other packages are called dependencies. A skeleton can specify all its required dependencies so that when users install the skeleton with pak install, Pak will automatically download and install all dependent packages.

A skeleton specifies dependent packages in the dependencies property of its package.json file. In this example, we'll specify the Bootstrap client library as a dependency. Bootstrap in-turn, depends on jQuery, so we don't need to explicitly specify jQuery as a dependency. In fact, it is better that we do not, so that Bootstrap can control the version of jQuery it requires. For example:

The bootstrap dependency version is a SemVer compliant version expression that defines what versions of Bootstrap are acceptable for our skeleton. The leading ^ prefix indicates that public releases that are compatible with Bootstrap 3.3 are acceptable. See the Pak Versions documentation for more information. In general, try to specify the most liberal version criteria, while still ensuring compatibility and correct operation of your skeleton, should new versions of dependencies be released. i.e. You don't want the skeleton to break because Bootstrap 4.0 is released and it introduces breaking changes.

Skeleton Files

The skeleton can provide layouts, partial pages, content pages, scripts, stylesheets, assets and fonts. Use the appropriate directories:

• layouts — for layout pages
• partials — for partial pages
• contents — for content web pages
• scripts — for content web pages

The contents/lib directory should be reserved for Paks to export their libraries and you should not distribute skeleton content in the lib directory. There is no firm rule regarding where to put scripts or stylesheet, but many packages put stylesheets under contents/css and scripts under contents/script.

Skeleton Configuration

The skeleton should supply the default expansive.json for the user's web site and it should provide appropriate configuration for all the Expansive services used by the skeleton. Where possible, the skeleton should configure a debug and release configurations. For example, the esp-angular-skeleton provides the following default configuration.

Blending Package.json

When Pak installs a skeleton, it will first install the dependent packages. As such, subsequent packages and the skeleton itself may need to blend configuration from its own package.json into the web site package.json. Pak provides three facilities to assist blending package configuration.

• pak.blend — to blend properties into another package.json.
• pak.manage — to blend other JSON files.
• pak.export — to export files from the package to another location.

pak.blend

Blending is a process of merging a package's JSON properties into the application. The pak.blend property specifies a collection of properties that are to be blended into the top level of the web site's package.json. For example:

This will blend all the properties under, and including "pak" into the top level of the package.json. A question ? prefix may be used to signify that the property should be blended only if it does not already exist. See Blending Properties in the Pak documentation for more details about blending.

pak.manage

The pak.manage property can list an array of file to blend. For example:

This instructs Pak to also blend the properties in the expansive.json and esp.json files. If the files do not exist, they will be created.

pak.export

During installation, files may be exported from the paks directory into the lib directory. This can be useful to select a subset of package files that must be deployed with the application. For example, a package or skeleton may export library scripts that are needed at runtime into the lib directory.

See Exporting Runtime Files in the Pak documentation for more details about exporting.

Publishing Skeletons

To publish a skeleton first commit to GitHub or a similar Git repository. Then tag a release with the version of the release. After this, the package can be installed using Pak via:

Register in the Pak Catalog

You may optionally register your skeleton in the Pak catalog, thereafter you can install the skeleton by your chosen skeleton name. For example:

See Publishing Packages for more information about publishing in the Pak catalog.

Sample Skeletons

• exp-html-skeleton — Expansive HTML5 Skeleton
• exp-bootstrap-skeleton — Expansive Bootstrap Skeleton
• exp-semantic-skeleton — Expansive Semantic-UI Skeleton
• esp-angular-skeleton — ESP AngularJS Skeleton
• esp-html-skeleton — ESP HTML5 Skeleton