Page Layout

# Variables used to capture state etc. passed to various of our hooks:
our @our_astrPage_SiteMenuItem_Labels = ();
our @our_astrPage_SiteMenuItem_URLs = ();
our @our_anPage_SiteMenuItem_Flags = ();
.
.


# Hook thats called to add a menu item for the 'site menu'. Multiple calls to 
# this are usually made before any part of the page is emitted - each one to 
# 'declare' each menu item that is to go in the site menu.
#
# The difference between page menu and site menu items is that page menu items 
# typically vary from one page to another, whereas site menu items are normally 
# constant throughout the logged-in pages.
#
# The default implementation of these hooks places site menu items in a bar on 
# the left side of the page, and page menu items in a bar across the top of the 
# page beneath the context heading. The positioning of the site menu is controlled 
# through the stylesheet.
#
# Arg 1 - label
# Arg 2 - target URL
# Arg 3 - flags
# OPTIONAL
# Arg 4 - reference to map for future additional arguments; possibly undefined
sub hookPage_AddSiteMenuItem {
   my ($strLabel, $strURL, $nFlags, $rmArgsEx) = @_;

   # A typical implementation of this hook just stores the parameters.
   # These are then used by your &hookPage_AfterOpeningBodyTag() to 
   # generate + emit the HTML of the site menu.
   push(@::our_astrPage_SiteMenuItem_Labels, $strLabel);
   push(@::our_astrPage_SiteMenuItem_URLs, $strURL);
   push(@::our_anPage_SiteMenuItem_Flags, $nFlags);
}

# Hook thats called to add custom site menu items.
# Called twice - once at the beginning of the site menu (to insert items at 
# the start of the menu), and once at the end (to insert items at the end of the menu).
#
# Arg 1 - flag: 0 when called before any other site items have been added (though, 
#         after any home page link); or 1 after standard site items have been added.
# Arg 2 - flag: 0 if logged out, or 1 if logged in or an open system
# OPTIONAL
# Arg 3 - reference to map for future additional arguments; possibly undefined
sub hookPage_AddCustomSiteMenuItems {
   my ($fPosition, $fLoggedIn, $rmArgsEx) = @_;
   
   if ($fPosition) {
      &pdsPageAddSiteMenuItem("About Me", 
                                      &pdsMakeStaticFileURL('aboutme.html'), $::c_CMDITEM_ENABLED);
      &pdsPageAddSiteMenuItem("Google", 'http://www.google.com', $::c_CMDITEM_ENABLED);
   }
}

# Variables used to capture state etc. passed to various of our hooks:
our @our_astrPage_PageMenuItem_Labels = ();
our @our_astrPage_PageMenuItem_URLs = ();
our @our_anPage_PageMenuItem_Flags = ();
.
.

# Hook thats called to add an item for the 'page menu'. Multiple calls to this 
# may be made before any part of the page HTML is actually emitted - each one to 
# 'declare' each menu item that is to go in the page menu.
#
# The difference between page menu and site menu items is that page menu items 
# typically vary from one page to another, whereas site menu items are normally 
# constant throughout the logged-in pages.
#
# The default implementation of these hooks places site menu items in a bar on 
# the left side of the page, and page menu items in a bar across the top of the 
# page beneath the context heading.
#
# Arg 1 - label
# Arg 2 - target URL
# Arg 3 - flags
# OPTIONAL
# Arg 4 - reference to map for future additional arguments; possibly undefined
sub hookPage_AddPageMenuItem {
   my ($strLabel, $strURL, $nFlags, $rmArgsEx) = @_;

   # A typical implementation of this hook will just store the parameters.
   # These are then used by &hookPage_OutputPageMenu() to subsequently 
   # generate + emit the HTML of the site menu.
   push(@::our_astrPage_PageMenuItem_Labels, $strLabel);
   push(@::our_astrPage_PageMenuItem_URLs, $strURL);
   push(@::our_anPage_PageMenuItem_Flags, $nFlags);
}

