// ***************************************************************************
// APPLICATION/CENTER_COLUMN/MENU_ITEM_CLICK_HANDLING.JS
// (C) 2007 Peter Newman
// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
// Support routines for handling a click on one of the 'center column'
// menus...
// ***************************************************************************

// ===========================================================================
// SCCC_handle_click
// ===========================================================================

function SCCC_handle_click(
    menu_name__for_error_messages                   ,
    className_selected                              ,
    className_selectable                            ,
    className_unselectable                          ,
    menu_item_id_prefix                             ,
    clicked_on_items_id_suffix                      ,
    selected_items_id_suffix__according_to_cookie   ,
    cookie_container_name                           ,
    cookie_name                                     ,
    ajax_target
    ) {

    // -----------------------------------------------------------------------
    // SCCC_handle_click(
    //      menu_name__for_error_messages                   ,
    //      className_selected                              ,
    //      className_selectable                            ,
    //      className_unselectable                          ,
    //      menu_item_id_prefix                             ,
    //      clicked_on_items_id_suffix                      ,
    //      selected_items_id_suffix__according_to_cookie   ,
    //      cookie_container_name                           ,
    //      cookie_name                                     ,
    //      ajax_target
    //      ) {
    // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    // Called to handle things when a 'standard center column' menu item is
    // clicked on.
    //
    // This routine then:-
    //
    // 1.   De-highlights the currently selected/highlit item (on the menu).
    //
    // 2.   Highlights and selects the clicked-on item (on the menu).
    //
    // 3.   Loads the new page content (which generally involves making a
    //      'target=<ajax_target>' Ajax call).
    // -----------------------------------------------------------------------

    // -----------------------------------------------------------------------
    // BACKGROUND
    // ----------
    // This routine makes the following assumptions:-
    //
    // 1.   The menu whoose item was clicked on is a PARENT element
    //      (typically a DIV), full of CHILD elements (typically SPANs).
    //
    //      For example:-
    //
    //          <div>
    //              <span
    //                  id    = "[menu_item_id_prefix]_[menu_item_id_suffix_1]"
    //                  class = "[selected|selectable|unselectable]"
    //                  >
    //                  Menu Item 1
    //              </span>
    //              <span
    //                  id    = "[menu_item_id_prefix]_[menu_item_id_suffix_2]"
    //                  class = "[selected|selectable|unselectable]"
    //                  >
    //                  Menu Item 2
    //              </span>
    //              ...
    //              <span
    //                  id    = "[menu_item_id_prefix]_[menu_item_id_suffix_N]"
    //                  class = "[selected|selectable|unselectable]"
    //                  >
    //                  Menu Item N
    //              </span>
    //          </div>
    //
    // 2.   The menu items are each assigned one of three 'class names':-
    //
    //          'selected'      :   This is the currently
    //                              selected/highlit menu item.  Only one
    //                              menu item may have this class at any
    //                              time.
    //
    //          'selectable'    :   This is a menu item that may be
    //                              clicked on.
    //
    //          'unselectable'  :   This is a menu item for which clicks
    //                              should be ignored.
    //
    // 3.   However, the actual class names used are specified by the
    //      'className_xxx' input parameters:-
    //
    //          className_selected
    //          className_selectable
    //          className_unselectable
    //
    //      This allows a single page to have a variety of menus whoose
    //      items are click-handled by this routine - even though they have
    //      different class names - and thus can appear very different.
    //
    // 4.   The 'onclick' handler for the 'sccc_selected' and
    //      'sccc_selectable' menu items is this routine.  The
    //      'sccc_unselectable' menu items have NO 'onclick' handler.
    //
    // 5.   The id attribute of the menu items is of the form:-
    //          id="[menu_item_id_prefix]_[menu_item_id_suffix_i]"
    //
    //      Where the 'menu_item_id_suffix' is generally the same as the
    //      value of the cookie that the menu is associated with.
    //
    //      So for example, take the ISSUE_ORDER cookie (whoose cookie name
    //      is 'io').
    //
    //      This cookie can have any of FOUR values:-
    //          o   'a2z'   (A to Z)
    //          o   'z2a'   (Z to A)
    //          o   'n2o'   (Newest to Oldest)
    //          o   'o2n'   (Oldest to Newest)
    //
    //      And this cookie is associated with the 'issue order menu':-
    //
    //          +------------------------------------------------------------+
    //          |  A to Z    Z to A    Newest to Oldest    Oldest to Newest  |
    //          +------------------------------------------------------------+
    //
    // -----------------------------------------------------------------------

    // -----------------------------------------------------------------------
    // NOTES!
    // ------
    //
    // THE 'SELECTED' MENU ITEM:  COOKIE VALUE vs CLASS ATTRIBUTE
    // - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    // Whilst doing this routine, we have to bear in mind that there are
    // TWO different indicators of what the currently selected menu item is.
    //
    // 1.   The cookie value that's the 'official' indicator of what the
    //      currently selected item on the menu concerned is, and;
    //
    // 2.   The class attribute of the menu items - one of which should be
    //      the class attribute of a 'selected' item.
    //
    // So we have to allow for the possibility that these two could get out
    // of step.
    // -----------------------------------------------------------------------

    // -----------------------------------------------------------------------
    // Initialisation...
    // -----------------------------------------------------------------------

    var software_bug__detected_in = wos1__software_bug__get_detected_in(
                                        "SCCC_handle_click"                ,
                                        "application/center_column/menu_item_click_handling.js"
                                        ) ;

    // -----------------------------------------------------------------------
    // Check if the click is to be ignored...
    //
    // NOTE!
    // -----
    // 'question_ignore_click_javascript' is a string that gives some
    // javascript to be eval'd.  That javascript should return either:-
    //      true  = Ignore this click, or;
    //      false = DON'T ignore this click
    //
    // If 'question_ignore_click_javascript' is anything other than a
    // non-null string, it will be be ignored.
    // -----------------------------------------------------------------------

/*
    if ( typeof( question_ignore_click_javascript ) === 'string' ) {

        question_ignore_click_javascript = wos1_trim( question_ignore_click_javascript ) ;

        if ( question_ignore_click_javascript != '' ) {

            $result = eval( question_ignore_click_javascript ) ;

            if ( $result === true ) {

                return ;

            } else if ( $result !== false ) {

                alert( "Bad 'question_ignore_click_javascript' (must return either true or false)!" +
                            software_bug__detected_in
                            ) ;

                return ;

                }

            }

        }
*/

    // -----------------------------------------------------------------------
    // Get the clicked on element's ID...
    // -----------------------------------------------------------------------

    var clicked_on_element_id = menu_item_id_prefix + '_' + clicked_on_items_id_suffix ;

    // -----------------------------------------------------------------------
    // Search for the Webos window object in which the clicked-on element
    // lives...
    // -----------------------------------------------------------------------

    // -----------------------------------------------------------------------
    // webos__element_id_to_webos_window_object(
    //      target_element_id
    //      )
    // - - - - - - - - - - - - - - - - - - - - -
    // Searchs through BOTH the background web page - AND all the active
    // Webos window objects - for elements that have the specified
    // 'target_element_id'.  If EXACTLY ONE copy of the element is
    // found, returns the details of the WEBOS WINDOW that owns it
    // (which may be null - meaning that the element was found in the
    // background web page).
    //
    // Otherwise, issues the appropriate error message, and returns
    // undefined.
    //
    // RETURNS either:-
    //
    //      o   undefined (error message issued), if either:-
    //          --  The 'target_element_id' COULDN'T BE FOUND (either in
    //              the background web page - or in any active WebOS
    //              window), or;
    //          --  Searching through BOTH the background web page - AND
    //              all the active Webos window objects - revealed MORE
    //              THAN ONE element with the specified 'target_element_id',
    //
    //      o   null, if EXACTLY ONE copy of the 'target_element_id' was
    //          found - and that was in the BACKGROUND WEB PAGE, or;
    //
    //      o   The owner Webos window object, if EXACTLY ONE copy of the
    //          'target_element_id' was found - and that was in the Webos
    //          window object returned.
    // -----------------------------------------------------------------------

    var host_webos_window_object = webos__element_id_to_webos_window_object(
                                        clicked_on_element_id
                                        ) ;

    // -----------------------------------------------------------------------

    if ( host_webos_window_object === undefined ) {
        return ;
        }

    // -----------------------------------------------------------------------
    // Get the document object of the document in which the clicked-on
    // element (and the other menu elements) live...
    // -----------------------------------------------------------------------

    // -----------------------------------------------------------------------
    // webos__get_document_object(
    //      target_window_object
    //      )
    // - - - - - - - - - - - - - -
    // Utility function to return the window's document object.
    //
    // If 'target_window_object' === null (the background web page), then
    // document is returned.
    //
    // Otherwise, document object for the document in the specified Webos
    // window's IFRAME is returned.
    // -----------------------------------------------------------------------

    var host_document_object = webos__get_document_object(
                                    host_webos_window_object
                                    ) ;

    // -----------------------------------------------------------------------
    // Get the clicked on element object - and make sure it exists...
    // -----------------------------------------------------------------------

    var clicked_on_element_object = host_document_object.getElementById( clicked_on_element_id ) ;

    // -----------------------------------------------------------------------

    if ( !clicked_on_element_object ) {

        alert( 'Bad:-' +
                    "\n\t'menu_item_id_prefix':  " + menu_item_id_prefix +
                "\nand/or:-" +
                    "\n\t'clicked_on_items_id_suffix':  " + clicked_on_items_id_suffix +
                "\n\nThe resulting 'clicked_on_element_id':-\n\t" +
                    clicked_on_element_id +
                "\nWASN'T FOUND!" +
                software_bug__detected_in
                ) ;

        return ;

        }

    // -----------------------------------------------------------------------
    // Get the selected element object - according to the cookie - and make
    // sure it exists...
    // -----------------------------------------------------------------------

    var selected_element_id__according_to_cookie = menu_item_id_prefix + '_' + selected_items_id_suffix__according_to_cookie ;

    // -----------------------------------------------------------------------

    var selected_element_object__according_to_cookie = host_document_object.getElementById( selected_element_id__according_to_cookie ) ;

    // -----------------------------------------------------------------------

    if ( !selected_element_object__according_to_cookie ) {

        alert( 'Bad:-' +
                    "\n\t'menu_item_id_prefix':  " + menu_item_id_prefix +
                "\nand/or:-" +
                    "\n\t'selected_items_id_suffix__according_to_cookie':  " + selected_items_id_suffix__according_to_cookie +
                "\n\nThe resulting 'selected_element_id__according_to_cookie':-\n\t" +
                    selected_element_id__according_to_cookie +
                "\nWASN'T FOUND!" +
                software_bug__detected_in
                ) ;

        return ;

        }

    // -----------------------------------------------------------------------
    // Get the parent of the clicked on element.
    //
    // This parent element is the menu.  Or in other words, it's the
    // container element that holds the menu items...
    // -----------------------------------------------------------------------

    var menu_object = clicked_on_element_object.parentNode ;

    // -----------------------------------------------------------------------

    if ( !menu_object ) {

        alert( 'Bad:-' +
                    "\n\t'menu_item_id_prefix':  " + menu_item_id_prefix +
                "\nand/or:-" +
                    "\n\t'clicked_on_items_id_suffix':  " + clicked_on_items_id_suffix +
                "\n\nThe resulting 'clicked_on_element_id':-\n\t" +
                    clicked_on_element_id +
                "\nhas NO PARENT!" +
                software_bug__detected_in
                ) ;

        return ;

        }

    // -----------------------------------------------------------------------
    // Check that the menu element has children...
    //
    // NOTE!
    // -----
    // In theory, this is unnecessary - since we already know that the menu
    // has at least one child (the clicked-on element that brought us here)!
    //
    // But let's be super-neurotic...
    // -----------------------------------------------------------------------

    if ( !menu_object.hasChildNodes()  ) {

        var parent_data = '' ;

        if ( menu_object.tagName ) {
            parent_data += "\n\ttagName:     " + menu_object.tagName ;
            }

        if ( menu_object.id ) {
            parent_data += "\n\tid:                 " + menu_object.id ;
            }

        if ( menu_object.className ) {
            parent_data += "\n\tclassName:  " + menu_object.className ;
            }

        alert( 'Bad:-' +
                    "\n\t'menu_item_id_prefix':  " + menu_item_id_prefix +
                "\nand/or:-" +
                    "\n\t'clicked_on_items_id_suffix':  " + clicked_on_items_id_suffix +
                "\n\nThe resulting 'clicked on element's parent:-" +
                    parent_data +
                "\nhas NO CHILDREN!" +
                software_bug__detected_in
                ) ;

        return ;

        }

    // -----------------------------------------------------------------------
    // Check to see if the clicked-on element is a 'static' one.  If it is,
    // make sure the corresponding content container element exists...
    // -----------------------------------------------------------------------

    var just_select_me = false ;

    // -----------------------------------------------------------------------

    var static = clicked_on_element_object.getAttribute( 'static' ) ;

    // -----------------------------------------------------------------------

    if ( static === 'static' ) {

        // -------------------------------------------------------------------
        // The new tab's contents are static.  So, if the content
        // container's 'innerHtml' is already loaded, we only need select
        // the content container concerned...
        //
        // NOTE!
        // -----
        // The clicked-on item's content container is assumed to have:-
        //      id = item_id + '_content_container'
        // -------------------------------------------------------------------

        var container_id = clicked_on_element_id + '_content_container' ;

        // -------------------------------------------------------------------

        var container_element_object = host_document_object.getElementById( container_id ) ;

        // -------------------------------------------------------------------

        if ( container_element_object ) {

            // ---------------------------------------------------------------
            // We FOUND the tab's content container...
            // ---------------------------------------------------------------

            if ( container_element_object.innerHTML != '' ) {

                // -----------------------------------------------------------
                // The tab container's content is already downloaded.
                //
                // ==>  We just need to select the tab container concerned
                //      (and de-select it's brothers and sisters).
                // -----------------------------------------------------------

                just_select_me = true ;

                // -----------------------------------------------------------

                }

            // ---------------------------------------------------------------

        } else {

            // ---------------------------------------------------------------
            // We DIDN'T find the tab's content container...
            // ---------------------------------------------------------------

            alert( 'Tab container not found!' +
                        "\n\nThe missing tab container's id is:  " + container_id +
                        software_bug__detected_in
                        ) ;

            return ;

            // ---------------------------------------------------------------

            }

        // -------------------------------------------------------------------

        }

    // -----------------------------------------------------------------------
    // Walk over the menu.  And:-
    //
    // 1.   Reset any 'selected' menu items to 'selectable'.
    //
    // 2.   Issue a warning unless there's exactly ONE 'selected' item.
    //
    // 3.   Issue a warning if the 'selected' menu item (indicated by the
    //      class attribute,) is different from the 'selected' item indicated
    //      by the cookie.
    // -----------------------------------------------------------------------

    // -----------------------------------------------------------------------
    // childNodes[]
    // - - - - - -
    // Returns an array of all of the child nodes of an element as objects.
    // Use the properties "nodeName" and "nodeType" to retrieve additional
    // information about a node.
    //
    // EXAMPLE
    //
    //      //access some <ul> element
    //      var mylist=document.getElementById("mylist")
    //      for (i=0; i<mylist.childNodes.length; i++){
    //      if (mylist.childNodes[i].nodeName=="LI")
    //          //do something
    //          }
    //
    // -----------------------------------------------------------------------

    var children = menu_object.childNodes ;

    // -----------------------------------------------------------------------

    var selected_items_id_suffix__according_to_class_attribute ;

    var errors_detected = false ;

    var number_selected_items = 0 ;

    // -----------------------------------------------------------------------

    for ( i=0 , j=children.length ; i<j ; i++ ) {

        // -------------------------------------------------------------------

        if ( children[i].className === className_selected ) {

            // ---------------------------------------------------------------
            // De-select the currently selected element...
            //
            // Ie:-     class="sccc_selected" --> class="sccc_selectable"
            // ---------------------------------------------------------------

            children[i].className = className_selectable ;

            // ---------------------------------------------------------------
            // Update the number of 'selected' menu items...
            // ---------------------------------------------------------------

            number_selected_items++ ;

            // ---------------------------------------------------------------
            // Make a note of this selected menu item's id suffix...
            // ---------------------------------------------------------------

            if ( children[i].id.length > menu_item_id_prefix.length + 1 ) {

                // -----------------------------------------------------------
                // OK!
                // -----------------------------------------------------------

                selected_items_id_suffix__according_to_class_attribute =
                    children[i].id.substr( menu_item_id_prefix.length + 1 ) ;

                // -----------------------------------------------------------

            } else {

                // -----------------------------------------------------------
                // ERROR!
                // -----------------------------------------------------------

                alert( 'Bad menu item id (shorter than id prefix)!' +
                        "\n\nThe bad id was:  " + children[i].id +
                        "\nThe id prefix is:  " + menu_item_id_prefix +
                        software_bug__detected_in
                        ) ;

                errors_detected = true ;

                // -----------------------------------------------------------

                }

            // ---------------------------------------------------------------

            }

        // -------------------------------------------------------------------

        }

    // -----------------------------------------------------------------------
    // Issue a warning unless there was exactly ONE 'selected' menu item...
    // -----------------------------------------------------------------------

    if ( number_selected_items == 0 ) {

        alert( 'WARNING!  No \'selected\' item!' +
                "\n\nWe couldn't find the 'selected' item in the \"" + menu_name__for_error_messages + '" menu.' +
                "\n\nThe 'selected' item would have had:-" +
                    "\n\tclass=\"" + className_selected + '"' +
                software_bug__detected_in
                ) ;

        errors_detected = true ;

    } else if ( number_selected_items > 1 ) {

        alert( 'WARNING!  Too many \'selected\' items!' +
                "\n\nThe \"" + menu_name__for_error_messages + '" menu has more than one \'selected\' item.' +
                "\n\n'Selected' items from this menu have:-" +
                    "\n\tclass=\"" + className_selected + '"' +
                software_bug__detected_in
                ) ;

        errors_detected = true ;

    } else {

        // -------------------------------------------------------------------
        // Issue a warning unless the 'selected' item according to the class
        // attribute is the same as the 'selected' item according to the
        // cookie...
        // -------------------------------------------------------------------

        if (    selected_items_id_suffix__according_to_class_attribute
                &&
                (
                selected_items_id_suffix__according_to_class_attribute
                !=
                selected_items_id_suffix__according_to_cookie
                )
            ) {

            alert( 'Bad selected item (the class attribute and cookie give a different selected item)!' +
                    "\n\nThe selected item id according to the class attribute is:  " + menu_item_id_prefix + '_' + selected_items_id_suffix__according_to_class_attribute +
                    "\nThe selected item id according to the cookie is:  "            + menu_item_id_prefix + '_' + selected_items_id_suffix__according_to_cookie +
                    software_bug__detected_in
                    ) ;

            errors_detected = true ;

            }

        // -------------------------------------------------------------------

        }

    // -----------------------------------------------------------------------
    // Highlight the 'new' element...
    // -----------------------------------------------------------------------

    // -----------------------------------------------------------------------
    // className
    // - - - - -
    // Returns the CSS class attribute of an element.  Read/write.
    //
    // Example(s):
    //      document.getElementById("test").className="class1"
    //          //  Assign the class "class1" to element
    //
    //      document.getElementById("test").className+=" class2"
    //          //  Assign an additional "class2" class to element
    // -----------------------------------------------------------------------

    clicked_on_element_object.className = className_selected ;

    // -----------------------------------------------------------------------
    // Update the cookie...
    // -----------------------------------------------------------------------

    // ===========================================================================
    // function processCookie(
    //      cookieName  ,
    //      func        ,
    //      name        ,
    //      value       ,
    //      days
    //      )
    // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    // Do stuff with cookies.  In particular, support "stacked cookies" (=
    // multiple "name=value" pairs in the one cookies proper).
    //
    // NOTE!
    // -----
    // 1.   To create/use use a stacked cookie; make 'cookieName' and 'name'
    //      different.
    //
    // 2.   The operations available are:-
    //      o   Kill    (delete),
    //      o   Clear   (non-stacked - delete, stacked - remove name/value pair),
    //      o   Set     (add/update the name/value pair creating cookie if needs
    //                  be),
    //      o   Read    (return the value, if present, of the provided named
    //                  element)
    //
    //      cookieName  [required]  -   The name of the cookie.
    //
    //      func        [required]  -   What processing on the cookie is required,
    //                                  i.e. kill (delete), clear (non-stacked -
    //                                  delete, stacked - remove name/value pair),
    //                                  set (add/update the name/value pair creating
    //                                  cookie if needs be), read (return the value,
    //                                  if present, of the provided named element)
    //
    //      name        [required]  -   Identifies the name/value pair to be
    //                                  operated on. If the same as cookieName
    //                                  indicates a non-stacked cookie.
    //
    //      value       [optional]  -   Supplies the data the be associated with the
    //                                  identified named cookie element.
    //
    //      days        [optional]  -   In cases where a cookie is created or
    //                                  updated, this sets the period of validity.
    //                                  Defaults to 365 days.
    //
    // See: "Javascript/PHP Cookies"
    //      kos Haks
    //      http://cass-hacks.com/articles/discussion/js_php_cookies/
    //
    // RETURNS
    //      o   If func == 'read'
    //          - - - - - - - - -
    //          cookie value = Cookie read OK!
    //          null         = Read ERROR (NO error message issued)!
    //      o   Otherwise
    //          - - - - -
    //          true  = Cookie killed, cleared or set OK!
    //          false = ERROR (NO error message issued)!
    // ===========================================================================

/*
    hunlock_setCookie(
        cookie_name                 ,
        clicked_on_items_id_suffix  ,
        30                          ,   //  30 days = 1 month
        COOKIE_PATH
        ) ;
*/

    processCookie(
        cookie_container_name       ,   //  cookieName
        'set'                       ,   //  func
        cookie_name                 ,   //  name
        clicked_on_items_id_suffix  ,   //  value
        30                              //  days = 1 month
        ) ;

    // -----------------------------------------------------------------------
    // Now at this point, if there were no errors detected, and the
    // clicked-on item is the same as the currently selected item, then
    // there's no need to do any more.
    //
    // Or more specifically, we can skip the Ajax request to update the page
    // content...
    // -----------------------------------------------------------------------

    if (    !errors_detected
            &&
            (
            clicked_on_items_id_suffix
            ==
            selected_items_id_suffix__according_to_cookie
            )
        ) {
        return ;
        }

    // -----------------------------------------------------------------------
    // If we can just select the clicked-on element's content container,
    // then do this now...
    // -----------------------------------------------------------------------

    if ( just_select_me ) {

        // -----------------------------------------------------------------------
        // TAB_select(
        //      target_window_object    ,
        //      id_of_tab_to_select
        //      )
        // - - - - - - - - - - - - - - -
        // Selects the specified tab - by showing that tab - and hiding all of
        // it's brothers and sisters.
        //
        // RETURNS:-
        //      true  = ERROR (error message issued)!
        //      false = Tab selected OK!
        // -----------------------------------------------------------------------

        TAB_select(
            host_webos_window_object    ,
            container_id
            )

        // -----------------------------------------------------------

        return ;

        // -----------------------------------------------------------

        }

    // -----------------------------------------------------------------------
    // Send an Ajax request to download/update the target container's
    // content...
    // -----------------------------------------------------------------------

//  send_ajax_request_to_update_center_column() ;

    wos1__send_ajax_request( {
        url             :   public_root_url             ,
        parameters1     :   { target : ajax_target }    ,
        window_object   :   host_webos_window_object
        } ) ;

    // -----------------------------------------------------------------------
    // That's that!
    // -----------------------------------------------------------------------

    }

