User Tools

Site Tools

:: Version 2.6.0 ::

2_6_0:customization:insert-xml

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

2_6_0:customization:insert-xml [2019/08/14 17:02] (current)
vdumas created
Line 1: Line 1:
 +====== Syntax used in Examples =====
 +
 +===== Add XML code =====
 +
 +This tutorial will explain how to expend a piece of XML provided in other tutorial to make it compliant with [[2_6_0:​customization:​xml_reference|iTop XML tree structure]].
 +
 +//In order to make it readable, we are using a true example, which modifies the way the User Portal displays available services and services sub-categories,​ when creating a new request. By default, iTop displays them in a list, and we will change it to be displayed them by default as a tree structure.//​
 +
 +==== Simplified syntax ====
 +
 +In order to increase the tutorials readability and highlight the XML nodes which need to be changed, the surrounding XML structure will be provided in a simplified path syntax.
 +
 +  * Each level is separated by  **/​**  ​
 +  * ''​itop_design''​ is the only possible top tag, it might be omitted sometimes in the wiki syntax, but don't omit it in the XML file.
 +  * tags with a ''​s''​ at the end are usually collections ​
 +  * Under a collection, you retrieve usually the same tag without ''​s''​ and with a ''​id''​ to differentiate the nodes
 +  * ''​brick@toto''​ means **<brick id="​toto">​**
 +
 +Here is the shortest possible syntax for this example, where **only one node need to be modified**: ​
 +<code XML itop_design / module_designs / module_design@itop-portal / bricks / brick@services / browse_modes>​
 +      <default _delta="​redefine">​tree</​default>​
 +</​code>​
 +
 +Instead of opening each level of XML tags and then closing them one by one, we will just provide in a single string, representing the tree structure, and put it in the title of the code block.
 +
 +In general it will be less compressed for better readability:​
 +
 +<code XML itop_design / module_designs / module_design@itop-portal / bricks>
 +   <​brick id="​services">​
 +       <​browse_modes>​
 +           <​default _delta="​redefine">​tree</​default>​
 +       </​browse_modes>​
 +   </​brick>​
 +</​code>​
 +
 +==== Full XML structure ====
 +
 +Now this is how you need to expend the above blocks into the full XML structure required by iTop 
 +
 +<code XML  itop_design / module_designs / module_design@itop-portal / bricks / brick@services / browse_modes>​
 +            <!-- block content -->
 +</​code>​
 +
 +should be translated into:
 +
 +<code XML>
 +<?xml version="​1.0"​ encoding="​UTF-8"?>​
 +<​itop_design version="​1.6">​
 +  <​module_designs>​
 +    <​module_design id="​itop-portal">​
 +      <​bricks>​
 +        <brick id="​services">​
 +          <​browse_modes>​
 +            <!-- Insert here the block content -->
 +          </​browse_modes>​
 +        </​brick>​
 +      </​bricks>​
 +    </​module_design>​
 +  </​module_designs>​
 +</​itop_design>​
 +</​code>​
 +
 +Also not part of the simplified syntax, those 2 rows must be documented at the top
 +<code XML>
 +<?xml version="​1.0"​ encoding="​UTF-8"?>​
 +<​itop_design version="​1.6">​
 +</​code>​
 +
 +**version="​1.6"​** correspond to the minimal iTop XML version required by your extension. \\
 +The XML version is available since iTop 2.0 and at least until iTop 2.6, can be guessed from the iTop version, by removing 1 to the first digit.
 +  * example: all iTop 2.6.x versions uses an XML version of 1.6
 +  * If you use a XML tag which was added in iTop 2.5 for eg. then don't put an XML version below 1.5
 +
 +<note tip>If you use a **_delta="​define"​** it's safer to set a _delta="​must_exist"​ somewhere above in the tree structure.</​note>​
 +
 +==== Test it ====
 +
 +Once you have expended the simplified XML into the full required structure, copy it into the file ''​datamodel.my-extension.xml''​ of your extension - //​my-extension//​ being your true extension name - and run the setup or the toolkit to see the result.
 +
 +
 +====== Add PHP code =======
 +
 +For inserting a method, it can only be done in 2 places, in a class or in a module.
 +  * for class we will just provide the class in which the method need to be declared in the box title: **class:​UserRequest**
 +  * for module, no specific syntax exist.
 +
 +===== Method on existing class =====
 +
 +This part explains how to define/​overwrite a PHP method on a class. ​
 +  * Multiple tutorials will tell you to write a PHP method on a class, to implement a new behavior in iTop.
 +  * They may even provide you the exact piece of PHP code,
 +  * But they won't explain how to insert that PHP code into the iTop XML structure.
 +  * This technic, independent of the method itself, is just what we will explain
 +  * To make it less abstract, we are using a true example:
 +
 +
 +==== Simplified syntax ====
 +
 +In the title box, you will find the class in which the method need to be declared. eg. **class:​UserRequest**
 +
 +<code PHP class:​UserRequest>​
 +public function IncrementCounter($sAttCode,​ $iIncrement=1)
 +{
 +   // Defensive programming,​ ensure that the field code is valid on current class       
 +   if (MetaModel::​IsValidAttCode(get_class($this),​ $sAttCode))
 +   {
 +       $iNew = $this->​Get($sAttCode) + $iIncrement;​
 +       ​$this->​Set($sAttCode,​ $iNew);
 +   }
 +   ​return true;
 +}         
 +</​code>​
 +
 +The PHP code must be expended before being paste in the file ''​datamodel.my-extension.xml'' ​
 +
 +==== Full XML code ====
 +
 +Here is how it must be expended:
 +
 +<code XML>
 +<?xml version="​1.0"​ encoding="​UTF-8"?>​
 +<​itop_design version="​1.3">​
 +  <​classes>​
 +    <!-- the class name is found in the title of the simplified syntax box -->
 +    <class id="​UserRequest"​ _delta="​must_exist">​
 +      <​methods>​
 +        <!-- any '​id'​ could work, but easier to remember if equal to function name -->
 +        <method id="​IncrementCounter"​ _delta="​define">​
 +          <​static>​false</​static>​
 +          <​access>​public</​access>​
 +          <!-- comment is optional -->
 +          <​comment><​![CDATA[
 +/**
 + * $sAttCode should be a valid field code of the UserRequest class of type Integer or Decimal
 + * $iIncrement must be an integer
 + */
 +          ]]></​comment>​
 +          <​code><​![CDATA[
 +public function IncrementCounter($sAttCode,​ $iIncrement=1)
 +{
 +   // Defensive programming,​ ensure that the field code is valid on current class       
 +   if (MetaModel::​IsValidAttCode(get_class($this),​ $sAttCode))
 +   {
 +       $iNew = $this->​Get($sAttCode) + $iIncrement;​
 +       ​$this->​Set($sAttCode,​ $iNew);
 +   }
 +   ​return true;
 +}         
 +          ]]></ code> <!-- remove the blank between </ and code (wiki limitation) -->
 +        </​method>​
 +      </​methods>​
 +    </​class>​
 +  </​classes>​
 +</​itop_design>​
 +</​code>​
 +
 +Some details on how to decode:
 +|  Source ​ |  should be translated into... ​ |
 +| **public** function IncrementCounter() | <​access>​**public**</​access>​ |
 +| **protected** function ... | <​access>​**protected**</​access>​ |
 +| public ​      ​function ... | <​static>​false</​static>​ |
 +| public **static** function ... | **<​static>​true**</​static>​ |
 +| public function **IncrementCounter**( | **<​method id="​IncrementCounter">​** |
 +
 +=== Risks ===
 +
 +When you define one of the DBObject overwritable methods, be aware that it may have been done already within the standard iTop datamodel. If it is the case, at setup/​toolkit compilation,​ as you add the method with a ''​_delta="​define"''​ it will fails if it exists already. In that case, you can do a "​redefine",​ but then mirror the existing code or you will break the current behavior of iTop.
 +
 + 
 +=== ITSM Designer specific ===
 +
 +''​arguments''​ tags are required if:
 +  * you extension will be loaded in the ITSM Designer
 +  * AND the method must be called by an action on a transition
 +
 +<code XML itop_design / classes / class@UserRequest / methods>
 +        <method id="​IncrementCounter"​ _delta="​define">​
 +          < ... >
 +          <​arguments>​
 +            <​argument id="​1">​
 +              <​mandatory>​true</​mandatory>​
 +              <​type>​attcode</​type>​
 +            </​argument>​
 +            <​argument id="​2">​
 +              <​mandatory>​false</​mandatory>​
 +              <​type>​int</​type>​
 +            </​argument>​
 +          </​arguments>​
 +        </​method>​
 +</​code>​
 +
 +===== Within a new PHP class =====
 +
 +The easiest is to put this code into the file ''​main.my-extension.php''​ of your extension.
 +
 +But it can also be put in the XML structure under: ​
 +
 +<code XML itop_design / snippets>​
 +    <snippet id="​ScheduledStart"​ _delta="​define">​
 +      <​placement>​module</​placement>​
 +      <​module>​itop-request-mgmt</​module>​
 +      <​rank>​200</​rank>​
 +      <​content><​![CDATA[
 +         /* enter here the code with class definition and methods */
 +      ]]></​content>​
 +    </​snippet> ​
 +</​code>​
  
2_6_0/customization/insert-xml.txt ยท Last modified: 2019/08/14 17:02 by vdumas

";