Clone wiki

MinCat / Directives

MinCat Script Directives

MinCat provides support for three new in-line directives to help control the minimization process. These directives are specially-formed JavaScript comments that give MinCat extra information about how to handle your JavaScript.

Although simple to use, these directives open up exciting new ways to organize and structure your client-side scripts.

Skip Minimize

The /* skip minimzie */ directive causes MinCat to avoid minimizing whatever file it appears in. This overrides MinCat's behavior, even if the file it otherwise included in your project file or specified as part of a minimization context.

When organizing JavaScript, you often end up with scripts that are not directly useful, but instead serve to augment other scripts. For example, consider a abstract-widget.js file. Although many scripts may subclass this widget, you may never want to load abstract-widget.js all by itself on a page. The only reason to load this file is when another script has required it. When another script requires it, the contents of the abstract-widget.js file will be minimized along with the rest of the concatenated source anyway. Because minimization is not a quick process, you may want to skip minimizing abstract-widget.js by itself, knowing that it will be rolled up and minimized into whatever other files need it.

Require

The /* @require "filename.js" */ directive instructs MinCat that the current file depends on code from another file.

When the current file is minimized, all required external files will be collected, sorted into the correct order, reduced to a distinct list, and concatenated in front of the file that requires them.

Therefore, the resulting minimized file will contain everything it needs to function.

When MinCat processes the list of @require directives, it does so with the current minimization context in mind. Minimization contexts may indicate that specific files are considered "library" code, and available on every page in your site. These files are minimized separately for that context, so the user's browser has a better chance to cache them.

Meanwhile, any file is free to @require library code. When MinCat encounters a @require directive that points to known library code in the current context, it will ignore that @require directive.

Read about minimization contexts for more details.

Include

The /* @include "filename.js" */ directive causes MinCat to include the complete contents of the specified file directly in-line, in place of the directive.

Most use cases will call for @require instead of @include. Usage of @include should be reserved for advanced scenarios. Specifically, if you find yourself using the @include directive to re-use code, think again. There are better ways to do that.

Instead, @include provides the ability to create JavaScript assemblies. With careful use of @include, it is possible to design JavaScript code with protected access, or partial class structures:

var GlobalObject = (function () {
	"use strict";

	var internal = {};

	// Any file referenced with @require can only see GlobalObject and the
	// properties that it exposes.
	/* @require "Access to GlobalObject Only.js" */

	// However, because @include is replaced in-line, all @included files
	// have access to both GlobalObject and the "internal" variables
	// captured in the current scope.
	/* @include "Access to Internal and GlobalObject.js" */

	function GlobalObject() {
		var instance = {};

		// Files @included here will have access to GlobalObject, internal,
		// and the instance variables.
		/* @include "Access to Internal, Instance, and GlobalObject.js" */
	}

	return GlobalObject;
}());

Updated