为控制台仪表板创建新的仪表盘:iFrame

学习:添加新的仪表盘类型

水平:高级

域:PHP,  Presentation

最低版本:2.1.0

本文档逐步说明了如何创建自己的iTop模块,以便将新的仪表盘添加到控制台仪表板:iFrame。

教程的目标

在本分步教程中,您将学习:

  • 为iTop 2.5创建自己的扩展模块
  • 仪表盘的创建类
  • 在现有仪表板中添加新条目

出于此教程的目的,我们将使用称为IFrameDashlet的仪表盘的创建类,这将非常简单并嵌入外部网页。

https://www.itophub.io/wiki/media?w=800&tok=66e9b9&media=2_7_0%3Acustomization%3Aadd-dashlet-sample-01.png

您将需要什么

  • 将iTop安装在开发机器上,您可以在其上轻松地访问编辑文件。
  • 一个文本编辑器,能够编辑PHP和XML文件并支持U-8。在Windows上,您可以使用写字板(记事本不喜欢Unix行结尾)或出色的免费开发IDE之一,例如PSPad 要么记事本++.

定制流程

定制流程如下:

  1. 安装iTop的开发实例。最好不要在生产中进行试验!
  2. 安装工具包 协助您进行定制
  3. 使用以下命令创建一个新的(空)模块模块创建向导 
  4. 将此新模块复制到iTop上的扩展文件夹,然后再次运行安装程序以安装空模块
  5. 修改扩展中的模块并使用工具包检查您的自定义

重复最后一点,直到对自定义满意为止。完成后,就可以部署新模块了。将模块文件夹复制到生产iTop实例的扩展目录中,然后运行安装程序进行安装。

循序渐进教程

创建您的自定义模块

使用模块创建向导。用以下值填充表单:

标签价值备注
模块名称sample-add-dashlet以itop-和combodo-开头的名称保留供Combodo使用。建议不要在模块名称中添加空格或强调字符。具有相同名称的两个模块不能在同一iTop实例中共存。
模块标签Add Dashlet Sample该标签将显示在设置向导中。允许使用本地化的字符和空格
模块版本1.0.0惯例是使用3位数编号方案:X.Y.Z
类别business对数据模型进行修改的模块应位于类别'业务'中

单击生成!将空模块下载为zip文件。

安装空模块

将zip的内容扩展到开发iTop实例的扩展文件夹中。现在,您应该在扩展文件夹中有一个名为sample-add-仪表盘的文件夹。此文件夹包含以下文件:

  • datamodel.sample-add-dashlet.xml
  • module.sample-add-dashlet.php
  • en.dict.sample-add-dashlet.php
  • model.sample-add-dashlet.php

确保Web服务器的文件conf/production/config-itop.php是可写的(在Windows上:右键单击以显示文件属性,并取消选中只读标志;在Linux变更上为文件的权利),然后通过以下方式启动iTop安装:将您的浏览器指向http ::: your_itop/setup/

Launching the re-install

单击“继续»”开始重新安装。

https://www.itophub.io/wiki/media?w=300&tok=554538&media=2_7_0%3Acustomization%3Ainstall-extension-2.png

在单击“下一步»”之前,请确保已选择“更新现有实例”。

https://www.itophub.io/wiki/media?w=300&tok=2395b2&media=2_7_0%3Acustomization%3Aupgrade-screenshot2.png

继续执行向导的下一步……

Select the new extension

您的自定义模块应出现在“扩展”列表中。如果不是这种情况,请检查是否在正确的位置复制了模块文件,并且Web服务器具有足够的权利可以读取它们。

在单击“下一步»”之前,请选择您的自定义模块并完成安装。

添加IFrameDashlet类

使用常用文本编辑器,在扩展文件夹中创建文件iframedashlet.class.inc.php。

添加以下代码:

<?php class DashletIFrame extends Dashlet { public function __construct($oModelReflection, $sId) { parent::__construct($oModelReflection, $sId); } static public function GetInfo() { } public function GetPropertiesFields(DesignerForm $oForm) { } public function Render($oPage, $bEditMode = false, $aExtraParams = ()) { } }

