// ***************************************************************************
// SITE/COOKIES/ISSUE_SELECTION_CRITERIA.JS
// (C) 2007 Peter Newman
// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
// 'Issue Selection Criteria' cookie support...
// ***************************************************************************

//  ==========================================================================
//  kiwiparty__get_issue_selection_criteria__raw_but_clean
//  ==========================================================================

function kiwiparty__get_issue_selection_criteria__raw_but_clean() {

    //  ----------------------------------------------------------------------
    //  kiwiparty__get_issue_selection_criteria__raw_but_clean()
    //  - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    //  Returns one of the following values:-
    //
    //      -1  :   There IS a COOKIE_NAME__ISSUE_SELECTION_CRITERIA cookie
    //              - but it has an INVALID VALUE.
    //
    //       0  :   There IS NO COOKIE_NAME__ISSUE_SELECTION_CRITERIA cookie.
    //
    //      <anything else> :
    //              There IS a COOKIE_NAME__ISSUE_SELECTION_CRITERIA cookie
    //              - and it has the VALID VALUE specified.  This will be a
    //              string (one of the 'short_name' field values from the:-
    //                  $GLOBAL[issue_selection_criteria]
    //              array.  See:-
    //                  "site/issues/issue_selection_criteria.php"
    //
    //  NOTE!
    //  -----
    //  This routine issues NO error messages.
    //  ----------------------------------------------------------------------

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

    var no_such_cookie       =  0 ;
    var invalid_cookie_value = -1 ;

    //  ----------------------------------------------------------------------
    //  The 'currently selected content type' is that defined by the:-
    //      COOKIE_NAME__ISSUE_SELECTION_CRITERIA
    //
    //  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_selection_criteria = quirksmode_readCookie(
                                        COOKIE_NAME__ISSUE_SELECTION_CRITERIA
                                        ) ;

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

    if ( !issue_selection_criteria ) {
        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_selection_criteria = processCookie(
                                        'issues'                                ,   //  cookieName
                                        'read'                                  ,   //  func
                                        COOKIE_NAME__ISSUE_SELECTION_CRITERIA       //  name
                                        ) ;

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

    if ( issue_selection_criteria === 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 selection criteria value:-
    //  o   Contains lowercase alphanumeric characters only,
    //  o   Is a 'short_name' from the:-
    //          $GLOBALS[issue_selection_criteria]
    //      array.
    //  ----------------------------------------------------------------------

    if ( /[^0-9a-z]/.test( issue_selection_criteria ) ) {
        return invalid_cookie_value ;
        }

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

/*
    //  -----------------------
    //  NOT YET IMPLEMENTED !!!
    //  -----------------------

    include_once( site_filespec( 'issues/issue_selection_criteria.php' ) ) ;

    // -----------------------------------------------------------------------
    // NOTE!
    // -----
    // The:-
    //      $GLOBALS[issue_selection_criteria]
    //
    // array is like:-
    //      array(
    //          array(
    //              'title'                     =>  'All'                           ,
    //              'long_name'                 =>  'all'                           ,
    //              'short_name'                =>  'all'                           ,
    //              'question_implemented'      =>  FALSE
    //              )
    //          ...
    //          }
    // -----------------------------------------------------------------------

    $not_found = TRUE ;

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

    foreach ( $GLOBALS[issue_selection_criteria] as $candidate ) {

        if ( $candidate[short_name] === $issue_selection_criteria ) {
            $not_found = FALSE ;
            break ;
            }

        }

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

    if ( $not_found ) {
        return $invalid_cookie_value ;
        }
*/

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

    return issue_selection_criteria ;

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

    }

//  ==========================================================================
//  kiwiparty__get_issue_selection_criteria__clean_and_simplified
//  ==========================================================================

function kiwiparty__get_issue_selection_criteria__clean_and_simplified() {

    //  ----------------------------------------------------------------------
    //  kiwiparty__get_issue_selection_criteria__clean_and_simplified()
    //  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    //  Returns the currently selected issue selection criteria.  Unless
    //  the issue selection criteria isn't defined, or is invalid, in
    //  which case the default issue selection criteria will be returned.
    //
    //  The currently selected issue selection criteria is determined from
    //  the:-
    //      COOKIE_NAME__ISSUE_SELECTION_CRITERIA
    //
    //  cookie (sent by the user's browser).
    //
    //  NOTE!
    //  ------
    //  This routine issues NO error messages.
    //  ----------------------------------------------------------------------

    var issue_selection_criteria = kiwiparty__get_issue_selection_criteria__raw_but_clean() ;

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

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

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

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

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

    }

//  ==========================================================================
//  kiwiparty__set_issue_selection_criteria
//  ==========================================================================

function kiwiparty__set_issue_selection_criteria( issue_selection_criteria ) {

    //  ----------------------------------------------------------------------
    //  kiwiparty__set_issue_selection_criteria( true|false )
    //  - - - - - - - - - - - - - - - - - - -
    //  Sets the:-
    //      COOKIE_NAME__QUESTION
    //
    //  cookie to either:-
    //      false ==> 0, or;
    //      true  ==> 1.
    //
    //  RETURNS
    //      Nothing
    //  ----------------------------------------------------------------------

/*
    hunlock_setCookie(
        COOKIE_NAME__ISSUE_SELECTION_CRITERIA   ,
        issue_selection_criteria                ,
        30                                      ,   //  30 days = 1 month
        COOKIE_PATH
        ) ;
*/

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

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

    }