What is PlanningBox
PlanningBox is an advanced representation for ERP5 web presentation. It displays ERP5's objects in a visualisable way using blocks (based on HTML div) to build graphs. PlanningBox is easily editable and skinable, allowing you to display whatever you want : calendar, Gantt charts, statistics, etc.
Furthermore, PlanningBox supports content edition "on the fly". This means the user can move the blocks representing the content, and save it directly. This will automatically call a validation script in charge of converting the new blocks' position into expected date (DateTime, Integer, etc.)
Implementing PlanningBox
PlanningBox view is available within the 'erp5_xhtml_style' Business Template, as it is a kind of web visual representation, and all its main scripts (to generate axis, standard statistics, etc.) are included in erp5_core. This Business Template only holds files to build and manage plannings, but does not include interface for every ERP5 Product. As a typical use of PlanningBox, you can create a new button in your Product view, that render an ERP5 Form containing a planningbox field. The only special thing to do is to position correctly the PlanningBox field inside the planning view : PlanningBox must be in the bottom side of the form, otherwise its name is displayed and result in a bad rendering. Precise steps are :
Go to your Product portal_type, in the action tab. There create a new action, that call an 'ERP5 Form' with the name you want to give to the action (typically Product_viewPlanning). Example:
Name : Product Planning
Id : product_planning
Action : string:${object_url}/Product_viewPlanning
Icon : string:${object_url}/images/planningbox.png
Condition :
Permission : View
Category : object_button
Visible? : checked
Priority : 10.0
In 'portal_skins/custom' (or any portal_skins subfolder), create the corresponding 'ERP5 Form' and add a 'planning_box' field.
Move to the 'order' tab in the 'ERP5Form' and rename the group to 'bottom'.
In 'order' tab change the 'Page Template' to 'form_report'.
By clicking on the 'planning_box' object, you can access directly its properties. (see PlanningBox Configuration in the bottom of this document)
Note : If you want to test an implementation of PlanningBox, you have two options: try the 'project' Business Template, that includes a preconfigured tab for handling planning view; or you can try run the functional tests for PlanningBox at "erp5_ui_test" Business Template.
First steps with PlanningBox
PlanningBox can be divided into four parts :
- on the top of the rendering, the "toolbar"
- the report axis
- the lane axis
- the planning content
Toolbar
The toolbar holds widgets for quick selection of the report method and the lane_path (zoom_level) over the report and lane axis. This allow a quick access to the most usefull properties.
Report axis
The report axis can be vertical or horizontal depending on the current planning rotation. It can also be moved anywhere around the content area (top / bottom / left / right). This axis provides links to fold or unfold the current group in case of report mode (just need to click on the title for that). Beside the axis you can find depth widget to automatically unfold all groups to the specified level (from 0 to 3).
Lane axis
The secondary axis can also be horizontal or vertical depending on the planning rotation. Its content depends on the current zoom selected (lane_path).
Planning Content
The planning content holds the task representations by using blocks. these blocks have a lot of characteristics. They can be personalised with tooltip, top-left, top-right, bottom-left, bottom-right info text, and their main title (in the middle of the block) is a link to the corresponding ERP5 object (1). In case the block is small, the priority is given to the main title, this means that first info text are removed to allow main text data (2). If the block is really extremely small, then the text is removed and replaced by a small picture (3) (NEW : This small picture has been replaced by a single '.' character to fit correctly the block). By leaving the mouse over this item, you will get all the data through a tool tip text, and you can still access to the corresponding ERP5 object by clicking on it.
Interacting with PlanningBox
PlanningBox includes a interactive and simple way to edit and reorganise correctly the objects. This works very easily and transparently thanks to a javascript.
Editing
To move a block, you just have to drag it and drop it where you want. To resize a block, double click on it, four sliders should appear around the block, by dragging and dropping a slider, you resize the corresponding side.
here is an example :
You have a Planning, and from there you can drag & drop a block from one place to another. The block follows your pointer until you release it.
To resize a block, double click on it, slider appears around the block
Drag a slider and keep it until the block reaches the size wanted. Note the values are not updated on the block moved as on the extended block. This is because the editing process is static to prevent massive interaction with the server.
Saving
Once editing is done, click on the usual save button to run validation process. In case of error the planning is not updated, and you are redirected to the same planning, with a special presentation for the blocks unvalidated (other colour, special text to have more information about the kind of error). You can correct the error blocks and try to save again until all errors are fixed, or cancel validation at any time by refreshing another page. Beware if any error occurs, no modification is applied : The planning must be error free to be saved.
PlanningBox Configuration
PlanningBox is easily and almost fully configurable through the management interface that allow the user to personalise the objects rendered and the way to do so.
Use manage on a PlanningBox rendering ( 'Project_viewPlanning method' ) to get to the configuration interface. Once you have selected the object you want to edit (usually 'planning_box' object)
General Properties
CSS Class
This field is a default property for all ERP5 fields, but should stay empty as the PlanningBox generates its own CSS classes to have the expected rendering. Specifying a generic CSS class in such field may result in a modified rendering.
Selection Name
name of the selection used on the current Planning.
End User Display
Enable 'on the fly' edition
Check this if you want to allow graphic interactions with the planning, i.e moving and resizing blocks before saving. Default is checked. Uncheck it only if you want to prevent from updating values by mistake.
Vertical view
Defining the axis rendering order. Default (unchecked) is standard planning view, with Y axis as report axis, and lane axis horizontal. In case of calendar use, it is usually better to switch axis so that small time axis is represented vertically.
Size border width left
Defining the space between the browser's left border and the first rendered element. Is used to prevent the planning content or planning Y axis to be stuck on the browser.
Planning width
Defining the width of the planning content. BEWARE this does not include any width of axis, or space between axis : this is exclusively for the Planning content part.
Y axis space
Defining the spacer between the Y axis and the planning content.
Y axis width
Defining the width of the Y axis.
Note : corresponding properties are available for size over the Y axis.
Force Y axis to the right instead of left
Y axis is placed on the left by default, but it can be placed on the right side of the planning just by checking this option.
Force X axis to the bottom instead of top
Idem but concerning the X axis : default is top, but can be bottom if checked
Objects selection
List Method
Name of the method listing the objects. See HowToConfigureListbox wiki page for more information
Secondary Layer List Method
Name of the method listing the objects used for secondary layer.
Report Root
A list of domains defining the possible root for report axis.
Lane Root
A list of domains defining the possible root for lane axis, the default domains are:
base_day_domain | Day base_week_domain | Week base_month_domain | Month base_year_domain | Year
Portal Types
Portal Types of objects to list. Used to make a selection on objects depending on their portal type.
Default Sort
Sorting order for selected objects.
Objects properties
Specific method which fetches the title of each line
Defining specific object method to recover the title of each group line.
Specific property to get start of blocks
Defining specific object property to get block beginning position. BEWARE this is a property name and not a method name.
Specific property to get stop of blocks
Idem for end position.
Specific property to get height of blocks
Idem for height of each block (used only in case of statistic mode). This is just the property name used to store the height value, this does not means that statistics are done using this special property (as statistics are generated through an external script).
Specific method of data called for inserting info in block
Objects methods to get block display (topleft corner to bottomleft corner)
Specific external scripts
Name of script generating statistics
Used to generate statistics lines. Statistics are ignored if no valid script can be found here. The script takes the selection, the report_group and the current object, and returns a list of temp_objects with the necessary properties (including height property filled for each object).
Name of script splitting activities into blocks
This can be used if necessary to split an activity (an object) into several blocks, according to some rules. These blocks can be colourised if necessary. name of script colourising blocks : used to apply a special colour on each block. Takes the block and the object in parameter.
Name of script rounding blocks during validation
New start & stop bounds recovered from the validator are not always exacts (day, hours, min, sec, less) because of the rendering (in pixels), and this script is aimed to fix data to fit expected values (rounded days for ex.). There is some scripts included at erp5_xhtml_style as Planning_roundBoundToDay for example.
Setting Vertical View
As described, PlanningBox also supports calendar representation. Here is described how to use such mode.
Configuring Planning Box to get a calendar like view is very simple, the most difficult part is to get good group structure split by predicates.
PlanningBox Configuration
To get a Calendar, you need first of all to switch the axis, so that the main dates will be displayed on the X axis whereas sub-dates will be positioned on the Y axis. for that just check the 'vertical view mode' option in the planning properties.
That's all for PlanningBox configuration.
Domain Generation
Domain generation must fit a defined rule to be correctly supported by PlanningBox : objects must be reorganised in groups, each group representing a unit on the main axis. So for example, for a month calendar, the domain generation method must return a tree of month, with attributes start_date and stop_date fitting the month properties (first day of the current month, first day of the next month).
This group must holds all the tasks objects that are represented within the month. Even if only a part of the task is represented (in case of long tasks matching several months), the task must be present : PlanningBox will automatically cut task bounds if necessary. According to this, task objects can be present several times in a report_tree, but in different groups representing months.
From there PlanningBox is able to help itself, detect that actual view is calendar mode just thanks to the group structure, and then apply the special process necessary to handle correctly Calendars.
Frozen Blocks
To define a block as fronzen means that he will be static (no JS) and he will be showed with a diferent look. Every block is tested go check if was frozen or not with the script portal_skins/erp5_core/PlanningBox_isFrozenBlock .
F.A.Q
Q:I can't edit the PlanningBox even if 'On the fly edition' is checked.
A:PlanningBox uses java script to handle such a functionality. Please be sure your web browser supports correctly JavaScript. Also check 'wzdragdrop.js' is present on the ERP5 website.
TODO Notes
There is some new modifications that will be included here soon and also more explanations about the current topics. That includes:
- Add Differences between domains and parent explanations
|
|
|
| ||||||||
|
|
|
| ||||||||
|
|
|
|