Control a patch file setting

When you use patch files to change the SitecoreAI configuration, you must identify the node you want to add or update. By default, SitecoreAI updates existing nodes with the patched attributes, but you can use significant attributes to force SitecoreAI to add new nodes instead.

This topic explains how to:

Specify a node
Use a significant attribute
Add a significant attribute definition

Specify a node

You must specify which node you want to update.

To specify the node:

Specify the element name and its place in the XML structure in the Sitecore.config file.

For example, the AliasActive setting is part of the <settings> element node, which is part of the <sitecore> element node. To change the value of the AliasActive setting to false you must include these element nodes in the patch file:

xml

<sitecore>
 <settings>
   <setting name="AliasActive">
     <patch:attribute name="value">False</patch:attribute>
   </setting>
 </settings>
</sitecore>

Use a significant attribute

When SitecoreAI processes attributes from patch files, it looks for existing nodes in the Sitecore.config file that fit the attributes in the patch file node. If it finds one, by default, it merges the attributes in the patch file with the existing node.

For example, you can have two patch files that both add a script file to the <clientscripts> node in the Sitecore.config file:

xml

<configuration xmlns:patch="http://www.sitecore.net/xmlconfig/">
  <sitecore>
 <clientscripts>
 <template data-markdown-script src="script-1.js" language="javascript" />
 </clientscripts>
  </sitecore>
</configuration>

xml

<configuration xmlns:patch="http://www.sitecore.net/xmlconfig/">
  <sitecore>
 <clientscripts>
 <template data-markdown-script src="script-2.js" language="javascript" att1="test" />
 </clientscripts>
  </sitecore>
</configuration>

When SitecoreAI processes the first patch file, it adds the <template data-markdown-script src="script-1.js"> element. When it processes the second patch file, it merges the new information with the first <template data-markdown-script> element, updating the src attribute and adding the att1 attribute. The final result is:

xml

<sitecore>
 <clientscripts>
   <template data-markdown-script src="script-2.js" language="javascript" att1="test" patch:source="Add-script-2.config"
/>
 </clientscripts>
</sitecore>

If you want to add the node from the second patch file as a new node, you can add a significant attribute to the node definition. SitecoreAI never merges significant attributes, so if the second script element includes a significant attribute with a unique value, SitecoreAI adds it as a new element. For example, you can add a desc attribute to the script element in the second patch file:

xml

<configuration xmlns:patch="http://www.sitecore.net/xmlconfig/">
  <sitecore>
 <clientscripts>
 <template data-markdown-script src="script-2.js" language="javascript" att1="test" desc="new script" />
 </clientscripts>
  </sitecore>
</configuration>

The result after processing both patch files is now:

xml

<sitecore>
    <clientscripts>
        <template data-markdown-script src="script-1.js" language="javascript" patch:source="Add-script-1.config" />
        <template data-markdown-script desc="new script" src="script-2.js"
            language="javascript" att1="test" patch:source="Add-script-2.config" />
    </clientscripts>
</sitecore>

You can use the following significant attributes in this way:

ancestor
assembly
builderType
category
channelId
comment
contains
creationType
desc
description
displayName
extensions
facetKey
fieldId
fieldName
fieldType
fieldTypeName
file
find
folder
groupName
hint
hostname
id
implementationType
innerText
interface
key
messageDataType
messageItemBaseType
method
name
namespace
networkName
originalKey
path
postingConfiguration
prefix
providerName
querystring
ref
region
serviceType
sitecoreKey
statusCode
tagName
templateId
trafficType
trigger
type
typeConverter
typeName
uid
urlReferrerHost
value
verb
viewName
with
xmlControl
xmlns

To change the value of a significant attribute in an existing node:

Use the patch

syntax:

xml

<sitecore>
 <clientscript >
   <template data-markdown-script src="script-1.js" att1="test">
     <patch:attribute name="desc">new description</patch:attribute>
   </template>
 </clientscript>
</sitecore>

Add a significant attribute definition

If you cannot use any of the default significant attributes, you can define your own.

To define your own significant attribute:

Add the significant attribute to the Sitecore.config file, within the <sitecore> element node.

For example, the following adds a significant attribute called my-own-attribute:

xml

<patch>
  <significantAttributes>
  <add name="my-own-attribute"/>
  </significantAttributes>
</patch>

Important

SitecoreAI processes its list of significant attributes before it processes the patch files. You must therefore add new significant attributes directly to the Sitecore.config file and you cannot add them through a patch file. Only use this method if you absolutely cannot use any of the predefined attributes.

If you have suggestions for improving this article, let us know!