Protecting and unprotecting Documents
It is possible via the optional attribute protectionInstruction at the element <document> to protect and unprotect a whole document in the same way as you are protecting and unprotecting properties. The possible values for protectionInstruction are:
| Value | Description |
|---|---|
none | If a document with the given external id already exists in the repository and if this document is protected, the import of the document cannot be executed and an import error is thrown. Skipping the attribute protectionInstruction has the same meaning as using the value none! |
unprotect | If a document with the given external id already exists in the repository and if this document is protected, the protection will be removed and then the document's XML will be imported. After the import of the document, the protection will not be (re-)established. |
protect | If a document with the given external id already exists in the repository and if this document is not protected (or if the document is newly created), the document's XML will be imported and then the document will be protected. If a document with the given external id already exists in the repository and if this document is protected, the import of the document cannot be executed and an import error is thrown. |
forceProtect | The document's XML will be imported in any case and then the document will be protected. |
reprotect | The document's XML will be imported in any case. If a document with the given external id had already existed in the repository and if this document was protected, the protection will be re-established. In any other case (document was not protected in the repository / document was newly created) the document will not be protected. |
The follwing XML snippet shows the use case of forcing the imported document to be protected (no matter if it was protected before or not):
<?xml version="1.0" encoding="UTF-8"?>
<document nodeType="sophora-content:story" protectionInstruction="forceProtect" xmlns="http://www.sophoracms.com/import/4.2">
<properties>
[...]
</properties>
<childNodes>
[...]
</childNodes>
<resourceList />
<fields>
[...]
</fields>
<instructions>
[...]
</instructions>
</document>
You can only protect documents of nodetypes which implement the mixin
sophora-mix:protectable.Protecting and unprotecting Childnodes
There are two ways to protect/unprotect childnodes:
- On document level you can protect/unprotect childnodes via the name of the childnode.
- On every level of the component tree you can protect/unprotect component boxes via the childnode id of the box.
Protecting and unprotecting Childnodes on Document Level
To protect/unprotect childnodes on document level via the name of the childnode you have to provide an element <childNode> inside an element <updateBehaviour> in the way it is described in chapter Managing the Update Behaviour of Documents. With the optional attribute protectionInstruction at the element <childNode> you can provide the wanted protection behaviour. Analogous to protecting/unprotecting properties (see chapter Protecting and unprotecting Properties) and protecting/unprotecting the whole document (see chapter Protecting and unprotecting Documents) there are five possible values for the attribute protectionInstruction:
| Value | Description |
|---|---|
none | If the corresponding childnode name in the repository is protected, the existing childnodes with the given name are not modified or removed. Childnodes with the given name in the import XML are ignored. Skipping the attribute protectionInstruction has the same meaning as using the value none! |
unprotect | If the corresponding childnode name in the repository is protected, the protection will be removed and then the corresponding childnodes from the XML will be set (regarding the attribute behaviour which can be set to merge or delete - see Managing the Update Behaviour of Documents). After setting the childnodes, the protection of the childnode name will not be (re-)established. |
protect | If the corresponding childnode name in the repository is not protected (or if the document is newly created), the corresponding childnodes from the XML will be set and after setting them, the childnode name will be protected. If the corresponding childnode name in the repository is protected, the corresponding childnodes from the XML will be ignored! |
forceProtect | If the corresponding childnode name in the repository is protected, the protection will be forced to be removed and then the corresponding childnodes from the XML will be set (regarding the attribute behaviour which can be set to merge or delete - see Managing the Update Behaviour of Documents). After setting the childnodes, the childnode name will be protected regardless of whether the childnode name was protected before or not. |
reprotect | If the corresponding childnode name in the repository is protected, the protection will be removed and then the corresponding childnodes from the XML will be set (regarding the attribute behaviour which can be set to merge or delete - see Managing the Update Behaviour of Documents). After setting the childnodes, the childnode name will only be protected if it was protected before. (Therefore the childnode name will never be protected if the document is newly created.) |
The following example shows different protection use cases:
<document nodeType="sophora-content-nt:story" externalID="import_000001" xmlns="http://www.sophoracms.com/import/4.2">
<properties>
[...]
</properties>
<childNodes>
<updateBehaviour>
<!-- Remove the copytext in the repository (if it exists) and protect it after setting it new. -->
<childNode name="sophora-content:copytext" behaviour="delete" protectionInstruction="forceProtect" />
<!-- Merge the teaser images in the repository (if existing) with the teaser images in the XML and protect them after merging.
(But: If the teaser images are already protected in the repository, the existing teaser images are not touched and the
teaser images in the XML are ignored!) -->
<childNode name="sophora-content:teaserImage" behaviour="merge" protectionInstruction="protect" />
<!-- Remove the protection of the story teasers in the repository (if it exists) and set the story teasers from the XML. -->
<childNode name="sophora-content:teaser" behaviour="delete" protectionInstruction="unprotect" />
<!-- Remove the protection of the dynamic table in the repository (if it exists), remove all existing rows of the dynamic table
and afterwards set the rows of the dynamic table from the XML. Protect the dynamic table if it was protected before. -->
<childNode name="sophora-content:dynamictableRow" behaviour="delete" protectionInstruction="reprotect" />
</updateBehaviour>
<childNode nodeType="sophora-extension-nt:copytext" name="sophora-content:copytext">
[...]
</childNode>
<childNode nodeType="sophora-content-nt:imageRef" name="sophora-content:teaserImage">
[...]
</childNode>
<childNode nodeType="sophora-content-nt:storyRef" name="sophora-content:teaser">
[...]
</childNode>
<childNode nodeType="sophora-content-nt:dynamictableRow" name="sophora-content:dynamictableRow">
[...]
</childNode>
[...]
</childNodes>
[...]
</document>
Notice that using the attribute
protectionInstruction at an element <updateBehaviour> has only effect for childnodes on document level!Protecting and unprotecting Component boxes via Childnode Id
To protect/unprotect a component box in the component tree you have to provide the attribute protectionInstruction at the corresponding element <childNode>. This childnode must have a property sophora:childNodeId to match an existing box in the repository. If you don't provide a childnode id while using the protectionInstruction protect or forceProtect, the child node id will be created during the import process. Analogous to protecting/unprotecting childnodes via childnode name (see previous chapter), properties (see chapter Protecting and unprotecting Properties) and protecting/unprotecting the whole document (see chapter Protecting and unprotecting Documents) there are five possible values for the attribute protectionInstruction:
| Value | Description |
|---|---|
none | If the corresponding box in the repository is protected, this existing box with the given childnode id is not touched. The box in the XML is ignored. Skipping the attribute protectionInstruction has the same meaning as using the value none! |
unprotect | If the corresponding box in the repository (identified via childnode id) is protected, the protection will be removed and then the box from the XML will be set (regarding the attribute behaviour of a possible childnode behaviour for this childnode name, which can be set to merge or delete - see Managing the Update Behaviour of Documents). After setting the box, the protection of the box will not be (re-)established. |
protect | If the corresponding box in the repository (identified via childnode id) is not protected (or if the document is newly created), the box from the XML will be set and after setting it, the box will be protected. If the corresponding box in the repository (identified via childnode id) is protected, the box from the XML will be ignored! |
forceProtect | If the corresponding box in the repository (identified via childnode id) is protected, the protection will be forced to be removed and then the corresponding box from the XML will be set (regarding the attribute behaviour of a possible childnode behaviour for this childnode name, which can be set to merge or delete - see Managing the Update Behaviour of Documents). After setting the box, the box will be protected regardless of whether the box was protected before or not. |
reprotect | If the corresponding box in the repository (identified via childnode id) is protected, the protection will be removed and then the corresponding box from the XML will be set (regarding the attribute behaviour of a possible childnode behaviour for this childnode name, which can be set to merge or delete - see Managing the Update Behaviour of Documents). After setting the box, the box will only be protected if it was protected before. (Therefore the box will never be protected if the document is newly created.) |
The following example shows different protection use cases:
<document nodeType="sophora-content-nt:story" externalID="import_000001" xmlns="http://www.sophoracms.com/import/4.2">
<properties>
[...]
</properties>
<childNodes>
<!-- Remove the existing box with childnode id "-5896417165016167967" from repository, set this box from XML
and protect it after setting it. -->
<childNode nodeType="sophora-content-nt:storylist" name="sophora-content:box" protectionInstruction="forceProtect">
<properties>
<property name="sophora:childNodeId">
<value>-5896417165016167967</value>
</property>
<property name="sophora-extension:title">
<value>Box title</value>
</property>
</properties>
<childNodes>
<childNode nodeType="sophora-content-nt:storyref" name="sophora-extension:teaser">
<properties>
<property name="sophora:reference">
<value>external_id_000001</value>
</property>
</properties>
<childNodes />
<resourceList />
</childNode>
</childNodes>
<resourceList />
</childNode>
<!-- Create this box new (no childnode id is set!) and protect it. -->
<childNode nodeType="sophora-content-nt:storylist" name="sophora-content:box" protectionInstruction="protect">
<properties>
<property name="sophora-extension:title">
<value>Box title</value>
</property>
</properties>
<childNodes>
<childNode nodeType="sophora-content-nt:storyref" name="sophora-extension:teaser">
<properties>
<property name="sophora:reference">
<value>external_id_000002</value>
</property>
</properties>
<childNodes />
<resourceList />
</childNode>
</childNodes>
<resourceList />
</childNode>
<!-- Remove the existing box with childnode id "-5896417165016167968" from repository, set this box from XML
and protect it after setting it. (But: If the box exists in the repository and is already protected
in the repository, the existing box is not touched and the box in the XML is ignored!) -->
<childNode nodeType="sophora-content-nt:storylist" name="sophora-content:box" protectionInstruction="protect">
<properties>
<property name="sophora:childNodeId">
<value>-5896417165016167968</value>
</property>
<property name="sophora-extension:title">
<value>Box title</value>
</property>
</properties>
<childNodes>
<childNode nodeType="sophora-content-nt:storyref" name="sophora-extension:teaser">
<properties>
<property name="sophora:reference">
<value>external_id_000003</value>
</property>
</properties>
<childNodes />
<resourceList />
</childNode>
</childNodes>
<resourceList />
</childNode>
</childNodes>
</document>
Technically it is possible to use the attribute
protectionInstruction at any childnode where the property sophora:childNodeId can be set. But this makes little sense because the deskclient supports only the protection of boxes in the component tree - the protection of particular components is not possible.