这是创建仪表盘的基本代码。如您所见,这些方法暂时是空的,我们将必须实现它们,但首先让我们看看它们的用途是什么。

  • “ GetInfo”用于检索仪表盘的基本信息,例如其标签,描述和图标。这主要在仪表板的“可用dashlets”菜单下使用。
  • “ GetPropertiesFields”用于仪表盘的构建,配置表单。在这里,我们必须放置用户将填充的参数以设置仪表盘。
  • “渲染”用于制作仪表盘的HTML渲染,这是大多数逻辑发生的地方。

https://www.itophub.io/wiki/media?w=800&tok=082f15&media=2_7_0%3Acustomization%3Aadd-dashlet-sample-03.png

让我们从GetInfo方法开始。用下面的代码替换空方法:

  • 编辑仪表板时,“ label”将用作仪表盘面板中的工具提示。
  • 仪表盘面板中还将使用“icon”。该路径必须相对于应用根文件夹。
  • “ description”暂时不显示,但应尽快显示。

static public function GetInfo() { return ( 'label' => Dict::S('UI:DashletIframe:Label'), 'icon' => 'env-'.utils::GetCurrentEnvironment().'/sample-add-dashlet/images/iframe.png', 'description' => Dict::S('UI:DashletIframe:Description'), ); }

然后,将GetPropertiesFields方法替换为以下内容:

public function GetPropertiesFields(DesignerForm $oForm) { $oField = new DesignerLongTextField('url', Dict::S('UI:DashletIframe:Prop-Url'), $this->aProperties['url']); $oField->SetMandatory(); $oForm->AddField($oField); $oField = new DesignerIntegerField('width', Dict::S('UI:DashletIframe:Prop-Width'), $this->aProperties['width']); $oField->SetMandatory(); $oForm->AddField($oField); $oField = new DesignerIntegerField('height', Dict::S('UI:DashletIframe:Prop-Height'), $this->aProperties['height']); $oField->SetMandatory(); $oForm->AddField($oField); }

如您所见,我们为每个参数添加一个DesignerXXXField,我们需要用户来填充它。 iTop将处理表单的处理以及与仪表板的交互。

不幸的是,没有可用字段类的文档。要找到可用的内容,请在application/forms.class.inc.php中检查DesignerFormField类及其派生类。

最后,用以下代码替换Render方法:

public function Render($oPage, $bEditMode = false, $aExtraParams = ()) { $sUrl = $this->aProperties['url']; $iWidth = (int) $this->aProperties['width']; $iHeight = (int) $this->aProperties['height']; $oPage->add('<div class="dashlet-content">'); $sId = utils::GetSafeId('dashlet_iframe_'.($bEditMode? 'edit_' : '').$this->sId); $oPage->add('<iframe id="'.$sId.'" width="'.$iWidth.'" height="'.$iHeight.'" frameborder="0" src="'.$sUrl.'"></iframe>'); if($bEditMode) { $oPage->add('<div style="width: 100%; height: 100%; position: absolute; top: 0px; left: 0px; cursor: not-allowed;"></div>'); } $oPage->add('</div>'); }

在这种情况下,代码非常简单,因为我们只想显示一个指向URL的iframe标签。但这是您应该执行仪表盘的逻辑,通过OQL检索对象,计算内容等的地方。拥有$ oPage元素的访问权限后,您甚至可以携带CSS或JS filessnippets。天空才是极限!

现在,您的文件应如下所示:

