Customisation
To let the planboard work for your specific planning needs, you have to link it in with your own backend manages:
- The special periods between the (firstnum, lastnum) dates on the planboard.
- The resources to be allocated to populate the rows of the board.
- The allocations already known. (for the shown rows between the displayd dates)
Each of the above information sets should be made available by your backend at distinct URI's returning clear json array result-sets.
Obviously the URIs will need to hold various parameters to be able to return the exact needed result. The uri-templates syntax will be used to capture how these parameters are to be injected in the URI. Reversly, to find the required information out of the returned domain-objects you will need to configure which object properties map to what needed information.
On top of this (and more optionally) the planboard can be customised in a number of ways:
- behaviour and essential settings can be modified through deviating from the standard configuration
- style and looks can be overriden through css
- your own tools can be added into the grid of the planboard.
All of the settings in this section are done through a so-called "config" object to be passed when the planboard is created. This objcect is a standard javascript hashtable with predefined keys, each allowing a specific part of the planboard to be tuned to your needs.
In the web-context where the planboard is to be used "calls" are noted down as URIs where GET requests will be send to, and responses with valid resulsets are obtained encoded in json Array representations.
Since
- these URIs need a mechanism to transport various parameters, and
- these URIs need to be fully customisable to meet the design of your backend
we've opted for allowing to express these using the uri-templates specification. ere
| key | default | Usage |
|---|---|---|
| uri | No defaults exist. Required configuration | Each of the listed keys can hold a uri-template (relative to the page base) to obtain the actual data. |
Here is a sample of what the configuration of this key might look like:
{
"row" : "http://example.com/yourservice/rows",
"period" : "../data/allperiods{/firstdate,lastdate}",
"allocation": "../data/reservations.json{?rows*,firstdate,lastdate}",
}
The context-variables for the template expansion consists of:
- firstdate
- the iso8601 (ie YYYY-MM-DD) variant of the first date on the planboard
- firstnum
- the integer numeric date-count variant of the first date on the planboard
- lastdate
- the iso8601 (ie YYYY-MM-DD) variant of the last date on the planboard
- lastnum
- the integer numeric date-count variant of the last date on the planboard
- rows
- the array-list of all row-ids displayed on the planboard
These are only available on the relevant uris of course:
| uri-key | available params |
|---|---|
| row | (none) |
| period | firstdate, lastdate (, firstnum, lastnum) |
| allocation | rows, firstdate, lastdate (, firstnum, lastnum) |
The mentioned integer numeric date-count is used internally in the planboard logic. It assigns a unique number to individual dates by truncating the millisecond-count since 1/1/1970 (in javascript obtained through date.getTime()) down to the daycount level (by taking the integer part of the milliseconds divided by the number of milliseconds in one day)
In this system January 1st 1970 gets number 0, March 7th 2012 gets 15406.
Further reading:
The above URI's need to return a json Array resultset, but the objects in there can organize information with propertynames best matching your own domain logic. These propertynames can include . (period) to reference properties nested inside more complex json structures. The planboard can be configured to read those properties through the following mapping:
| Row Model Mapping | ||
|---|---|---|
| key | default | Usage |
| rowIdProperty | "id" | Name of the domain property holding the row identifier. |
| rowLabelProperty | "label" | Name of the domain property holding a label for the row. |
| Period Model Mapping | ||
| key | default | Usage |
| periodInclusive | 1 | Is the enddate-property (see below) to be interpreted as inclusive (1) or not (0) to the range. |
| periodFromProperty | "from" | Name of the domain property holding the from-date. |
| periodTillProperty | "till" | Name of the domain property holding the till-date. |
| periodIdProperty | "id" | Name of the domain property holding the period identifier. |
| periodLabelProperty | "label" | Name of the domain property holding a label for the period. |
| Allocation Model Mapping | ||
| key | default | Usage |
| allocInclusive | 0 | Is the enddate-property (see below) to be interpreted as inclusive (1) or not (0) to the range. |
| allocOffset | 0.5 | Allocation bars are displayed with this offset to give a more natural/logical feel to them. E.g. Hotel days allocated for one night typically extend to the evening before and the morning after. The value should be between 0 and 1 indicating the percentage of one day-with unit) |
| allocFromProperty | "from" | Name of the domain property holding the from-date. |
| allocTillProperty | "till" | Name of the domain property holding the till-date. |
| allocIdProperty | "id" | Name of the domain property holding the allocation identifier. |
| allocLabelProperty | "label" | Name of the domain property holding a label for the allocation. |
| allocRowProperty | "rowid" | Name of the domain property holding the reference to the row associated to the allocation. |
| allocTypeProperty | "type" | Name of the domain property holding the style-type for the allocation. |
This is the list of available configuration-keys, their use, and the built-in default value.
| key | default | Usage |
|---|---|---|
| jScrollPane | {showArrows: true} | This is a pass-through config object to the jScrollPanes used in the planboard. See their [docs](http://jscrollpane.kelvinluck.com/settings.html) for more details. |
| datepicker | {
autoSize: true,
changeYear: true,
showOtherMonths: false,
selectOtherMonths: true,
numberOfMonths: 2,
stepMonths: 2,
yearRange: "c-5:c+5"
} |
This is a pass-through config object to the jQueri-UI date-picker used in the planboard. See their [docs](http://jqueryui.com/demos/datepicker/) for more details. |
| datePickerButton | "<button class='tool'><img src='./image/date.png' /></button>" | html for date-picker-button 
|
| prependButton | "<button class='colPrepend'><<</button>" | html for prepend-dates-button << |
| appendButton | "<button class='colAppend'>>></button> | html for append-dates-button >> |
| scrollBarSize | 16 | The width of vertical and height of horizontal scrollbars in px. We assume they are the same. |
| northScrollHeight | "115px" | The height of the "north" section of the grid. This is the top row where the date-headers (or column headers) are put. |
| westScrollWidth | "95px" | The width of the "west" section of the grid. This is the leftmost column where the row headers are put. |
| lang | Calculated as: $('html').attr('lang') |
Language to use for custom month and date names. These are borrowed/loaded from the translations configured/available in the datepicker of jQuery UI. Recommended way to set this is not through this option, but through the @lang attribute of the root-html-tag. Only use the config for this if you need that attribute for something else already. |
| datenames | l10n variant derived from datepickter | Array with the short (2 character) names of the days of the week starting with Sunday. By default these are borrowed/loaded from the translations configured/available in the datepicker of jQuery UI based on the 'lang' configuration explained above. |
| monthnames | l10n variant derived from datepickter | Array with the full names of the months starting with January. By default these are borrowed/loaded from the translations configured/available in the datepicker of jQuery UI based on the 'lang' configuration explained above. |
| labelRepeatDayCount | 28 | When allocation bars on the planboard become to big, one occurance of the label on them becomes to sparse to be viewable in the viewport of the planboard, leading to extensive scrolling just to know what it is about. This value indicates per how many days the label should be repeated. You should set it to a value that roughly matches the size of the expected viewport (in days). This will guarantee at least one occurance of the label in the viewport. |
| addDayCount | 7 | Number of days being added when pressing the buttons to add dates at the start of the end of the current date-range. (ie using the << and >> buttons) |
| daysafter | 14 | When selecting a date using the datepicker the system will guarantee this number of days to be available after the selected date. |
| daysbefore | 7 | When selecting a date using the datepicker the system will guarantee this number of days to be available before the selected date. |
| startDate | null (means today) | The date at which the planboard should be pointed at when first initialized. Can be a valid Date object, or a string in YYYY-MM-DD format. |
Using css stylesheets you can easily change the look and feel of your planboard to meet your own requirements.
Your own allocation-types will typically lead to new css styles, don't forget to style those.
Finally you can introduce your own buttons in the "tools" section of the planboard. Just produce the wanted HTML, attach specific event-handlers and add them to the planboard using the API.
Typically these tools will help you to do some of the following in a custom way
- manage (add/remove) the rows shown on the planboard by communicating to your back-end
- navigate the board
- possibly create new periods
- ...