# Variables used to capture state etc. passed to various of our hooks:
our $our_htmlPage_ContextHeading = '';
.
.

# Hook thats called to set the 'context heading' HTML for a page. This is called prior 
# to any part of the page being emitted, to set the HTML that is to be displayed at the
# top of the page. This contains the 'page heading'.
#
# Arg 1 - html
# OPTIONAL
# Arg 2 - reference to map for future additional arguments; possibly undefined
sub hookPage_SetContextHeadingHTML {
   my ($html, $rmArgsEx) = @_;

   # A typical implementation of this hook just stores the HTML text.
   # This is then emitted by &hookPage_AfterOpeningBodyTag() later.
   $::our_htmlPage_ContextHeading = $html;
}

# Variables used to capture state etc. passed to various of our hooks:
our $our_strPage_ContentTitle = '';
.
.

# Hook thats called to set the 'content title' for a page. This is plain text that, 
# if present, would typically be output using an <h1> tag somewhere near the
# top of the page. This should not be confused with the window title
# that gets displayed in the title bar, and set using <title>; that is handled
# internally by pedserve.
#
# Arg 1 - title
# OPTIONAL
# Arg 2 - reference to map for future additional arguments; possibly undefined
sub hookPage_SetContentTitle {
   my ($strTitle, $rmArgsEx) = @_;

   # A typical implementation of this hook just stores the text.
   # This is then used by hookPage_OutputContentTitle() to generate + emit 
   # the HTML of the content title.
   $::our_strPage_ContentTitle = $strTitle;
}

# Hook to customize the attributes of the HTML header and the body tag.
# A reference to a map is passed as the single argument. This is the map 
# that pedserve will then pass to CGI.ppm::start_html() to output the HTML header.
#
# Arg 1 - reference to attribute map 
# OPTIONAL
# Arg 2 - reference to map for future additional arguments; possibly undefined
sub hookPage_AdjustBodyAttrs {
   my ($rmstrAttrs, $rmArgsEx) = @_;

   # This example just shows how to set an attribute that will be passed to 
   # CGI.pm when emitting the <body> tag. Here we set text to be blue.
   # In practice you wouldnt want to do this; colors etc. are much better 
   # controlled through the stylesheet.
   $$rmstrAttrs{'-text'} = 'blue';
}

# Variables used to capture state etc. passed to various of our hooks:
our @our_astrPage_SiteMenuItem_Labels = ();
our @our_astrPage_SiteMenuItem_URLs = ();
our @our_anPage_SiteMenuItem_Flags = ();
.
.

# Hook thats called immediately after the opening <body> tag of a 
# page has been emitted. You can use this to apply overall page formatting.
# See also the corresponding function &hookPage_BeforeClosingBodyTag()
# thats called immediately prior to the closing </body> is output.
#
# OPTIONAL
# Arg 1 - reference to map for future additional arguments; possibly undefined
sub hookPage_AfterOpeningBodyTag {
   my ($rmArgsEx) = @_;

   # This implementation outputs the site menu items in a <div> 
   # using a css selector that causes the menu to be output in a bar on 
   # the left side of the page, and then opens a new <div> for the page content.

   # Start the Menu div:
   print "<div id='Menu'>\n";

   # Emit main menu items:
   my @ahtmlTmp = ();
   for (my $i = 0; $i < scalar(@::our_astrPage_SiteMenuItem_Labels); $i++) {
      my $strLabel = $::our_astrPage_SiteMenuItem_Labels[$i];
      my $strURL = $::our_astrPage_SiteMenuItem_URLs[$i];
      my $nFlags = $::our_anPage_SiteMenuItem_Flags[$i];
      my $htmlItem = &pdsStyleMakeCmdItemHTML($strLabel, $strURL, $nFlags, 'pds-sitemenu-cmd');
      push(@ahtmlTmp, $htmlItem);
   }
   print $::g_q->div({'-class' => 'pds-sitemenu-div'}, join($::g_q->br, @ahtmlTmp));

   # End the Menu div, then start the Content div:
   print "</div><div id='Content'>\n";
}

