Understanding Paths

Understanding Paths

Paths are a simple way to tell curl.js where to find your modules. Every dev wants to structure her/his project by her/his own best practices. We're not going to try to force you to do it our way. But since curl.js can't read your mind, you must tell it where to find your modules.

Note: paths are not as precise as packages. Packages are the preferred method to organize your code and to configure curl.js. Paths, however, are easy for smallish projects and may be a good choice for prototyping.

Simple Paths

curl.js uses a config property called paths that acts like a hash map. The properties (a.k.a. keys) are typically module ids or package names. The values are paths to the locations of those modules or packages.

A typical config might look like this:

var mycfg = {
	baseUrl: '/path/to/top/of/frontend/code',
	paths: {
		curl: 'awesome-oss/curl',
		my: 'my', // this isn't actually needed since it is the default
		other: '../../other/third-party/js'
	}
};

In this scenario, curl.js will look for modules and other resources that start with "curl", "my", and "other" in specific locations. Examples:

• "curl/loader/cjsm11": "/path/to/top/of/frontend/code/awesome-oss/curl/loader/cjsm11"
• "my/app/controller": "/path/to/top/of/frontend/code/my/app/controller"
• "other/junk": "/path/to/top/of/other/third-party/js/other/junk"

During url resolution, the property names (keys) in paths are matched to the start of the module id being required. If there's a match, the path information is prepended. If a baseUrl is also specified, it is prepended as well.

Complex Paths

Paths may be specified at multiple levels. This can be quite handy for instructing curl.js that some modules -- or even whole folders of modules -- have been relocated. Paths take presendence over others via specificity. Paths that have more slashes ("/") are considered more specific and are used instead of any paths that match with less slashes. Here's an example:

var mycfg = {
	baseUrl: 'app/code', // relative to current page!
	paths: {
		'my/app': 'my/app',
		'my/otherapp': '../../otherapp/code',
		'my/otherapp/foo': 'my/foo'
	}
};

In this scenario, we've instructed curl.js that all of our modules that start with "my/app" are located in the usual place. (In fact, we don't need to specify 'my/app': 'my/app' in the paths config at all since this would be the default.) However, any modules that start with "my/otherapp" reside in a completely separate folder tree (possibly in some reused folder). For instance, "my/otherapp/awesome" will be sought at "otherapp/code/awesome".

Also, we've instructed curl.js to NOT use the usual "my/otherapp/foo" module. Instead, it will use the "my/foo" module.

Absolute Paths

Paths are only used when an absolute url is not used. Typically, you won't use absolute paths for modules. However, absolute paths can occasionally come in handy for plugin-based resources, such as css files. For instance, you can specify a dependency on a remote stylesheet as follows:

define(['css!//mycdn.com/path/to/stylesheets/dark.css'], function () {
	// do something stylish
});

(If a url starts with "//", it's a protocol-relative url. The "http:" or "https:" will be filled-in automatically by the browser.)

However, this situation would be better handled by removing the deep dependency from your module and moving it into the configuration:

curl = {
	paths: {
		'themes': '//mycdn.com/path/to/stylesheets/'
	}
};

define(['css!themes/dark.css'], function () {
	// do something stylish
});

Paths and Plugins

In curl.js 0.6 and higher, plugins have a special path syntax that allows plugin-based resources to reside on a separate domain or in a parallel folder within the same server. The normal syntax for it is as follows:

curl = {
	plugins: {
		css: {
			baseUrl: '//mycdn.com/base/path/for/all/stylesheets',
			paths: {
				layout: 'containers',
				theme: 'themes'
			}
		},
		text: {
			baseUrl: '//mycdn.com/base/path/for/all/templates',
			paths: {
				header: 'headers',
				footer: 'footers'
			}
		}
	}
};

However, there's a short-cut syntax for it that some people may prefer:

curl = {
	paths: {
		'css!': '//mycdn.com/base/path/for/all/stylesheets', // baseUrl for css!
		'css!layout': 'containers',
		'css!theme': 'themes',
		'text!': '//mycdn.com/base/path/for/all/templates', // baseUrl for text!
		'text!header': 'headers',
		'text!body': 'layouts'
	}
};

The previous two syntaxes are equivalent and allow you to write modules that look much saner (and are much more maintainable) than they would have been otherwise:

define(['text!body/three-column', 'css!layout/three-column', 'css!theme/dark'],
	function (template) {
		// make magic here
	}
);