To build:
cake build
To watch files for changes and build:
cake watch
To build and serve built files:
cake -s watch
Specify Port, default is 3001:
cake -s -p [PORT] watch
The easiest way to use the Ubret Library is to just include the hosted version on your site.
<script src="http://ubret.s3.amazonaws.com/ubret_library/lib/index.js"></script>
if you're running the server
<script src="http://localhost:3001/lib/index.js"></script>
To load tools you'll just need to pass an array of tool names, and a callback to be executed after the tools load.
Ubret.ToolLoader(["Table", "Histogram"], -> console.log 'Tools are loaded")
Because that loading method is super slow there are four provided minified tool sets that can also be loaded.
Ubret.ToolsetLoader("galaxy_zoo", -> console.log 'Tools are loaded')
The tool sets are
galaxy_zoowith Table, Histogram, Scatterplot, Spectra, SubjectViewer, Map, and Statisticsnavigatorwith Histogram and Scatterplotspacewarpwith SpacewarpViewerserengetiwith Table, Histogram, SubjectViewer, ImageGallery, Map, and Statistics
All methods in base tool return @ so they can be chained together.
All methods documented be below can also be triggered when a tool is created, by passing them in as the keys of an object. Hence:
new Ubret.Table
selector: 'table-1'
data: [{stuff: "is here"}, {stuff: "is also here"}]
height: 50
width: 150
is equivalent to
new Ubret.Table().selector('table-1')
.data([{stuff: "is here"}, {stuff: "is also here"}]
.height(50).width(150)
You're free to use whichever style you prefer, but any tools should support both methods of manipulating a tool.
Creates a new HTML node and assigns it to @el and sets its id to the value of selector. It also creates a new d3 node at @d3el. Triggers the 'selector' event with the d3 node.
Sets @opts.height to height and triggers 'height' event.
Sets @opts.width to width and triggers 'width' event.
Sets @opts.data to data sorted by each datum's uid. Also will call @keys with the keys that should be displayed in tools. Triggers the the 'data' event with the result of @childData()
Sets @opts.keys with the kinds of keys that be displayed in the tools. Triggers the 'keys' event.
If ids is an Array, sets @opts.selectedIds to the value of ids. Otherwise it appends ids to the end of @opts.selectedIds. Triggers 'selection' event.
Appends filters, a predicate function that can be passed to Underscore's _.filter function, to the end of @opts.filters. Triggers a 'data' event with @preparedData() if data has been passed to the tool. Triggers the 'add-filters' event.
Appends fields, an object containing a field name and a function that returns the value of the new field, to the end of @opts.fields. Triggers a 'data' event with @preparedData() if data has been passed to the tool. Triggers the 'add-fields' event.
Accepts settings as an object. For each key/value pair in settings, it tests whether @[setting_key] is a function and calls it with the value of the pair if that is the case. Otherwise sets @opts[setting_key] = setting_value. In both cases it triggers as a 'setting:key_name' event for each key/value pair, and a 'settings' event when it has finished with all settings.
Removes any current parent tool if one exists, and unbinds the parentTool's events. Sets @opts.parentTool to the new parentTool, and sets up event listeners on the parent tool. Triggers the 'bound-to' event.
Returns the tool's data with all fields and new fiels applied to it. It is memoized, so subsequent calls, when the data, filters and fields haven't changed, do not result in recalculation. You should always use a call to this function instead of using @opts.data (unless you've got a good reason not to).
Remove the current parentTool and unbinds its event events, if a parent tool exists.
Returns @preparedData(). Override in a tool to only provide a subset of a tool's data to child tools.
A very small probably incorrect API for handling events in tools.
If you want to specify events your Tool in one easy go
events:
'event_name' : 'some callbacks'
'other_event' : 'some more callbacks'
Accepts event as either the name of an event, or as an object of events and their associated callbacks. Callbacks can be a single function or a string of function names. When multiple callbacks are supplied they will always be executed in the order they were specified.
Calls any callbacks associated with the event with the supplied arguments.
Removes all callbacks for a specified event. If event is null it removes, all events from the object.
A small helper object for dealing tools that need pagination. Include in your tool by running _.extend @, Ubret.Paginated in the tools constructor.
You'll also need to implement two methods in your tool: perPage, which can either be a constant or a function that returns that number of items per page, pageSort, which accepts a single argument of an array of data, and returns it sorted.
Returns the page items for the current Page. If the current Page is outside the bounds of the tool's data set. It resets the page number to one that is.
Accepts an integer page number and returns the items for that page. Pages are zero-index because they should be.
A sub-object of Paginated that sets perPage to 1 and has a default pageSort that returns object that have been selected if there are selections, and all items otherwise. Include in your tool by running _.extend @, Ubret.Sequential.
Makes an AJAX request to the specified URL and returns an Ubret.Promise.
Wrapper for Ubret.Ajax('GET', url).
Wrapper for Ubret.Ajax('POST', url).
An implementation of the Promise/A+ Spec. Ubret.Ajax returns a promise.
Either callback is optional. It returns another promise that will be fulfilled after the then returns.
A class for viewing all the images of multi-image Zooniverse subjects. Create with new Ubret.MultiImageView(selector or dom node, array of image uris).
Updates the images being displayed in the Multi Image View.
The Table tool, and the Spectra Tool, should be fairly well documented.
The Ubret Library is licensed under an MIT-style license. See COPYING