Here is a complete and precise description of PlanningBox internal script.
End users or people who just want to personalize the planning output through scripts should first have a look at HowToUsePlanningBox, as that wiki document deals with PlanningBox configuration. This means the current document is nothing else than a technical note to help developper maintaining, understanding and optimizing PlanningBox.
How does this works
Follows a description of the rendering process for HTML rendering in a web browser. If you want to focus on the internal generic process please go directly to the Detailled Processing.
Rendering
PlanningBox uses 2 rendering methods 'render_css' and 'render' to get a correct visual output. And the process is divided between these two methods. Note : these two methods are called from the same Page Template in charge of the field rendering.
'render_css' is doing the biggest process, as it is responsible for building the whole generic structure before generatic the HTML output. the steps are :
Building Generic structure containing the whole planning properties using method 'render_structure'. The description of this method and the structure generated will follow in the Detailled Processing.
Calling a special script to generate the CSS classes from this structure, 'planning_css' (using 'planning_coordinates' to get a dict with all object properties).
Saving the structure into the current REQUEST to prevent duplicate DATA generation during the HTML rendering.
- returning the CSS classes.
The second method 'render' consists of the second part of the work needded to display a Planning in a web browser.
Recovering directly the whole structure from the REQUEST.
calling the HTML script generator (called 'planning_content').
calling the DHTML script (in charge of specifying which blocks can be moved, 'planning_dtml').
- returning the HTML structure + DHTML informations (as text to insert in the HTML squeleton).
Once the 'view_master' Page Template has finished its job, the planning can be displayed. The block movements are handled through a Javascript able to update in real time HTML tag size and position (in the case of PlanningBox, this is done on <div> tags. The list of <div> to take into account is known thanks to the DHTML data.
Validation
The validation procedure is called once the User click on the 'Save' button. The javascript automatically returns a list with the moved blocks and their coordinates (oldX, oldY, newX, newY, width, height). From there the internal structure is no more available, as the REQUEST object has changed, so a part of the process will have to be done again. So the steps of the validation process are :
- recovering and converting the list of blocks moved with their coordinates to a dict structure.
calling 'render_structure' internal method to rebuild the whole generic structure
calling external script 'planning_coordinates' to get the structure of coordinates from the generic structure.
- getting the blocks final destination and size, and converting these coordinates backtovalues : the destination is recovered (in case of Drag Drop over different groups) as well as the new block bounds.
- returning a dict containing each object with the values to update.
Detailled processing
This is a presentation of the 'render_structure' method, in charge of building a generic structure. This structure is absolutely compatible with every kind of rendering (HTML + CSS, PDF, OOo), and takes into account all the necessary parameters (selection over the axis, zoom, etc.).
Class structure
The planning structure is itself divided into two parts :
a 'BasicStructure',a first structure built from the objects. The corresponding process just take the parameters to recover the ERP5 objects to display, and organize them in a structure that matches the final output (groups with their subgroups, depth, report) with their specificity (the report or lane axis). Note that no block are generated : this is only abstract structure.
a 'PlanningStructure', alias generic process, is based on the 'BasicStructure', but offers a final an evoluated structure, with all the precise informations : objects can be divided into several blocks if needed, blocks are displayed on several lines if needed, info on blocks, tootlips, axis completed, etc.)
Notes :
- There is no axis representation in the basic structure. only the second one deals with the final axis rendering.
'PlanningStructure' uses several levels for axis representation : the axis itself is an 'Axis object'. This 'Axis' is composed of several 'AxisGroups' representing an entity. but in some cases an 'AxisGroup' need several lines to be represented correctly, and that is why 'AxisElement' is present. 'AxisElement' is a sub-entity of 'AxisGroup', and permits to identify each line separately. Using this system, a Block belongs to an 'AxisElement', that composes an 'AxisGroup', itself a component of an 'Axis'.
'AxisGroups', as well as 'Blocks', uses 'Positions' objects for determining their position over the corresponding axis. Two 'Position' instances are required for each 'Block' or 'AxisGroup'. These 'Position' objects handle two kind of coordinates : absolute and relative. The absolute coordinates specify the position and size of the current object in an abstract way (usually with integers : start=2, range=3, stop=5), whereas relatives coordinates is from a rendering point of vue, i.e in a representative way (usually with floats : start=40% of the full size, range=60%, stop=100%).
'AxisGroups' can be identified differently depending on the way we want to access them : to set the start and stop of a block over an axis (generic way), just use 'position_main' and 'position_secondary' (used to set block position over the axis). On the other hand, to acces a specific axis to set the coordinates for example, use 'position_x' and 'position_y' (used to set CSS properties).
render_structure processing
These class implementations are done in the 'render_structure' method, that calls itself a sub-method for each sub structure. these two methods are respectively basic.build() and planning.build() (They are called in this order).
basic.build()
work description :
- uses the different parameters to build a Query (selection, report folded / unfolded, list_method, etc.)
call the makeTreeList method to recover the objects. This method is also used in ListBox.
process these objects to order them in a list : 'report_group_list'. Check if there is any report_mode with different depths, or if need to import a sub object list. After this process 'report_group_list' holds all the planning objects. In case of statistic mode with valid statistic script provided, then call it.
- apply selection on the report axis, to cut the planning into several pages, and offer a navigation mode over the report axis.
- apply selection on the lane axis : Once the main axis objects are known, can get axis bounds or the lane axis, depending on the current domain selected.
finally parses the resulting 'report_group_list' structure to build the basic structure, composed of 'BasicAxis' and 'BasicActivity' objects.
planning.build()
work description :
- create the axis : instanciate Axis classes for X and Y
- link axis to their corresponding accessor : report or lane
build main group structure for the main axis. This does not take into account the lane axis. This 'buildGroups()' method uses AxisGroup and AxisElement objects to insert each Activity corresponding to an Object.
- build the secondary axis thanks to the extreme bounds recovered from the basic structure. this step uses the external script for generating the axis itself.
- complete axis : this complementing process is here to fix axis properties (and absolute position).
- build blocks from Activity, fix info text in blocks. If needed, can call an external script to split activities into blocks in a special way.
|
|
|
| ||||||||
|
|