Documentation Center

Medium

PutDoc adapter callbacks that have been determined by SDL Contenta Engineering to be medium in usefulness.

pcm_examine_header
Note: In SDL Contenta 3.1C.1, when customizing the (Arbortext) Epic Cat tool, do not use this callback. Instead, examine the header using the callback, pcm_preparse_cat_file. This gives you access to the entire concatenated document after it has been saved by the editor.
Arguments passed to this callback are:
  • $header_changed - set to true|false (1|0).

    True if time stamp of header file changed.

  • $header_path - full pathname to the header file.

    If this is data exported from a leaf node, then the header and the content are all in this one file.

Use this subroutine to read the header file to extract user added file entity definitions.

pcm_get_next_rcd
This callback reads the data from the modified file entities and returns the data for import.

Override this method to filter out unwanted data, convert data, and extract data that needs to be stored as property data or attribute data.

This method is overridden by CustomPutDocEpic.pm, CustomPutDocXMetaL.pm and CustomPutDocFrame.pm.

If you are customizing one of the delivered Editors, copy the implementation from one of these delivered custom modules into your new custom module and modify it, carefully—read the comments in the file.

Arguments passed to this callback are:
  • $fh - the file handle to the file entity being read and imported.
  • $record_cnt - Caution: This is misnamed. It should be a boolean $isFirstRecord. Some of the code needs to know if the record being read is the first one read from the file entity.

    This argument does not give an accurate record count beyond the first record.

  • $CompoundO - a reference to the currently selected SDL Contenta object into which the data read from the file entity is being written.

    One method on this object is: GetLabelByValue( )

    Example:
    $CompoundO->GetLabelByValue(0,"NAME")

    returns the name of the SDL Contenta object represented by $CompoundO.

    Labels other than NAME include DATABASE, ID_PATH, NAME_PATH, DESKTOP, TYPE, CLASS, OBJECT_ID, CONFIGURATION_ID, STATUS, PROJECT_LOCK, OWNER_LOCK, EDIT_LOCK, LOCK_TYPE, LOCK_SESSION_ID, OBJECT_TYPE, HAS_NOTES, REV, IS_CURRENT

    If you call property data or attribute data methods on the command object, $self->{CmdO}, it is this SDL Contenta object represented by $CompoundO, that is affected.

  • $entity_ref - The file entity reference used in the parent file, which refers to this file entity (that is, the file entity being read).
  • $LeafNode - Boolean that indicates whether this is a leaf node or branch node edit session.

    If true, there is only one file containing content data and it is not a file entity.

pcm_reorder_slices

In this callback, you can see the order of the slices and change the order if desired, before the compound object is closed but after all the slices have been created.

With the reference to the PCMcompound object, you can iterate through its PCMslice objects, calling methods on the slice objects returned in order to identify those slices whose position may need to change. Refer to pcm_should_skip_child_slice for a partial list of PCMslice methods.

Example: First slice is made last
My $CompoundO = shift;
my $SliceIds;
$SliceO = $CompoundO->SliceFirst();
my $FirstSliceId = $SliceO->Id;
while($SliceO = $Compound->SliceNext()) {
$SliceIds .= $SliceO->Id . " ";
}
$SliceIds .= $FirstSliceId;
$Compound->SliceOrderSet($SliceIds);
pcm_set_new_obj_prop
Arguments passed to this callback are:
  • $CmdO - a reference to the PCMcommand object. You can also use: $self->{CmdO}
  • $idpath - SDL Contenta idpath of the newly created object. This method is only called by SDL Contenta version 3.1 of the EpicEdit tool, (the EpicCat versions).
  • $entity - The name of the entity reference. This looks like, for example: "xyent-nw001" to "xyent-nw999"
  • $filename - The filename of the newly created file entity which contains the user's newly entered document data.
This method sets the Property Data field named Document Type with the data read from the new object's parent's Document Type field.

The base implementation is called using SUPER so that the Document Type is set in the base implementation.

pcm_what_new_child_type

For the Arbortext tool, EpicCat version only; this callback is only invoked for object-mapped elements inserted by the editor. The type is added by the Arbortext custom code to the element's processing instructions (PIs) that describes how the object should be created.

The Arbortext custom code refers to four files developed by SDL, written in ArborText Command Language (ACL). These are not part of the adapters. They are delivered in the SDL Contenta/encaps/EpicEdit directory with the filename extension .cmd. The four files are sourced at the end of an ArborText delivered file, Arbortext Home/lib/init.acl.

Example from a PLAY document saved after an Arbortext user inserted a new SPEECH, an object-mapped element. A PI was automatically inserted after the SPEECH start tag. Note the value of objecttype:
<SPEECH><?xy_object id="" name="speech-example-895" 
objecttype="DataModule" modified="yes" access="write"?>

The Arbortext custom code uses the di (Dynamic Import) map to determine the correct type for the object.

The implementation of this callback in CustomPutDocEpicCat.pm returns the object type assigned to the PI's objecttype attribute. The PI in question was inserted after the start tag of the element that is mapped to the soon-to-be-created object.

Arguments passed to this callback are:
  • $CompoundO - A reference to the currently selected Contenta CompoundAscii based object which will be the parent of the child object about to be created.
  • $parentElement - The element that maps to the object that is the parent object of the child object to be created. The new child object is created when this callback returns.
  • $filename - The name of the file entity that contains the newly authored data.
  • $type - reserved; or ""
  • $Mapped - A reference. If set to 0 then:
    • the type for this object is not determined by the type the callback returns
    • the type is determined using the map created by Dynamic Import and stored in AppData

    Always set $$Mapped=1. If for some (unusual) reason you have to set type to a value other than the type assigned to the PI attribute objecttype, then override this callback, return the type you determine is correct, but make sure you first set $$Mapped=1;Refer to the callback override in CustomPutDocEpicCat.pm.

The base implementation found in CustomPutDocDefault.pm returns the type CompoundDoc. This default implementation is not used by any tools. The callback is overridden in CustomPutDocEpicCat.pm.

pcm_preparse_cat_file

Use this callback to parse the concatenated document before any import commences. If customizing the Epic Cat version, this callback can be used to gain access to the concatenated document before it is busted.

To abort the import process so that the user can make corrections in the document and try again, throw an exception using the die function. For example:
die "You cannot check in the document until the attribute 'cost' 
on element 'car' has a valid dollar amount greater than $100.00."