Maarch Framework 3/Developer handbook/Autofoldering

De Maarch // Wiki.

Cette section du wiki est en cours de restructuration et de rédaction. Nous nous excusons pour la gêne occasionnée. This section of the wiki is under heavy restructuring and writing. We're sorry for the inconvenience.

Summary

Installation

Quick Install

The tables for this module are defined in the file autofoldering/sql/structure/ directory depending on your database engine, and the mimimal data in the autofoldering/sql/data/ directory. As of now, we provide only mysql and postgresql scripts, but it is not difficult to build script for other database with existing scripts.

To load the module, just add these lines in the apps config.xml file in the <MODULES> section :

<MODULES>
   <moduleid>autofoldering</moduleid>
   <comment>_AUTOFOLDERING</comment>
</MODULES>

Make sure the service is active (the <loaded> tag is set to true in autofoldering/xml/config.xml).

Setting

config.xml file

This file contains information about the generation and the display of sorting trees inside Maarch Framework 3.

The database information are necessary as autofoldering module contains also a batch process.

The configuration of access rights to the trees configures in the administration interface.

<?xml version="1.0" encoding="utf-8"?>
<ROOT>
	<CONFIG>
		<name>autofoldering</name>  <!-- module name : MUST BE THE DIRECTORY NAME OF THE 
                                                 MODULE -->
		<comment>_AUTOFOLDERING</comment>  <!-- Label of the module, defined in the 
                                                        autofoldering language file -->
		<file_prefix>af</file_prefix>
		<loaded>true</loaded>
		<databaseserver>127.0.0.1</databaseserver> <!-- Maarch Database server IP or NAME -->
		<databaseserverport>3306</databaseserverport> <!-- Maarch Database server port -->
		<databasename>maarch_v3</databasename> <!-- Maarch Database name-->
		<databasetype>MYSQL</databasetype>  <!-- Maarch Database type : MYSQL, POSTGRESQL, ...-->
		<databaseuser>root</databaseuser> <!-- Maarch Database user -->
		<databasepassword></databasepassword> <!-- Maarch Database password -->
		<lang>fr</lang> <!-- Maarch language -->
		<MaarchDirectory>/path/to/maarch_v3/</MaarchDirectory>  <!-- Path to Maarch directory -->
		<AutofolderingUrl>http://127.0.0.1/maarch_v3/modules/autofoldering/</AutofolderingUrl>	
                                  <!-- URL to the Autofoldering  -->
		<ErrorLevel>1</ErrorLevel> <!-- Error Level : 0 /1 -->
		<LogFile>log.txt</LogFile> <!-- Name of the log file -->
		<DebugMode>true</DebugMode> <!-- Enabled / Disabled the debug mode -->
	</CONFIG>
	<TABLENAME> <!-- Module specific tables -->
		<af_nodes_items>autofoldering_node_item</af_nodes_items>
		<af_security>autofoldering_security</af_security>
	</TABLENAME>
	<HISTORY> <!-- What will be traced in the module -->
		<treedel>true</treedel>  <!-- Delete right on a tree -->
		<treeup>true</treeup>  <!-- Modify right on a tree -->
	</HISTORY>
</ROOT>
</xml>

The <HISTORY> tag contains the list of all events that can be saved in the application history. To disable this, just set the action tag to false.

autofoldering.xml file

This file contains the definition of the trees.

The autofoldering.xml file can contains more than one <tree> tag.

A tree contains at least one node. A node can also contain node.

The <select_key> tag can be different from <select_label>. The first one is used for next search, as the second one is the one displayed in the tree.

The <where_clause> tag is a filter on rows to display. You must use html entities instead of < an >.

The <script> tag can be placed on any node. It indicates the script that queries the view for the selected branch. You can replace it by your own script. Be careful not to change native maarch scripts, so you can upgrade more easily to future versions.

The <DOCTYPE> : autofoldering.xml is related to a dtd (autofoldering.dtd), in this example, the application server can be accessed at the address 127.0.0.1, and the configuration is standard. If you want to install Maarch Framework on another server, do not forget to change the IP address in the <DOCTYPE> tag to run properly the autofoldering module.

Here is an example:

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE root SYSTEM "http://127.0.0.1/maarch_v3/modules/autofoldering/xml/autofoldering.dtd">
 <!--  If not on 127.0.0.1 server, you must change the IP Address to run properly the autoldering batch -->
<root>
	<tree>
		<id>view_year</id> <!-- Tree identifier : ONLY alphanumeric characters
                                        and _ allowed -->
		<desc>_TREE_VIEW_YEAR</desc> <!-- Tree description : defined in the module language file -->
		<view>res_view_invoices</view> <!-- SQL view : mandatory to build the tree -->
		<node>
			<node_id>country</node_id> <!-- Node identifier : ONLY alphanumeric characters
                                                        and _ allowed -->
			<comment>Pays / Country</comment> <!-- Node description -->
			<select_key>doc_custom_t3</select_key>  <!-- SQL field in the defined view : 
                                                                     represents the key of the node -->
			<datatype>STRING</datatype> <!-- Node value data type -->
			<select_label>doc_custom_t3</select_label> <!-- Node displayed value  -->
			<whereclause>status &lt;&gt; 'DEL' and status &lt;&gt; 'ATT' and status 
