语法

添加XML代码

该教程将说明如何扩展其他教程中提供的XML以使其与iTop XML树结构.

为了使其可读,我们使用了一个真实的示例,该示例修改了用户门户在创建新请求时显示可用服务和服务子类别的方式。默认情况下,iTop将它们显示在列表中,并且我们将变更将其默认显示为树结构。

简化的语法

为了提高教程的可读性并突出显示需要更改的XML节点,将在简化路径语法中提供周围的XML结构。

  • 每个级别由
  • itop_design是唯一可能的顶级标签,有时在语法样例中可能会省略它,但在XML文件中不要忽略它。
  • 末尾带有s的标签通常是集合
  • 在集合下,您通常检索不带s且具有ID以区分节点的相同标签
  • brick @ toto表示<brick id =“ toto”>

这是此示例的最短语法,其中仅需要修改一个节点:

itop_design / module_designs / module_design@itop-portal / bricks / brick@services / browse_modes

      <default _delta="redefine">tree</default>

无需打开XML标记的每个级别然后一个接一个地关闭它们,我们只需提供一个表示树结构的单个字符串,并将其放在代码块的标题中即可。

通常,它将减少压缩以提高可读性:

itop_design / module_designs / module_design@itop-portal / bricks
 
   <brick id="services">
       <browse_modes>
           <default _delta="redefine">tree</default>
       </browse_modes>
   </brick>

完整的XML结构

现在,这就是您需要将上述块扩展为iTop所需的完整XML结构的方式

itop_design / module_designs / module_design@itop-portal / bricks / brick@services / browse_modes

            <!-- block content -->

应该翻译成:

<?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>

同样不是简化的语法的一部分,这2行必须记录在顶部

<?xml version="1.0" encoding="UTF-8"?>
<itop_design version="1.6">

本=“ 1.6”对应于您的扩展程序所需的最小iTop XML版本。
通过将iTop版本的第一个数字删除1,可以从iTop版本猜到XML版本,直到iTop 2.6为止。

  • 示例:所有iTop 2.6.x版本都使用1.6的XML版本
  • 如果您使用XML标签,例如在iTop 2.5中添加的XML。那么不要将XML版本放在1.5以下

如果使用_delta =“ define”,则在树结构上方的某个位置设置_delta =“ must_exist”更安全。

测试它

将简化的XML扩展为完整的所需结构后,将其复制到扩展名的文件datamodel.my-extension.xml(my-extension是您的真实扩展名)中,然后运行安装程序或工具包以查看结果。

添加PHP代码

对于插入方法,只能在类或模块中的2个位置进行。

  • 对于类,我们将仅在框标题中提供需要在其中声明方法的类:class:UserRequest
  • 对于模块,不存在特定的语法。

现有类的方法

本部分说明如何在类上定义和覆盖PHP方法。

  • 多个教程将告诉您在类上编写PHP方法,以在iTop中实现新行为。
  • 他们甚至可以为您提供确切的PHP代码,
  • 但是他们不会解释如何将PHP代码插入iTop XML结构中。
  • 这项技术与方法本身无关,正是我们将要解释的内容
  • 为了使它不那么抽象,我们使用一个真实的示例:

所使用的示例摘自复杂的用例,这里我们只看一下用XML声明PHP方法

简化的语法

在标题框中,您将找到需要在其中声明方法的类。例如。 class:UserRequest

class:UserRequest

public function IncrementCounter($sAttCode, $iIncrement=1)
{
   // Defensive programming, ensure that the field code is valid on current class       
   if (MetaModel::IsValidAttCode(($this), $sAttCode))
   {
       $iNew = $this->Get($sAttCode) + $iIncrement;
       $this->Set($sAttCode, $iNew);
   }
   return true;
} 

在粘贴到文件datamodel.my-extension.xml中之前,必须先扩展PHP代码。

完整的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>

有关如何解码的一些详细信息:

资源应该翻译成…
众职能增量计算器()<access>public</access>
受保护的职能…<access>protected</access>
公众职能…<static>false</static>
公众静态职能…<static>true</static>
公众职能增量计数器<method id=“IncrementCounter”>

风险性

定义DBObject可重写方法之一时,请注意,它可能已在标准iTop数据模型中完成。如果是这种情况,在setup/toolkit编译时,当您使用_delta =“ define”添加该方法时,如果该方法已经存在,则将失败。在这种情况下,您可以执行“重新定义”,但是镜像现有代码,否则将破坏iTop的当前行为。

特定于ITSM设计器

如果满足以下条件,则必须使用arguments标签:

  • 您的扩展程序将被加载到ITSM Designer中
  • AND方法必须由转换上的功能调用

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>

在新的PHP类中

最简单的方法是将此代码放入扩展的文件main.my-extension.php中。

但是也可以将其放在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> 

原贴链接:https://www.itophub.io/wiki/page?id=2_7_0%3Acustomization%3Ainsert-xml


Syntax used in Tutorials

Add XML code

This tutorial will explain how to expand a piece of XML provided in other tutorial to make it compliant with 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:

itop_design / module_designs / module_design@itop-portal / bricks / brick@services / browse_modes
 
      <default _delta="redefine">tree</default>

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:

itop_design / module_designs / module_design@itop-portal / bricks
 
   <brick id="services">
       <browse_modes>
           <default _delta="redefine">tree</default>
       </browse_modes>
   </brick>

Full XML structure

Now this is how you need to expand the above blocks into the full XML structure required by iTop

itop_design / module_designs / module_design@itop-portal / bricks / brick@services / browse_modes
 
            <!-- block content -->

should be translated into:

<?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>

Also not part of the simplified syntax, those 2 rows must be documented at the top

<?xml version="1.0" encoding="UTF-8"?>
<itop_design version="1.6">

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

If you use a _delta=“define” it's safer to set a _delta=“must_exist” somewhere above in the tree structure.

Test it

Once you have expanded the simplified XML into the full required structure, copy it into the file datamodel.my-extension.xml of your extension - my-extensionbeing 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:

The used example is an extract from a more complex use case, here we only look at declaring a PHP method in XML

Simplified syntax

In the title box, you will find the class in which the method need to be declared. eg. class:UserRequest

class:UserRequest
 
public function IncrementCounter($sAttCode, $iIncrement=1)
{
   // Defensive programming, ensure that the field code is valid on current class       
   if (MetaModel::IsValidAttCode(($this), $sAttCode))
   {
       $iNew = $this->Get($sAttCode) + $iIncrement;
       $this->Set($sAttCode, $iNew);
   }
   return true;
}         

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:

<?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>

Some details on how to decode:

Sourceshould 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:

  • your extension will be loaded in the ITSM Designer

  • AND the method must be called by an action on a transition

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>

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:

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> 
标签:
由 superadmin 在 2020/08/27, 16:32 创建
    

需要帮助?

如果您需要有关XWiki的帮助,可以联系:

深圳市艾拓先锋企业管理咨询有限公司