Sample Page - Record Highlighting - Text Emphasis - Pedigree

This sample demonstrates record-level highlighting where you supply a value that Pedserve uses to apply various text effects to the whole record.

To get the effect shown here you need to reimplement the hookHighlighting_GetForRecord hook. It shows how to set the text emphasis depending on the date of birth field ('A_DOB'). It tests the birth year, and if it is in the 1970's, returns a text emphasis code of $::c_EMPH_ITALIC to italicise the text; hardly a real world example but it shows the basics of getting the field data and using it to generate a highlight.

The following table lists the available text effects. These may be combined using the bit-wise or operator ('|').

Effect Value
$::c_EMPH_BOLD Add bold emphasis
$::c_EMPH_ITALIC Add italic emphasis
$::c_EMPH_CODE Add 'code' emphasis (typically a fixed-width font)
$::c_EMPH_BIG Make the text a bit bigger
$::c_EMPH_ERROR Apply 'error' emphasis - typically formatting in red.
$::c_EMPH_WARNING Apply 'warning' emphasis - typically formatting in red.
$::c_EMPH_SINGLEQUOTED Enclose the text in single quotes
$::c_EMPH_DOUBLEQUOTED Enclose the text in double quotes

(You can also redefine the actual visual effect of most of these, via CSS. E.g. the $::c_EMPH_BOLD code is applied using a <span> tag with a class attribute of pds-emph-bold-span. So to redefine what 'bold' means, all you need to do is edit the stylesheet and change the pds-emph-bold-span entry).

To see how the same code can highlight a search results page, click here.

To see how you can use a similar highlighting method at the field level, rather than the record level, click here.

Show/Hide Sample Code

# Hook function to apply highlighting for a record - storing
# the required highlighting decorations in a supplied map.
#
# Arg 1 - table suffix
# Arg 2 - reference to map holding decoded highlight definition
# Arg 3 - context
# Arg 4 - reference to map into which highlight effects are to be stored
# Arg 5 - reference to map of field values
# Arg 6 - primary key
# Arg 7 - field name prefix
# Arg 8 - reference to map into which highlighting state can be
#         stored for the current panel
# OPTIONAL
# Arg 9 - reference to map for future additional arguments; possibly undefined
sub hookHighlighting_GetForRecord {
   my ($strTableSuffix, $rmHighlightingDef, $strContext, $rmEffects,
       $rmFieldValues, $nPrimaryKey, $strFldPrefix, $rmState, $rmArgsEx) = @_;
   
   # You probably dont want to interfere with the correct working of
   # pedserve's internally defined highlighting methods.
   # So what you should do is make your highlighting definition
   # identifiable - by including terms that you can test
   # for here. Then you can defer to the default implementation when
   # necessary.
   
   my $fUseStdImpl = 1;

   # Example that checks for the term 'myhighlighting=yes' in
   # the highlighting definition, and if present handles it here.
   # To use this, you would have to define a highlighting during
   # the script startup with a call to &pdsSetHighlightingDef() e.g. 
   #   &pdsSetHighlightingDef('A_myhighlighting',
   #      'label=Highlight DOB;myhighlighting=yes;');
   # Note also the check against $strTableSuffix to ensure this is
   # only used with animal records, and the check that this is
   # not a pedserve-private definition:
   if (!defined($$rmHighlightingDef{'pdsprivate'}) &&
       $strTableSuffix eq 'A' && 
       defined($$rmHighlightingDef{'myhighlighting'}) &&
       $$rmHighlightingDef{'myhighlighting'} eq 'yes') {
      # Dont defer to standard implementation below:
      $fUseStdImpl = 0;

      # This demonstrates record-level highlighting by adding
      # text emphasis to the rendered output for a record.

      # Extract the value of the date of birth field from the 
      # field results map:
      my $date = $$rmFieldValues{$nPrimaryKey.':'.$strFldPrefix.'A_DOB'};
      # If the DOB is valid and in the 1970's:
      if (defined($date) && $date =~ m/^197.*/) {
         # ... then we will emphasis the whole 
         # record with italics:
         $$rmEffects{'emphasis_code'} = $::c_EMPH_ITALIC;
         # Set up an entry for the highlighting legend:
         $$rmEffects{'emphasis_legend'} = 
             $::g_q->escapeHTML("Born in the 1970's");
      }
   }

   # If the above code has not handled this highlighting definition itself,
   # defer to the standard implementation:
   if ($fUseStdImpl) {
      &pdsHookStdImpl_Highlighting_GetForRecord(
         $strTableSuffix, $rmHighlightingDef, $strContext, $rmEffects,
         $rmFieldValues, $nPrimaryKey, $strFldPrefix, $rmState, $rmArgsEx);
   }
}

This custom highlighting method uses the date of birth field ('A_DOB'). When Pedserve fetches data from the database, it does not automatically fetch all the fields - it only fetches those it needs. For this reason, when your custom highlighting method is selected, you need to take steps to ensure that Pedserve will pull any fields you need. You do this by reimplementing the hookHighlighting_GetExtraFlds hook:

Show/Hide Sample Code

# Hook function to return extra fields that are required by a given
# highlighting method.
#
# Arg 1 - table suffix
# Arg 2 - reference to map holding decoded highlight definition
# Arg 3 - context
# Arg 4 - field name prefix
# OPTIONAL
# Arg 4 - reference to map for future additional arguments; possibly undefined
sub hookHighlighting_GetExtraFlds {
   my ($strTableSuffix, $rmHighlightingDef, 
       $strContext, $strFldPrefix, $rmArgsEx) = @_;
   
   # You probably dont want to interfere with the correct working
   # of pedserve's internally defined highlighting methods.
   # So what you should do is make your highlighting definition
   # identifiable - by including terms that you can test
   # for here. Then you can defer to the default implementation
   # when necessary.
   
   my $fUseStdImpl = 1;
   my $strReturn = '';

   # Trivial example that checks for the term 'myhighlighting=yes'
   # in the highlighting definition, and if present returns a specific
   # field name. To use this, you would have to define a highlighting
   # method during the script startup with a call to
   # &pdsSetHighlightingDef() e.g. 
   #   &pdsSetHighlightingDef('A_myhighlighting',
   #                    'label=Highlight DOB;myhighlighting=yes;');
   # Note also the check against $strTableSuffix to ensure this is only
   # used with animal records, and
   # the check that this is not a pedserve-private definition:
   if (!defined($$rmHighlightingDef{'pdsprivate'}) &&
       $strTableSuffix eq 'A' && 
       defined($$rmHighlightingDef{'myhighlighting'}) &&
       $$rmHighlightingDef{'myhighlighting'} eq 'yes') {
      # Dont defer to standard implementation below:
      $fUseStdImpl = 0;

      # Set the fields to return:
      # (this example will use the date of birth field to apply specific
      # highlights for given dates etc)
      $strReturn = $strFldPrefix.'A_DOB';
   }

   # If the above code has not handled this highlighting definition itself,
   # defer to the standard implementation:
   if ($fUseStdImpl) {
      $strReturn = &pdsHookStdImpl_Highlighting_GetExtraFlds($strTableSuffix,
                    $rmHighlightingDef, $strContext, $strFldPrefix, $rmArgsEx);
   }
   
   return $strReturn;
}
Record Highlighting - Text Emphasis - Pedigree

This screen shot was taken from the Standfast Golden Retriever Database