// ***************************************************************************
// APPLICATION/COOKIES/ISSUE_EXPAND_COLLAPSE.JS
// (C) 2007 Peter Newman
// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
// 'Issue Expand/Collapse' cookie support...
// ***************************************************************************

//  ==========================================================================
//  kiwiparty__get_issue_expand_collapse__raw_but_clean
//  ==========================================================================

function kiwiparty__get_issue_expand_collapse__raw_but_clean() {

    //  ----------------------------------------------------------------------
    //  kiwiparty__get_issue_expand_collapse__raw_but_clean()
    //  - - - - - - - - - - - - - - - - - - - - - -
    //  Returns one of the following values:-
    //
    //      -1  :   There IS a COOKIE_NAME__ISSUE_EXPAND_COLLAPSE cookie
    //              - but it has an INVALID VALUE.
    //
    //       0  :   There IS NO COOKIE_NAME__ISSUE_EXPAND_COLLAPSE cookie.
    //
    //      'e' :   There IS a COOKIE_NAME__ISSUE_EXPAND_COLLAPSE cookie -
    //              and it has the VALID VALUE 'e' (= expand = show the
    //              'synopsis')
    //
    //      'c' :   There IS a COOKIE_NAME__ISSUE_EXPAND_COLLAPSE cookie -
    //              and it has the VALID VALUE 'c' (= collpase = DON'T
    //              show the 'synopsis')
    //
    //  NOTE!
    //  -----
    //  This routine issues NO error messages.
    //  ----------------------------------------------------------------------

    //  ----------------------------------------------------------------------
    //  Local variables...
    //  ----------------------------------------------------------------------

    var no_such_cookie       =  0 ;
    var invalid_cookie_value = -1 ;

    //  ----------------------------------------------------------------------
    //  The current issue expand/collapse setting is given by the
    //  value of the:-
    //      COOKIE_NAME__ISSUE_EXPAND_COLLAPSE
    //
    //  cookie (if there is one)...
    //  ----------------------------------------------------------------------

/*
    //  ----------------------------------------------------------------------
    // quirksmode_readCookie( name )
    // - - - - - - - - - - - - - - -
    // To read out a cookie, call this function and pass the name of the
    // cookie.  Put the returned value in a variable.  Then check if this
    // variable has a value (if the cookie does not exist the variable
    // becomes null, which might upset the rest of your function), then
    // do whatever is necessary.
    //
    // For example:-
    //      var x = quirksmode_readCookie('ppkcookie1')
    //      if (x) {
    //          [do something with x]
    //          }
    //  ----------------------------------------------------------------------

    var issue_expand_collapse = quirksmode_readCookie(
                                        COOKIE_NAME__ISSUE_EXPAND_COLLAPSE
                                        ) ;

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

    if ( !issue_expand_collapse ) {
        return no_such_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)!
    // ===========================================================================

    var issue_expand_collapse = processCookie(
                                    'issues'                            ,   //  cookieName
                                    'read'                              ,   //  func
                                    COOKIE_NAME__ISSUE_EXPAND_COLLAPSE      //  name
                                    ) ;

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

    if ( issue_expand_collapse === null ) {
        return no_such_cookie ;
        }

    //  ----------------------------------------------------------------------
    //  Watch out for hackers (the value just obtained was supplied over the
    //  NET - and might have been supplied by a hacker wishing to attack
    //  the site).
    //
    //  So, if the value is illegal/invalid, we return:-
    //      $invalid_cookie_value
    //
    //  NOTE!
    //  -----
    //  A valid issue expand_collapse value is either 'e' or 'c'.
    //  ----------------------------------------------------------------------

    if ( issue_expand_collapse !== 'e' && issue_expand_collapse !== 'c' ) {
        return invalid_cookie_value ;
        }

    // -----------------------------------------------------------------------
    // OK; the supplied cookie looks OK!
    //
    // So, we can return it's value...
    // -----------------------------------------------------------------------

    return issue_expand_collapse ;

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

    }

//  ==========================================================================
//  kiwiparty__get_issue_expand_collapse__clean_and_simplified
//  ==========================================================================

function kiwiparty__get_issue_expand_collapse__clean_and_simplified() {

    //  ----------------------------------------------------------------------
    //  kiwiparty__get_issue_expand_collapse__clean_and_simplified()
    //  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    //  Returns the current issue expand/collapse setting.  Unless that
    //  value isn't defined, or is invalid, in which case the default
    //  issue expand/collapse value ('c' = collapse) will be returned.
    //
    //  The current selected issue expand/collapse value is determined
    //  from the:-
    //      COOKIE_NAME__ISSUE_EXPAND_COLLAPSE
    //
    //  cookie (sent by the user's browser).
    //
    //  NOTE!
    //  ------
    //  This routine issues NO error messages.
    //  ----------------------------------------------------------------------

    var issue_expand_collapse = kiwiparty__get_issue_expand_collapse__raw_but_clean() ;

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

    if ( typeof( issue_expand_collapse ) === 'string' ) {
        return issue_expand_collapse ;
        }

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

    return 'c' ;
        // This is the default...

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

    }

//  ==========================================================================
//  kiwiparty__set_issue_expand_collapse
//  ==========================================================================

function kiwiparty__set_issue_expand_collapse( issue_expand_collapse ) {

    //  ----------------------------------------------------------------------
    //  kiwiparty__set_issue_expand_collapse( issue_expand_collapse )
    //  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    //  Sets the:-
    //      COOKIE_NAME__ISSUE_EXPAND_COLLAPSE
    //
    //  cookie.
    //
    //  issue_expand_collapse should be either:-
    //      'e' (= expand   = show the 'synopsis'), or;
    //      'c' (= collpase = DON'T show the 'synopsis').
    //
    //  RETURNS
    //      Nothing
    //  ----------------------------------------------------------------------

/*
    hunlock_setCookie(
        COOKIE_NAME__ISSUE_EXPAND_COLLAPSE    ,
        issue_expand_collapse                 ,
        30                          ,   //  30 days = 1 month
        COOKIE_PATH
        ) ;
*/

    processCookie(
        'issues'                            ,   //  cookieName
        'set'                               ,   //  func
        COOKIE_NAME__ISSUE_EXPAND_COLLAPSE  ,   //  name
        issue_expand_collapse               ,   //  value
        30                                      //  30 days = 1 month
        ) ;

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

    }