iTopCN – 用户界面

Docs: iframe 仪表盘

Fri, 27 Jun 2025 00:00:00 +0000

本文档介绍如何创建自定义 iframe 仪表盘组件，用于在控制台仪表盘中嵌入外部网页。更多详细内容请参考 iTop 官方文档。

概述

本教程将指导您一步步创建 iTop 扩展模块，添加一个新的仪表盘组件类型：iframe 仪表盘。该组件可以嵌入外部网页到 iTop 控制台仪表盘中。

前置条件

已安装 iTop 开发环境
可编辑 PHP 和 XML 文件的文本编辑器（支持 UTF-8）

定制流程

安装 iTop 开发实例（请勿在生产环境实验）
安装工具包辅助定制
使用扩展创建向导生成空模块
将模块复制到 extensions 目录并运行安装向导
修改模块代码并使用工具包验证

创建扩展模块

使用扩展创建向导，填写以下信息：

标签	值	说明
模块名称	sample-add-dashlet	名称不能以 `itop-` 或 `combodo-` 开头，不建议使用空格或特殊字符
模块标签	Add Dashlet Sample	安装向导中显示的模块名称，允许使用本地化字符和空格
模块版本	1.0.0	使用三位版本号：X.Y.Z
类别	business	修改数据模型的模块应属于 business 类别

点击 Generate! 下载空模块压缩包。

安装空模块

将压缩包解压到开发 iTop 实例的 extensions 目录中。模块文件夹包含以下文件：

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

确保 conf/production/config-itop.php 对 Web 服务器可写，然后访问 http://your_itop/setup/ 运行安装向导，选择 Update an existing instance，在扩展列表中勾选您的模块完成安装。

添加 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 = array())
 {
 }
}

实现 GetInfo 方法

GetInfo 返回仪表盘的基本信息（标签、图标、描述），用于仪表盘编辑器的"可用组件"菜单中：

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

实现 GetPropertiesFields 方法

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);
}

实现 Render 方法

Render 负责组件的 HTML 渲染：

public function Render($oPage, $bEditMode = false, $aExtraParams = array())
{
 $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>');
}

完整类代码