<?php class DashletIFrame extends Dashlet { public function __construct($oModelReflection, $sId) { parent::__construct($oModelReflection, $sId); $this->aProperties['url'] = ''; $this->aProperties['width'] = 600; $this->aProperties['height'] = 650; $this->aCSSClasses[] = 'dashlet-inline'; } public function Render($oPage, $bEditMode = false, $aExtraParams = ()) { $sUrl = $this->aProperties['url']; $iWidth = (int) $this->aProperties['width']; $iHeight = (int) $this->aProperties['height']; $oPage->add('<div class="dashlet-content">'); $sId = utils::GetSafeId('dashlet_iframe_'.($bEditMode? 'edit_' : '').$this->sId); $oPage->add('<iframe id="'.$sId.'" width="'.$iWidth.'" height="'.$iHeight.'" frameborder="0" src="'.$sUrl.'"></iframe>'); if($bEditMode) { $oPage->add('<div style="width: 100%; height: 100%; position: absolute; top: 0px; left: 0px; cursor: not-allowed;"></div>'); } $oPage->add('</div>'); } public function GetPropertiesFields(DesignerForm $oForm) { $oField = new DesignerLongTextField('url', Dict::S('UI:DashletIframe:Prop-Url'), $this->aProperties['url']); $oField->SetMandatory(); $oForm->AddField($oField); $oField = new DesignerIntegerField('width', Dict::S('UI:DashletIframe:Prop-Width'), $this->aProperties['width']); $oField->SetMandatory(); $oForm->AddField($oField); $oField = new DesignerIntegerField('height', Dict::S('UI:DashletIframe:Prop-Height'), $this->aProperties['height']); $oField->SetMandatory(); $oForm->AddField($oField); } static public function GetInfo() { return ( 'label' => Dict::S('UI:DashletIframe:Label'), 'icon' => 'env-'.utils::GetCurrentEnvironment().'/itop-iframe-dashlet/images/iframe.png', 'description' => Dict::S('UI:DashletIframe:Description'), ); } }

通过运行工具包检查您的修改。将浏览器指向http ::: your_itop/toolkit。

Checking the modifications with the toolkit

如果在此阶段报告了任何错误,请通过编辑XML文件进行修复,然后单击工具包页面中的“刷新”按钮再次检查您的修改。

解决所有错误后,您可以使用工具包的第二个选项卡将修改应用于iTop。单击按钮更新iTop代码和数据库!至:

  1. 将XML数据模型编译为PHP类
  2. 更新数据库架构(创建监视器表)。

此时,如果您在iTop中导航并单击“欢迎页面”中的“编辑此页面”,则可以在仪表盘列表中看到“ iFrame”可用:

https://www.itophub.io/wiki/media?w=800&tok=4aec75&media=2_7_0%3Acustomization%3Aadd-dashlet-sample-04.png

将仪表盘拖放到仪表板时,将显示以下表单:

https://www.itophub.io/wiki/media?w=800&tok=7d37e7&media=2_7_0%3Acustomization%3Aadd-dashlet-sample-05.png

填写参数,保存,您将在仪表板中看到仪表盘!

https://www.itophub.io/wiki/media?w=800&tok=66e9b9&media=2_7_0%3Acustomization%3Aadd-dashlet-sample-01.png

添加元信息

当您要将仪表盘与ITSM Designer一起使用时,元信息将非常有用,因为它们将使它能够用于配置仪表板。

为此,请编辑扩展程序的datamodel.sample-add-dashlet.xml文件,并创建标签itop_design/meta/dashlets/dashlet [@ id =“ IFrameDashlet”]。请注意,仪表盘标签ID必须是仪表盘的类名。您应该具有以下条件:

<?xml version="1.0" encoding="UTF-8"?>
<itop_design xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="1.0">
  <meta>
        <dashlets>
          <dashlet id="DashletIFrame" _delta="define">
          </dashlet>
        </dashlets>
  </meta>
</itop_design>

现在,将仪表盘元信息放入仪表盘仪表盘中:

  • “label”,您的仪表盘的标签。
  • “icon”,图标出现在“可用的dashlets”菜单中。请注意,该路径相对于扩展文件夹而不是应用程序根目录!
  • “description”,即仪表盘的说明。
  • “configuration”,这是与仪表盘:: GetInfo方法的主要区别。它应该包含配置的XML配置示例,以帮助用户知道要配置什么。这是必要的,因为由于安全原因,ITSM设计器将无法呈现属性表单。

您现在应该具有以下内容:

<?xml version="1.0" encoding="UTF-8"?>
<itop_design xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="1.0">
  <meta>
        <dashlets>
          <dashlet id="DashletIFrame" _delta="define">
                <label>iFrame</label>
                <icon>itop-iframe-dashlet/images/iframe.png</icon>
                <description>Embed external web page as a dashlet.</description>
                <configuration>
                        <url>http://via.placeholder.com/600x300</url>
                        <width>600</width>
                        <height>300</height>
                </configuration>
          </dashlet>
        </dashlets>
  </meta>
