使用变量示例

您可以组合一些变量来获得更复杂的结果。请参见按复杂性和用例组织的不同场景中使用变量的示例。

本文内容：

快速参考

常见变量模式及其用例：

模式	用例	示例
`{#variable}...{/variable}`	遍历条目	`{#markups}{name}{/markups}`
`{#!variable}...{/}`	当变量为空时显示	`{#!amount}$0.00{/}`
`{#variable}...{/}{#!variable}...{/}`	显示值或默认值	`{#previousAmount}{previousAmount}{/}{#!previousAmount}0{/}`
`{variable \| filter:"field":"value"}`	过滤数据	`{items \| filter:"type":"SOV"}`
`{variable \| sumBy:"field"}`	计算总数	`{items \| sumBy:"approved"}`
`{#condition}...{/}`	条件显示	`{#amount!="0.00"}{amount}{/}`
`{variable \| groupItemsByXCO: 'type'}`	按变更单类型分组	`{items \| groupItemsByXCO: 'COR'}`

基本变量用法

如果您是新接触在文档模板中使用变量，请从这里开始。这些示例涵盖了适用于所有文档类型的基本概念。

如何添加包含变量的表？

您可以使用变量，并以表的形式（包含列和标题）显示数据。下面是一个语法示例：

显示开始和结束标记变量的表变量语法示例

使用打开部分变量（以 # 开头，例如 {#markups}）和结束部分变量（以 / 结束，例如 {/markups}）。

注意：请勿在一个表中重复相同的打开和关闭变量。

错误用法：

在一个表中显示重复的开始和结束变量的错误用法示例

正确用法：

显示适当的开始和结束变量结构的正确用法示例

在打开和关闭变量之间，您可以列出所有必需的数据，如 {name} 或 {description}。

具有名称和描述变量的表变量语法示例

生成的文档中的结果：

生成的文档结果，显示了带变量数据的格式化表

如何为空白变量显示默认值？

场景：您在文档模板中使用了 {previousAmount} 和 {materialsStored} 之类的变量，但在生成文档时，某些列显示空白，而不是显示“$0”值。

若要在变量为空或空白时显示默认值，请使用具有以下模式的条件表达式：