# Hook thats called immediately before the closing </body> tag 
# of a page has been emitted. See also the corresponding function 
# &hookPage_AfterOpeningBodyTag() thats called immediately after the
# opening <body> has been output.
#
# OPTIONAL
# Arg 1 - reference to map for future additional arguments; possibly undefined
sub hookPage_BeforeClosingBodyTag {
   my ($rmArgsEx) = @_;

   # Our implementation closes the <div> that
   # &hookPage_AfterOpeningBodyTag() left open:
   print "</div>\n";
}

# Hook thats called to output the standard page elements - 
# context heading, page menu and content title. This is what controls 
# the order of those elements on the page.
#
# OPTIONAL
# Arg 1 - reference to map for future additional arguments; possibly undefined
sub hookPage_OutputStandardElements {
   my ($rmArgsEx) = @_;

   # The default implementation simply calls &hookPage_OutputContextHeading(), 
   # &hookPage_OutputPageMenu() and &hookPage_OutputContentTitle()
   # - in that order.
   &hookPage_OutputContextHeading();
   &hookPage_OutputPageMenu();
   &hookPage_OutputContentTitle();
}

# Variables used to capture state etc. passed to various of our hooks:
our $our_htmlPage_ContextHeading = '';
.
.

# Hook thats called to output the standard 'context heading' page element.
# This is normally the first real element that gets output on the page.
#
# OPTIONAL
# Arg 1 - reference to map for future additional arguments; possibly undefined
sub hookPage_OutputContextHeading {
   my ($rmArgsEx) = @_;

   # Our implementation simply outputs the HTML that was captured 
   # by &hookPage_SetContextHeadingHTML:
   if ($::our_htmlPage_ContextHeading ne '') {
      print $::our_htmlPage_ContextHeading;
   }
}

# Variables used to capture state etc. passed to various of our hooks:
our @our_astrPage_PageMenuItem_Labels = ();
our @our_astrPage_PageMenuItem_URLs = ();
our @our_anPage_PageMenuItem_Flags = ();
.
.

# Hook thats called to output the 'page menu' element.
# This is normally output immediately after the context heading.
# 
# OPTIONAL
# Arg 1 - reference to map for future additional arguments; possibly undefined
sub hookPage_OutputPageMenu {
   my ($rmArgsEx) = @_;

   # The default implementation outputs the page menu items in a
   # <div> using a css selector that causes them to be displayed in
   # a horizontal 'ribbon' below the context heading.
   my @ahtmlTmp = ();
   for (my $i = 0; $i < scalar(@::our_astrPage_PageMenuItem_Labels); $i++) {
      my $strLabel = $::our_astrPage_PageMenuItem_Labels[$i];
      my $strURL = $::our_astrPage_PageMenuItem_URLs[$i];
      my $nFlags = $::our_anPage_PageMenuItem_Flags[$i];
      my $htmlItem =
                 &pdsStyleMakeCmdItemHTML($strLabel, $strURL, $nFlags, 'pds-pagemenu-cmd');
      push(@ahtmlTmp, $htmlItem);
   }
   if (scalar(@ahtmlTmp) > 0) {
      print $::g_q->div({'-class' => 'pds-pagemenu-div'}, 
                               join("&nbsp;$::custom_htmlStdSep ", @ahtmlTmp));
   }
}

# Variables used to capture state etc. passed to various of our hooks:
our $our_strPage_ContentTitle = '';
.
.

# Hook thats called to output the 'page content title' element.
# This is normally output immediately after both the context heading
# and the page menu.
# 
# OPTIONAL
# Arg 1 - reference to map for future additional arguments; possibly undefined
sub hookPage_OutputContentTitle {
   my ($rmArgsEx) = @_;

   # Our implementation simply outputs any text that was captured by 
   # &hookPage_SetContextHeadingHTML() using the heading tag <h1>.
   # Remember to apply escapeHTML() to any text.
   if ($::our_strPage_ContentTitle ne '' ) {
      print $::g_q->h1($::g_q->escapeHTML($::our_strPage_ContentTitle));
   }
}