</itop_design>

下一步

要将定制部署到另一台iTop服务器,只需将文件夹“ sample-add-dashlet”复制到iTop的扩展文件夹,然后再次运行安装程序。

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


Creating a new dashlet for console dashboards: iFrame

learning:
Add a new type of dashlet
level:
Advanced
domains:
PHPPresentation
min version:
2.1.0

This document explains, step by step, how to create your own iTop module in order to add a new dashlet to the console dashboards: an iFrame.

Goals of this tutorial

In this step-by-step tutorial you will learn to:

  • create your own extension module for iTop 2.5

  • create a new class of dashlet

  • add a new entry into an existing dashboard

For the purpose of this tutorial we will create a new class of Dashlet, called IFrameDashlet, that will be very simple and embed a external webpage.

https://www.itophub.io/wiki/media?w=800&tok=66e9b9&media=2_7_0%3Acustomization%3Aadd-dashlet-sample-01.png

What you will need

  • iTop installed on a development machine, on which you can easily access/edit the files.

  • A text editor capable of editing PHP and XML file and supporting UTF-8. On Windows you can use Wordpad (Notepad does not like Unix line endings) or one of the excellent free development IDEs like PSPad or Notepad++.

Customization process

The customization process is the following:

  1. Install a development instance of iTop. It is always better not to experiment in production !!

  2. Install the toolkit to assist you in the customization

  3. Create a new (empty) module using the module creation wizard

  4. Copy this new module to the extensions folder on iTop and run the setup again to install the empty module

  5. Modify the module in extensions and use the toolkit to check your customizations

Repeat the last point until you are satisfied with your customization. When you are done, your new module is ready to be deployed. Copy the module folder in the extension directory on your production iTop instance and run the setup to install it.

Step by step tutorial

Create your customization module

Use the module creation wizard. Fill the form with the following values:

LabelValueRemarks
Module namesample-add-dashletNames starting with itop- and combodo- are reserved for use by Combodo. It is recommended not to put spaces or accentuated characters in the name of the module. Two modules with the same name cannot co-exist in the same iTop instance.
Module LabelAdd Dashlet SampleThis label will be displayed in the setup wizard. Localized characters and spaces are allowed
Module Version1.0.0The convention is to use a 3 digits numbering scheme: X.Y.Z
CategorybusinessModules that provide modifications to the data model should be in the category 'business'

Click Generate ! to download the empty module as a zip file.

Install the empty module

Expand the content of the zip into the extensions folder of your development iTop instance. You should now have a folder named sample-add-dashlet inside theextensions folder. this folder contains the following files:

  • datamodel.sample-add-dashlet.xml

  • module.sample-add-dashlet.php

  • en.dict.sample-add-dashlet.php

  • model.sample-add-dashlet.php

Make sure that the file conf/production/config-itop.php is writable for the web server (on Windows: right click to display the file properties and uncheck the read-only flag; on Linux change the rights of the file), then launch the iTop installation by pointing your browser to http://your_itop/setup/

Launching the re-install

Click “Continue »” to start the re-installation.

https://www.itophub.io/wiki/media?w=300&tok=554538&media=2_7_0%3Acustomization%3Ainstall-extension-2.png

Make sure that “Update an existing instance” is selected before clicking “Next »”.

https://www.itophub.io/wiki/media?w=300&tok=2395b2&media=2_7_0%3Acustomization%3Aupgrade-screenshot2.png

Continue to the next steps of the wizard…

Select the new extension

Your custom module should appear in the list of “Extensions”. If it's not the case, check that the module files were copied in the proper location and that the web server has enough rights to read them.

Select your custom module before clicking “Next »” and complete the installation.

Add the IFrameDashlet class

Using you favorite text editor, create the file iframedashlet.class.inc.php in your extension folder.

Add the following piece of code:

<?php class DashletIFrame extends Dashlet { public function __construct($oModelReflection, $sId) { parent::__construct($oModelReflection, $sId); } static public function GetInfo() { } public function GetPropertiesFields(DesignerForm $oForm) { } public function Render($oPage, $bEditMode = false, $aExtraParams = ()) { } }