// ===========================================================================
// send_ajax_request_to_update_center_column
// ===========================================================================

function send_ajax_request_to_update_center_column() {

    // -----------------------------------------------------------------------
    // Send an Ajax request to update the center column...
    // -----------------------------------------------------------------------

    // -----------------------------------------------------------------------
    // wos1__send_ajax_request(
    //      request_details_array
    //      )
    // -------------------------------------
    // wos1__send_ajax_request__from_window(
    //      request_details_array   ,
    //      target_window_object
    //      )
    // -------------------------------------
    // Sends the Ajax request described by the 'request details array'.
    //
    // The 'request details array' is a Javascript object (aka
    // 'associative array'), with the following "name=value" pairs (mostly
    // optional):-
    //
    //      {   method              :                       //  OPTIONAL
    //              "GET" (the default) --OR-- "POST"
    //
    //          url                 :                       //  REQUIRED
    //              URL of PHP (or whatever) server side script to which the
    //              request should be sent
    //
    //          parameters1         :                       //  OPTIONAL
    //              A Javascript object of 'name = value' pairs.
    //
    //          parameters2         :                       //  OPTIONAL
    //              Same as 'parameters1'.
    //
    //              If you've got just the one set of 'name = value pairs'
    //              you want to send to the server - you can use either
    //              'parameters1' or 'parameters2' (it doesn't matter
    //              which).
    //
    //              Both are provided in case you want to send TWO sets of
    //              'name = value pairs' to the server.  For example:-
    //              o   Some 'name = value pairs' - related (say,) to the
    //                  window or web page in use, AND:-
    //              o   The 'name = value pairs' derived from a form
    //                  that you're submitting.
    //
    //          window_object       :                       //  OPTIONAL (#)
    //              null    (if the request was issued from the background
    //                      web page)
    //              --OR--
    //              A reference to the target "WebOS_Window" object
    //
    //          group_name          :                       //  OPTIONAL (#)
    //              ""
    //              --OR--
    //              Target "WebOS_Window"'s 'group_name'
    //
    //          nobustcache         :                       //  OPTIONAL
    //              false   (the default)
    //              --OR--
    //              true    (if you want to disable cache busting, for this
    //                      request)
    //
    //          noresponse          :                       //  OPTIONAL
    //              false   (the default)
    //              --OR--
    //              true    (if the request is one for which NO response
    //                      is expected)
    //
    //          }
    //
    // (#)  NOTE that you should specify either 0 or 1 of:-
    //          window_object
    //          unique_integer_id
    //          unique_name
    //          group_name
    //
    // If you specify NONE of the above - then the target "WebOS_Window"
    // to which the request belongs will default to null (the background
    // web page).
    //
    // If you specify MORE THAN ONE of the above...
    //
    // If you specify 'group_name'...
    //
    // RETURNS:-
    //      true  = ERROR! (error message issued - NO request sent)
    //      false = OK!    (request sent successfully)
    // -----------------------------------------------------------------------

    wos1__send_ajax_request( {
        url             :   public_root_url         ,
        parameters1     :   { target : 'sccc' }     ,
        window_object   :   null
        } ) ;

    // -----------------------------------------------------------------------
    // That's that!
    // -----------------------------------------------------------------------

    }