&lt;&gt; 'REP'</whereclause> <!-- SQL where clause : node restriction -->
			<orderby>asc</orderby> <!-- Node order : asc or desc -->
			<node>
				<node_id>year</node_id>
				<comment>Année / Year</comment>
				<select_key>year(doc_date)</select_key>
				<datatype>DATE</datatype>
				<select_label>year(doc_date)</select_label>
				<whereclause> year(doc_date) is not null </whereclause>
				<orderby>asc</orderby>
				<node>
					<node_id>customer</node_id>
					<comment>Client / Customer</comment>
					<select_key>doc_custom_t4</select_key>
					<datatype>STRING</datatype>
					<select_label>doc_custom_t4</select_label>
					<orderby>asc</orderby>
					<script>show_doc_folders</script> <!-- script which displays
                                                                            the results of the current node -->
				</node>
			</node>
		</node>
	</tree>
</root>

Launching Autofoldering

The script autofoldering_load_db.php is a batch process that needs to be launched apart. It takes 2 arguments : the config file and the tree definition file, as seen in the command batch examples :

Windows : using xampp

 
cd C:\Program Files\xampp\php
php ..\htdocs\maarch_v3\modules\autofoldering\autofoldering_load_db.php ..\htdocs\maarch_v3\modules
\autofoldering\xml\config.xml ..\htdocs\maarch_v3\modules\autofoldering\xml\autofoldering.xml

Linux

 
php /var/www/maarch_v3/modules/autofoldering/autofoldering_load_db.php /var/www/maarch_v3/modules
/autofoldering/xml/config.xml /var/www/maarch_v3/modules/autofoldering/xml/autofoldering.xml

Log file in verbose mode is pretty detailed. In case of error, "ERROR" string appears in the log :

08 08 2008 14:46:16 INFO  0 : Load xml config file : ..\htdocs\maarch_v3\modules\autofoldering\xml\config.xml
08 08 2008 14:46:16 INFO  0 : Begin validation mapping file : ..\htdocs\maarch_v3\modules\autofoldering\xml\autofoldering.xml
08 08 2008 14:46:16 INFO  0 : End validation mapping file : ..\htdocs\maarch_v3\modules\autofoldering\xml\autofoldering.xml
08 08 2008 14:46:16 INFO  0 : Load xml mapping file : ..\htdocs\maarch_v3\modules\autofoldering\xml\autofoldering.xml
08 08 2008 14:46:16 INFO  0 : Begin parsing mapping file 
08 08 2008 14:46:16 INFO  0 : Begin parsing tree node : view_year

08 08 2008 14:46:16 INFO  0 : Put status to DEL in database : view_year
08 08 2008 14:46:16 INFO  0 : Exploring node : Pays / Country
08 08 2008 14:46:16 INFO  0 : Selecting item corresponding to the node : Pays / Country
08 08 2008 14:46:16 INFO  0 : Query : select DISTINCT doc_custom_t3 as id from res_view_invoices where status <> 'DEL' and status <> 'ATT' and status <> 'REP'
08 08 2008 14:46:16 INFO  0 : Node id France
08 08 2008 14:46:16 INFO  0 : Selecting label of France
08 08 2008 14:46:16 INFO  0 : Insert node in the database 
08 08 2008 14:46:16 INFO  0 : Add level 1 node :
08 08 2008 14:46:16 INFO  0 :   Tree id : view_year 
08 08 2008 14:46:16 INFO  0 :   Key value : France 
08 08 2008 14:46:16 INFO  0 :   Label value : France 
08 08 2008 14:46:16 INFO  0 :   Parent item id : 0 
08 08 2008 14:46:16 INFO  0 :   Node id : country 
08 08 2008 14:46:16 INFO  0 :   Query : insert into autofoldering_node_item (tree_id, level, key_value, label_value, parent_item_id, node_id, status) values  ('view_year', 1, 'France', 'France', 0, 'country', 'OK') 
08 08 2008 14:46:16 INFO  0 : Get node item id 
08 08 2008 14:46:16 INFO  0 : Value : 1419 
...

Provided Services

All the localization constants used in service.xml are defined in the autofoldering languages files.

All the css styles defined in the style tag are defined in css files of the autofoldering/css directory.

By default, some service are defined as system services. It means that these services will be activated for all users. You can easily modify it by setting the <system_service> tag to false.

To deactivate a service, simply set the <enabled> tag to false.

admin_tree_autofoldering

This service grant an user access to the admin panel for autofoldering.

<SERVICE>
   <id>admin_tree_autofoldering</id> <!-- service identifier -->
   <name>_ADMIN_TREE_AUTOFOLDERING</name>  <!-- service label -->
   <comment>_ADMIN_TREE_AUTOFOLDERING_DESC</comment><!-- service description -->
   <servicepage>index.php?page=af_trees&amp;module=autofoldering</servicepage> <!-- service page -->
   <servicetype>admin</servicetype>  <!-- service type -->
    <system_service>false</system_service>
   <style>af_admin_tree_autofoldering</style>
   <enabled>true</enabled>
   <WHEREAMIUSED>
     <page>admin.php</page>
     <nature>listelement</nature>
   </WHEREAMIUSED>
 </SERVICE>

This service is an admin service. This is not a system service by default.

view_tree

This adds an "Autofoldering" entry in Maarch menu for a user goup.

<SERVICE>
   <id>view_trees</id> <!-- if servicetype = menu, this id must be equal to the id of the menu item -->
   <name>_VIEW_TREES</name>
   <comment>_VIEW_TREES_DESC</comment>
   <servicetype>menu</servicetype>
    <system_service>false</system_service>
   <enabled>true</enabled>
 </SERVICE>

This is not a system service by default.

Customisation