Pyramid js: A dependency manager to load/combine web development files

Aug 14, 2011 by     No Comments    Posted under: Software Development

Pyramid js is a javascript library for managing dependencies.  While there are a few javascript dependency managers, Pyramid has some unique features:

  • It handles any file type (js, css, html, myFileType, …) and lets you define how it should be included/rendered.
  • During development, it can automatically insert the contents of a file. Now you can separate your views/templates and have the contents inserted automatically. Knockout/jquery.tmpl users will find this feature particularly useful.
  • Combines files for you in javascript (no need for external tools! Just use your browser.)
  • Lets you define your includes in one place. (You don’t need to update each header every time a file is renamed, added, etc!)

 

Download Pyramid 1.0.1

 

Note: To combine files or insert file content directly into a page, Chrome must be opened with –allow-file-access-from-files option. More details can be found in the Renderers section.

 

Basic usage of Pyramid

  1. Creating the dependency loader file
  2. Loading dependencies in web pages
  3. Combine files for a release
  4. Renderers
    1. Default renderers
    2. Defining custom renderers for dependencies
    3. Determining where dependencies are rendered
  5. Documentation

 

1. Creating the dependency loader file

This file allows developers to define groups of files into a dependency called dependency groups. Different dependency groups can be chained to control the order that files are loaded.

An example dependency loader file is shown below.

dependencyLoader.js

//set the rootPath.  The rootPath determines 
//the base directory where all the files get loaded from.
Pyramid.rootPath = './';
 
//Set up file dependencies
Pyramid.newDependency({
    name: 'standard',
    files: [
    'standardResources/jquery.1.6.1.min.js'
    ]
});
 
Pyramid.newDependency({
name:'lookAndFeel',
files: [
	'styles.css',
	'customStyles.css',
        'createAnimations.js'
    ]
});
 
Pyramid.newDependency({
name:'main',
files: [
	'createNamespace.js',
	'models/person.js',
	'init.js'
    ],
    dependencies: ['standard','lookAndFeel']
});

2. Loading dependencies in web pages

Load the dependencies by including the following in the header of each html page

<script type="text/javascript" src="standardResources/Pyramid-1.0.1.js"></script><script type="text/javascript" src="dependencyLoader.js"></script><script type="text/javascript">// <![CDATA[
             Pyramid.load('main');
// ]]></script>

Using the above, we can now add, move, and rename files in the dependencyLoader without having to update all our html pages.

3. Combining files for a release

To combine files, a buildNodes.html file is included with the Pyramid source code.

Modify these two variables in the html source according to your project and then open the modified file in your browser.

var dependencyGroupToCombine = 'main';
var excludeDependencies = ['standard'];

Depending on the number of different file types you are trying to combine, the output will look something like the following.

 

Now you can just save the content of these files to a single js, css, etc files and include them in your web pages for release. Note: the includes textarea generates the code required to include the files that were excluded from the join process.

*Note: Chrome must be opened with –allow-file-access-from-files option to use this feature.  I believe other browsers do not require this option but I have not tested this feature with other browsers.

“C:\Documents and Settings\Developer\Local Settings\Application Data\Google\Chrome\Application\chrome.exe” –allow-file-access-from-files

4. Renderers

Renderers determine how dependencies are included in an html file.

4.1 Default Renderers

Renderers currently included in Pyramid are

  • css – Outputs html to include css dependencies
  • js – Outputs html to include js dependencies
  • *Files with no extensions – Content of files is included in the web page

*Note: To include file content directly into the html page, Chrome must be opened with –allow-file-access-from-files option.  I believe other browsers do not require this option but I have not tested this feature with other browsers.

“C:\Documents and Settings\Developer\Local Settings\Application Data\Google\Chrome\Application\chrome.exe” –allow-file-access-from-files

4.2 Defining custom renderers for dependencies

Renderers are created using the Pyramid.setTypeRenderer(options) function (see documentation).  An example of a renderer is shown below for renderering javascript files.

Pyramid.setTypeRenderer({
	name: 'js',
	isExtension: true,
	template: '<script type="text/javascript" src="${file}"></script>
 
\n'
	});

To retrieve the dependency file path, just use the ${file} variable. If no template is defined, then the contents of the file are inserted directly into the html. An example of this is shown below for jquery.tmpl templates.

//the contents of files with the extension .tmpl can now be included in web pages using Pyramid
Pyramid.setTypeRenderer({
	name: 'tmpl',
	isExtension: true
	});

As previously stated in the Default Renderers section, to include the contents of a file, your browser may need to be opened with special options.

4.3 Determining where dependencies are rendered

Where a particular dependency is written in the web page can be defined by setting the Pyramid.insertContentMethod function.  The default insertContentMethod is shown below.

Pyramid.insertContentMethod = function (content) { document.write(content); };

 

5. Documentation

Pyramid.newDependency(options) Creates a new dependency group.  If the group already exists, an error is thrown. Parameters:options – an object with the following properties

  • options.name(required) – dependency group name used to reference the the new dependency
  • options.files(optional) – array of file paths relative to root
  • options.dependencies(optional) – array of parent dependency group names.  These dependencies will be loaded before the newly created dependency

Pyramid.rootPath Public property that determines the base directory where all the files get loaded from. Pyramid.load(depGroupName1, depGroupName2, …) Loads the dependencies passed as arguments Parameters: Simply list the dependency group names that need to be loaded Pyramid.getIncludeString(dependencyGroupName) gets the include string of all renderers combined eg … <script type=”text/javascript” src=”myDep.js”></script>… Parameters: dependencyGroupName – name of dependencies group Return: string containing include text Pyramid.setTypeRenderer(options) Determines how a file is rendered for inclusion in a webpage Parameters:options – an object with the following properties

  • options.name – name of the renderer
  • options.isExtension – determines if the name is an extension or if it can be referenced explicitly for renderering. For now, this feature is in testing so an extension should always be used.
  • options.template (optional) – template used to render a file for inclusion. Template uses the variable ${file} to represent the path to the file to be used for rendering.

Pyramid.insertContentMethod = function(content) Determines how dependencies are written to the web page. Sometimes developers may want to change where dependencies are included. In these cases, insertContentMethod can be redefined to fit the developer’s needs. For example:

Pyramid.insertContentMethod = function(content){ $(‘.footer’).html(content); };

Got anything to say? Go ahead and leave a comment!