High
GetDoc adapter callbacks that have been determined by SDL Contenta Engineering to be high in usefulness.
- pcm_begin_node
-
The trees are composed of nodes. Every SDL Contenta object in the tree is a node. This callback is invoked only once for each node, the first time the node is encountered by the tree-walk process.
A file handle, created in PcmGetDocEnt or PcmGetDocCat, is passed to this callback and assigned to $fh. In the case of PcmGetDocEnt, the file handle refers to a file entity created for this node. If it is not the top node of the tree, the file entity is always empty at the start of this callback.
Another callback, pcm_begin_tree, is invoked on the top level node before pcm_begin_node is invoked. You can write data to the file entity for the top node from the pcm_begin_tree callback as well. When these two callbacks are invoked from PcmGetDocCat, the file handle passed always refers to the same file since the objective for PcmGetDocCat is to write all data being exported to a single file.
There is an example in the callback comments that demonstrates how to write data to the file.
Return Value: None
- pcm_begin_tree
-
This method is invoked only once at the very start of the tree walking process before any data is exported to the file system.
Refer to pcm_begin_node
Return Value: None
- pcm_end_node
-
This method (or callback) is similar to the pcm_begin_node except that it is invoked when the object is last encountered by the tree-walk process, typically after the end tag has been exported.
Use to write data that is to follow the end tag of the data store in the given SDL Contenta object.
Return Value: None
- pcm_end_tree
-
This callback is invoked after all data is exported from the tree and after pcm_end_node is called on the top level node. It gives you a last chance to write data to the file system following the exported data and following any data written by pcm_end_node which is called on the top level node.
It can also be used to do clean-up work.
Return Value: None
- pcm_should_skip_child_slice
-
This method is passed a reference to the current child slice object, $SliceO. If this method returns true, the child slice is skipped and the object to which it points is skipped along with its descendents.
With PcmGetDocEnt, a place holder file entity reference is inserted into the parent file entity as if this slice were not being skipped. (This is not the case with PcmGetDocCat.) An empty file entity with a comment is created.
While you can modify this behavior by overriding other callbacks, you should do so with caution. The other callbacks you should read about and be familiar with are pcm_should_skip_node, pcm_write_empty_entity, and pcm_write_entity_definition.
Without the place holder entity reference in the parent file entity, child slices that are skipped (not exported) shift to the start of the slice list when PutDocPerl( ) is invoked for import of the data—unless you also modify this behavior in a custom PutDoc module.
If you are not locking the data, as in the case of a publish tool, this is not a problem since you will not be importing. When locking data (as in the case of the edit tools when you want to lock data in any or all objects in the selected tree) this is important.
Import of data from the file entity into the object from which it was exported occurs if the file entity has been modified during the editing process. If, for example, a CompoundAscii-based object contains SDL Contenta graphic objects that you skipped during export, the graphics all appear at the start of object list when viewed in SDL Contenta Explorer (unless you do something to reorder them in a PutDoc custom module).
- pcm_should_skip_node
-
This method is passed a reference to the current compound object. Export of this node has not started; however, a file entity has been created and opened.
You can call methods on $CompoundO such as GetValueByLabel( ) or use PCMcommand methods to check property data or attribute data on this currently selected object.
If you return true (1), pcm_write_empty_entity( ) is invoked. That callback writes a comment into the file entity and sets the file entity's permissions to read only, which indicates that this is dummy data and is not going to be imported; it serves as a place holder. The parent file entity will contain a file entity reference pointing to this empty file entity. The user viewing the data in an editor, for example, sees the file entity reference and the comment contained in the empty file entity.
The advantage of this is that the data more accurately reflects the structure in Contenta. The comment warns the user exactly what the empty file entity represents in Contenta.
If the user moves the file entity reference or deletes it, it is reflected in Contenta on import (PutDoc). Otherwise, slice order and object order in Contenta are unaffected by using this callback.
Return Value: If you want to skip exporting this node (and its descendents), return true, 1, else return false, 0. - pcm_write_empty_entity
-
This method is called if pcm_should_skip_node( ) returns true (1). (Refer to pcm_should_skip_node.)
In CustomGetDocDefault, this callback writes a comment to the empty file entity. This file entity is acting as a place holder for a node that was skipped during export (GetDoc). A reference to a PCMdata object is passed as an argument and assigned to $DataO. Its data describes the Contenta node that is being skipped.
Method calls to the command object, $self->{CmdO}, to read property data or attribute data return information specific to the object being skipped.
Also passed is the file handle, $fh, to the empty file entity.
- pcm_write_slice
-
This method (or callback) writes the slice data to the file entity (or the file itself if a leaf node is being exported) pointed to by the file handle passed to this callback, $fh. The data is passed in a reference variable, $SliceContent_ref. You can use this callback to filter, modify, etc. the data that is being exported. For example, whenever you publish for a particular purpose, if you need to convert all occurrences of the string "<rare/>" to "(rare)", you could override the method as shown in the pcm_write_slice example below.
Example: pcm_write_slice
sub pcm_write_slice { my $self = shift; my $fh = shift; my $SliceContent_ref = shift; my $SliceO = shift; my $CompoundO = shift; my $EntName = shift; my $RootEntityName = shift; my $top_element_start = shift; my $LeafNode=shift; $$SliceContent_ref =~ s|<rare/>|(rare)|gsi; print $fh $$SliceContent_ref; }Description:$SliceO A reference to the current slice object $CompoundO A reference to the current compound object $EntName The name of the file pointed to by $fh $RootEntityName When $EntName matches $RootEntityName, you are focused on the topmost file entity. $top_element_start Start tag of the top-level element for this document. For example: <act number="2" duration="25 minutes">
Property data and attribute data methods on the command object, $self->{CmdO}, operate on the currently selected object in Contenta, which is the one whose data is being passed to this callback in $SliceContent_ref.