This is the base code to create a dashlet. As you can see, the methods are empty for now, we will have to implement them, but first let see what their purposes are.

  • “GetInfo” is used to retrieve basic informations on the dashlet such as its label, description and icon. This is mainly used in the dashboard un der the “Available dashlets” menu.

  • “GetPropertiesFields” is used to build the configuration form fo the dashlet. It is where we will have to put the parameters the user will fill to set the dashlet up.

  • “Render” is used to make the HTML rendering of the dashlet, which is where most of the logic happen.

https://www.itophub.io/wiki/media?w=800&tok=082f15&media=2_7_0%3Acustomization%3Aadd-dashlet-sample-03.png

Let's start with the GetInfo method. Replace the empty method with the following piece of code:

  • “label” will be used as a tooltip in the dashlet palet when editing a dashboard.

  • “icon” will also be used in the dashlet palet. The path must be relative to the application root folder.

  • “description” is not displayed for now, but should be soon.

static public function GetInfo() { return ( 'label' => Dict::S('UI:DashletIframe:Label'), 'icon' => 'env-'.utils::GetCurrentEnvironment().'/sample-add-dashlet/images/iframe.png', 'description' => Dict::S('UI:DashletIframe:Description'), ); }

Then replace the GetPropertiesFields method with the following:

public function GetPropertiesFields(DesignerForm $oForm) { $oField = new DesignerLongTextField('url', Dict::S('UI:DashletIframe:Prop-Url'), $this->aProperties['url']); $oField->SetMandatory(); $oForm->AddField($oField); $oField = new DesignerIntegerField('width', Dict::S('UI:DashletIframe:Prop-Width'), $this->aProperties['width']); $oField->SetMandatory(); $oForm->AddField($oField); $oField = new DesignerIntegerField('height', Dict::S('UI:DashletIframe:Prop-Height'), $this->aProperties['height']); $oField->SetMandatory(); $oForm->AddField($oField); }

As you can see, we add one DesignerXXXField for each parameter we need the user to fill and that is it. iTop will handle the form processing and interactions with the dashboard.

Unfortunately there is no documentation of the available field classes. To find what's available, check the DesignerFormField class and its derivated classes in application/forms.class.inc.php

Finally replace the Render method with the following code:

public function Render($oPage, $bEditMode = false, $aExtraParams = ()) { $sUrl = $this->aProperties['url']; $iWidth = (int) $this->aProperties['width']; $iHeight = (int) $this->aProperties['height']; $oPage->add('<div class="dashlet-content">'); $sId = utils::GetSafeId('dashlet_iframe_'.($bEditMode? 'edit_' : '').$this->sId); $oPage->add('<iframe id="'.$sId.'" width="'.$iWidth.'" height="'.$iHeight.'" frameborder="0" src="'.$sUrl.'"></iframe>'); if($bEditMode) { $oPage->add('<div style="width: 100%; height: 100%; position: absolute; top: 0px; left: 0px; cursor: not-allowed;"></div>'); } $oPage->add('</div>'); }

In this case, the code is pretty simple as we just want to display an iframe tag pointing to an URL. But this is where you should do your dashlet's logic, retrieving objects through OQL, computing stuff and all. As you have access to the $oPage element, you can even bring CSS or JS files/snippets. Sky is the limit!

Now, your file should look like this:

