README
SLURI: Sling URI Manipulation Library for AEM and Apache Sling
SLURI is a client-side URI/URL manipulation library for Adobe Experience Manager (AEM/CQ5) and Apache Sling. SLURI is an implementation of the URL API (see the Mozilla Developer Network: URL documentation) with considerations for the unique URL structure of AEM and Sling applications.
An AEM/Sling URI could look something like http://user:pass@www.nateyolles.com/us/en/page.foo.bar.html/biz/baz?a=alpha&b=bravo#charlie
. See the documentation for Apache Sling URL decomposition.
SLURI encodes the URL string according to RFC 3986.
Instead of writing repetitive and tedious string manipulation such as:
qs += (qs.indexOf('?') === -1 ? '?' : '&') + key + '=' + value;
url = path.split('.html')[0] + selectors + '.html';
SLURI allows you to write:
sluri.searchParams.append(key, value);
sluri.suffix = '/foo/bar';
sluri.selectors.append('foo');
sluri.selectors.delete('bar');
sluri.extension = 'json';
Using SLURI
SLURI can be be used in three ways: as a global, with AMD and an AMD loader such as RequireJS or Almond, or in CommonJS-like environments that support module.exports
such as Node or Grunt.
Include the provided JavaScript and simply instantiate SLURI objects using the new
keyword.
Bower
Install with Bower:
bower install sluri --save
NPM
Install with NPM (https://www.npmjs.com/package/sluri):
npm install sluri --save
Global
Include the minified distribution file /dist/sluri.min.js or the expanded development file /src/sluri.js in your project.
var sluri = new SLURI('http://www.nateyolles.com/us/page.foo.bar.html/alpha/bravo');
RequireJS
If required, setup your RequireJS config.js
file with the SLURI dependency:
require.config({
paths: {
SLURI: 'bower_components/sluri/sluri'
}
});
require(['sluri'], function(SLURI) {
var sluri = new SLURI('http://www.nateyolles.com/us/page.foo.bar.html/alpha/bravo');
});
CommonJS
var SLURI = require('sluri');
var sluri = new SLURI('http://www.nateyolles.com/us/page.foo.bar.html/alpha/bravo');
Browser Compatibility
Even though the URL API is listed as experimental, SLURI does not depend on the browser's implementation of the API. SLURI works on all modern browsers and Internet Explorer 9+.
Building SLURI
Tests
SLURI tests are written with Jasmine and run on the PhantomJS headless browser. Tests are run with CircleCI's integration testing platform. Tests can be run locally with:
grunt test
Build
Build SLURI with:
grunt build
API
SLURI implements the URL API with a few additions and modification building upon the URL API to handle selectors
, suffixes
, resourcePath
and extensions
. SLURI respects all read-only
property definitions. The only alteration in this version is that the implementation of the URLSearchParams
interface returns arrays rather than Iterators.
given the following instantiated object for example:
var sluri = new SLURI('http://user:pass@www.nateyolles.com:4502/us/en/page.biz.baz.html/foo/bar?alpha=bravo&charlie=delta&echo#foxtrot');
SLURI
SLURI(urlString [, baseURL])
The SLURI object must be instantiated with the new keyword. Throws TypeError if unable to construct a URL.
urlString
String to parse into a URL. Can also be a URL, SLURI, Location or HTMLAnchorElement object.
baseURL
String to use for the origin when parsing urlString into a URL. This parameter is optional but useful if urlString is a relative path. Can also be a URL, SLURI, Location or HTMLAnchorElement object.
SLURI.protocol
getter
sluri.protocol; // returns 'http:'
setter
sluri.protocol = 'https';
SLURI.username
getter
sluri.username; // returns 'user'
setter
sluri.username = 'newuser';
SLURI.password
getter
sluri.password; // returns 'pass'
setter
sluri.password = 'newpass';
SLURI.hostname
getter
sluri.hostname; // returns 'www.nateyolles.com'
setter
sluri.hostname = 'www.example.com';
SLURI.port
getter
sluri.port; // returns '4502'
setter
sluri.port = 4503;
SLURI.host
getter
sluri.host; // returns 'www.nateyolles.com:4502'
setter
sluri.host = 'www.example.com:4503';
SLURI.origin
getter
sluri.origin; // returns 'http://www.nateyolles.com:4502'
setter
read-only
SLURI.pathname
getter
sluri.pathname; // returns '/us/en/page.biz.baz.html'
setter
sluri.pathname = '/fr/fr/example.html';
SLURI.resourcePath
getter
sluri.resourcePath; // returns '/us/en/page'
setter
sluri.resourcePath = '/fr/fr/example';
SLURI.extension
getter
sluri.extension; // returns 'html'
setter
sluri.extension = 'json';
SLURI.selectorString
getter
sluri.selectorString; // returns 'biz.baz'
setter
sluri.selectorString = 'foo.bar';
SLURI.search
getter
sluri.search; // returns '?alpha=bravo&charlie=delta&echo'
getter
sluri.search = '?foo=bar';
SLURI.suffix
getter
sluri.suffix; // returns '/foo/bar'
setter
sluri.suffix = '/biz/baz';
SLURI.hash
getter
sluri.hash; // returns '#foxtrot'
setter
sluri.hash = 'foo';
SLURI.href
getter
sluri.href; // returns 'http://user:pass@www.nateyolles.com:4502/us/en/page.biz.baz.html/foo/bar?alpha=bravo&charlie=delta&echo#foxtrot'
setter
sluri.href = 'http://www.example.com/fr/fr/foo.html/bar/biz';
SLURI.toString()
returns {string}
sluri.toString(); // returns 'http://user:pass@www.nateyolles.com:4502/us/en/page.biz.baz.html/foo/bar?alpha=bravo&charlie=delta&echo#foxtrot'
SLURISelectors
SLURISelectors(selectorString)
Allows easy access to create, read, update and delete the selectors without having to resort to manual string manipulation.
Selectors are unique to Apache Sling and Adobe Experience Manager, as such there isn't an interface to implement. However, the SLURISelectors API matches the slURLSearchParams API and URLSearchParams interface as closely as possible.
selectorString
The selector string to be deconstructed and manipulated
SLURI.selectors
getter
sluri.selectors; // returns instanceof SLURISelectors
setter
read-only
SLURI.selectors.toString()
returns {string}
sluri.selectors.toString(); // returns 'biz.baz'
SLURI.selectors.has(selector)
selector
The string to check the SLURI object's selectors against
returns {boolean}
sluri.selectors.has('biz'); // returns true
SLURI.selectors.append(selector)
selector
The string to append to the SLURI object's selectors
sluri.selectors.append('qux'); // sluri.selectorString === 'biz.baz.qux'
SLURI.selectors.delete(selector)
selector
The string to delete from the SLURI object's selectors
sluri.selectors.delete('biz'); // sluri.selectorString === 'baz'
SLURI.selectors.values()
returns {array}
sluri.selectors.values(); // returns ['biz', 'baz']
SLURISearchParams
SLURISearchParams(searchString)
The SLURI implementation of the URLSearchParams interface.
Allows easy access to create, read, update and delete querystring parameters without having to resort to manual string manipulation.
Handles multiple values for a given key in the querystring. There are many ways different web frameworks handle this. SLURISearchParams takes the same approach as the SearchParams interface that it is implementing. An example of multiple values is: ?foo=red&bar=blue&foo=green. Calling the #get method will return the first occurrence, while calling the #getAll method will return an array of all values. Calling the #set method with remove all values and create the new one. Calling #delete will remove all values. The #append method is how multiple values can be added to the querystring.
searchString
The querystring to be deconstructed and manipulated
SLURI.searchParams
getter
sluri.searchParams; // returns instanceof SLURISearchParams
setter
read-only
SLURI.searchParams.toString()
returns {string}
sluri.searchParams.toString(); // returns 'alpha=bravo&charlie=delta&echo'
SLURI.searchParams.has(key)
key
The parameter key to check against the querystring to see if it exists
returns {boolean}
sluri.searchParams.has('alpha'); // returns true
SLURI.searchParams.get(key)
key
The parameter key to retrieve the querystring value
returns {string}
sluri.searchParams.get('alpha'); // returns 'bravo'
SLURI.searchParams.getAll(key)
key
The parameter key to retrieve the querystring values
returns {array}
sluri.searchParams.getAll('alpha'); // returns ['bravo']
SLURI.searchParams.keys()
returns {array}
sluri.searchParams.keys(); // returns ['alpha', 'charlie', 'echo']
SLURI.searchParams.values()
returns {array}
sluri.searchParams.values(); // returns ['bravo', 'delta', '']
SLURI.searchParams.set(key, value)
key
The parameter key to set in the querystring
value
The parameter value to set in the querystring for the key
sluri.searchParams.set('alpha', 'golf'); // sluri.search === '?alpha=golf&charlie=delta&echo='
SLURI.searchParams.delete(key)
key
The parameter key to delete from the querystring
sluri.searchParams.set('alpha'); // sluri.search === '?charlie=delta&echo='