API

Planboard Creation

Assuming you have loaded the required javascript, see Usage:

To create a planboard, you simply find or create the element that should contain it, and initialize it through calling planboard(). Optionally you can pass a custom configuration object as explained on the Customisation page.

var $pb = $('div#planboard');
$pb.planboard(config);

API Access

After that you can get a hold of the api object by requesting the data() object associated with the 'planboard' key.

var api = $pb.data('planboard');

You use the api object to register event handlers and call specific actions.

Events

The supported events are

• selectionChange: called when the selection on the board changes (row and/or dates)
• selectionDetail: called when the selection is clicked.
• allocDetail: called when an allocation is clicked.
• dateRangeChanged: called when the first or last date in the range of the planboard is changed.

selectionChange event

This is called when the selection on the board changes.

Your eventhandler should use this method signature:

function(evt, sel)

Where the parameters are:

• evt: the jquery event object
• sel: the selection object holding the fields:
  • id: id of the object, will always be "NEWID"
  • lbl: a handy label holding the information about selected row and date-range
  • code: id of the associated row
  • fromdate: starting-date of the selection
  • tilldate: ending-date of the selection

Sample:

api.selectionChange(function(evt, sel){
    if (sel) { 
        console.log(sel.lbl);
    } else {
        console.log("selection cleared.");
    }
});

selectionDetail

This is called when the selection on the board is clicked for detail or action.

Your eventhandler should use this method signature:

function(evt, sel)

Where the parameters are identical to above.

Sample:

api.selectionDetail(function(evt, sel) {
    console.log("selection click: " + sel.lbl);
});

allocDetail

This is called when a present allocation on the board is clicked.

Your eventhandler should use this method signature:

function(evt, alloc)

Where the parameters are:

• evt: the jquery event object
• alloc: the alloc object from your domain (ie what you pass down into addAlloc)

Sample:

api.allocDetail(function(evt, alloc) {
    console.log("you clicked alloc: " + alloc.id);
});

dateRangeChanged

This is called when the first or last date in the range of the planboard is changed.

Your eventhandler should use this method signature:

function(evt, range)

Where the parameters are:

• evt: the jquery event object
• range: the selection object holding the fields:
  • firstdate: first-date of the range active in the planboard
  • lastdate: last-date of the range active in the planboard

Sample:

api.dateRangeChanged(function(evt, range) {
    console.log("range spans from: " + range.firstdate + " - till: " + range.lastdate);
});

Methods

api.eachRow([selection,] fn)

Repeats the action coded into the function fn(api, row) to be

Arguments:

• selection: array containing the 'code' ids of the rows to visit. Optional: if ommitted all rows will be visited.
• fn(api, row): function called for each visited row.

api.addToElement(elmName, $stuff)

Adds the passed $stuff through jquery append to the selected region in the planboard.

To select a region the elmName parameter should be one off:

• "tools": for the tools-section
• "north-west": for the upper-left corner

api.getElement(elmName)

Selects the region (jQuery-wrapped) of the planboard specified by elmName (see above for supported element names)

api.getSelection()

Returns the current selection on the planboard (if any) the returned structure has the folleowing properties:

• "code" identification of the row the selection is in (can be null if no row selection is done yet)
• "fromdate" start-date of the selection (can be null if no date range is active yet)
• "tilldate" end-date of the selection (idem)
• lbl a shorthand toString-like variant useful for logging

api.clearSelection()

Clears the selction on the planboard.

api.setSelection(code, fromdate, tilldate)

Sets the selection on the board based on the parameters (equal as above, lbl will be calculated based on that.)

api.gotoDatedate(date)

Scrolls down to the selected date, and possibly creates the needed columns to include the date. If the date is too far out of the current range the current columns will be deleted, and a configurable period around the selected date will be created to be the new date-range.

api.appendRow(rowData)

Adds a row to allow allocations on the passed resource. You can configure which fields of the object map to label and id.

api.appendCol(count)

Appends (i.e. towards the end, the future) the passed number of columns to the current date-range.

api.prependCol(count)

Prepends (i.e. at the start, towards the past) the passed number of columns to the current date-range.

api.addPeriod(period)

Adds the passed period to the date-range header, and marks them over the matching date-cells in the grid. You should configure which fields of the passed object structure map to the needed label, id, start and end of the period.

api.addAlloc(alloc)

Adds the passed allocation as an allocated period to the grid of the planboard. You should configure which fields of the passed object structure map to the needed label, id, row-reference, start and end of the allocation.

More

Other methods on the object

Introspection and code-reading will show you more methods that are available. You can use those to your benefit, but they are not considered as part of the public interface, and will be subject to change without prior notice in further iterations.

Do let us know however if one of them looks useful in any way, we are likely to do an effort to properly include it in the public API.

Not currently foreseen

removeAlloc, removePeriod, updateAlloc, updatePeriod

You might think you need one of the methods above. We in fact agree, but you can stop loosing time searching for them: they're not there. Please consider using the gained time to fork and code away :)