Example of customizing the Bust by overriding pcm_normalize

Example for a defined, specific situation of a customization to override pcm_normalize.

About this task

Assume that you are using FrameMaker and you discover that it inserts a special PI (processing instruction) if the user collapses an element in the structured view and then saves. You do not want to filter out PIs on import because you want them preserved so that the document has the same appearance the next time the user edits it. However, if the user changes the view of the document but doesn’t actually edit the OME affected by the view, the chunk should not be imported.

You want to prevent these false positives by overriding pcm_normalize and adding to its functionality. Ignore the warnings in the module telling you not to customize the module.

Procedure

  1. Copy CustomBustFrameCat.pm to CustomBustFrameCatZARC.pm
  2. Open CustomBustFrameCatZARC.pm in a text editor and modify so it reads as follows.
    ################################################################
    # File Name : CustomBustFrameCatZARC.pm                                #
    # Description : This module implements an override of pcm_normalize to #
    # prevent false positives caused by a Frame PI                         #
    #                                                                      #
    ########################################################################
    package CustomBustFrameCatZARC;
    use strict;
    use vars qw(@ISA);
    use PCMAPIMgr;
    PCMAPIMgr::set_Warn(3); # turn on exception handling for Win32
    use custom::CustomBustFrameCat;
    @ISA=qw(CustomBustFrameCat);
    # overrides start
    sub pcm_normalize {
    my $self = shift;
    my $string = shift; # this is passed as a reference
    # First, call the parent's version of this subroutine so that it can make its changes.
    # If in the next release code is added or fixed in the parent's version of this callback
    # this verion will inherit the new behavior.
    $self->SUPER::pcm_normalize($string);
    # Remove <?collapse?> which means make this element collapse in document view and
    # causes a false positive when compared to original data.
    # NOTE: this is a fictious problem. FrameMaker doesn't actually do this.
    $$string =~ s/<\?FM collapse\?>//g; # strip Frame's (fictitious) structural collapse markers
    }
    # overrides end
    1;
    # end of file
  3. Now customize the PutDoc callback pcm_get_custom_bind_module. If you have a custom PutDoc module then add the pcm_get_custom_bust_module routine you see in the example below to your module.

    If you have not created a custom module to override other PutDoc callbacks found in CustomPutDocDefault.pm, CustomPutDocCatDefault.pm or CustomPutDocFrameCat.pm then enter the following at a command prompt:

    copy CustomPutDocFrameCat.pm CustomPutDocFrameCatZARC.pm

  4. Open CustomPutDocFrameCatZARC.pm in a text editor and modify so it reads as follows.
    ###########################################################################
    # Script Name : CustomPutDocFrameCatZARC.pm
    # Description : Adds custom overrides to FrameEdit
    # PutDoc adapter for ZARC Inc.
    ###########################################################################
    package CustomPutDocFrameCatZARC;
    use strict;
    use custom::CustomPutDocFrameCat;
    use vars qw(@ISA);
    use PCMAPIMgr;
    PCMAPIMgr::set_Warn(3); # turn on exception handling for Win32
    @ISA = qw(CustomPutDocFrameCat);
    # overrides start
    sub pcm_get_custom_bust_module {
    my $self = shift;
    # this override is customized because ZARC needs to
    # customize pcm_normaize in Bust
    #
    return("CustomBustFrameCatZARC");
    }
    # overrides end
    1;
    # end of file
    
  5. Specify the Document Types that are to use CustomPutDocFrameCatZARC.pm in AppData.
    Be certain that the case in the Value Data column matches the case of the package name in the perl module, not the case of the filename for that module. You can keep the package name and the file name the same (but this does not always happen).

    For example: Updating the AppData for a custom PutDoc adapter, CustomPutDocFrameCatZARC

    UserKeyValue NameValue Data
    {Global}\Document Types\Book\FrameCheckinCat.plPutDocCustomPutDocFrameCatZARC
    {Global}\Document Types\Book\FrameEditCat.plPutDocCustomPutDocFrameCatZARC