// ===========================================================================
// innerHTML_insert_slash_replace
// ===========================================================================

function innerHTML_insert_slash_replace(
    target_window_object                            ,
    innerHTML_insert_slash_replace_details_list
    ) {

    // -----------------------------------------------------------------------
    // innerHTML_insert_slash_replace(
    //      target_window_object                            ,
    //      innerHTML_insert_slash_replace_details_list
    //      )
    // - - - - - - - - - - - - - - - - - - - - - - - - - - -
    // Takes an 'innerHTML_insert_slash_replace_details_list' like:-
    //
    //      PHP syntax...
    //      - - - - - - -
    //          array(
    //              array(
    //                  'container_id'  =>  'SCCC_body'         ,
    //                  'innerHTML'     =>  '...whatever...'
    //                  ) ,
    //              array(
    //                  'container_id'  =>  'SCCC_footer'       ,
    //                  'innerHTML'     =>  '...whatever...'
    //                  )
    //             )
    //
    //
    //      Javascript literal syntax...
    //      - - - - - - - - - - - - - -
    //          [   {   container_id    :   'SCCC_body'         ,
    //                  innerHTML       :   '...whatever...'
    //                  } ,
    //              {   container_id    :   'SCCC_footer'       ,
    //                  innerHTML       :   '...whatever...'
    //                  }
    //              ]
    //
    // and inserts the specified 'innerHTML' into the specified container
    // elements (overwriting any existing 'innerHTML' that the container
    // elements concerned may already contain).
    //
    // RETURNS:-
    //      true  = ERROR (error message issued)!
    //      false = innerHTML inserted OK!
    // -----------------------------------------------------------------------

    // -----------------------------------------------------------------------
    // Error handling...
    // -----------------------------------------------------------------------

    var software_bug__detected_in = wos1__software_bug__get_detected_in(
                                        "innerHTML_insert_slash_replace"        ,
                                        "standard_center_column_content.js"
                                        ) ;

    // -----------------------------------------------------------------------

    var succeeded = false ;
    var failed    = true  ;

    // -----------------------------------------------------------------------
    // Check the input...
    // -----------------------------------------------------------------------

    if ( crockford_typeof( innerHTML_insert_slash_replace_details_list ) !== 'array' ) {
        alert( "Bad 'innerHTML_insert_slash_replace_details_list' (not an array)!" + software_bug__detected_in ) ;
        return failed ;
        }

    // -----------------------------------------------------------------------
    // Install the innerHTML...
    // -----------------------------------------------------------------------

    var this_innerHTML_details_object ;

    var i , j ;

    var question_error = false ;

    var container_element ;

    // -----------------------------------------------------------------------

    for ( i=0 , j=innerHTML_insert_slash_replace_details_list.length ; i<j ; i++ ) {

        // -------------------------------------------------------------------
        // Get the object describing the current innerHTML container and
        // text...
        // -------------------------------------------------------------------

        this_innerHTML_details_object = innerHTML_insert_slash_replace_details_list[i] ;

        // -------------------------------------------------------------------
        // Check that object...
        // -------------------------------------------------------------------

        if (    wos1__validate_object(
                    this_innerHTML_details_object   ,
                    {   container_id    :   [   'required'  ,   'string'    , undefined ]   ,
                        innerHTML       :   [   'required'  ,   'string'    , undefined ]
                        }
                    )
            ) {

            question_error = true ;

            continue ;

            }

        // -------------------------------------------------------------------
        // Insert/replace the inner HTML...
        // -------------------------------------------------------------------

        // -----------------------------------------------------------------------
        // webos__get_document_object(
        //      target_window_object
        //      )
        // - - - - - - - - - - - - - -
        // Utility function to return the window's document object.
        //
        // If 'target_window_object' === null (the background web page), then
        // document is returned.
        //
        // Otherwise, document object for the document in the specified Webos
        // window's IFRAME is returned.
        // -----------------------------------------------------------------------

        container_element = webos__get_document_object(
                                target_window_object
                                ).getElementById( this_innerHTML_details_object.container_id ) ;

        // -------------------------------------------------------------------

        if ( !container_element ) {

            alert( "Bad 'container_id' (not found)!" +
                        "\n\nThe missing 'container_id' is:  " +
                        this_innerHTML_details_object.container_id +
                        software_bug__detected_in
                        ) ;

            question_error = true ;

            continue ;

            }

        // -------------------------------------------------------------------

        container_element.innerHTML = this_innerHTML_details_object.innerHTML ;

        // -------------------------------------------------------------------
        // Repeat with the next innerHTML container (if there is one)...
        // -------------------------------------------------------------------

        }

    // -----------------------------------------------------------------------
    // That's that!
    // -----------------------------------------------------------------------

    if ( question_error ) {
        return failed ;

    } else {
        return succeeded ;

        }

    // -----------------------------------------------------------------------

    }