# Hook thats called to display the logged-in front page
# 'content', if your site uses such a 'front page'.
# (see config variable custom_fEnablePage_Front)
#
# OPTIONAL
# Arg 1 - reference to map for future additional arguments; possibly undefined
sub hookPage_FrontPageContent {
   my ($rmArgsEx) = @_;

   # Our implementation displays a welcome message and any
   # 'message of the day' message.

   # Output welcome message:
   print $::g_q->p($::g_q->escapeHTML(
              "Welcome to $::custom_strSiteTitle, "
             ."a pedigree database site run by $::custom_strSiteOwner."));
   
   # Output any message of the day:
   my $strMessageOfTheDay = &pdsDbGetMOTD();
   if ($strMessageOfTheDay ne '') {
      print $::g_q->p($::g_q->escapeHTML($strMessageOfTheDay));
   }
}

# Variables used to capture state etc. passed to various of our hooks:
our $our_strPanel_Title = '';
.
.

# Hook that sets the title for a panel.
#
# Arg 1 - title
# OPTIONAL
# Arg 2 - reference to map for future additional arguments; possibly undefined
sub hookPanel_SetTitle {
   my ($strTitle, $rmArgsEx) = @_;

   # Typical implementations of this hook simply store the title text,
   # for subsequent output by &hookPanel_OutputTitle().
   $::our_strPanel_Title = $strTitle;
}

# Variables used to capture state etc. passed to various of our hooks:
our @our_afPanel_OptionsBarElement_NeedsSeparatorBefore = ();
our @our_anPanel_OptionsBarElement_Groupings = ();
our @our_ahtmlPanel_OptionsBarElement_Elements = ();
.
.

# Hook that adds an element for the options bar area.
#
# Arg 1 - flag: whether or not this element require a separator with
#         any preceding options bar element?
# Arg 2 - grouping value: elements with the same grouping value should
#         be placed together in the options bar when it is generated.
# Arg 3 - element HTML
# OPTIONAL
# Arg 4 - reference to map for future additional arguments; possibly undefined
sub hookPanel_AddOptionsBarElement {
   my ($fNeedsSeparatorBefore, $nGrouping, $htmlElement, $rmArgsEx) = @_;

   # All implementations of this hook should capture the element label,
   # grouping value, + html then use the captured data in
   # &hookPanel_OutputOptionsBar() to format and output the options bar
   # in the manner chosen.
   push(@::our_afPanel_OptionsBarElement_NeedsSeparatorBefore, $fNeedsSeparatorBefore);
   push(@::our_anPanel_OptionsBarElement_Groupings, $nGrouping);
   push(@::our_ahtmlPanel_OptionsBarElement_Elements, $htmlElement);
}

# Hook thats called to output the standard elements at the start of
# a panel. The standard panel elements are the panel title and options bar. This is called
# before the actual 'panel content' gets emitted.
#
# OPTIONAL
# Arg 1 - reference to map for future additional arguments; possibly undefined
sub hookPanel_OutputStandardElements {
   my ($rmArgsEx) = @_;

   # We simply call the hook functions that will output the title and
   # options bar, in that order:
   &hookPanel_OutputTitle();
   &hookPanel_OutputOptionsBar();
}

# Variables used to capture state etc. passed to various of our hooks:
our $our_strPanel_Title = '';
our @our_afPanel_OptionsBarElement_NeedsSeparatorBefore = ();
our @our_anPanel_OptionsBarElement_Groupings = ();
our @our_ahtmlPanel_OptionsBarElement_Elements = ();
.
.

# Hook thats called at the end of the panel. You should reset any panel state
# data to their initial values - in case the current page contains multiple panels.
#
# OPTIONAL
# Arg 1 - reference to map for future additional arguments; possibly undefined
sub hookPanel_End {
   my ($rmArgsEx) = @_;

   # Now we reset our panel state variables, in case there are
   # multiple panels on the page.
   $::our_strPanel_Title = '';
   @::our_afPanel_OptionsBarElement_NeedsSeparatorBefore = ();
   @::our_anPanel_OptionsBarElement_Groupings = ();
   @::our_ahtmlPanel_OptionsBarElement_Elements = ();
}