<?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 = array())
 {
 $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 array(
 '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，修复所有错误后，点击 Update iTop Code and Database! 应用修改。

此时在 iTop 欢迎页面点击 Edit this page，可在仪表盘组件列表中看到 “iFrame” 选项。

添加元信息

编辑 datamodel.sample-add-dashlet.xml，添加仪表盘元信息，使其可在 ITSM Designer 中使用：

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

部署

将 sample-add-dashlet 文件夹复制到目标 iTop 实例的 extensions 目录，重新运行安装向导即可。

参考

iTop 官方文档

原文：https://www.itophub.io/wiki/page?id=3_2_0:customization:add-dashlet-sample

版本：3_2_0/customization/add-dashlet-sample.txt · Last modified: 2026/03/16 14:02 by 127.0.0.1

Docs: 表单预填充

Fri, 27 Jun 2025 00:00:00 +0000

本文档介绍如何使用 API 方法预填充 iTop 表单中的字段值。更多详细内容请参考 iTop 官方文档。

概述

iTop 已经内置了一些自动预填充行为：

搜索预设：编辑 Team 并添加成员时，Person 搜索会自动按 Team 的组织过滤
创建预设：在编辑 User Request 时创建新的 Caller Person，该 Person 的组织会自动填充为 User Request 的组织

对于 95% 的情况这些自动行为已经足够，但某些特殊场景需要通过 API 方法进行定制。

前置条件：熟悉教程中使用的语法，并已创建扩展。

API 方法

方法	说明
`PrefillSearchForm(&$aContextParam)`	预设相关对象的搜索框字段
`PrefillCreationForm(&$aContextParam)`	预设对象创建表单字段
`PrefillTransitionForm(&$aContextParam)`	预设转换表单字段

这些方法可以在以下场景中使用：

从菜单/操作调用
在间接 LinkedSet 属性（n:n 关系）中添加对象时
从编辑对象时 ExternalKey 属性旁的 + 按钮（1:n 关系）
从 LinkedSet 属性的行内编辑模式（n:1 关系）

预填充搜索表单

在源对象类上定义，预设每个相关对象搜索框中的字段。

上下文参数

参数	说明
`$aContextParam['dest_class']`	搜索的目标类
`$aContextParam['filter']`	过滤条件（DBObjectSearch 对象）
`$aContextParam['user']`	当前登录用户的用户名
`$aContextParam['origin']`	`console` 或 `portal`

示例：按提供商过滤服务

在 Contract 类上，限制搜索仅返回提供商的服务，以及客户和提供商的联系人及文档：

/** 示例：在 Contract 类上修改搜索，仅搜索：
 * 提供商的服务
 * 客户和提供商的联系人及文档 **/
public function PrefillSearchForm(&$aContextParam)
{
 // 如果搜索的是 'Service' 类或其子类
 if($aContextParam['dest_class'] == 'Service'
 || is_subclass_of($aContextParam['dest_class'], 'Service'))
 {
 // 如果搜索类有 'org_id' 属性且 Contract 的 provider_id 不为空
 if(MetaModel::IsValidAttCode($aContextParam['dest_class'],'org_id')
 && !empty($this->Get('provider_id')))
 {
 // 移除默认搜索设置的任何条件
 $aContextParam['filter']->ResetCondition();
 // 设置搜索类的 org_id 条件为 Contract 的提供商
 $aContextParam['filter']->AddCondition('org_id', $this->Get('provider_id'));
 }
 }
 // 如果搜索的是 Contact 或 Document 类或其子类
 elseif (($aContextParam['dest_class'] == 'Contact'
 || is_subclass_of($aContextParam['dest_class'], 'Contact'))
 || ($aContextParam['dest_class'] == 'Document'
 || is_subclass_of($aContextParam['dest_class'], 'Document')))
 {
 if(MetaModel::IsValidAttCode($aContextParam['dest_class'],'org_id'))
 {
 $aOrgIds = array();
 if(!empty($this->Get('provider_id'))) $aOrgIds[] = $this->Get('provider_id');
 if(!empty($this->Get('org_id'))) $aOrgIds[] = $this->Get('org_id');

 if(count($aOrgIds)>0)
 {
 // 使用 IN 参数设置多个 org_id 条件
 $aContextParam['filter']->ResetCondition();
 $aContextParam['filter']->AddCondition('org_id', $aOrgIds , 'IN');
 }
 }
 }
}

示例：限制为 Server 子类

class UserRequest extends Ticket
{
 /**
 * 限制 CI 搜索仅返回 Server 类
 * 并允许用户设置其他 Server 字段作为搜索条件
 */
 public function PrefillSearchForm(&$aContextParam)
 {
 if($aContextParam['dest_class'] == 'FunctionalCI')
 {
 // 将 FunctionalCI 搜索改为仅搜索 Server
 $aContextParam['filter']->ChangeClass('Server');
 }
 }
}

使用 ChangeClass('Server') 比 AddCondition('finalclass', 'Server') 更好，因为前者允许使用任何 Server 字段作为搜索条件，而后者仅限于 FunctionalCI 的字段。

示例：使用关系过滤

class UserRequest extends Ticket
{
 /**
 * 限制 CI 搜索仅返回与请求者关联的 PC
 * SELECT PC JOIN lnkContactToFunctionalCI AS L ON L.functionalci_id=PC.id
 * WHERE L.contact_id = :this->caller_id
 */
 public function PrefillSearchForm(&$aContextParam)
 {
 if($aContextParam['dest_class'] == 'FunctionalCI')
 {
 // 过滤为仅 PC
 $aContextParam['filter']->AddCondition('finalclass', 'PC');
 // 搜索 lnkContactToFunctionalCI
 $oSearchLnk = new DBObjectSearch('lnkContactToFunctionalCI');
 // 限制为与请求者相关的链接
 $oSearchLnk->AddCondition('contact_id', $this->Get('caller_id'));
 // 将链接搜索与 FunctionalCI 搜索关联
 $aContextParam['filter']->AddCondition_ReferencedBy($oSearchLnk, 'functionalci_id');
 }
 }
}

预填充创建表单

预设类的创建表单字段。

自动机制已完成预设工作，如果对象是从另一个对象创建的，字段可能已被填充
$this 引用即将创建的对象

上下文参数

参数	说明
`$aContextParam['user']`	当前登录用户的用户名
`$aContextParam['origin']`	`console` 或 `portal`
`$aContextParam['source_obj']`	仅在创建外部键对象时可用（例如从 Person 创建 Team）

示例 1：从 ServiceSubcategory 创建 RequestTemplate

public function PrefillCreationForm(&$aContextParam)
{
 $id = $this->Get('servicesubcategory_id');
 if ($id != 0)
 {
 // 获取原始对象
 $oSubcategoryObject = MetaModel::GetObject('ServiceSubCategory', $id, false);
 // 使用原始对象的字段值预填充其他数据
 $this->Set('service_id', $oSubcategoryObject->Get('service_id'));
 }
}

示例 2：预设 Contract 的日期和提供商

public function PrefillCreationForm(&$aContextParam)
{
 // 如果尚未设置，将合同开始日期预设为当前日期
 if(empty($this->Get('start_date'))) {
 $this->Set('start_date', time());
 }

 // 获取当前用户
 $oUser = UserRights::GetUserObject();
 // 将合同提供商预设为当前用户的组织
 // 注意：'org_id' 仅在 iTop 2.5.0 及以上版本的 User 类中可用
 $this->Set('provider_id', $oUser->Get('org_id'));
}

示例 3：预设 UserRequest 的请求者

public function PrefillCreationForm(&$aContextParam)
{
 // 获取当前用户
 $oUser = UserRights::GetUserObject();
 // 将 caller 字段预填充为用户的联系人
 $this->SetIfNull('caller_id', $oUser->Get('contactid'));

 return true;
}

预填充转换表单

预设转换表单中的值：

此时转换尚未执行
$this 引用即将应用转换的当前对象

上下文参数

参数	说明
`$aContextParam['expected_attributes']['attribute_code']`	表单中属性的显示标志
`$aContextParam['origin']`	`console` 或 `portal`
`$aContextParam['stimulus']`	应用的刺激

示例：“分配给我” 逻辑

如果分配或重新分配工单，且工单未分配给我，同时我是该工单派发团队的一员，则在进入转换表单时将我的名字预设为 “agent”：

public function PrefillTransitionForm(&$aContextParam)
{
 $oPerson = UserRights::GetContactObject();
 // 如果当前用户有关联的 Person 且处于分配转换
 if ($oPerson && ($aContextParam['stimulus'] == 'ev_assign'
 || $aContextParam['stimulus'] == 'ev_reassign'))
 {
 $iTicketAgentId = $this->Get('agent_id');
 $iPersonId = $oPerson->GetKey();

 // 如果 agent 不是当前用户
 if ($iTicketAgentId != $iPersonId )
 {
 // 检查当前联系人是否可以分配给该工单
 $iTicketTeamId = $this->Get('team_id');

 $oTeamLinkSet = $oPerson->Get('team_list');
 $bIsInTeam = false;
 while($oTeamLink = $oTeamLinkSet->Fetch())
 {
 $iTeam = $oTeamLink->Get('team_id');
 if ($iTicketTeamId == $iTeam) { $bIsInTeam = true; }
 }
 if($bIsInTeam)
 {
 $this->Set('agent_id', $iPersonId);
 // 移除 MUST CHANGE 标志
 if(array_key_exists('agent_id', $aContextParam['expected_attributes']))
 {
 $aContextParam['expected_attributes']['agent_id'] = ~OPT_ATT_MUSTCHANGE & $aContextParam['expected_attributes']['agent_id'];
 }
 }
 }
 }
}

已知限制

当 agent 被预设为用户名时，工单详情中的显示也会更新，仿佛修改已完成，可能造成混淆
用户可以通过将 agent 设置回之前的值来绕过 “must-change” 标志

在 XML 中集成方法

以下是在 XML 数据模型定义中声明上述方法的示例：

<class id="RequestTemplate" _delta="must_exist">
 <methods>
 <method id="PrefillCreationForm" _delta="define">
 <static>false</static>
 <access>public</access>
 <type>Overload-DBObject</type>
 <arguments>
 <argument id="1">
 <type>reference</type>
 <mandatory>true</mandatory>
 </argument>
 </arguments>
 <code><![CDATA[public function PrefillCreationForm(&$aContextParam)
 { // 函数代码 }]]>
 </code>
 </method>
 </methods>
</class>

参考

iTop 官方文档

原文：https://www.itophub.io/wiki/page?id=3_2_0:customization:form_prefill

2025/07/09 16:07 by127.0.0.1

版本：3_2_0/customization/form_prefill.txt · Last modified: 2025/07/09 16:07 by 127.0.0.1

Docs: 创建主题

Fri, 27 Jun 2025 00:00:00 +0000

本文档介绍如何创建自定义主题，从修改少量颜色到编写完整的 CSS 主题。更多详细内容请参考 iTop 官方文档。

概述

除了现有的默认主题外，还可以：

修改少量颜色以匹配企业品牌色
如果有 CSS 技能，可以创建自己的主题，彻底改变 iTop 控制台的外观

前置条件：熟悉教程中使用的语法，并已创建扩展。

修改少量颜色

<branding>
 <themes>
 <theme id="fullmoon">
 <variables>
 <variable id="ibo-hyperlink-color" _delta="define">purple</variable>
 </variables>
 </theme>
 </themes>
</branding>

修改更多颜色

主要变量

SCSS 变量	用途
`ibo-color-primary-XXX`	标准 iTop 中大多数橙色出现的位置
`ibo-hyperlink-color`	超链接文本颜色，如菜单条目、外部键
`ibo-hyperlink-color--on-hover`	悬停时面包屑或超链接条目的文本颜色
`ibo-color-secondary-XXX`	字段集标题背景、表头文本、编辑容器边框
`ibo-navigation-menu--body--background-color`	左侧菜单面板
`ibo-top-bar--background-color`	顶部栏
`ibo-navigation-menu--action--background-color--on-hover`	悬停菜单组时的背景色
`ibo-tab-container--tab-header--background-color--on-hover`	悬停标签页时的背景色

所有 iTop 3.0 变量定义在 <iTop>/css/backoffice/ 下的多个文件中：

ibo- 表示新内容（变量或类），ibo 代表 ItopBackOffice，因此不适用于终端用户门户
ibo-vendor- 表示在第三方库提供的 SCSS 规则中使用的变量
例如 ibo-input-text--padding-x 可在 <iTop>/css/backoffice/input/_input-text.scss 中找到

变量值

为每个要修改的变量创建 XML 条目，指定新值：

可以设置任意数量的变量
如果定义的变量 ID 在任何 scss 文件中都不存在，将被忽略
变量值可以是：
- 另一个变量：$ibo-color-transparent、$ibo-body-text-color 等（变量必须在上方定义）
- 颜色：颜色名称 purple、十六进制 #F6F6F6、RGB rgb(123, 123, 132)、RGBA rgba(123, 123, 123, 0.5)、HSL hsl(123, 50%, 50%)、HSLA hsla(123, 50%, 50%, 0.23)
- 文本
- 数字，如 box-radius:0
- SCSS 函数：hue-rotate(-139deg) 或 lighten($brand-primary, 15%)

导入 SCSS 变量文件

从 iTop 3.0 开始，可以通过添加 xsi:type="variable" 导入包含变量列表的 SCSS 文件：

<theme id="light-grey">
 <imports>
 <import id="my-css-variables" xsi:type="variable" _delta="define">my-module/css/my-css-variables.scss</import>
 </imports>
</theme>

$ibo-body-text-color: #000000;
$ibo-body-background-color: $ibo-color-white-200;

自定义样式表

可以在模块中定义自己的样式表和 scss 文件，并在主题中指定。假设 SCSS 文件位于扩展的 <my-module>/css/ 下，则 XML 中的路径为：

<theme id="fullmoon">
 <imports>
 <import id="my-helpers" xsi:type="utility" _delta="define">my-module/css/my-helpers.scss</import>
 </imports>
 <stylesheets>
 <stylesheet id="my-style" _delta="define">my-module/css/my-style.scss</stylesheet>
 </stylesheets>
</theme>

创建新主题

经典主题

在 XML 中创建新主题（例如 old-school），修改 scss 变量并添加新的 css 规则。为此需要在 iTop 扩展中编写 scss 文件。

必须将规则与变量重定义分开放在不同的源文件中
对于变量，可以在 import 标签下的文件中重定义，或直接在 variable 标签下定义

<branding>
 <themes>
 <theme id="old-school" _delta="define">
 <variables>
 </variables>
 <imports>
 <import id="old-school-scss-variables" xsi:type="variables">combodo-theme-old-school/scss/scss-variables.scss</import>
 </imports>
 <stylesheets>
 <stylesheet id="backoffice">../css/backoffice/main.scss</stylesheet>
 <stylesheet id="old-school">combodo-theme-old-school/scss/rules.scss</stylesheet>
 </stylesheets>
 </theme>
 </themes>
</branding>

注意：

导入 scss 时使用 xsi:type="variables"，这些文件必须只包含"变量"
如果有 CSS 规则，在 stylesheet 标签下指定
必须指定标准 scss 样式表 ../css/backoffice/main.scss，除非您重写了全部内容，并且建议放在第一个位置，以便您自己的 scss 覆盖默认样式

示例 CSS 规则：

.ibo-fieldset-legend {
 color: $ibo-color-grey-600;
 font-size: small;
 width:unset;
 border-bottom:0;
 margin-bottom:0;
 padding: 4px 4px 0 4px;
 margin-left: -4px;
}

.ibo-fieldset {
 border: 1px solid $ibo-color-grey-400 !important;
 padding: 10px 10px;
 border-radius: 6px;
 margin-top: 18px;
}

测试实例主题

以下是 iTop 内置的 test-red 主题的 XML：

iTop 3.0 及以上版本

<theme id="test-red" _delta="define">
 <variables>
 <variable id="ibo-page-banner--background-color">$ibo-color-red-600</variable>
 <variable id="ibo-page-banner--text-color">$ibo-color-red-100</variable>
 <variable id="ibo-page-banner--text-content">"THIS IS A TEST INSTANCE"</variable>
 </variables>
 <imports>
 </imports>
 <stylesheets>
 <stylesheet id="fullmoon">../css/backoffice/main.scss</stylesheet>
 <stylesheet id="environment-banner">../css/backoffice/themes/page-banner.scss</stylesheet>
 </stylesheets>
</theme>

在顶部添加彩色横幅和文本消息。

从 2.7 迁移到 3.0 主题

主题名称

如果您有 2.7.x 版本的 iTop 并自定义了 light-grey：

<theme id="light-grey" _delta="force">
 ...
</theme>

对于 iTop 3.0 及更高版本，需要同时自定义 fullmoon 和 darkmoon 主题：

<theme id="fullmoon" _delta="force">
 ...
</theme>
<theme id="darkmoon" _delta="force">
 ...
</theme>

SCSS 文件

2.7 主题中的代码：

<stylesheets>
 <stylesheet id="jqueryui">../css/ui-lightness/jqueryui.scss</stylesheet>
 <stylesheet id="main">../css/light-grey.scss</stylesheet>
 <stylesheet id="environment-banner">../css/backoffice-environment-banner.scss</stylesheet>
</stylesheets>

在 3.0 中替换为：

<stylesheets>
 <stylesheet id="fullmoon">../css/backoffice/main.scss</stylesheet>
 <stylesheet id="environment-banner">../css/backoffice/themes/page-banner.scss</stylesheet>
</stylesheets>

2.7 与 3.0 变量名称映射

直接对应

2.7 变量	3.0 变量
hyperlink-color	ibo-hyperlink-color
breadcrumb-text-highlight-color	ibo-hyperlink-color–on-hover
frame-background-color	ibo-navigation-menu–body–background-color
frame-background-color	ibo-top-bar–background-color
hover-background-color	ibo-navigation-menu–action–background-color–on-hover
hover-background-color	ibo-tab-container–tab-header–background-color–on-hover

3.0 的 XXX 变量

在 3.0 中，某些变量使用了变体。在 2.7 中可能只声明了一个颜色变量，而在 3.0 中需要设置多个具有颜色变化的变量：

2.7 变量	3.0 变量列表
brand-primary	ibo-color-primary-XXX
complement-color	ibo-color-secondary-XXX
complement-light	ibo-color-secondary-XXX

XXX 范围从 100 到 900（100, 200, 300, … 900）以及 950，共 10 个变量。

使用现有颜色

要使用现有 iTop 颜色代码，在 iTop 3.0+ 中使用浏览器开发工具查看现有值，然后使用以下语法之一转换：

$ibo-lifecycle-success-state-primary-color
var(--ibo-lifecycle-success-state-primary-color)

使用现有颜色的优势在于，主题创建或修改时会自动应用到您的设置/新类，保持 iTop 界面的一致性。

参考

iTop 官方文档

原文：https://www.itophub.io/wiki/page?id=3_2_0:customization:theme

Last modified: 2024/09/10 10:25 by127.0.0.1

版本：3_2_0/customization/theme.txt · Last modified: 2024/09/10 10:25 by 127.0.0.1

Docs: 定义废弃规则

Fri, 27 Jun 2025 00:00:00 +0000

本文档介绍如何为 iTop 类定义废弃规则，自动标记过时对象。更多详细内容请参考 iTop 官方文档。

概述

废弃规则用于自动标记不再活跃或过时的对象。在使用废弃功能前，请先了解 Obsolescence 的基本概念。

前置条件：熟悉教程中使用的语法，并已创建扩展。

定义方式

废弃规则按类定义
废弃条件是一个 OQL 表达式，可以使用类的任何字段，包括 AttributeExternalField 类型
废弃条件从父类继承，但可以在子类上重新定义
如果类及其父类都未定义废弃条件，则该类的对象永远不会被视为过时

基本示例

<properties>
 <obsolescence _delta="redefine">
 <condition><![CDATA[status='inactive']]></condition>
 </obsolescence>
</properties>

处理空值：

<obsolescence _delta="redefine">
 <condition><![CDATA[status='inactive' OR ISNULL(status)=1]]></condition>
</obsolescence>

复杂示例

基于对象状态结合父对象状态

<condition>
 <![CDATA[status = 'obsolete' OR (server_id != 0 AND server_id_obsolescence_flag)]]>
</condition>

结合状态和延迟时间

<condition>
 <![CDATA[
 operational_status='closed'
 AND
 ( close_date < DATE_FORMAT(DATE_SUB(NOW(), INTERVAL 15 MONTH),'%Y-%m-%d 00:00:00')
 OR
 (
 ISNULL(close_date)
 AND
 last_update < DATE_FORMAT(DATE_SUB(NOW(), INTERVAL 15 MONTH),'%Y-%m-%d 00:00:00')
 )
 )]]>
</condition>

此示例标记关闭超过 15 个月的对象为过时。

参考

iTop 官方文档

原文：https://www.itophub.io/wiki/page?id=3_2_0:customization:obsolescence

2024/09/10 10:25 by127.0.0.1

版本：3_2_0/customization/obsolescence.txt · Last modified: 2024/09/10 10:25 by 127.0.0.1

Docs: 对特定用户隐藏字段

Fri, 27 Jun 2025 00:00:00 +0000

本文档介绍如何对特定用户隐藏字段，使其无法查看和修改。更多详细内容请参考 iTop 官方文档。

概述

本示例展示如何对不具有特定角色的用户隐藏 Contract 的 cost 字段。

前置条件：熟悉教程中使用的语法，并已创建扩展。

实现方法

需要重写以下方法，阻止用户查看和修改 “cost” 值：

Get()：阻止通过详情页、列表、CSV 导出或 REST 获取字段值
GetAttributeFlags() 和 GetInitialAttributeFlags()：阻止在创建和修改表单中显示和编辑 “cost” 字段

PHP 代码

public function Get($sAttCode)
{
 // 每次请求对象属性时调用此函数
 if (($sAttCode == 'cost') && !(UserRights::HasProfile('Service Manager')))
 {
 // 如果不允许查看此字段，不返回真实内容
 return('****');
 }
 else return parent::Get($sAttCode);
}

public function GetAttributeFlags($sAttCode, &$aReasons = array(), $sTargetState = '')
{
 // 在控制台编辑对象时调用此函数
 // 为对象的每个字段调用

 // 获取父类设置的标志
 $iFlags = parent::GetAttributeFlags($sAttCode, $aReasons, $sTargetState);

 // 仅修改单个字段的行为
 if (($sAttCode == 'cost') && !(UserRights::HasProfile('Service Manager')))
 {
 // 使用 | 将新标志与现有标志组合
 $iFlags = (OPT_ATT_READONLY | OPT_ATT_HIDDEN | $iFlags);
 }
 return $iFlags;
}

public function GetInitialStateAttributeFlags($sAttCode, &$aReasons = array())
{
 // 在控制台创建对象时调用此函数
 if (($sAttCode == 'cost') && !(UserRights::HasProfile('Service Manager')))
 {
 return(OPT_ATT_READONLY | OPT_ATT_HIDDEN | parent::GetInitialStateAttributeFlags($sAttCode, $aReasons));
 }
 // 其他情况由父类处理
 return parent::GetInitialStateAttributeFlags($sAttCode, $aReasons);
}

效果

cost 字段在视图、创建和修改表单中不显示
即使用户对该类具有批量写入权限，CSV 导入也无法写入 cost 字段
REST/JSON API 访问也会受到限制

注意事项

是否需要同时设置 hidden 和 readonly 标志，还是 hidden 已隐含 readonly？
从 iTop 2.6.1 开始，CSV 导入在创建时已正确调用 GetInitialAttributeFlags()
目前无法阻止用户通过 dashlet 分组查看受保护的值

参考

iTop 官方文档

原文：https://www.itophub.io/wiki/page?id=3_2_0:customization:hide-field-on-profile

版本：3_2_0/customization/hide-field-on-profile.txt · Last modified: 2025/05/20 12:42 by 127.0.0.1

Docs: 对象间导航

Fri, 27 Jun 2025 00:00:00 +0000

本文档介绍如何在对象详情页添加导航按钮，方便在同类对象间切换。更多详细内容请参考 iTop 官方文档。

概述

本教程将在某些对象详情页上添加两个按钮，允许导航到上一个和下一个对象。

导航范围由以下条件定义：

code（必需）：一个标量属性代码，其值必须与当前对象相同。例如：在同一组织的人员间导航
filter（可选）：一个过滤条件，减少可导航的对象范围。例如：仅导航活动状态的人员
order（可选）：默认 id。一个标量属性代码，定义导航顺序。目前假设该字段值唯一，重复值会被忽略/跳过。

前置条件：熟悉教程中使用的语法，并已创建扩展。

配置

可以在 iTop 中启用对象间导航。每个类只能定义一个导航规则：

$MyModuleSettings = array(
 'combodo-object-navigation' => array(
 'classes' => array(
 'UserRequest' => array(
 'code' => 'org_id',
 'filter'=> array('code'=>'status','value'=>'closed','operator'=>'!='),
 ),
 'WorkOrder' => array(
 'code' => 'ticket_id',
 'filter'=> array('code'=>'status','value'=>'closed','operator'=>'!='),
 'order' => 'start_date',
 ),
 'Team' => array(
 'code' => 'org_id',
 'filter'=> array('code'=>'status','value'=>'active'),
 'order'=>'name',
 ),
 'Person' => array(
 'code' => 'org_id',
 'filter'=> array('code'=>'status','value'=>'active'),
 'order'=>'name',
 ),
 )
 )
);

过滤条件参数

参数	必填	默认值	说明
code	是	-	属性代码
operator	否	`=`	支持 `>`, `>=`, `<`, `<=`, `!=`
value	否	`''`	空字符串

扩展代码

class ObjectNavigationMenuExtension implements iPopupMenuExtension
{
 static public function GetConfig()
 {
 return MetaModel::GetModuleSetting('combodo-object-navigation', 'classes', array());
 }

 public static function EnumItems($iMenuId, $param)
 {
 $aResult = array();
 $aClassCode = static::GetConfig();
 switch($iMenuId)
 {
 case iPopupMenuExtension::MENU_OBJDETAILS_ACTIONS: // 仅控制台

 $sClass = get_class($param);
 if (array_key_exists($sClass, $aClassCode)) {
 $sAttCode = $aClassCode[$sClass]['code'];
 $sOrder = array_key_exists('order', $aClassCode[$sClass]) ? $aClassCode[$sClass]['order'] :'id';
 $sOrderValue = ($sOrder === 'id') ? $param->GetKey() : $param->Get($sOrder);
 $bFilter = false;
 if (array_key_exists('filter', $aClassCode[$sClass])) {
 $sFilterCode = array_key_exists('code', $aClassCode[$sClass]['filter']) ? $aClassCode[$sClass]['filter']['code'] : '';
 $sFilterValue = array_key_exists('value', $aClassCode[$sClass]['filter']) ? $aClassCode[$sClass]['filter']['value'] : '';
 $sFilterOperator = array_key_exists('operator', $aClassCode[$sClass]['filter']) ? $aClassCode[$sClass]['filter']['operator'] : '=';
 $bFilter = MetaModel::IsValidAttCode($sClass, $sFilterCode);
 }

 foreach ( ['>','<'] AS $sOperator) {
 $bAsc = ($sOperator === '>') ? true : false;
 $oSearch = new DBObjectSearch($sClass);
 if (MetaModel::IsValidAttCode($sClass, $sAttCode))
 $oSearch->AddCondition($sAttCode, $param->Get($sAttCode), '=');
 if (($sOrder === 'id') || MetaModel::IsValidAttCode($sClass, $sOrder))
 $oSearch->AddCondition($sOrder, $sOrderValue, $sOperator);
 if ($bFilter)
 $oSearch->AddCondition($sFilterCode, $sFilterValue, $sFilterOperator);
 $oSet = new DBObjectSet($oSearch, array($sOrder => $bAsc),[],null,3);
 $oObj = $oSet->Fetch();
 if (is_object($oObj)) {
 if ($sOperator === '>') {
 $oItem = new URLButtonItem(
 'UI:next:object',
 'Next',
 utils::GetAbsoluteUrlAppRoot().'pages/UI.php?operation=details&class='.get_class($oObj).'&id='.$oObj->GetKey(),
 '_top'
 );
 $oItem->SetIconClass('fas fa-caret-right');
 $oItem->SetTooltip("Switch to the next logical object");
 } elseif ($sOperator === '<') {
 $oItem = new URLButtonItem(
 'UI:previous:object',
 'Previous',
 utils::GetAbsoluteUrlAppRoot().'pages/UI.php?operation=details&class='.get_class($oObj).'&id='.$oObj->GetKey(),
 '_top'
 );
 $oItem->SetIconClass('fas fa-caret-left');
 $oItem->SetTooltip("Switch to the previous logical object");
 }
 $aResult[] = $oItem;
 }
 }
 }
 break;
 }
 return $aResult;
 }
}

参考

iTop 官方文档

原文：https://www.itophub.io/wiki/page?id=3_2_0:customization:nextobject

版本：3_2_0/customization/nextobject.txt · Last modified: 2025/05/20 16:14 by 127.0.0.1

Docs: 防止重复

Fri, 27 Jun 2025 00:00:00 +0000

本文档介绍如何为 iTop 类定义唯一性规则，防止重复数据。更多详细内容请参考 iTop 官方文档。

概述

通过自定义 iTop，可以在类上指定唯一性规则，防止重复条目。本教程涵盖：

唯一性规则的用户体验
如何定义新的唯一性规则
iTop 默认在 Person 类上定义的唯一性规则
如何移除现有的唯一性规则

前置条件：熟悉教程中使用的语法，并已创建扩展。

用户体验

规则指定必须检查唯一性的对象范围。例如，不希望两个 Person 具有相同的员工编号，除非该编号为空。范围则是所有 employee_number 不为空的 Person
在控制台或门户的单个创建/修改操作中，规则可以：
- 阻止对象的创建/更新
- 或仅在创建/更新后显示警告消息
唯一性规则适用于类的一个或多个字段（包括 ExternalFields）
不支持 File、Image、Dashboard、Stopwatch 等属性类型的唯一性

管理员视角

默认规则

类	规则 ID	字段	行为
Brand	name	name	必须唯一（阻止）
Model	name_brand	name + brand_id	必须唯一（阻止）
Person	employee_number	org_id + employee_number	仅当 employee_id 已定义时必须唯一（阻止）
Person	name	org_id + first_name + name	应该唯一（仅警告）

定义自己的规则

定义唯一性规则只需要编写 XML。

示例：Server 名称唯一

在同一组织内，不允许两个 Server 具有相同名称：

<uniqueness_rules>
 <rule id="server_name" _delta="define">
 <!-- 必须唯一的 "Server" 字段或字段组合 -->
 <attributes>
 <attribute id="name"/>
 <attribute id="org_id"/>
 </attributes>
 </rule>
</uniqueness_rules>

错误消息字典条目：

<entry id="Class:Server/UniquenessRule:server_name">
 <![CDATA[There is already a server with the same name in the '$this->org_id_friendlyname$' organization]]>
</entry>

示例：跨子类唯一

防止两个 FunctionalCI 具有相同名称，但 SoftwareInstance、MiddlewareInstance、DatabaseSchema 和 ApplicationSolution 除外：

<classes>
 <class id="FunctionalCI" _delta="must_exist">
 <properties>
 <uniqueness_rules>
 <!-- "id" 必须是单个单词，不含特殊字符，下划线除外 -->
 <rule id="functionalci_name" _delta="define">
 <!-- 必须唯一的 "FunctionalCI" 字段或字段组合 -->
 <attributes>
 <attribute id="name"/>
 </attributes>
 <!-- 定义 OQL WHERE 子句，条件基于 FunctionalCI 字段 -->
 <!-- 将被组合为 "SELECT FunctionalCI WHERE " + <filter> -->
 <filter><![CDATA[
 finalclass NOT IN ('DBServer','Middleware',
 'OtherSoftware','WebServer','PCSoftware','MiddlewareInstance',
 'DatabaseSchema','ApplicationSolution')]]>
 </filter>
 <!-- 此标志允许保留规则但禁用 -->
 <disabled>false</disabled>
 <!-- 如果为 true 或省略，重复将阻止创建/更新 -->
 <!-- 否则在创建/更新后显示警告消息 -->
 <is_blocking>true</is_blocking>
 </rule>
 </uniqueness_rules>
 </properties>
 </class>
</classes>
<dictionaries>
 <dictionary id="EN US" _delta="must_exist">
 <entries>
 <entry id="Class:FunctionalCI/UniquenessRule:functionalci_name" _delta="define">
 <![CDATA[There are already a Functional CI with that name, please use another name.]]>
 </entry>
 <entry id="Class:FunctionalCI/UniquenessRule:functionalci_name+" _delta="define">
 <![CDATA[FunctionalCI name should be unique]]>
 </entry>
 </entries>
 </dictionary>
</dictionaries>

不带 + 的条目用于唯一性规则的错误消息
带 + 的相同代码对应规则的描述，目前尚未在任何地方显示，但未来可能在数据模型查看器中显示

默认规则示例：Person

iTop 默认在 Person 类上定义了两个规则：

employee_number

阻止规则，出错时阻止创建/更新
阻止同一组织中的两个 Person 具有相同的员工编号
允许空员工编号，不会生成错误，即使同一组织中存在其他空员工编号的 Person
两个 Person 只有在属于不同组织时才可以具有相同的非空员工编号

name

仅警告规则，不阻止创建/更新，仅显示消息
当同一组织中存在同名时生成

<uniqueness_rules>
 <rule id="employee_number">
 <attributes>
 <attribute id="org_id"/>
 <attribute id="employee_number"/>
 </attributes>
 <!-- 允许空员工编号，不会被视为重复 -->
 <filter><![CDATA[employee_number != '']]></filter>
 <disabled>false</disabled>
 <is_blocking>true</is_blocking>
 </rule>
 <rule id="name">
 <attributes>
 <attribute id="org_id"/>
 <attribute id="name"/>
 <attribute id="first_name"/>
 </attributes>
 <filter/>
 <disabled>false</disabled>
 <is_blocking>false</is_blocking>
 </rule>
</uniqueness_rules>

移除默认规则

要移除默认数据模型中定义的现有唯一性规则，需要知道：

规则声明的类（如 “Person”）
规则的 rule_id（如 employee_number）

移除规则需要一段嵌入在扩展中的 XML，关键是上层节点中使用 _delta="delete"，将移除该节点及其所有子节点：

<class id="Person" _delta="must_exist">
 <properties>
 <uniqueness_rules>
 <rule id="employee_number" _delta="delete"/>
 </uniqueness_rules>
 </properties>
</class>

部分禁用规则

假设 FunctionalCI 上定义了以下规则：

<uniqueness_rules>
 <rule id="functionalci_name" _delta="define">
 <attributes>
 <attribute id="name"/>
 <attribute id="finalclass"/>
 </attributes>
 </rule>
</uniqueness_rules>

现在要为 DatacenterDevice（FunctionalCI 的子类）更改此规则，要求 DatacenterDevice 的所有子类中名称唯一。

为此，禁用父类规则 functionalci_name，并定义新规则 datacenterdevice_name：

<uniqueness_rules>
 <!-- 使用与要停止的规则相同的 rule_id -->
 <!-- 在子类上，节点是新的，因此使用 _delta="define" -->
 <rule id="functionalci_name" _delta="define">
 <!-- 覆盖现有规则时，'disabled' 是唯一支持的标签 -->
 <!-- 这将禁用 DatacenterDevice 的 'functionalci_name' 规则 -->
 <disabled>true</disabled>
 </rule>
 <!-- 然后可以添加另一个规则... -->
 <rule id="datacenterdevice_name" _delta="define">
 <attributes>
 <attribute id="name"/>
 </attributes>
 </rule>
</uniqueness_rules>

参考

iTop 官方文档

原文：https://www.itophub.io/wiki/page?id=3_2_0:customization:uniqueness-rules

版本：3_2_0/customization/uniqueness-rules.txt · Last modified: 2024/09/10 10:25 by 127.0.0.1

Docs: 丰富对象显示

Fri, 27 Jun 2025 00:00:00 +0000

本文档介绍如何通过 PHP 代码在对象详情页添加自定义内容、标签页和操作。更多详细内容请参考 iTop 官方文档。

概述

通过重写 DisplayBareRelations() 方法，可以在对象详情页的关系标签页中添加自定义内容，如邮件链接、相关对象列表等。

前置条件：熟悉教程中使用的语法，并已创建扩展。

发送团队成员邮件

本示例在团队详情页的成员标签页中添加一个 mailto 链接，直接打开邮件客户端并将所有成员邮箱填入收件人字段。

function DisplayBareRelations(WebPage $oPage, $bEditMode = false)
{
 // 必须调用父类方法，否则所有关系标签页都会丢失
 parent::DisplayBareRelations($oPage, $bEditMode);
 // 仅在只读模式下添加自定义内容
 if (!$bEditMode)
 {
 // 假设 Team 类有 'persons_list' 属性
 $oToNotify = $this->Get('persons_list');
 $aMailList = array();
 while ($oContact = $oToNotify->Fetch()) {
 $aMailList[] = $oContact->Get('email');
 }
 $sMailList = implode(', ', $aMailList);
 if ($sMailList != '')
 {
 // 通过标签名称查找特定标签页
 $sTabName = $oPage->FindTab('/^' . Dict::S('Class:Team/Attribute:persons_list') . '/');
 // 将该标签页设为当前标签页
 $oPage->SetCurrentTab($sTabName);
 // 在该标签页末尾添加超链接
 $sLink = "<br>&nbsp;<a href=\"mailto:?to={$sMailList}\">Open mailer</a>";
 $oPage->Add($sLink);
 }
 }
}

显示工单适用的已知错误

本示例在 UserRequest 详情页中添加一个标签页，显示与该工单相关的已知错误。已知错误与 UserRequest 没有直接的 LinkedSet 关系，但通过 FunctionalCI 可以间接关联。

function DisplayBareRelations(WebPage $oPage, $bEditMode = false)
{
 // 必须调用父类方法，否则其他标签页不会显示
 parent::DisplayBareRelations($oPage, $bEditMode);
 // 仅在只读模式且 KnownError 类存在时
 if ((!$bEditMode) && (MetaModel::IsValidClass('KnownError')))
 {
 // 搜索与当前 UserRequest 相关的已知错误
 $iTicketID = $this->GetKey();
 // 使用 OQL 创建搜索定义
 $oSearch = DBObjectSearch::FromOQL("
 SELECT KnownError AS ke
 JOIN lnkErrorToFunctionalCI AS l1 ON l1.error_id=ke.id
 JOIN FunctionalCI AS ci ON l1.functionalci_id=ci.id
 JOIN lnkFunctionalCIToTicket AS l2 ON l2.functionalci_id=ci.id
 WHERE l2.ticket_id={$iTicketID}");
 // 获取已知错误对象集
 $oKnownErrorSet = new CMDBObjectSet($oSearch);
 $iNumberKE = $oKnownErrorSet->count();
 // 创建新标签页（可选择仅在存在已知错误时显示）
 if ($iNumberKE > 0)
 {
 $oPage->SetCurrentTab(Dict::S('Class:UserRequest:KnownErrorList') . " ({$iNumberKE})");
 }
 else {
 $oPage->SetCurrentTab(Dict::S('Class:UserRequest:KnownErrorList'));
 }
 // 创建列表模式的显示块
 $oBlock = new DisplayBlock($oKnownErrorSet->GetFilter(), 'list', false);
 $aExtraParam = array('menu' => true, 'display_limit' => false);
 $oBlock->Display($oPage, Dict::S('Class:UserRequest:KnownErrorList'), $aExtraParam);
 }
}

常见问题

问题：对象显示不完整，关系标签页缺失？

答案：请确保在方法中始终调用 parent::DisplayBareRelations($oPage, $bEditMode);。

问题：标签页标题显示为 Class:UserRequest:KnownErrorList，如何修复？

答案：需要为 Class:UserRequest:KnownErrorList 定义字典条目。

替代方案

除了重写 DisplayBareRelations() 方法，还可以使用：

iApplicationUIExtension 接口的 OnDisplayRelations() 方法
添加新的操作菜单项

参考

iTop 官方文档

原文：https://www.itophub.io/wiki/page?id=3_2_0:customization:display-bare-relation

版本：3_2_0/customization/display-bare-relation.txt · Last modified: 2024/09/10 10:25 by 127.0.0.1

Docs: 高亮关键对象

Fri, 27 Jun 2025 00:00:00 +0000

本文档介绍如何在对象列表中高亮显示关键对象。更多详细内容请参考 iTop 官方文档。

概述

本示例展示如何在列表中高亮显示某些关键对象实例，以便 iTop 用户快速识别它们。

前置条件：熟悉教程中使用的语法，并已创建扩展。

列表中的背景色

以下示例根据团队成员的角色为列表中的成员设置不同的颜色：

/**
 * 此函数返回一个 'hilight' CSS 类，用于高亮表格中的某一行
 * 当前 CSS 中定义了 4 种可能的值：
 * HILIGHT_CLASS_CRITICAL, HILIGHT_CLASS_WARNING, HILIGHT_CLASS_OK, HILIGHT_CLASS_NONE
 * 可以像这里一样被派生类覆盖
 */
public function GetHilightClass()
{
 // 可能的返回值：
 // HILIGHT_CLASS_CRITICAL, HILIGHT_CLASS_WARNING, HILIGHT_CLASS_OK, HILIGHT_CLASS_NONE
 $current = parent::GetHilightClass(); // 默认计算

 switch ($this->Get('role_id_friendlyname')) {
 case 'Manager': $new = HILIGHT_CLASS_CRITICAL; break;
 case 'Support Agent': $new = HILIGHT_CLASS_OK; break;
 case 'Team leader': $new = HILIGHT_CLASS_WARNING; break;
 }
 // 比较父类返回的和新的高亮类，保留优先级更高的
 @$current = self::$m_highlightComparison[$current][$new];

 return $current;
}

高亮颜色

表格高亮颜色由两个 SCSS 变量控制，可以在 Designer 或扩展中修改：

高亮类	表格颜色
HILIGHT_CLASS_CRITICAL	red
HILIGHT_CLASS_WARNING	orange
HILIGHT_CLASS_OK	green

$ibo-vendors-datatables--row-highlight--colors:(
 'red': ($ibo-color-red-100),
 'danger': ($ibo-color-danger-200),
 'alert': ($ibo-color-red-200),
 'orange': ($ibo-color-orange-100),
 'warning': ($ibo-color-warning-200),
 'blue': ($ibo-color-blue-200),
 'info': ($ibo-color-information-200),
 'green': ($ibo-color-green-100),
 'success': ($ibo-color-success-200),
) !default;

自定义颜色

<variable id="ibo-vendors-datatables--row-highlight--colors" _delta="define">
('red': ($ibo-color-red-200),'danger': ($ibo-color-danger-300),'alert': ($ibo-color-red-300),'orange': ($ibo-color-orange-100),'warning': ($ibo-color-warning-200),'blue': ($ibo-color-blue-200),'info': ($ibo-color-information-200),'green': ($ibo-color-green-100),'success': ($ibo-color-success-200),)
</variable>

单行单个值，无换行，空白不影响，语法应与示例一致。

首单元格颜色：

$ibo-vendors-datatables--row-highlight--first-cell--colors:(
 'red': ($ibo-color-red-300),
 'danger': ($ibo-color-danger-400),
 'alert': ($ibo-color-red-400),
 'orange': ($ibo-color-orange-300),
 'warning': ($ibo-color-warning-400),
 'blue': ($ibo-color-blue-400),
 'info': ($ibo-color-information-400),
 'green': ($ibo-color-green-300),
 'success': ($ibo-color-success-300),
) !default;

参考

iTop 官方文档

原文：https://www.itophub.io/wiki/page?id=3_2_0:customization:highlight-critical-objects

Last modified: 2024/09/10 10:25 by127.0.0.1

版本：3_2_0/customization/highlight-critical-objects.txt · Last modified: 2024/09/10 10:25 by 127.0.0.1

Docs: 高亮状态

Fri, 27 Jun 2025 00:00:00 +0000

本文档介绍如何为枚举属性的值设置颜色和图标，以突出显示特定状态。更多详细内容请参考 iTop 官方文档。

概述

iTop 3.0 引入了为枚举值设置颜色和图标的新功能。在单独显示对象或在列表中显示时，特定枚举值会以彩色标签形式呈现。

前置条件：熟悉教程中使用的语法，并已创建扩展。

使用 ITSM Designer

如果您与 Combodo 有支持合同，可以在 ITSM Designer 中通过以下步骤修改枚举颜色：

打开 ITSM Designer
在 “Classes” 标签页中打开目标类
选择枚举字段
点击要自定义的值对应的铅笔图标
设置颜色和图标（可通过帮助链接查找图标代码）
确认
对每个要修改的值重复上述步骤
将修改推送到 iTop 实例

使用扩展

值样式

在 datamodel.xxxx.xml 文件中，为枚举值添加 style 标签。注意以下三个子标签都是必需的：

main_color：主色调（CSS 颜色或 SCSS 变量）
complementary_color：辅助色
decoration_classes：装饰图标类（Font Awesome V5 Free），可以为空但必须存在

<field id="priority" xsi:type="AttributeEnum">
 <sql>priority</sql>
 <values>
 <value id="must">
 <code>must</code>
 <style>
 <main_color>#234268</main_color>
 <complementary_color>$ibo-body-text-color</complementary_color>
 <decoration_classes>fas fa-chess-king</decoration_classes>
 </style>
 </value>
 <value id="want">
 <code>want</code>
 <style>
 <main_color>$ibo-color-blue-400</main_color>
 <complementary_color>white</complementary_color>
 <decoration_classes/>
 </style>
 </value>
 </values>
</field>

使用默认值

以下示例展示如何仅提供图标而不使用其他高亮效果，使用透明背景和默认文本颜色：

<field id="status" xsi:type="AttributeEnum">
 <sql>status</sql>
 <values>
 <value id="planned">
 <code>planned</code>
 </value>
 <value id="development">
 <code>development</code>
 </value>
 <value id="delivered">
 <code>delivered</code>
 <style>
 <main_color>$ibo-color-transparent</main_color>
 <complementary_color>$ibo-body-text-color</complementary_color>
 <decoration_classes>far fa-bell</decoration_classes>
 </style>
 </value>
 <value id="obsolete">
 <code>obsolete</code>
 </value>
 </values>
 <default_style>
 <main_color>$ibo-color-transparent</main_color>
 <complementary_color>$ibo-body-text-color</complementary_color>
 <decoration_classes>far fa-bell-slash</decoration_classes>
 </default_style>
 <default_value>planned</default_value>
 <is_null_allowed>false</is_null_allowed>
 <display_style>list</display_style>
 <dependencies/>
</field>

iTop 默认设置

以下是 iTop Community 版本中 UserRequest 类的默认状态颜色设置：

值代码	颜色	图标
new	#2C5382（深蓝色）	无
assigned	#2C5382（深蓝色）	无
waiting_for_approval	#F6AE55（橙色）	fas fa-hourglass-half
pending	#F6AE55（橙色）	fas fa-hourglass-half
approved	#689F38（绿色）	fas fa-user-check
resolved	#689F38（绿色）	fas fa-check
closed	#689F38（绿色）	无
rejected	#B83280（紫色）	fas fa-user-times
escalated_tto	#B83280（紫色）	fas fa-fire
escalated_ttr	#B83280（紫色）	fas fa-fire
	#2B6CB0（蓝色）	fas fa-user-check

<field id="status" xsi:type="AttributeEnum">
 <values>
 <value id="new">
 <style _delta="define">
 <main_color>#2C5382</main_color>
 <complementary_color>#FFFFFF</complementary_color>
 <decoration_classes/>
 </style>
 </value>
 <value id="waiting_for_approval">
 <style _delta="define">
 <main_color>#F6AE55</main_color>
 <complementary_color>#FFFFFF</complementary_color>
 <decoration_classes>fas fa-hourglass-half</decoration_classes>
 </style>
 </value>
 <!-- ... 其他值 -->
 </values>
</field>

参考

iTop 官方文档

原文：https://www.itophub.io/wiki/page?id=3_2_0:customization:enum-colors

版本：3_2_0/customization/enum-colors.txt · Last modified: 2024/09/10 10:25 by 127.0.0.1

Docs: 类颜色与图标

Fri, 27 Jun 2025 00:00:00 +0000

本文档介绍如何为 iTop 类设置主色调、图标以及每个对象实例的图标。更多详细内容请参考 iTop 官方文档。

概述

iTop 3.0 引入了为类设置颜色和图标的新功能：

类颜色：为每个类设置特定颜色，在列表中显示为彩色线条，便于区分不同类
枚举值颜色：枚举字段的值在对象名称下方显示，并关联颜色（如工单状态）
对象图标：每个对象实例可以使用不同的图标（如 Person 的头像）

前置条件：熟悉教程中使用的语法，并已创建扩展。

使用 ITSM Designer

在 ITSM Designer 中打开类定义，选择颜色和要使用的属性即可。

使用扩展

类图标

在 datamodel.xxxx.xml 文件的类属性中添加 style 标签：

<class id="FAQCategory" _delta="if_exists">
 <properties>
 <style>
 <!-- 指定类的可选图标（相对于 iTop 模块的路径）-->
 <icon _delta="define">../my-extension-code/images/icon8-faq.svg</icon>
 </style>
 </properties>
</class>

图标约束：

推荐使用 SVG 格式，体积小且缩放效果好
图标必须是正方形
240px 是类图标的理想尺寸
最好使用透明背景
不应有边框
提供指向 iTop 中 SVG 或 PNG 文件的相对路径
也可以引用 XML 中以 base64 编码的 fileref

使用 fileref 的图标

使用在线工具将图标编码为 base64
在 datamodel.xxxx.xml 中创建以下 XML 结构：

<classes>
 <class id="xxxx">
 <properties>
 <style>
 <!-- 指定以文件形式嵌入 XML 的图标 -->
 <icon _delta="define">
 <fileref ref="my-image-unique-id"/>
 </icon>
 </style>
 </properties>
 </class>
</classes>
<files>
 <file id="my-image-unique-id" xsi:type="File" _delta="define">
 <name>cron.svg</name>
 <mime_type>image/svg</mime_type>
 <width>240</width>
 <height>240</height>
 <!-- 粘贴 base64 转换结果（非常长） -->
 <data>VBORw0KGgoAAAANSUhE.[...].UgAAALQAAAC5CA</data>
 </file>
</files>

类颜色

在 datamodel.xxxx.xml 文件的类属性 style 标签中：

main_color：类的主色调
complementary_color：辅助色

颜色格式：

CSS 颜色代码：#689F38FF
iTop SCSS 变量：$ibo-color-blue-400、$ibo-transparent、$ibo-body-text-color 等

<properties>
 <style _delta="define">
 <!-- 指定类的可选图标（相对于 iTop 根目录的路径）-->
 <icon>images/user-request.png</icon>
 <!-- 类的主色调，可使用任何有效的 CSS 颜色（十六进制、HSLA、变量）或 SCSS 变量 -->
 <main_color>$ibo-color-primary-500</main_color>
 <complementary_color></complementary_color>
 </style>
</properties>

对象图标

可以为每个类实例设置不同的图标。类必须具有 Image 类型的字段来存储实例相关的信息。

在 datamodel.xxxx.xml 中修改类的 XML：

<properties>
 <fields_semantic _delta="define">
 <!-- 指定类中 AttributeImage 类型的属性代码 -->
 <image_attribute>picture</image_attribute>
 </fields_semantic>
</properties>

完整示例

以下是在 Location 类上同时实现三种定制的完整示例：

<class id="Location" _delta="must_exist">
 <properties>
 <fields_semantic>
 <state_attribute _delta="redefine">type</state_attribute>
 <image_attribute _delta="define">image</image_attribute>
 </fields_semantic>
 <style>
 <main_color _delta="define">#00ff00</main_color>
 </style>
 </properties>
 <fields>
 <field id="type" xsi:type="AttributeEnum" _delta="define">
 <sql>type</sql>
 <values>
 <value id="campus">
 <code>campus</code>
 </value>
 <value id="building">
 <code>building</code>
 </value>
 <value id="floor">
 <code>floor</code>
 </value>
 <value id="room">
 <code>room</code>
 </value>
 </values>
 <default_value>building</default_value>
 <is_null_allowed>false</is_null_allowed>
 <display_style/>
 <dependencies/>
 <tracking_level>all</tracking_level>
 </field>
 <field id="image" xsi:type="AttributeImage" _delta="define">
 <default_image/>
 <is_null_allowed>true</is_null_allowed>
 <storage_max_width>600</storage_max_width>
 <storage_max_height>400</storage_max_height>
 <display_max_width/>
 <display_max_height/>
 <tracking_level>all</tracking_level>
 </field>
 </fields>
 <presentation>
 <details>
 <items>
 <item id="type" _delta="define">
 <rank>100</rank>
 </item>
 <item id="image" _delta="define">
 <rank>110</rank>
 </item>
 </items>
 </details>
 </presentation>
</class>

参考

iTop 官方文档

原文：https://www.itophub.io/wiki/page?id=3_2_0:customization:class-colors

2024/09/10 10:25 by127.0.0.1

版本：3_2_0/customization/class-colors.txt · Last modified: 2024/09/10 10:25 by 127.0.0.1

Docs: 排序枚举值

Fri, 27 Jun 2025 00:00:00 +0000

本文档介绍如何自定义枚举属性值的显示顺序。更多详细内容请参考 iTop 官方文档。

概述

iTop 3.1 引入了枚举属性值排序的新功能。

在 3.1 版本之前，枚举值按代码的字母顺序排序。

现在可以在 XML 中通过 sort_type 标签指定排序方式：

code（默认）：与 3.1 之前的行为相同，按代码字母顺序排序
label：按标签的字母顺序排序（不同语言可能有不同的顺序）
rank：假设为每个值指定了 rank。有 rank 的值优先显示，按 rank 排序；没有 rank 的值随后按代码字母顺序排序

前置条件：熟悉教程中使用的语法，并已创建扩展。

按标签排序

<field id="origin" xsi:type="AttributeEnum">
 <sort_type>label</sort_type>
 <values>
 <value id="in_person"><code>in_person</code></value>
 <value id="chat"><code>chat</code></value>
 <value id="mail"><code>mail</code></value>
 <value id="phone"><code>phone</code></value>
 <value id="portal"><code>portal</code></value>
 <value id="monitoring"><code>monitoring</code></value>
 </values>
 <sql>origin</sql>
 <default_value>phone</default_value>
 <is_null_allowed>true</is_null_allowed>
 <display_style>list</display_style>
</field>

按 Rank 排序

<field id="status" xsi:type="AttributeEnum">
 <always_load_in_tables>true</always_load_in_tables>
 <sort_type>rank</sort_type>
 <values>
 <value id="new">
 <code>new</code>
 <rank>10</rank>
 <style>
 <main_color>$ibo-lifecycle-new-state-primary-color</main_color>
 <complementary_color>$ibo-lifecycle-new-state-secondary-color</complementary_color>
 <decoration_classes/>
 </style>
 </value>
 <value id="waiting_for_approval">
 <code>waiting_for_approval</code>
 <rank>20</rank>
 <style>
 <main_color>$ibo-lifecycle-waiting-state-primary-color</main_color>
 <complementary_color>$ibo-lifecycle-waiting-state-secondary-color</complementary_color>
 <decoration_classes>fas fa-hourglass-half</decoration_classes>
 </style>
 </value>
 <value id="approved">
 <code>approved</code>
 <rank>30</rank>
 <style>
 <main_color>$ibo-lifecycle-success-state-primary-color</main_color>
 <complementary_color>$ibo-lifecycle-success-state-secondary-color</complementary_color>
 <decoration_classes>fas fa-user-check</decoration_classes>
 </style>
 </value>
 <!-- ... 其他值 -->
 </values>
</field>

参考

iTop 官方文档

原文：https://www.itophub.io/wiki/page?id=3_2_0:customization:order-enum

版本：3_2_0/customization/order-enum.txt · Last modified: 2024/09/10 10:25 by 127.0.0.1

Docs: 排序转换

Fri, 27 Jun 2025 00:00:00 +0000

本文档介绍如何自定义具有生命周期的对象转换按钮的显示顺序。更多详细内容请参考 iTop 官方文档。

概述

iTop 3.1 引入了转换按钮排序的新功能。

在 3.1 版本之前，给定状态下的转换按钮按 XML 声明顺序显示。

现在可以通过 iTop 配置参数 lifecycle.transitions_sort_type 指定排序方式：

排序类型	说明
xml	默认值，与 3.1 之前的行为相同
alphabetical	按标签的字母顺序排序（不同语言可能有不同的顺序）
fixed	基于"转换目标状态"的顺序排序。顺序始终相同，不受用户语言或当前对象状态影响
relative	基于"转换目标状态"的顺序排序，从当前状态上方开始，然后是当前状态，最后是下方。顺序随当前状态变化，最频繁使用的转换优先显示

前置条件：熟悉教程中使用的语法，并已创建扩展。

Fixed 与 Relative 的区别

要使用这些逻辑，建议为状态定义 rank（状态是枚举属性的值）。从 iTop 3.1 开始，标准数据模型中所有具有生命周期的对象都已为状态设置了 rank。

假设有一个类具有以下状态（ranked）：1:New, 2:Dispatch, 3:Assign, 4:Resolve, 5:Close，以及这些状态之间的经典转换：

当前状态	Relative 顺序	Fixed 顺序
New	Dispatch→Assign→Resolve→Close	Dispatch→Assign→Resolve→Close
Dispatch	Assign→Resolve→Close→Re-dispatch→Re-open	Re-open→Re-dispatch→Assign→Resolve→Close
Assign	Resolve→Close→Re-assign→Re-dispatch→Re-open	Re-open→Re-dispatch→Re-assign→Resolve→Close
Resolved	Close→Re-assign→Re-dispatch→Re-open	Re-open→Re-dispatch→Re-assign→Close
Closed	（无转换）	（无转换）

配置

在 iTop 配置文件中设置：

'lifecycle.transitions_sort_type' => 'relative',

参考

iTop 官方文档

原文：https://www.itophub.io/wiki/page?id=3_2_0:customization:order-transition

版本：3_2_0/customization/order-transition.txt · Last modified: 2024/09/10 10:25 by 127.0.0.1

Docs: 强制字段必填

Fri, 27 Jun 2025 00:00:00 +0000

本文档介绍强制字段必填的不同技术方案。更多详细内容请参考 iTop 官方文档。

概述

根据需求不同，有多种方式可以强制字段必填。每种技术适用于不同的场景，教程会说明每种技术能控制哪些修改方式。

可能的修改方式包括：

控制台 - 对象创建/修改表单以及批量修改表单
门户 - 对象创建/修改表单
CSV 导入 - 控制台和命令行
DataSynchro
REST/JSON API

前置条件：熟悉教程中使用的语法，并已创建扩展。

第一系列：PhysicalDevice “Location” 字段必填

Always mandatory for all sub-classes of PhysicalDevice
Always mandatory but only for a subset of the PhysicalDevice sub-classes
Mandatory for a given class, but only if the object respects a particular condition

第二系列：UserRequest “Service” 和 “Service subcategory” 字段必填或可选

Mandatory on a transition or a state of the lifecycle
Mandatory on the User Portal while it is not mandatory in the Console

参考

iTop 官方文档

原文：https://www.itophub.io/wiki/page?id=3_2_0:customization:mandatory-field

2025/05/16 15:19 by127.0.0.1

版本：3_2_0/customization/mandatory-field.txt · Last modified: 2025/05/16 15:19 by 127.0.0.1

Docs: 强制字段只读

Fri, 27 Jun 2025 00:00:00 +0000

本文档介绍如何强制字段在创建和编辑表单中只读。更多详细内容请参考 iTop 官方文档。

概述

本示例确保用户无法在 WorkOrder 对象上输入结束日期，因为其值已通过其他方式计算。

前置条件：熟悉教程中使用的语法。

实现方式

可以通过 ITSM Designer 或扩展实现。两种方式的主要区别在于将 PHP 代码集成到 iTop 中的方式：Designer 更快捷，扩展更灵活。

使用 Designer

需要具有 “Designer PHP developer” 角色。

使用扩展

必须已创建扩展。

使字段只读

需要重载两个方法：一个用于"创建表单"，一个用于"修改表单"。强制 end_date 在创建和修改时都只读。

public function GetAttributeFlags($sAttCode, &$aReasons = array(), $sTargetState = '')
{
 // 在控制台编辑对象时调用此函数
 // 为对象的每个字段调用
 // 但仅修改单个字段的行为
 if ($sAttCode == 'end_date')
 {
 // 将新标志与父类设置的标志组合
 return(OPT_ATT_READONLY | parent::GetAttributeFlags($sAttCode, $aReasons, $sTargetState));
 }
 return parent::GetAttributeFlags($sAttCode, $aReasons, $sTargetState);
}

public function GetInitialStateAttributeFlags($sAttCode, &$aReasons = array())
{
 // 在控制台创建对象时调用此函数
 // 为对象的每个字段调用
 // 但仅修改单个字段的行为
 if (($sAttCode == 'end_date'))
 {
 // 将新标志与父类设置的标志组合
 return(OPT_ATT_READONLY | parent::GetInitialStateAttributeFlags($sAttCode, $aReasons));
 }
 // 其他字段由父类处理
 return parent::GetInitialStateAttributeFlags($sAttCode, $aReasons);
}

参考

iTop 官方文档

原文：https://www.itophub.io/wiki/page?id=3_2_0:customization:read-only-field

2024/09/10 10:25 by127.0.0.1

版本：3_2_0/customization/read-only-field.txt · Last modified: 2024/09/10 10:25 by 127.0.0.1

Docs: 区分同名对象

Fri, 27 Jun 2025 00:00:00 +0000

本文档介绍如何在编辑外部键时区分同名对象。更多详细内容请参考 iTop 官方文档。

概述

iTop 3.0 引入了区分同名对象的新功能。在编辑外部键选择远程对象时，可以显示除 friendlyname 之外的其他属性。

在只读模式下，从 iTop 3.1 开始可以通过添加 summary card 来实现相同目标。

前置条件：熟悉教程中使用的语法，并已创建扩展。

使用补充属性

在 XML 中为目标类指定 complementary_attributes，选择下拉列表时将显示额外属性：

<properties>
 <naming>
 <attributes>
 <attribute id="first_name"/>
 <attribute id="name"/>
 </attributes>
 <complementary_attributes _delta="force">
 <attribute id="email"/>
 <attribute id="org_name"/>
 </complementary_attributes>
 </naming>
 <fields_semantic>
 <image_attribute>picture</image_attribute>
 <main_color/><!-- 类的主色调，CSS 格式 -->
 <complementary_color/>
 </fields_semantic>
 <style>
 <icon>../../images/icons/icons8-person-female.svg</icon>
 </style>
</properties>

注意：使用 org_id 会显示数字，对 iTop 用户没有帮助，因此最好指定 org_name（人类可读）。

自定义显示格式

可以通过字典条目为补充字段指定格式：

<dictionaries>
 <dictionary id="EN US" _delta="must_exist">
 <entries>
 <entry id="Class:Person/ComplementaryName" _delta="force"><![CDATA[%1$s - (%2$s)]]></entry>
 </entries>
 </dictionary>
</dictionaries>

参考

iTop 官方文档

原文：https://www.itophub.io/wiki/page?id=3_2_0:customization:longname

Last modified: 2024/09/10 10:25 by127.0.0.1

版本：3_2_0/customization/longname.txt · Last modified: 2024/09/10 10:25 by 127.0.0.1

Docs: 使用事件检查数据完整性

Fri, 27 Jun 2025 00:00:00 +0000

本文档介绍如何使用事件机制检测数据不一致并阻止不合规对象保存到数据库。更多详细内容请参考 iTop 官方文档。

概述

通过订阅事件并编写回调方法，可以在对象写入数据库前进行数据一致性检查。

在控制台或门户中，提交后报告错误
阻止 DataSynchro、REST/JSON 和 CSV 导入创建或更新不合规对象

前置条件：熟悉教程中使用的语法，并已创建扩展。

理论基础

订阅事件并在对象类上编写回调方法 XxxxxXxxx()：

该方法在写入数据库前被调用
遇到数据不一致时添加错误消息
错误使用 $this->AddCheckIssue() 记录
警告使用 $this->AddCheckWarning() 记录
如果返回时存在至少一个错误，对象不会被写入数据库

消息显示方式

交互模式（控制台、门户、CSV 导入）：向用户显示错误和警告
非交互模式（DataSynchro、REST/JSON、CLI）：根据跟踪级别记录到 itop/log/error.log

示例：防止组织修改破坏关联用户

本示例检查修改 Person 的组织时，如果该 Person 有关联的 User，确保这些 User 不会因组织修改而损坏。

订阅事件

<class id="Person" _delta="define">
 <event_listeners>
 <event_listener id="CheckUsersUpdate">
 <event>EVENT_DB_CHECK_TO_WRITE</event>
 <callback>CheckUsersOnUpdate</callback>
 <rank>1</rank>
 </event_listener>
 </event_listeners>
</class>

可通过查看 iTop 数据模型的 “Events” 标签页了解类支持的事件。

检查条件

public function CheckUsersOnUpdate(Combodo\iTop\Service\Events\EventData $oEventData)
{
 // 该方法可以通过添加 Check Issue 阻止 Person 修改
 $aChanges = $this->ListChanges();
 // Person 的组织被修改
 if (array_key_exists('org_id', $aChanges))
 {
 // 当前用户可能无权查看 User 类，因此不能使用 $this->Get('user_list')
 $oSearch = new DBObjectSearch('User');
 $oSearch->AddCondition('contactid', $this->GetKey(), '=');
 $oSearch->AllowAllData();
 $oUserSet = new DBObjectSet($oSearch);

 // Person 有关联的 User
 if ($oUserSet->Count() > 0) {
 $oAddon = UserRights::GetModuleInstance();
 // 遍历每个关联的 User
 while($oUser = $oUserSet->Fetch())
 {
 // 获取其允许的组织列表和角色
 $aOrgs = $oAddon->GetUserOrgs($oUser,'Organization');
 $oSet = $oUser->Get('profile_list');
 $aProfiles = $oSet->GetColumnAsArray('profile');

 // User 有允许的组织列表、不在新组织中、具有 "Portal user" 角色且已启用
 if ((count($aOrgs) > 0) && !in_array($this->Get('org_id'), $aOrgs)
 && in_array('Portal user',$aProfiles) && ($oUser->Get('status') === 'enabled'))
 {
 // 阻止 Person 修改
 // 如不想阻止，可使用 $this->AddCheckWarning(...)
 $this->AddCheckIssue(Dict::Format('Class:Person/Error:ChangingOrgDenied', $this->Get('org_id_friendlyname')));
 }
 }
 }
 }
}

参考

iTop 官方文档

原文：https://www.itophub.io/wiki/page?id=3_2_0:customization:event_db_check_to_write

版本：3_2_0/customization/event_db_check_to_write.txt · Last modified: 2024/09/10 10:25 by 127.0.0.1

Docs: 数据完整性检查

Fri, 27 Jun 2025 00:00:00 +0000

本文档介绍如何使用事件机制在对象保存前检查数据完整性，阻止不合规数据写入数据库。更多详细内容请参考 iTop 官方文档。

概述

通过订阅 EVENT_DB_CHECK_TO_WRITE 事件，可以在对象写入数据库前进行数据完整性检查。该方法适用于：

控制台和门户中的交互式操作（提交后报告错误）
阻止 DataSynchro、REST/JSON 和 CSV 导入创建或更新不合规对象

前置条件：熟悉教程中使用的语法，并已创建扩展。

理论基础

订阅 EVENT_DB_CHECK_TO_WRITE 事件，并定义对象类的回调方法 evtCheckToWrite()：

该事件在写入数据库前触发
回调方法在遇到数据不一致时应提供错误消息
错误使用 $this->AddCheckIssue('错误消息') 记录
警告使用 $this->AddCheckWarning('警告消息') 记录
如果返回时存在至少一个错误，对象不会被写入数据库

消息显示方式

交互模式（控制台、门户、CSV 导入）：向用户显示错误和警告
非交互模式（DataSynchro、REST/JSON、CLI）：根据跟踪级别记录到 itop/log/error.log

迁移注意事项

升级后，不合规的现有对象无法再被修改，直到修复为合规状态。建议创建审计规则来识别不合规对象并逐一修复。

在 iTop 3.1.0 之前，可以使用 Extensibility API 将相同代码放入 iApplicationObjectExtension::OnCheckToWrite() 中。

示例

示例一：结束日期必须晚于开始日期

防止 Change 对象的结束日期早于开始日期：

XML 事件订阅：

<class id="Change" _delta="must_exist">
 <event_listeners>
 <event_listener id="evtCheckToWrite" _delta="define">
 <!-- 事件 ID 不需要与函数名相同，但保持一致更方便 -->
 <event>EVENT_DB_CHECK_TO_WRITE</event>
 <rank>10</rank>
 <!-- 回调必须是现有类方法的名称，名称可自定义 -->
 <callback>evtCheckToWrite</callback>
 </event_listener>
 </event_listeners>
</class>

PHP 回调方法：

public function evtCheckToWrite(Combodo\iTop\Service\Events\EventData $oEventData)
{
 // 防御性编程：确保 'end_date' 和 'start_date' 未被其他扩展移除
 // 比较前先转换为秒更安全
 if (MetaModel::IsValidAttCode(get_class($this), 'start_date')
 && MetaModel::IsValidAttCode(get_class($this), 'end_date')
 && (AttributeDateTime::GetAsUnixSeconds($this->Get('start_date'))
 > AttributeDateTime::GetAsUnixSeconds($this->Get('end_date'))))
 {
 $this->AddCheckIssue(Dict::Format('Class:Error:EndDateMustBeGreaterThanStartDate'));
 }
}

示例二：生产状态服务器必须填写位置

防止生产状态的服务器未提供位置信息：

XML 事件订阅：

<class id="Server" _delta="must_exist">
 <event_listeners>
 <event_listener id="evtCheckToWrite" _delta="define">
 <event>EVENT_DB_CHECK_TO_WRITE</event>
 <rank>10</rank>
 <callback>evtCheckToWrite</callback>
 </event_listener>
 </event_listeners>
</class>

PHP 回调方法：

public function evtCheckToWrite(Combodo\iTop\Service\Events\EventData $oEventData)
{
 // 防御性编程：确保 'status' 是当前类上的有效字段
 // 枚举值返回的是 code 而非 label，因此测试 code
 if (MetaModel::IsValidAttCode(get_class($this), 'status')
 && ($this->Get('status') == 'production'))
 {
 // AttributeExternalKey 永远不会为 NULL，空值用 0 表示
 if (MetaModel::IsValidAttCode(get_class($this), 'location_id')
 && ($this->Get('location_id') == 0))
 {
 // 'Server:Error:LocationMandatoryInProduction' 必须在字典中声明
 $this->AddCheckIssue(Dict::Format('Server:Error:LocationMandatoryInProduction'));
 }
 }
}

也可以使用纯文本错误消息：

$this->AddCheckIssue('Location is mandatory for all Servers in production');

字典条目定义：

<entry id="Server:Error:LocationMandatoryInProduction" _delta="define">
 <![CDATA['Location is mandatory for all Servers in production']]>
</entry>

示例三：FunctionalCI 名称唯一性

防止两个 FunctionalCI 具有相同名称（SoftwareInstance、MiddlewareInstance、DatabaseSchema 和 ApplicationSolution 除外）：

public function evtCheckToWrite(Combodo\iTop\Service\Events\EventData $oEventData)
{
 // 检查 FunctionalCI 名称是否必须唯一
 $aChanges = $this->ListChanges();
 // 检查 name 字段是否被设置或修改
 if (array_key_exists('name', $aChanges))
 {
 $sNewName = $aChanges['name'];
 // 检索所有具有该新名称的 FunctionalCI，忽略某些子类
 $oSearch = DBObjectSearch::FromOQL_AllData("
 SELECT FunctionalCI WHERE name = :newFCI
 AND finalclass NOT IN ('DBServer','Middleware','OtherSoftware','WebServer',
 'PCSoftware','MiddlewareInstance','DatabaseSchema','ApplicationSolution')
 ");
 $oSet = new DBObjectSet($oSearch, array(), array('newFCI' => $sNewName));
 // 如果至少有一个 FunctionalCI 匹配
 if ($oSet->Count() > 0)
 {
 // 阻止写入数据库
 $this->AddCheckIssue(Dict::Format('Class:FunctionalCI:FCINameMustBeUnique', $oSet->Count(), $sNewName));
 }
 }
}

带占位符的字典条目：

<entry id="Class:FunctionalCI:FCINameMustBeUnique" _delta="define">
 <![CDATA['Functional CI name are expected to be unique, there are already %1$s using the name %2$s']]>
</entry>

示例四：变更必须关联 CI

确保每个变更至少关联一个 CI：

public function evtCheckToWrite(Combodo\iTop\Service\Events\EventData $oEventData)
{
 // 检查当前变更是否应有关联的 CI
 if (is_subclass_of($this,'Change'))
 {
 $oSet = $this->Get('functionalcis_list');
 if ($oSet->Count() == 0)
 {
 $this->AddCheckIssue(Dict::S('Class:Change/Error:AtLeastOneCiIsNeeded'));
 }
 }
}

从 iTop 3.2.0 开始，可以通过在 XML 中标记字段 with_php_constrains 来确保当 LinkedSet 或 LinkedSetIndirect 被修改时触发 CheckToWrite：

<class id="Ticket">
 <fields>
 <field id="functionalcis_list">
 <with_php_constrains _delta="define">true</with_php_constrains>
 </field>
 </fields>
</class>

示例五：用户必须至少有一个角色

确保用户至少关联一个角色：

public function evtCheckToWrite(Combodo\iTop\Service\Events\EventData $oEventData)
{
 // 检查 profile_list 是否被修改，避免不必要的加载
 $aChanges = $this->ListChanges();
 if (array_key_exists('profile_list', $aChanges))
 {
 $oSet = $this->Get('profile_list');
 if ($oSet->Count() == 0)
 {
 $this->AddCheckIssue(Dict::S('Class:User/Error:AtLeastOneProfileIsNeeded'));
 }
 }
}

示例六：阻止创建权限

允许某些用户修改 FunctionalCI，但仅允许具有 “Configuration Manager” 角色的用户创建新的 FunctionalCI：

public function evtCheckToWrite(Combodo\iTop\Service\Events\EventData $oEventData)
{
 if ($this->IsNew() // 是否尝试创建新对象
 && !(UserRights::HasProfile('Configuration Manager')) // 用户没有 "Configuration Manager" 角色
 {
 $this->AddCheckIssue(Dict::S('Class:FunctionalCI/Error:CreationDenied'));
 }
}

此示例中的字典条目不存在，需要自行创建。

参考

iTop 官方文档

原文：https://www.itophub.io/wiki/page?id=3_2_0:customization:check-to-write

2026/02/09 12:02 by127.0.0.1

版本：3_2_0/customization/check-to-write.txt · Last modified: 2026/02/09 12:02 by 127.0.0.1

Docs: 添加对象概览

Fri, 27 Jun 2025 00:00:00 +0000

本文档介绍如何定义对象摘要卡片，在悬停时显示更多信息。更多详细内容请参考 iTop 官方文档。

概述

iTop 3.1 引入了对象摘要卡片功能。在对象列表或详情页中，外部链接仅显示 friendlyname，虽然可以点击打开详情，但用户可能希望在不打开的情况下看到更多信息。摘要卡片就是解决方案。

在编辑模式下，要区分下拉列表中的同名对象，请使用 complementary name。

前置条件：熟悉教程中使用的语法，并已创建扩展。

功能特性

每个对象类可以定义一个摘要
当定义了摘要卡片时，鼠标悬停在 friendlyname 上超过一定延迟后，会显示弹出窗口，包含：
- 对象图标
- friendlyname
- 语义属性（如已定义）
- 类名
- 直接编辑或查看对象的菜单（取决于用户权限）
- XML 摘要展示中指定的其他字段
如果在类层次结构的不同级别定义了摘要，将使用最接近当前对象类的摘要
如果显示的某个字段是外部键，且该对象也定义了摘要，则可以级联打开摘要弹出窗口

iTop 默认数据模型已为少数类定义了摘要卡片，您可以修改它们或为尚未定义的类创建新的摘要。

XML 定义

<presentation>
 <summary _delta="define">
 <items>
 <item id="function">
 <rank>10</rank>
 </item>
 <item id="phone">
 <rank>20</rank>
 </item>
 <item id="email">
 <rank>30</rank>
 </item>
 <item id="location_id">
 <rank>40</rank>
 </item>
 <item id="org_id">
 <rank>50</rank>
 </item>
 </items>
 </summary>
</presentation>

参考

iTop 官方文档

原文：https://www.itophub.io/wiki/page?id=3_2_0:customization:summary-card

2024/09/10 10:25 by127.0.0.1

版本：3_2_0/customization/summary-card.txt · Last modified: 2024/09/10 10:25 by 127.0.0.1

Docs: 修改 iTop Logo

Fri, 27 Jun 2025 00:00:00 +0000

本文档介绍如何修改 iTop 的 Logo，包括控制台菜单 Logo、登录页面 Logo 和门户 Logo。更多详细内容请参考 iTop 官方文档。

概述

iTop 默认在控制台菜单中显示 iTop Logo，可以通过 ITSM Designer 或扩展模块进行自定义。

使用 ITSM Designer

前置条件：必须是 Combodo 客户。

上传 Logo

打开 ITSM Designer 的 “Branding” 标签页
在 Logo 下拉列表中选择，或点击上传按钮上传自定义 Logo

支持的图片格式：

PNG（推荐用于 iTop 2.7 及更早版本，支持透明背景）
JPG / JPEG
GIF
SVG（仅推荐用于 iTop 3.0 及以上版本）

图片会自动调整大小以适应 iTop UI。

Logo 尺寸要求

Logo 类型	iTop 3.0.0 之前	iTop 3.0.0 及之后
主 Logo	220×64	310×70
主 Logo（折叠）	不适用	74×74（显示为 37×37）
登录页面	300×54	300×54
门户	192×50	192×50

使用 iTop 扩展

前置条件：熟悉教程中使用的语法，并已创建扩展。

添加文件

添加 Logo 图片文件有两种方式：

直接放在模块中：需要指定相对路径（模块代码 + 文件名）
将图片数据嵌入 XML：使用 fileref 引用（参见 XML 参考文档）

定义 Logo

在扩展的 XML 中通过 branding 节点重新定义 Logo：

<?xml version="1.0" encoding="UTF-8"?>
<itop_design xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="1.0">
 <branding>
 <!-- 折叠菜单时的 Logo（展开菜单请使用 main_logo） -->
 <main_logo_compact _delta="define">sample-itop-logos/custom-logo-compact.png</main_logo_compact>
 <!-- 登录页面 Logo -->
 <login_logo _delta="define">
 <fileref ref="custom-logo"/>
 </login_logo>
 </branding>
</itop_design>

完整示例

完整的工作示例可在以下仓库中找到：Combodo/sample-itop-logos

参考

iTop 官方文档

原文：https://www.itophub.io/wiki/page?id=3_2_0:customization:change-itop-logos

版本：3_2_0/customization/change-itop-logos.txt · Last modified: 2024/09/10 10:25 by 127.0.0.1

Docs: 修改 iTop 首页

Fri, 27 Jun 2025 00:00:00 +0000

本文档介绍如何修改 iTop 控制台的首页。更多详细内容请参考 iTop 官方文档。

概述

通过简单的 XML 扩展，可以将 iTop 控制台的首页重定向到任何其他 iTop 页面。

前置条件：熟悉教程中使用的语法，并已创建扩展。

使用 XML 扩展

<portals>
 <portal id="backoffice">
 <url _delta="redefine">pages/somepage.php</url>
 </portal>
</portals>

backoffice 是控制台的名称，在 iTop 中控制台被视为一种门户
此机制适用于任何 iTop 门户，只需知道其 ID 即可。对于 iTop 用户门户，ID 为 itop-portal

使用配置参数

不使用扩展的替代方案是使用配置参数 portal_dispatch_urls。

参考

iTop 官方文档

原文：https://www.itophub.io/wiki/page?id=3_2_0:customization:homepage

Last modified: 2024/09/10 10:25 by127.0.0.1

版本：3_2_0/customization/homepage.txt · Last modified: 2024/09/10 10:25 by 127.0.0.1

Docs: 修改菜单图标

Fri, 27 Jun 2025 00:00:00 +0000

本文档介绍如何修改 iTop 菜单组的图标。更多详细内容请参考 iTop 官方文档。

概述

从 iTop 3.0 开始，菜单组可以显示图标（菜单折叠时显示）。可使用的图标为 Font Awesome 5 版本。

前置条件：熟悉教程中使用的语法，并已创建扩展。

修改菜单图标

<menu id="RequestManagement" _delta="if_exists">
 <style>
 <decoration_classes _delta="force">fas fa-briefcase-medical</decoration_classes>
 </style>
</menu>
<menu id="IncidentManagement" _delta="if_exists">
 <style>
 <decoration_classes _delta="force">fas fa-car-crash</decoration_classes>
 </style>
</menu>
<menu id="ProblemManagement" _delta="if_exists">
 <style>
 <decoration_classes _delta="force">fas fa-ambulance</decoration_classes>
 </style>
</menu>
<menu id="ChangeManagement" _delta="if_exists">
 <style>
 <decoration_classes _delta="force">fas fa-random</decoration_classes>
 </style>
</menu>
<menu id="SystemTools" _delta="if_exists">
 <style>
 <decoration_classes _delta="force">fab fa-expeditedssl</decoration_classes>
 </style>
</menu>
<menu id="ConfigurationTools" _delta="if_exists">
 <style _delta="force">
 <decoration_classes>fas fa-mail-bulk</decoration_classes>
 </style>
</menu>

查找图标

使用 Font Awesome 5 Free 图标库
图标类格式为 fas fa-icon-name（solid）或 far fa-icon-name（regular）或 fab fa-icon-name（brand）

参考

iTop 官方文档

原文：https://www.itophub.io/wiki/page?id=3_2_0:customization:menu-icon

Last modified: 2024/09/10 10:25 by127.0.0.1

版本：3_2_0/customization/menu-icon.txt · Last modified: 2024/09/10 10:25 by 127.0.0.1

Docs: 修改颜色等

Fri, 27 Jun 2025 00:00:00 +0000

本文档介绍修改 iTop 控制台颜色的多种方案，从简单的颜色替换到完整的自定义主题。更多详细内容请参考 iTop 官方文档。

概述

本教程介绍修改 iTop 控制台颜色的不同方案，从简单的 ITSM Designer 修改到编写完整的自定义 CSS 主题。

对象颜色

替换默认橙色

iTop 在 full-moon 主题中使用从浅到深的橙色渐变。可以轻松替换为其他颜色渐变：

修改主色调

状态颜色

iTop 可以为每个状态值关联颜色和图标。默认数据模型中已定义许多状态颜色，您也可以修改或添加：

高亮状态

类颜色

iTop 为每个类使用特定颜色，在对象显示中使用：

类颜色与图标

列表高亮

在对象列表中，可以为某些对象设置背景色以便快速识别：

高亮关键对象

菜单图标与颜色

颜色格式

支持的颜色代码格式：

格式	示例
十六进制	`#FF0000`
RGB	`rgb(123, 123, 132)`
RGBA	`rgba(123, 123, 123, 0.5)`
HSL	`hsl(123, 50%, 50%)`
HSLA	`hsla(123, 50%, 50%, 0.23)`
SCSS 变量	`$ibo-color-transparent`、`$ibo-body-text-color` 等

使用现有 SCSS 变量

使用 iTop 现有 SCSS 变量的优势在于，当创建或修改主题时，这些设置会自动应用，保持界面一致性。

要使用现有 iTop 颜色代码，可以在 iTop 3.0+ 中使用浏览器开发工具查看现有值，然后使用以下语法转换：

$ibo-lifecycle-success-state-primary-color
var(--ibo-lifecycle-success-state-primary-color)

其他变量

标签最大宽度

如果标签值较长且不希望被截断，可以修改变量 $ibo-input-set--item--max-width，修改方式与颜色变量类似。

参考

iTop 官方文档

原文：https://www.itophub.io/wiki/page?id=3_2_0:customization:color-overview

2024/09/10 10:25 by127.0.0.1

版本：3_2_0/customization/color-overview.txt · Last modified: 2024/09/10 10:25 by 127.0.0.1

Docs: 修改页面标题

Fri, 27 Jun 2025 00:00:00 +0000

本文档介绍如何修改 iTop 对象详情页的浏览器标签页标题。更多详细内容请参考 iTop 官方文档。

概述

通过简单的 XML 扩展，可以重新定义 iTop 控制台中对象详情页的浏览器标签页标题。

前置条件：熟悉教程中使用的语法，并已创建扩展。

控制台页面标题

'UI:DetailsPageTitle' => ITOP_APPLICATION_SHORT.' - %2$s - Détails de %1$s',

%1$s 对应 friendlyname 的第一个属性。

门户页面标题

门户首页使用字典条目 Page:DefaultTitle，可以修改
其他页面的标题是 Brick 标签和应用程序短名称的组合，例如：Open Requests - iTop。此标题无法更改
全屏修改对象时的标题为 Updating R-000012 (UserRequest) - iTop。此标题无法更改

参考

iTop 官方文档

原文：https://www.itophub.io/wiki/page?id=3_2_0:customization:tab-title

Last modified: 2024/09/10 10:25 by127.0.0.1

版本：3_2_0/customization/tab-title.txt · Last modified: 2024/09/10 10:25 by 127.0.0.1

Docs: 修改主色调

Fri, 27 Jun 2025 00:00:00 +0000

本文档介绍如何修改 iTop 控制台的主色调，以匹配企业品牌色。更多详细内容请参考 iTop 官方文档。

概述

通过 ITSM Designer 或 XML 扩展，可以修改 iTop 控制台中按钮、搜索横幅、悬停行和超链接的颜色，使其与企业品牌色保持一致。

前置条件：熟悉教程中使用的语法，并已创建扩展。

标准主色调变量

iTop 3.0 使用 SCSS 变量系统定义主色调。以下是一组标准的主色调变量：

<variables>
 <variable id="ibo-color-primary-100" _delta="define">$ibo-color-blue-100</variable>
 <variable id="ibo-color-primary-200" _delta="define">$ibo-color-blue-100</variable>
 <variable id="ibo-color-primary-300" _delta="define">$ibo-color-blue-300</variable>
 <variable id="ibo-color-primary-400" _delta="define">$ibo-color-blue-400</variable>
 <variable id="ibo-color-primary-500" _delta="define">$ibo-color-blue-500</variable>
 <variable id="ibo-color-primary-600" _delta="define">$ibo-color-blue-500</variable>
 <variable id="ibo-color-primary-700" _delta="define">$ibo-color-blue-600</variable>
 <variable id="ibo-color-primary-800" _delta="define">$ibo-color-blue-800</variable>
 <variable id="ibo-color-primary-900" _delta="define">$ibo-color-blue-900</variable>
</variables>

自定义颜色

将上述 XML 代码粘贴到 ITSM Designer 或扩展中，将 $ibo-color-blue-XXX 替换为所需的颜色变量或具体颜色值。

颜色格式

支持的颜色格式包括：

颜色名称：purple
十六进制：#FF0000
RGB：rgb(123, 123, 132)
RGBA：rgba(123, 123, 123, 0.5)
HSL：hsl(123, 50%, 50%)
HSLA：hsla(123, 50%, 50%, 0.23)
SCSS 变量：$ibo-color-transparent、$ibo-body-text-color 等

使用现有变量

使用 iTop 现有 SCSS 变量的优势在于，当创建或修改主题时，这些设置会自动应用，保持界面一致性。

参考

iTop 官方文档

原文：https://www.itophub.io/wiki/page?id=3_2_0:customization:change-main-color

版本：3_2_0/customization/change-main-color.txt · Last modified: 2024/09/10 10:25 by 127.0.0.1

Docs: 修改左侧菜单颜色

Fri, 27 Jun 2025 00:00:00 +0000

本文档介绍如何修改 iTop 控制台左侧导航菜单的颜色，以匹配企业品牌色。更多详细内容请参考 iTop 官方文档。

概述

通过 ITSM Designer 或 XML 扩展，可以修改 iTop 控制台左侧菜单的颜色，使其与企业品牌色保持一致。

前置条件：熟悉教程中使用的语法，并已创建扩展。

菜单颜色变量

以下 XML 代码展示了控制左侧菜单各部分的 SCSS 变量：

<variables>
 <!-- 主菜单（图标使用与文本相同的颜色） -->
 <variable id="ibo-navigation-menu--body--background-color" _delta="define">$ibo-color-white-100</variable>
 <variable id="ibo-navigation-menu--body--text-color" _delta="define">$ibo-color-blue-800</variable>

 <!-- 主菜单悬停效果（背景与文本） -->
 <variable id="ibo-navigation-menu--action--background-color--on-hover" _delta="define">$ibo-color-blue-100</variable>
 <variable id="ibo-navigation-menu--action--text-color--on-hover" _delta="define">$ibo-color-blue-700</variable>

 <!-- 主菜单激活状态（图标与文本） -->
 <variable id="ibo-navigation-menu--menu-group-title--text-color--is-active" _delta="define">$ibo-color-blue-700</variable>
 <variable id="ibo-navigation-menu--menu-group-icon--text-color--is-active" _delta="define">$ibo-color-blue-500</variable>

 <!-- 子菜单（菜单组文本、数字和悬停背景） -->
 <variable id="ibo-navigation-menu--menu-node--background-color" _delta="define">$ibo-color-blue-100</variable>
 <variable id="ibo-navigation-menu--menu-node--text-color" _delta="define">$ibo-color-blue-900</variable>

 <!-- 底部菜单（用户图标下方） -->
 <variable id="ibo-navigation-menu--bottom-part--background-color" _delta="define">$ibo-color-grey-100</variable>
 <variable id="ibo-navigation-menu--user--text-color" _delta="define">$ibo-color-blue-800</variable>
 <variable id="ibo-navigation-menu--user-organization--text-color" _delta="define">$ibo-color-blue-600</variable>
</variables>

其他菜单变量

以下变量目前可能没有明显的视觉效果：

<variables>
 <variable id="ibo-navigation-menu--action-icon--text-color--on-hover" _delta="define">$ibo-color-red-300</variable>
 <variable id="ibo-navigation-menu--user-picture--background-color" _delta="define">$ibo-color-cyan-300</variable>
 <variable id="ibo-navigation-menu--action--background-color--on-active" _delta="define">$ibo-color-orange-300</variable>
</variables>

使用方法

将上述 XML 代码插入到扩展中，或粘贴到 ITSM Designer 中，然后修改变量值为所需的颜色。

参考

iTop 官方文档

原文：https://www.itophub.io/wiki/page?id=3_2_0:customization:change-menu-colors

版本：3_2_0/customization/change-menu-colors.txt · Last modified: 2024/09/10 10:25 by 127.0.0.1

Docs: 隐藏对象历史

Fri, 27 Jun 2025 00:00:00 +0000

本文档介绍如何对特定角色的用户隐藏对象历史记录。更多详细内容请参考 iTop 官方文档。

概述

本示例为具有 “Support Agent” 角色的用户隐藏对象的活动面板中的历史记录。

前置条件：熟悉教程中使用的语法，并已创建扩展。

注意事项

该方案在客户端隐藏历史记录，安全性不完全
可以通过 JS 代码从 DOM 中完全移除信息，但高级用户仍可在浏览器中设置断点阻止 JS 执行并查看历史
允许查看历史记录的角色列表可以放入模块参数中，便于后续修改

实现

通过实现 iBackofficeStyleExtension 接口，根据当前用户角色动态返回 CSS：

<snippets>
 <snippet id="hide_history_entries" _delta="define">
 <placement>core</placement>
 <rank>0</rank>
 <content><![CDATA[
 class HideHistoryEntries implements iBackofficeStyleExtension
 {
 public function GetStyle(): string
 {
 // 检查当前用户是否具有需要隐藏历史记录的角色
 $aCurrentUserProfiles = \UserRights::ListProfiles();
 $aProfilesToHideEntriesFor = ['Support Agent'];
 foreach ($aCurrentUserProfiles as $sCurrentUserProfile) {
 if (in_array($sCurrentUserProfile, $aProfilesToHideEntriesFor)) {
 // 强制隐藏编辑记录
 return <<<CSS
 .ibo-activity-entry.ibo-edits-entry {
 display: none !important;
 }
 CSS;
 }
 }

 // 当前用户没有受限角色，保持默认样式
 return '';
 }
 }
 ]]></content>
 </snippet>
</snippets>

自定义角色

修改 $aProfilesToHideEntriesFor 数组中的角色名称，即可控制对哪些用户隐藏历史记录：

$aProfilesToHideEntriesFor = ['Support Agent', 'Portal user'];

参考

iTop 官方文档

原文：https://www.itophub.io/wiki/page?id=3_2_0:customization:hide-history

2024/09/10 10:25 by127.0.0.1

版本：3_2_0/customization/hide-history.txt · Last modified: 2024/09/10 10:25 by 127.0.0.1

Docs: 隐藏影响分析

Fri, 27 Jun 2025 00:00:00 +0000

本文档介绍如何隐藏对象详情页中的特定标签页（如影响分析或仪表盘）。更多详细内容请参考 iTop 官方文档。

概述

通过简单的 PHP 扩展，可以从 Change 对象（或任何其他 Ticket 类）的详情页中隐藏 “Impact analyses” 标签页，也可以根据条件隐藏仪表盘标签页。

前置条件：熟悉教程中使用的语法，并已创建扩展。

隐藏影响分析标签页

public function DisplayBareRelations(WebPage $oPage, $bEditMode = false)
{
 parent::DisplayBareRelations($oPage, $bEditMode);
 $oPage->RemoveTab('Ticket:ImpactAnalysis');
}

根据条件隐藏仪表盘标签页

可以根据对象字段值隐藏属性仪表盘。以下示例假设 Team 类有一个代码为 dashboard 的 Dashboard 属性，当 notify 字段为 no 时隐藏该仪表盘：

public function DisplayBareRelations(WebPage $oPage, $bEditMode = false)
{
 parent::DisplayBareRelations($oPage, $bEditMode);
 if ($this->Get('notify') === 'no') {
 $oPage->RemoveTab('Class:Team/Attribute:dashboard');
 }
}

标签页标识符

标签页标识符与字典条目一致：

格式：Class:class_name/Attribute:attribute_code
注意区分大小写，属性代码通常为小写

参考

iTop 官方文档

原文：https://www.itophub.io/wiki/page?id=3_2_0:customization:hidetab

Last modified: 2024/09/10 10:25 by127.0.0.1

版本：3_2_0/customization/hidetab.txt · Last modified: 2024/09/10 10:25 by 127.0.0.1

Docs: 在弹出菜单中添加条目

Fri, 27 Jun 2025 00:00:00 +0000

本文档介绍如何在 iTop 的弹出菜单（“其他操作…"）中添加自定义菜单条目。更多详细内容请参考 iTop 官方文档。

概述

从 iTop 2.0.0 开始，框架支持在所有弹出菜单中添加新的菜单项，包括列表上的"其他操作…“和"工具包"菜单、对象详情页的"其他操作…“菜单、“注销"菜单等。

前置条件：需要具备 PHP 和 JavaScript 开发能力。

实现 iPopupMenuExtension 接口

要添加新的弹出菜单项，需要提供一个实现 iPopupMenuExtension 接口的 PHP 类。将该类文件添加到模块的 datamodel 文件列表中，确保其被正确加载。

模块定义

在 module.sample-add-menu.php 中声明数据模型文件：

<?php
// iTop module definition file
//

SetupWebPage::AddModule(
 __FILE__,
 'sample-add-menu/',
 array(
 // Identification
 'label' => 'Add Menu Sample',
 'category' => 'business',

 // Setup
 'dependencies' => array(),
 'mandatory' => false,
 'visible' => true,

 // Components
 'datamodel' => array(
 'main.sample-add-menu.php',
 'model.sample-add-menu.php'
 ),
 'webservice' => array(),
 'data.struct' => array(),
 'data.sample' => array(),

 // Documentation
 'doc.manual_setup' => '',
 'doc.more_information' => '',

 // Default settings
 'settings' => array(),
 )
);

实现菜单扩展类

创建 main.sample-add-menu.php：

<?php
/**
 * Sample extension to show how adding menu items in iTop
 * This extension demonstrates three possible types of menu items:
 * - URL 链接到任意网页
 * - JavaScript 函数调用
 * - 分隔线（水平线）
 */
class AddMenuSampleExtension implements iPopupMenuExtension
{
 /**
 * Get the list of items to be added to a menu.
 *
 * This method is called by the framework for each menu.
 * The items will be inserted in the menu in the order of the returned array.
 * @param int $iMenuId The identifier of the type of menu, as listed by the constants MENU_xxx
 * @param mixed $param Depends on $iMenuId, see the constants defined above
 * @return object[] An array of ApplicationPopupMenuItem or an empty array if no action is to be added to the menu
 */
 public static function EnumItems($iMenuId, $param)
 {
 $aResult = array();
 switch($iMenuId) // 要添加菜单项的菜单类型
 {
 /**
 * 在列表的操作菜单中插入条目
 * $param 是包含对象列表的 DBObjectSet
 */
 case iPopupMenuExtension::MENU_OBJLIST_ACTIONS:
 // 添加触发自定义 JS 函数的菜单项
 $sModuleDir = basename(dirname(__FILE__));
 $sJSFileUrl = utils::GetAbsoluteUrlModulesRoot().$sModuleDir.'/js/sample.js';
 $iCount = $param->Count(); // 对象集中的对象数量
 $aResult[] = new JSPopupMenuItem('_Custom_JS_', 'Custom JS Function On List...', "MyCustomJSListFunction($iCount)", array($sJSFileUrl));
 break;

 /**
 * 在列表的工具包菜单中插入条目
 * $param 是包含对象列表的 DBObjectSet
 */
 case iPopupMenuExtension::MENU_OBJLIST_TOOLKIT:
 break;

 /**
 * 在对象详情页的操作菜单中插入条目
 * $param 是当前显示的对象实例（DBObject）
 */
 case iPopupMenuExtension::MENU_OBJDETAILS_ACTIONS:
 // 为任意对象添加 "Google this..." 菜单，在新标签页打开 Google 搜索
 $aResult[] = new URLPopupMenuItem('_Google_this_', 'Google this...', "http://www.google.com?q=".$param->GetName(), '_blank');

 // 仅对 Contact（Team 和 Person）添加额外菜单项
 if ($param instanceof Contact)
 {
 // 添加分隔线（仅 iTop 2.0.1-beta 及以上版本支持）
 $aResult[] = new SeparatorPopupMenuItem();

 // 添加触发自定义 JS 函数的菜单项
 $sModuleDir = basename(dirname(__FILE__));
 $sJSFileUrl = utils::GetAbsoluteUrlModulesRoot().$sModuleDir.'/js/sample.js';
 $aResult[] = new JSPopupMenuItem('_Custom_JS_', 'Custom JS Function...', "MyCustomJSFunction('".addslashes($param->GetName())."')", array($sJSFileUrl));
 }
 break;

 /**
 * 在仪表盘菜单中插入条目
 * $param 是当前显示的仪表盘实例
 */
 case iPopupMenuExtension::MENU_DASHBOARD_ACTIONS:
 break;

 /**
 * 在用户菜单（页面右上角）中插入条目
 * $param 为 null
 */
 case iPopupMenuExtension::MENU_USER_ACTIONS:
 break;
 }
 return $aResult;
 }
}

自定义 JavaScript 函数

在 js/sample.js 中实现自定义函数：

// 从自定义菜单项调用的示例 JS 函数
function MyCustomJSFunction(sName)
{
 // 简单弹出提示框
 alert(sName);
}

// 从列表菜单项调用的示例 JS 函数
function MyCustomJSListFunction(iCount)
{
 alert('There are '+iCount+' element(s) in this list.');
}

菜单类型常量

常量	说明	$param 类型
`MENU_OBJLIST_ACTIONS`	列表的"其他操作…“菜单	DBObjectSet
`MENU_OBJLIST_TOOLKIT`	列表的"工具包"菜单	DBObjectSet
`MENU_OBJDETAILS_ACTIONS`	对象详情页的"其他操作…“菜单	DBObject
`MENU_DASHBOARD_ACTIONS`	仪表盘菜单	Dashboard
`MENU_USER_ACTIONS`	用户菜单（右上角）	null

菜单项类型

类型	类	说明
URL 链接	`URLPopupMenuItem`	打开指定 URL，可设置 target
JS 函数	`JSPopupMenuItem`	调用 JavaScript 函数，可加载外部 JS 文件
分隔线	`SeparatorPopupMenuItem`	水平分隔线（iTop 2.0.1+）

安装扩展

将扩展压缩包解压到 iTop 根目录的 extensions 文件夹中（如不存在则创建）
确保 Web 服务器对 extensions 文件夹中的所有文件具有读取权限
移除配置文件（conf/production/config-itop.php）的只读属性
访问 http://<itop-root>/setup 重新运行 iTop 安装向导
在安装向导最后一步的扩展列表中勾选 “Add Menu Sample”

参考

iTop 官方文档

原文：https://www.itophub.io/wiki/page?id=3_2_0:customization:add-menu-sample

2024/09/10 10:25 by127.0.0.1

版本：3_2_0/customization/add-menu-sample.txt · Last modified: 2024/09/10 10:25 by 127.0.0.1

Docs: 在列表上添加操作

Fri, 27 Jun 2025 00:00:00 +0000

本文档介绍如何在 iTop 对象列表上添加自定义批量操作。更多详细内容请参考 iTop 官方文档。

概述

通过实现 iPopupMenuExtension 接口，可以在对象列表的"工具包"菜单中添加自定义批量操作。本文提供两个示例：批量编辑远程对象和批量编辑链接关系。

前置条件：熟悉教程中使用的语法，并已创建扩展。

批量编辑远程对象

本示例在 Problem 或 NormalChange 的 CI 关联列表上添加操作，直接打开批量修改界面，仅修改与该工单关联的 Application Solution。

class AddModifyAllMenuPlugIn implements iPopupMenuExtension
{
 public static function EnumItems($iMenuId, $param)
 {
 $aExtraMenus = array();
 if ($iMenuId == iPopupMenuExtension::MENU_OBJLIST_TOOLKIT && $param->GetFilter()->GetClass() === 'lnkFunctionalCIToTicket' ) {
 $oFilter = $param->GetFilter();
 $sClass = $oFilter->GetClass();
 $sOQL = $oFilter->ToOQL();
 if(str_contains($sOQL, "`Ticket`.`id` = :id")) {
 $oTicket = MetaModel::GetObject('Ticket',$oFilter->GetInternalParams()['id']);
 if(in_array(get_class($oTicket),['Problem','NormalChange'])) {
 if (UserRights::IsActionAllowed($sClass, UR_ACTION_BULK_MODIFY) != UR_ALLOWED_NO) {
 $oApplicationQuery = DBSearch::FromOQL('SELECT ApplicationSolution');
 $oApplicationQuery->AddCondition_ReferencedBy($param->GetFilter(), 'functionalci_id');
 $aExtraMenus[] = new URLPopupMenuItem('ModifyAll::lnkFunctionalCIToTicket', 'Modify application solutions',
 utils::GetAbsoluteUrlAppRoot()."pages/".cmdbAbstractObject::ComputeStandardUIPage($sClass)
 ."?operation=select_for_modify_all&class=ApplicationSolution&filter=".urlencode('["'.$oApplicationQuery->ToOQL(true).'",{},[]]')
 );
 }
 }
 }
 }
 return $aExtraMenus;
 }
}

批量编辑链接关系

如果您需要经常批量编辑 n:n 关系中的属性，而不想通过"运行查询"菜单执行以下操作：

SELECT lnkFunctionalCIToTicket WHERE ticket_id=:id

然后输入工单 ID 再批量修改结果链接，可以在 FunctionalCI 标签页上添加一个快速操作。

代码与上述示例非常相似，只需修改返回的类和过滤条件：

 $oLnkQuery = DBSearch::FromOQL('SELECT lnkFunctionalCIToTicket');
 $oLnkQuery->AddCondition('ticket_id', $oFilter->GetInternalParams()['id']);
 $aExtraMenus[] = new URLPopupMenuItem('ModifyAll::lnkFunctionalCIToTicket', 'Bulk modify the Links',
 utils::GetAbsoluteUrlAppRoot()."pages/".cmdbAbstractObject::ComputeStandardUIPage($sClass)
 ."?operation=select_for_modify_all&class=lnkFunctionalCIToTicket&filter=".urlencode('["'.$oLnkQuery->ToOQL(true).'",{},[]]')
 );

关键要点

使用 MENU_OBJLIST_TOOLKIT 在列表的工具包菜单中添加操作
通过 $param->GetFilter() 获取当前列表的过滤条件
使用 AddCondition_ReferencedBy 建立关联查询
使用 cmdbAbstractObject::ComputeStandardUIPage 生成标准 UI 页面 URL
operation=select_for_modify_all 打开批量修改选择界面

参考

iTop 官方文档

原文：https://www.itophub.io/wiki/page?id=3_2_0:customization:bulk-edit-links

2024/09/10 10:25 by127.0.0.1

版本：3_2_0/customization/bulk-edit-links.txt · Last modified: 2024/09/10 10:25 by 127.0.0.1

Docs:

Fri, 27 Jun 2025 00:00:00 +0000

{% pageinfo %} 本文档介绍。更多详细内容请参考 iTop 官方文档。 {% /pageinfo %}

概述

是 iTop 3.2.0 文档中的主题。

原文：https://www.itophub.io/wiki/page?id=3_2_0:customization:dynamic-icon

版本：

Docs: 在控制台中高亮状态

Fri, 27 Jun 2025 00:00:00 +0000

本文档介绍如何使用 CSS 在控制台和门户中根据状态值以不同颜色高亮显示工单状态。更多详细内容请参考 iTop 官方文档。

在控制台中高亮

在本教程中，使用 HTML 标记，我们将展示如何在控制台中根据状态值以不同颜色高亮显示工单状态。

为此，需要编写一些 CSS 并将其嵌入到 iTop 扩展模块中。我们假设您熟悉 CSS 代码。以下是一个 CSS 示例，更改状态为 ‘closed’、‘rejected’ 和 ‘accepted’ 时的显示：

/* 定义一些颜色 */
$status-default-color: #757575 !default;
$status-default-bg-color: #DEDEDE !default;
$status-accepted-color: #FFFFFF !default;
$status-accepted-bg-color: #2F855A !default;
$status-closed-color: #757575 !default;
$status-closed-bg-color: #DEDEDE !default;

/* 定义一组可复用的属性 */
%status-icon{
 margin-right: 0.5rem;
 content: "";
 font-family: "Font Awesome 5 Free";
 font-weight: bold;
}

/* 在任何对象详情屏幕中，如果存在名为 'status' 的枚举字段 */
.object-details{
 *[data-attribute-type="AttributeEnum"][data-attribute-code="status"]{
 .field_label{
 vertical-align: baseline;
 }
 .field_value{ /* 修改值的显示 */
 display: inline-block;
 padding: 0.25rem 0.6rem;
 color: $status-default-color;
 background-color: $status-default-bg-color;
 border-radius: .25rem;
 }
 /* 如果值为 'accepted'，使用某些颜色 */
 &[data-value-raw="accepted"]{
 .field_value{
 color: $status-accepted-color;
 background-color: $status-accepted-bg-color;
 /* 在标签前添加一个 font awesome 图标 */
 &::before{
 @extend %status-icon;
 content: "\f4fc"; /* 字体代码 */
 }
 }
 }
 /* 如果值为 'rejected' 或 'closed'，使用其他颜色 */
 &[data-value-raw="rejected"],
 &[data-value-raw="closed"]{
 .field_value{
 color: $status-closed-color;
 background-color: $status-closed-bg-color;
 font-weight: bold;
 }
 }
 }
}

通过主题加载 CSS

为确保 iTop 使用您的 CSS，需要将其添加到 iTop 主题中：

<branding>
 <themes>
 <theme id="light-grey">
 <stylesheets>
 <stylesheet id="my-module" _delta="define">my-module/asset/css/console.scss</stylesheet>
 </stylesheets>
 </theme>
 </themes>
</branding>

当然，可以扩展此定义以覆盖状态的每个值。可以对任何枚举（不仅是状态）执行此操作。可以将其限制为工单类。

在门户中高亮

在 PHP 中加载 CSS

由于 iTop 2.7 中的主题在门户中不起作用，无法使用 XML 配置告诉 iTop 何时为门户上传 CSS。因此我们将使用另一种方式。

在 main.my-module.php 或模块的任何 .php 文件中。使用新的扩展逻辑，将其放在：

my-module/src/Hook/PortalUIExtension.php

以下是复制代码：

<?php

use iPortalUIExtension;
use RequestStatusBeautifierPortal;
use Symfony\Component\DependencyInjection\Container;
use utils;

/* AbsractPortalUIExtension 实现了 iPortalUIExtension，但没有任何行为 */
class MyModulePortalUIExtension extends AbsractPortalUIExtension
{
 const MODULE_CODE = 'my-module';

 public function GetCSSFiles(Container $oContainer)
 {
 $sModuleCSSFolderRelPath = 'env-'.utils::GetCurrentEnvironment().'/my-module/asset/css/';
 $sModuleCSSFolderAbsPath = utils::GetAbsoluteModulePath(static::MODULE_CODE).'asset/css/';
 $sAdditionalSCSSFileRelPath = $sModuleCSSFolderRelPath.'portal-additional.scss';
 $sAdditionalSCSSFileAbsPath = $sModuleCSSFolderAbsPath.'portal-additional.scss';

 $aCSSFiles = array(
 utils::GetAbsoluteUrlModulesRoot().static::MODULE_CODE.'/asset/css/portal.scss',
 );

 // 检查额外的 CSS 是否已编译
 clearstatcache();
 if (!file_exists($sAdditionalSCSSFileAbsPath) && (is_writable($sModuleCSSFolderAbsPath)))
 {
 // 获取额外的 SCSS
 $sAdditionalSCSS = '@import "../'.$sModuleCSSFolderRelPath.'variables.scss";'."\n";
 $sAdditionalSCSS .= RequestStatusBeautifierPortal::GetAdditionalSCSS();
 file_put_contents($sAdditionalSCSSFileAbsPath, $sAdditionalSCSS);

 $aCSSFiles[] = utils::GetAbsoluteUrlAppRoot().utils::GetCSSFromSASS($sAdditionalSCSSFileRelPath);
 }
 return $aCSSFiles;
 }
}

可以几乎复制粘贴此代码，只需更改：

类名
module_code
.scss 文件的名称和路径

不要忘记在模型中添加此 Hook 文件名：

SetupWebPage::AddModule(
 __FILE__, // 当前文件的路径，所有其他文件名相对于包含此文件的目录
 'my-module/1.0.0',
 array(
 'datamodel' => array(
 'model.my-module.php',
 'src/Hook/PortalUIExtension.php',
[...]

原文：https://www.itophub.io/wiki/page?id=3_2_0:customization:markup

版本：3_2_0/customization/markup.txt · Last modified: 2024/09/10 10:25 by 127.0.0.1