// ===========================================================================
// TAB_select
// ===========================================================================

function TAB_select(
    target_window_object    ,
    id_of_tab_to_select
    ) {

    // -----------------------------------------------------------------------
    // TAB_select(
    //      target_window_object    ,
    //      id_of_tab_to_select
    //      )
    // - - - - - - - - - - - - - - -
    // Selects the specified tab - by showing that tab - and hiding all of
    // it's brothers and sisters.
    //
    // RETURNS:-
    //      true  = ERROR (error message issued)!
    //      false = Tab selected OK!
    // -----------------------------------------------------------------------

    // -----------------------------------------------------------------------
    // TAB
    // ---
    // A TAB's HTML/DOM looks like
    //
    //      <div id="xxx">      <-- 'Tab container' / 'notebook'
    //
    //          <div id="my_tab1">...innerHTML for tab1</div>
    //          <div id="my_tab2">...innerHTML for tab2</div>
    //          ...
    //          <div id="my_tabN">...innerHTML for tabN</div>
    //
    //      </div>
    //
    // -----------------------------------------------------------------------

    // -----------------------------------------------------------------------
    // Error handling...
    // -----------------------------------------------------------------------

    var software_bug__detected_in = wos1__software_bug__get_detected_in(
                                        "TAB_select"                            ,
                                        "standard_center_column_content.js"
                                        ) ;

    // -----------------------------------------------------------------------

    var succeeded = false ;
    var failed    = true  ;

    // -----------------------------------------------------------------------
    // Get the tab to select...
    // -----------------------------------------------------------------------

    // -----------------------------------------------------------------------
    // webos__get_document_object(
    //      target_window_object
    //      )
    // - - - - - - - - - - - - - -
    // Utility function to return the window's document object.
    //
    // If 'target_window_object' === null (the background web page), then
    // document is returned.
    //
    // Otherwise, document object for the document in the specified Webos
    // window's IFRAME is returned.
    // -----------------------------------------------------------------------

    var target_tab = webos__get_document_object(
                        target_window_object
                        ).getElementById( id_of_tab_to_select ) ;

    // -----------------------------------------------------------------------

    if ( !target_tab ) {

        alert( "Tab not found!" +
                    "\n\nThe missing tab id is:  " + id_of_tab_to_select +
                    software_bug__detected_in
                    ) ;

        return failed ;

        }

    // -----------------------------------------------------------------------
    // Get the target tab's parent/container...
    // -----------------------------------------------------------------------

    var tab_container = target_tab.parentNode ;

    // -----------------------------------------------------------------------

    if ( !tab_container ) {

        alert( "Tab container not found!" +
                    "\n\nThe id of the tab whoose container is missing is:  " + id_of_tab_to_select +
                    software_bug__detected_in
                    ) ;

        return failed ;

        }

    // -----------------------------------------------------------------------
    // Hide all the selected tab's siblings - and show the selected tab...
    // -----------------------------------------------------------------------

    var children = tab_container.childNodes ;

    var i , j ;

    // -----------------------------------------------------------------------

    for ( i=0 , j=children.length ; i<j ; i++ ) {

        if (    children[i].tagName
                &&
                children[i] !== target_tab
            ) {
            children[i].style.display = 'none' ;
            }

        }

    // -----------------------------------------------------------------------
    // Show the target tab...
    // -----------------------------------------------------------------------

    target_tab.style.display = 'block' ;

    // -----------------------------------------------------------------------
    // That's that!
    // -----------------------------------------------------------------------

    return succeeded ;

    // -----------------------------------------------------------------------

    }