<?php class DashletIFrame extends Dashlet { public function __construct($oModelReflection, $sId) { parent::__construct($oModelReflection, $sId); $this->aProperties['url'] = ''; $this->aProperties['width'] = 600; $this->aProperties['height'] = 650; $this->aCSSClasses[] = 'dashlet-inline'; } public function Render($oPage, $bEditMode = false, $aExtraParams = ()) { $sUrl = $this->aProperties['url']; $iWidth = (int) $this->aProperties['width']; $iHeight = (int) $this->aProperties['height']; $oPage->add('<div class="dashlet-content">'); $sId = utils::GetSafeId('dashlet_iframe_'.($bEditMode? 'edit_' : '').$this->sId); $oPage->add('<iframe id="'.$sId.'" width="'.$iWidth.'" height="'.$iHeight.'" frameborder="0" src="'.$sUrl.'"></iframe>'); if($bEditMode) { $oPage->add('<div style="width: 100%; height: 100%; position: absolute; top: 0px; left: 0px; cursor: not-allowed;"></div>'); } $oPage->add('</div>'); } public function GetPropertiesFields(DesignerForm $oForm) { $oField = new DesignerLongTextField('url', Dict::S('UI:DashletIframe:Prop-Url'), $this->aProperties['url']); $oField->SetMandatory(); $oForm->AddField($oField); $oField = new DesignerIntegerField('width', Dict::S('UI:DashletIframe:Prop-Width'), $this->aProperties['width']); $oField->SetMandatory(); $oForm->AddField($oField); $oField = new DesignerIntegerField('height', Dict::S('UI:DashletIframe:Prop-Height'), $this->aProperties['height']); $oField->SetMandatory(); $oForm->AddField($oField); } static public function GetInfo() { return ( 'label' => Dict::S('UI:DashletIframe:Label'), 'icon' => 'env-'.utils::GetCurrentEnvironment().'/itop-iframe-dashlet/images/iframe.png', 'description' => Dict::S('UI:DashletIframe:Description'), ); } }

Check your modification by running the toolkit. Point your browser to http://your_itop/toolkit.

Checking the modifications with the toolkit

If any error is reported at this stage, fix it by editing the XML file and check again your modifications by clicking on the “Refresh” button in the toolkit page.

Once all the errors have been fixed, you can apply the modifications to iTop by using the second tab of the toolkit. Click on the button Update iTop Code and Database! to:

  1. Compile the XML data model to PHP classes

  2. Update the database schema (creation of the monitor table).

At this point, if you navigate in iTop and click on the “Edit this page” in the “Welcome page”, you can see that “iFrame” is available in the dashlet list:

https://www.itophub.io/wiki/media?w=800&tok=4aec75&media=2_7_0%3Acustomization%3Aadd-dashlet-sample-04.png

The following form gets displayed when you drag & drop the dashlet to the dashboard:

https://www.itophub.io/wiki/media?w=800&tok=7d37e7&media=2_7_0%3Acustomization%3Aadd-dashlet-sample-05.png

Fill the parameters, save and you will see your dashlet in the dashboard!

https://www.itophub.io/wiki/media?w=800&tok=66e9b9&media=2_7_0%3Acustomization%3Aadd-dashlet-sample-01.png

Add meta informations

Meta informations are useful when you want to use your dashlet with the ITSM Designer as they will enable it to be used for configuring dashboards.

To do so, edit the datamodel.sample-add-dashlet.xml file of your extension and create a tag /itop_design/meta/dashlets/dashlet[@id=“IFrameDashlet”]. Note that the dashlet tag id MUST be the class name of your dashlet. You should have the following:

<?xml version="1.0" encoding="UTF-8"?>
<itop_design xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="1.0">
  <meta>
        <dashlets>
          <dashlet id="DashletIFrame" _delta="define">
          </dashlet>
        </dashlets>
  </meta>
</itop_design>

Now, put the dashlet meta information within the dashlet tag:

  • “label”, the label of your dashlet.

  • “icon”, the icon to appear in the “Available dashlets” menu. Note that the path is relative to the extension folder and not the app root!

  • “description”, the description of the dashlet.

  • “configuration”, this is the main difference with the Dashlet::GetInfo method. It should contain a sample XML configuration of the dashlet to help the user know what is to be configured. This is necessary as the ITSM Designer will not be able to render the properties form due to security reasons.

You should now have the following:

<?xml version="1.0" encoding="UTF-8"?>
<itop_design xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="1.0">
  <meta>
        <dashlets>
          <dashlet id="DashletIFrame" _delta="define">
                <label>iFrame</label>
                <icon>itop-iframe-dashlet/images/iframe.png</icon>
                <description>Embed external web page as a dashlet.</description>
                <configuration>
                        <url>http://via.placeholder.com/600x300</url>
                        <width>600</width>
                        <height>300</height>
                </configuration>
          </dashlet>
        </dashlets>
  </meta>
</itop_design>

Next Steps

To deploy your customization to another iTop server, simply copy the folder “sample-add-dashlet” to the extensions folder of iTop and run the setup again.

标签:
由 superadmin 在 2020/08/27, 17:25 创建
    

需要帮助?

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

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