# Hook thats called to output HTML to the current panel.
#
# Arg 1 - the HTML to be output.
# OPTIONAL
# Arg 2 - reference to map for future additional arguments; possibly undefined
sub hookPanel_Output {
   my ($html, $rmArgsEx) = @_;

   # Our implementation is simply emits the HTML.
   # An alternative technique is to capture the output (accumulating it
   # in a global string variable), and then output it all at once in hookPanel_End(),
   # perhaps enclosed in some other HTML framework etc.
   print $html;
}

# Variables used to capture state etc. passed to various of our hooks:
our $our_strPanel_Title = '';
.
.

# Hook thats called to output the standard panel element 'title'.
#
# OPTIONAL
# Arg 1 - reference to map for future additional arguments; possibly undefined
sub hookPanel_OutputTitle {
   my ($rmArgsEx) = @_;

   # Typical implementation will simply output any title captured
   # by &hookPanel_SetTitle() using suitable tags such as <h1>.
   if ($::our_strPanel_Title ne '' ) {
      &hookPanel_Output($::g_q->h1($::g_q->escapeHTML($::our_strPanel_Title)));
   }
}

# Variables used to capture state etc. passed to various of our hooks:
our @our_afPanel_OptionsBarElement_NeedsSeparatorBefore = ();
our @our_anPanel_OptionsBarElement_Groupings = ();
our @our_ahtmlPanel_OptionsBarElement_Elements = ();
.
.

# Hook thats called to output the standard panel element 'options bar'.
#
# OPTIONAL
# Arg 1 - reference to map for future additional arguments; possibly undefined
sub hookPanel_OutputOptionsBar {
   my ($rmArgsEx) = @_;

   # Our implementation will output the labels+elements that were captured
   # by &hookPanel_AddOptionsBarElement() in a 'ribbon' bar.

   # We must process them first in grouping order, and then order within group
   # is the order in which the option elements were added.
   my $nElts = scalar(@::our_afPanel_OptionsBarElement_NeedsSeparatorBefore);
   my %mnGroupings = ();
   for (my $nElt = 0; $nElt < $nElts; $nElt++) {
      $mnGroupings{$::our_anPanel_OptionsBarElement_Groupings[$nElt]} = 1;
   }
   my $fFirst = 1;
   my $html = '';
   foreach my $nGrouping (sort keys(%mnGroupings)) {
      for (my $nElt = 0; $nElt < $nElts; $nElt++) {
         next if $::our_anPanel_OptionsBarElement_Groupings[$nElt] != $nGrouping;
         my $htmlElt = $::our_ahtmlPanel_OptionsBarElement_Elements[$nElt];
         next if $htmlElt eq '';

         if ($html ne '') {
            if ($::our_afPanel_OptionsBarElement_NeedsSeparatorBefore[$nElt]
                            && !$fFirst) {
               $html .= "&nbsp;$::custom_htmlStdSep ";
            } else {
               $html .= ' ';
            }
            $fFirst = 0;
         }
         $html .= $htmlElt;
      }
   }

   # If there is any HTML to output, enclose it within a form within div:   
   if ($html ne '') {
      # Generate the form:
      my %mFormAttrs = ();
      $mFormAttrs{'-method'} = 'GET';
      $mFormAttrs{'-name'} = &pdsPanelGetOptionsBarFormID();
          $html .= &pdsPageGetSelfArgsAsHiddenFieldsHTML();
      my $htmlForm = $::g_q->start_form(\%mFormAttrs).$html.$::g_q->endform();
      # Enclose the form within a <div>, with css class 'pds-optionsbar-div':
      $html = $::g_q->div({'-class' => 'pds-optionsbar-div'}, $htmlForm);
   }

   # Now output it, using the output hook:   
   &hookPanel_Output($html);
}