API Reference
Reef, Snorkel, and Reef Router expose a set of options, methods, and custom events that you can hook into.
Global Methods
Reef.debug()
Turn debug mode on or off. Pass in true
to turn debug mode on, and false
to turn it off.
// Turn debug mode on
Reef.debug(true);
// Turn debug mode off
Reef.debug(false);
Reef.clone()
Create an immutable copy of an array, object, Map()
, or Set()
.
Reef.clone({});
Reef.trueTypeOf()
Get the true type of an object.
Reef.trueTypeOf([]); // "array"
Reef.trueTypeOf({}); // "object"
Reef.trueTypeOf(''); // "string"
Reef.trueTypeOf(1); // "number"
Reef.err()
Log a warning in the console conditionally only if debug mode is on.
Reef.debug('You did something, silly!');
Reef.emit()
Emit a custom event. Pass in the element to emit the event on, the event name, and optionally, event details as arguments.
// Emits the "awesome" event on the document
Reef.emit(document, 'awesome');
// Emit the "awesome" event on the #app element, with some details
let app = document.querySelector('#app');
Reef.emit(app, 'awesome', {
whoIs: 'You are'
});
You can listen for custom events with the Element.addEventListener()
method.
Instance Methods
Reef.prototype.render()
Render a Reef component in the UI.
let app = new Reef('#app', {
template: 'Hello world!'
});
app.render();
Reef.prototype.attach()
Attach one or more components to a Reef component. Pass in the component or an array of components as an argument.
let app = new Reef('#app', {
template: '<ul id="todos"></ul>'
});
let todos = new Reef('#todos', {
template: '<li>Build something with Reef</li>'
});
// Attach one item
app.attach(todos);
// Attach an array of items
app.attach([todos]);
Reef.prototype.detach()
Detach an attached component. Pass in the component or an array of components as an argument.
// Detach one component
app.detach(todos);
// Detach an array of components
app.detach([todos]);
Reef.prototype.do()
Run a setter function. Pass in the name of the setter, and a comma-separate list of any arguments.
let app = new Reef('#app', {
data: {
count: 0
},
template: function (props) {
return count;
},
setters: {
increase: function (props) {
props.count++;
}
}
});
// Run the increase setter
app.do('increase');
Reef.prototype.get()
Run a getter function. Pass in the name of the getter, and a comma-separate list of any arguments.
let app = new Reef('#app', {
data: {
count: 0
},
template: function (props) {
return count;
},
getters: {
count: function (props) {
return props.count;
}
}
});
// Run the count getter
app.get('count');
ReefSnorkel.prototype.run()
Start or restart a Snorkel instance. This is run automatically when instantiating a new Snorkel instance.
// A snorkel instance
let snorkel1 = new ReefSnorkel();
// Another instance
// This stops snorkel1 from running
let snorkel2 = new ReefSnorkel({
autoLinks: false
});
// This restarts snorkel1, and stops snorkel2
snorkel1.run();
ReefSnorkel.prototype.stop()
Stops a snorkel instance from running.
let snorkel = new ReefSnorkel();
snorkel.stop();
ReefSnorkel.prototype.visit()
Visit a URL. Pass the URL in as an argument.
let snorkel = new ReefSnorkel();
snorkel.visit('/about');
ReefSnorkel.prototype.clearCache()
Clear the cache for a snorkel instance.
let snorkel = new ReefSnorkel();
snorkel.clearCache();
ReefSnorkel.prototype.addComponent()
Add one or more Reef components to be automatically rendered whenever the route changes. Pass in the component or an array of components as an argument.
// A Reef component
let app = new Reef('#app', {
template: 'Hello world!'
});
// Snorkel
let snorkel = new ReefSnorkel();
// Add one component
snorkel.addComponent(app);
// Add an array of components
snorkel.addComponent([app]);
ReefSnorkel.prototype.removeComponent()
Remove one or more Reef components from being automatically rendered whenever the route changes. Pass in the component or an array of components as an argument.
// A Reef component
let app = new Reef('#app', {
template: 'Hello world!'
});
// Snorkel
let snorkel = new ReefSnorkel();
// Remove one component
snorkel.removeComponent(app);
// Remove an array of components
snorkel.removeComponent([app]);
ReefRouter.prototype.addRoutes()
Add one or more routes to a Reef Router instance. Pass in a route or array of routes as an argument.
let router = new ReefRouter();
// Add one route
router.addRoutes({
url: '/about',
title: 'About'
});
// Add an array of routes
router.addRoutes([
{
url: '/about',
title: 'About'
},
{
url: '/contact',
title: 'Contact Us'
}
]);
ReefRouter.prototype.removeRoutes()
Remove one or more routes from a Reef Router instance. Pass in a route or array of routes as an argument.
let router = new ReefRouter({
routes: [
{
url: '/about',
title: 'About'
},
{
url: '/contact',
title: 'Contact Us'
}
]
});
// Remove one route
router.removeRoutes({
url: '/about',
title: 'About'
});
// Remove an array of routes
router.removeRoutes([
{
url: '/about',
title: 'About'
},
{
url: '/contact',
title: 'Contact Us'
}
]);
ReefRouter.prototype.addComponent()
Add one or more Reef components to be automatically rendered whenever the route changes. Pass in the component or an array of components as an argument.
// A Reef component
let app = new Reef('#app', {
template: 'Hello world!'
});
// Reef Router
let router = new ReefRouter();
// Add one component
router.addComponent(app);
// Add an array of components
router.addComponent([app]);
ReefRouter.prototype.removeComponent()
Remove one or more Reef components from being automatically rendered whenever the route changes. Pass in the component or an array of components as an argument.
// A Reef component
let app = new Reef('#app', {
template: 'Hello world!'
});
// Reef Router
let router = new ReefRouter();
// Add one component
router.removeComponent(app);
// Add an array of components
router.removeComponent([app]);
ReefRouter.prototype.visit()
Visit a URL. Pass the URL in as an argument.
let router = new ReefRouter();
router.visit('/about');
ReefRouter.prototype.navigate()
(deprecated)
This method has been replaced with ReefRouter.prototype.visit()
. It still works, but will be removed in the next major version release.
Instance Properties
Reef.prototype.data
Get a reactive copy of the app data.
let data = app.data;
Reef.prototype.elem
The element the component is associated with. Returns a string or Node.
let elem = app.elem;
Reef.prototype.allowHTML
Whether or not HTML is allowed in the Reef component data. Returns a boolean.
let allowed = app.allowHTML;
ReefRouter.prototype.routes
An immutable array of the routes for a router instance.
let routes = router.routes;
ReefRouter.prototype.current
The current route for a router.
let current = router.current;
Events
Reef, Snorkel, and Reef Router emit custom events throughout the life cycle of a component or instance.
All Reef events follow a library:event
pattern. Unless otherwise specified, all events are emitted on the document
element. Event details can be accessed on the event.details
property.
// Listen for when Reef components are rendered into the DOM
document.addEventListener('reef:render', function (event) {
console.log(event.target); // The element it was rendered into
console.log(event.detail); // The data used for the render
});
Reef Events
reef:ready
is emitted when Reef is loaded into the DOM and ready to use.reef:initialized
is emitted when a new Reef component is initialized.event.detail
- the instance
reef:before-render
is emitted on an element before a new UI is rendered into it.event.target
- the element the component is being rendered intoevent.detail
- the current componentdata
event.preventDefault()
- stop the component from rendering
reef:render
is emitted on an element after a new UI is rendered into it.event.target
- the element the component was rendered intoevent.detail
- the componentdata
at time of render
reef:attached
is emitted when one or more components is attached to a component.event.detail
- an object with thecomponent
and an array ofattached
components
reef:detached
is emitted when one or more components is detached from a component.event.detail
- an object with thecomponent
and an array ofdetached
components
Snorkel Events
snorkel:ready
is emitted when Snorkel is loaded into the DOM and ready to use.snorkel:initialized
is emitted when a new Snorkel instance is initialized.event.detail
- the instance
snorkel:stopped
is emitted when a Snorkel instance is stopped.event.detail
- the instance
snorkel:before
is emitted before a new route is fetched.event.detail
- an object with thecurrent
andnext
URLsevent.preventDefault()
- stop the route from being fetched
snorkel:after
is emitted after a new route is fetched and loaded into the UIevent.detail
- an object with thecurrent
andprevious
URLs
snorkel:not-found
is emitted when a fetched route is not foundevent.detail
- an object with thecurrent
andnotFound
URLs
snorkel:components-added
is emitted when one or more components are added for rendering on route changes.event.detail
- an object with thesnorkel
instance and an array of addedcomponents
snorkel:components-removed
is emitted when one or more components are removed from rendering on route changes.event.detail
- an object with thesnorkel
instance and an array of removedcomponents
snorkel:cache-updated
is emitted when a URL is added to the internal cache.event.detail
- an object with theurl
andhtml
string
snorkel:cache-cleared
is emitted when the internal cache is cleared.event.detail
- the Snorkel instance
Router Events
router:ready
is emitted when Reef Router is loaded into the DOM and ready to use.router:initialized
is emitted when a new Router instance is initialized.event.detail
- the instance
router:before
is emitted before a new route is fetched.event.detail
- an object with thecurrent
andnext
URLsevent.preventDefault()
- stop the route from being fetched
router:after
is emitted after a new route is fetched and loaded into the UIevent.detail
- an object with thecurrent
andprevious
URLs
router:routes-added
is emitted when one or more routes are added to the router.event.detail
- an object with therouter
instance and an array of addedroutes
router:routes-removed
is emitted when one or more routes are removed from the router.event.detail
- an object with therouter
instance and an array of removedroutes
router:components-added
is emitted when one or more components are added for rendering on route changes.event.detail
- an object with therouter
instance and an array of addedcomponents
router:components-removed
is emitted when one or more components are removed from rendering on route changes.event.detail
- an object with therouter
instance and an array of removedcomponents
Deprecated Events
These are events that are still emitted, but will be removed in the next major version release. You should migrate to one of the events listed above whenever possible.
render
was replaced byreef:render
beforeRouteUpdated
was replaced byrouter:before
routeUpdated
was replaced byrouter:after
Options
All of the options for Reef, Snorkel, and Reef Router. This section is still a work-in-progress.
Reef Options
// This can be a string or a element
let elem = '#app';
new Reef(elem, {
// The component data
data: {},
// A component or array of components to attach to
attachTo: [],
// A data store to use
// If used, the data option is ignored
store: null,
// A router to use for this component
router: null,
// An object of setter methods
setters: {},
// An object of getter methods
getters: {}
});
Snorkel Options
new ReefSnorke({
// If true, automatically run Snorkel on all links
autoLinks: true,
// The selector for links to follow
// Only needed if autoLinks is false or if you've used an ignore selector
follow: '[snorkel]',
// The selector for links to ignore
ignore: '[snorkel-ignore]',
// The selector for links that should replace the current state
// (instead of adding a new entry to browser history)
replace: '[snorkel="replace"]',
// The class that's added to the HTML element while a new route is loading
loading: 'reef-loading',
// The root for your app
// If your app is on a sub-page, you may want to change this
root: '/',
// If true, cache views for use with the forward/back button
cache: true,
// How many items to store in cache
cacheSize: 50,
// How long to keep cached items for, in seconds
cacheTime: 3600,
});
Reef Router Options
new ReefRouter({
// An array of routes
routes: [],
// The root path for your app
root: '',
// The format to use for the document.title
// Can be a string, or a function that returns a string
// Accepts the route object and page title as arguments
title: function (route, title) {
return title;
},
// If true, use a hashbang pattern instead of real URLs
useHash: false
});