{#variableName} {variableName} {/}{#!variableName}default_value{/}

例如，若要在 {previousAmount} 为空白时显示“0”：

{#previousAmount} {previousAmount} {/}{#!previousAmount}0{/}

此条件表达式的工作原理如下：

{#previousAmount} - 如果 previousAmount 有值，则显示该值
{previousAmount} - 实际变量值
{/} - 关闭第一个条件
{#!previousAmount} - 如果 previousAmount 没有值（为空白/空）
0 - 将“0”显示为默认值
{/} - 关闭第二个条件

您可以将此模式应用于要显示默认值而不是空白单元格的任何变量，例如：

{#materialsStored} {materialsStored} {/}{#!materialsStored}$0.00{/}
{#currentAmount} {currentAmount} {/}{#!currentAmount}0{/}

当字段为 null 时如何使用回退值？

场景：您希望在合同文档中显示保留款百分比，但该字段可能为 null。如果它为 null，则需要回退到其他来源的值（例如，合同的保留款设置）。

使用三元表达式检查 null 并提供回退：

{contract.completedWorkRetentionPercent === null? contract.retention.completedWorkRetentionPercent : contract.completedWorkRetentionPercent}

此表达式的工作原理如下：

contract.completedWorkRetentionPercent === null? - 检查字段是否为 null
contract.retention.completedWorkRetentionPercent - 如果为 null，则使用此回退值
: - 否则...
contract.completedWorkRetentionPercent - 使用原始字段值

当字段可能继承父设置的值，或者需要检查多个来源以获取某个值时，此模式非常有用。

特定于文档的示例

这些示例按文档类型进行组织，以帮助您找到特定用例的相关解决方案。

支付申请

自定义支付申请文档和电子表格的示例。

如何从支付申请中移除空行项目？

若要从支付申请中移除空行项目，请在表开头使用条件表达式 {#amount!="0.00"}，并在行末尾使用 {/}。例如：

展示从支付申请中移除空行项目的条件表达式示例

如何在支付申请中仅显示计划条目的成本，而不显示小计金额？

若要消除支付申请或合同中的小计，您可以采用 {#children.length===0}{xxx}{/} 格式输入付款行项目。例如：

显示如何使用 children.length 条件消除小计的示例

如何配置预算支付申请电子表格以按类型拆分变更单？

场景：您已创建一个名为“留量转移”的变更单类型。

显示留量转移配置的变更单类型设置

并且希望在 Excel 电子表格中看到这些留量的批准的业主变更。如何做到这一点？

为 Excel 电子表格中的列列出“业主变更单”。
将新类型应用于 OCO。
将名称与 Excel 电子表格中的类型匹配。

如何在成本支付申请电子表格中添加一个没有小计的新选项卡？

场景：您要在默认成本支付申请电子表格模板中创建一个新选项卡，该选项卡仅显示计划条目，而不显示小计金额。

若要在成本支付申请电子表格模板中添加一个不带小计的新选项卡，请使用以下变量模式：

{#children.length===0}{xxx}{/}

此条件表达式可确保在生成的电子表格选项卡中仅显示没有小计的行项目。{xxx} 表示要为每个行项目包含的特定数据字段。

用例：当您希望为分包商提供一个包含各个工作条目而没有复杂的小计计算的干净视图时，该选项卡特别有用。

如何将分组的 COR 选项卡添加到预算支付申请电子表格？

场景：您要在默认预算支付申请电子表格模板中创建新选项卡，该选项卡按 COR（变更单请求）对条目进行分组，而不显示各个成本条目详细信息。

例如，要将一个名为“按 COR 分组的可选详细信息”的新选项卡添加到预算支付申请电子表格模板，请使用以下变量模式：

{#payment.lineView.rootItems|groupItemsByXCO: 'COR'}{number}{/payment.lineView.rootItems|groupItemsByXCO: 'COR'}

此变量按付款行项目的关联 COR 对它们进行分组，并且仅显示 COR 编号，而不显示基础成本条目详细信息。

主要特点：

按 COR 对条目进行分组以便更好地进行组织
排除详细的成本条目信息，以使视图更加清晰
对高级预算跟踪和报告非常有用
帮助项目经理快速识别 COR 相关的成本

注意：生成的文档不包括成本条目详细信息，而是提供着重于 COR 组织的摘要视图。

变更单

自定义变更单文档（包括 RFQ、COR 和 OCO）的示例。

如何将注释部分的内容添加到变更单文档？

场景：您想要创建一个文档，使其包含在变更单的整个生命周期内添加的注释。

该示例将 {#rfq.comments} 显示为变量的打开标记，将 {/rfq.comments} 显示为关闭标记。其他相关变量必须介于这两个变量之间。

例如，包含以下注释部分的 RFQ：

显示多个注释条目的 RFQ 注释部分

使用以下方法将表添加到 Word 文档：

显示 RFQ 注释变量语法的 Word 文档模板

结果：

生成的文档输出，显示了格式化注释表

在文档模板中只需填写表的一行。软件将根据 Cost Management 中的数据构建包含指定信息的表。

如何按主合同 SOV 组织上游变更单？

按文档模板中主合同的价格一览表组织 COR 或 OCO。对于 COR，请使用以下模式：

按主合同价格一览表组织 COR 的变量模式

对于 OCO，将 rco 替换为 oco。

如何为成本条目添加工作条目小计和加价小计？

场景：您正在创建一个变更单文档（例如 OCO），并且希望其中有两个单独的表。一个用于带小计的常规成本项目，另一个用于加价成本项目。您还想要添加总变更单定价。如何做到这一点？下面是文档中所用变量的示例：

以单独的表显示工作条目和标记小计的 OCO 文档模板

按类型拆分变更单时，如何显示关联的 COR 和 OCO 编号？

若要显示关联的 COR 和 OCO 编号，请使用以下变量：

COR：{this.costItem.corNumber}
OCO：{this.costItem.ocoNumber}

显示 COR 和 OCO 编号变量的文档模板

结果：

生成的文档，在变更单表中显示了 COR 和 OCO 编号

合同

自定义合同文档和价格一览表显示的示例。

如何在合同 SOV 中仅显示计划条目的成本，而不显示小计金额？

场景：您想要创建一份合同，使其仅显示 SOV 子项的小计。您不希望父项对分包商可见。为此，请使用文档模板中的以下变量：

显示 SOV 子项的子变量语法的文档模板

此外，您也不希望将“单位成本”和“金额”值显示为 $0。您可以将 $0 替换为“Included”一词。如何做到这一点？丰富已使用的变量：

将 $0 值替换为“Included”的增强子变量模板

生成的合同中的结果将如下所示：

生成的合同，显示了用“Included”替换 $0 值的 SOV 子项

如何在合同文档模板中引用预算代码和名称？

若要在文档模板中引用预算代码和名称，请使用以下公式：

用于引用预算代码和名称的文档模板公式

例如，当合同的价格一览表如下所示时：

显示预算代码结构的合同价格一览表

显示的公式将生成以下结果：

生成的文档输出，显示了预算代码和名称格式

高级方法

这些示例演示了满足复杂文档自定义要求的复杂变量用法。

过滤和条件逻辑

用于在文档中显示或隐藏特定数据的高级过滤方法。

如何在生成文档时使用过滤器功能？

您可以在生成文档时使用过滤器功能。例如，若要仅显示风险应急费用条目，请使用 {#payment.columnView.rootItems | filter:"name":"Risk Contingency"} 变量：

显示风险应急费用条目过滤功能的文档模板

结果：

生成的文档，显示了过滤出的风险应急费用结果

成员还可以将含有所有已获批 SCO 的原始价格一览表分成两个单独的工作表。

若要生成仅包含原始 SOV 的工作表，请使用以下变量：

{#payment.lineView.rootItems | filter:"associationType":"SOV"} {/payment.lineView.rootItems | filter:"associationType":"SOV"}

若要生成仅包含已获批 SCO 的工作表，请使用以下变量：

{#payment.lineView.rootItems | filter:"number":"Change Orders"} {/payment.lineView.rootItems | filter:"number":"Change Orders"}

如何在成本支付申请电子表格中按 SCO 类型分隔变更单？

场景：您希望在成本支付申请电子表格中为不同的 SCO 类型（例如，“业主指令”和“分包商变更”）创建单独的工作表。

用法 1：遍历具有特定 SCO 类型的 SCO 关联支付条目

将 filter 函数与 scoType 结合使用，以遍历特定类型的变更单行条目。向电子表格中添加一个具有以下变量模式的新选项卡：

{#payment.lineView.rootItems| filter:"number":"Change Orders"}{#children | filter:"scoType":"Owner Directive"}
... // loop in each SCO associated payment item
{/children | filter:"scoType":"Owner Directive"}{/payment.lineView.rootItems| filter:"number":"Change Orders"}

这将首先过滤变更单根条目，然后遍历 SCO 类型与“业主指令”匹配的每个子条目。

用途 2：对具有特定类型的 SCO 关联支付条目的值求和

将 get 和 sumBy 函数与 scoType 结合使用，计算特定 SCO 类型的总数：

{payment.lineView.rootItems| filter:"number":"Change Orders" | get:"0.children" | filter:"scoType":"Owner Directive"|sumBy: "originalAmount"}

这将返回类型为“业主指令”的所有变更单条目的原始金额之和。

提示：将“业主指令”替换为项目中配置的任何 SCO 类型的名称。为要报告的每个 SCO 类型创建一个单独的选项卡。

如何按预算代码段（成本类型）过滤成本条目？

场景：您要创建一个变更单文档，按成本类型细分成本条目，并根据预算代码段显示材料、人工、设备和分包商条目的单独表。

将 filter 函数与 "budgetCode.original":"includes" 结合使用，以按预算代码过滤成本条目。例如，若要仅显示预算代码包含“SUB”（分包商）的条目：

{#rco.costItems | filter: "budgetCode.original":"includes":"SUB"}
{index} {name} {description} {submitted} {pcoNo}
{/rco.costItems | filter: "budgetCode.original":"includes":"SUB"}

若要为每种成本类型创建单独的部分，请创建具有不同过滤器值的多个表：

成本类型	过滤器值
材料	`"includes":"MAT"`
人工	`"includes":"LAB"`
设备	`"includes":"EQUIP"`
分包商	`"includes":"SUB"`

提示："includes" 过滤器与预算代码的任意部分匹配。“MAT”或“LAB”等过滤器值必须是项目的预算代码段设置中定义的主代码 - 不能按任意文本进行过滤。

如何在生成的文档中隐藏应急费用？

显示应急费用成本可见性设置的文档模板

如果管理员不希望在生成的文档中显示应急费用，可以使用以下过滤器：

过滤配置，用于在生成的文档中隐藏应急费用

结果：

生成的文档，其中已成功隐藏应急费用

数据聚合

用于在文档中计算总数和执行数据聚合的高级方法。

使用 sumBy 进行数据聚合

sumBy 函数有助于聚合数据集中的值。

示例 1：计算每个 PCO 的常规成本条目已批准值的小计。

{#oco.pco}{regular | sumBy:'approved'}{/oco.pco}

示例 2：计算每个 PCO 的所有成本条目已批准值的总计。

{#oco.pco}{this | getAll: "costItems" | sumBy: "approved"}{/oco.pco}

示例 3：计算特定加价（例如，加价 1 + 加价 2）的组合总计。

将 filter 函数与 sumBy 和 add 一起使用，为选定加价创建小计：

{(oco.markups | filter: "name":"Markup1" | sumBy: "approved") | add: (oco.markups | filter: "name": "Markup2" | sumBy: "approved")}

这将按名称过滤加价，对其批准的值求和，并将结果相加。使用此模式在文档模板中创建自定义小计行，例如“加价 1 和 2 小计”。

生成的文档，显示了加价 1、加价 2 以及组合的加价 1 和 2 小计行的加价小计计算

提示：

提示：当您需要显示计算总数，但该值不能以单个变量的形式直接获得时，sumBy 函数特别有用。