Documentation Center

Sample Custom CustomGetDocCatTweak Module

This is a simple example of a custom module, CustomGetDocTweak.pm, delivered to the encaps/adapters/custom directory.

This module inherits from CustomGetDocCat.pm which inherits from the base module, CustomGetDocDefault.pm. CustomGetDocCatTweak overrides 4 subroutines:
  • new - the constructor

    Shows how to capture and store the custom arguments that were added to the final fields of the custom args parameter passed to GetDocPerl( ). See how this is done in Contenta_home/encaps/adapters/testing/testExCat.pl

  • pcm_header_insert

    Writes to the document’s header, a file entity definition between the square brackets. This callback is called by pcm_make_header.

  • pcm_begin_tree

    Writes an SGML comment to the document file immediately before export of content begins.

  • pcm_end_tree

    Writes an SGML comment to the document file immediately after all export of content is completed.

Example: Below is the module’s contents (without the comments at start and end of the file)
package CustomGetDocCatTweak;
use PCMAPIMgr;
use strict;
use lib::PcmFS;
use lib::PcmEnvReg;
use custom::CustomGetDocCat;
use vars qw($VERSION @ISA @EXPORT @EXPORT_OK);
PCMAPIMgr::set_Warn(3); # turn on exception handling for Win32
require Exporter;
@ISA = qw(Exporter AutoLoader CustomGetDocCat);
# Items to export into callers namespace by default. Note: do not
# export names by default without a very good reason. Use EXPORT_OK
# instead. Do not simply export all your public functions/methods/
# constants.
@EXPORT = qw(
);
$VERSION = '0.01';
# Preloaded methods go here.
sub new {
my ($class) = shift; # name of this module "CustomGetDocTweak"
my $CmdO = shift;
my $pkg_chooser = shift; # again... "CustomGetDocTweak"
my $optional_ckout_dir = shift;
## This is a demonstration of how to
## capture and preserve custom arguments passed in
## the variable $CustomArgs, the fourth argument to
## $PCMCommandGetDocPerl(), see the Perl script
## adapters/testing/testExCat.pl, for an example of how $CustomArgs is
## passed. $CustomArgs starts out looking something like:
## "testExCat.pl|CustomGetDocCatTweak|D:\pub|custom arg1|custom_arg2|"
## (Note that you are not limited to two custom arguments.)
## This string is split on the pipe characters into a list.
## The first item in the list (the name of the program/script) is
## removed. The remaining list is passed as the second argument to this
## subroutine. The custom args in this subroutine start after $CmdO,
## which is assigned the PCMcommand object.
## The args that you want come after the "package chooser" and the
## "optional checkout directory". Then you can capture yours.
##
## Here is what you do to capture the 2 custom arguments:
my $cusArg1 = shift;
my $cusArg2= shift;
# instantiate the class
my $self = SUPER::new $class (
$CmdO,
$pkg_chooser,
$optional_ckout_dir,
@_
);
## Now store your custom arguments
## as data members of your object.
## Look at the subroutine, pcm_header_insert, to see how to access
##these data members.
$self{cus1} = $cusArg1;
$self{cus2} = $cusArg2;
return($self);
}
sub pcm_header_insert {
my $self = shift;
## Just a demo showing how to access my custom args. See "sub new" above.
my $demo = $self{cus1} . $self{cus2} . $self{cus3}. $self{cus4};
Customizing the Adapters 5-15
my $CompoundO = shift; # PCMtoolsAPI PCMdata object, to see data about
#the root Contenta object
my $fh_header=shift; # file handle to the header file DO NOT close
#it, please!
# Example of how to add something to header. All data written will
# go between "[" and "]>".
eval {
print $fh_header "<!ENTITY JustAtest SYSTEM \"testing123\" >\n";
};
if($@) {
die "Exception caught in ". __FILE__ . " at line " .
__LINE__ . "!\n" . $@;
}
}
sub pcm_begin_tree {
my $self = shift;
my $fh = shift;
my $CompoundO = shift;
# Any data written here will be prepended to file entity for root Node.
# NOTE: if customizer adds data here, she better strip it out in
# PutDoc or else it will be imported into the Contenta object.
#
my $rv;
eval {
print $fh "<!-- test by CustomGetDocDefault::pcm_begin_tree " . $CompoundOGetValueByLabel(0,"NAME") . " -->\n";
};
if($@) {
die "Exception caught in ". __FILE__ . " at line " .
__LINE__ . "!\n" . $@;
}
}
sub pcm_end_tree {
my $self = shift;
my $fh = shift;
my $CompoundO = shift;
# Any data written here will be appended to file entity for root Node.
# NOTE: if customizer adds data here, she better strip it out in PutDoc
# or else it will be imported into the Contenta object.
#
my $rv;
eval {
print $fh "<!-- test by CustomGetDocDefault::pcm_end_tree " .
$CompoundO->GetValueByLabel(0,"NAME") . " -->\n";
};
5-16 Customizing the Adapters
if($@) {
die "Exception caught in ". __FILE__ . " at line " .
__LINE__ . "!\n" . $@;
}
}
# If you add "private" methods, start their names with "_" and don't use
# the "pcm" prefix. That way, it will be easier to maintain the code
# (hopefully).
1;