//**************************************************************************
//*
//* Version 1.0  01/01/2006
//* Version 1.1  09/05/2006 - correction of date picker details
//* Version 1.11 28/08/2006 - Array declarations changed to old style (= new Array()) instead of (= [])
//* Version 1.12 28/08/2006 - aum_cbt_check_required_fields rewritten and aum_cbt_check_suggested_fields added
//* Version 1.13 06/09/2006 - aum_cbt_putInOrder constructor and methods added
//* Version 1.14 07/09/2006 - separated out "overlib" block and increased data encapsulation of aum_cbt_putInOrder
//* Version 1.15 25/09/2006 - changed names to cbt.module convention 
//*
//* DOCUMENTATION FOR THE CBT JAVASCRIPT FUNCTION LIBRARY
//*
//* Copyright © 2006 Modulus Pty. Ltd.
//*
//**************************************************************************
//*
//* CBT-Specific Functions
//**************************************************************************
//*
//* These (high-level) functions should be directly useful to CBT developers 
//*
//**************************************************************************
//*
//* function cbt_putInOrder - OOP constructor for put-in-order questions
//***********************************************************************
//* @author prh
//* @version 2006 1.0
//* @param 
//* @return n/a 
//* @exception
//* @method .selectItem(theItem,formID,offset)
//* @method .promote(formID)
//* @method .promotePlus(formID)
//* @method .demote(formID, maxNdx)
//* @method .demotePlus(formID, maxNdx)
//*
//* @example var pio = new cbt_putInOrder();
//* function cbt_previous(pageURL) attempts to load the specified page into the current window
//***************************************************************************
//* @author prh
//* @version 2006 1.0
//* @param pageURL - URL of the page to open
//* @param 
//* @return true if successful, false for failure 
//* @exception
//*
//* @example cbt_previous('prior_page.html');
//* @example cbt_previous('http://somewhere.modulus.com.au/prior_page.html');
//*
//* function cbt_next(pageURL) attempts to load the specified page into the current window
//***********************************************************************
//* @author prh
//* @version 2006 1.0
//* @param pageURL - URL of the page to open
//* @param 
//* @return  true if successful, false for failure 
//* @exception
//*
//* @example cbt_next('next_page.html');
//* @example cbt_next('http://somewhere.modulus.com.au/next_page.html');
//*
//* function cbt_illustrate(imageURL,width,height) creates a new, pop-up window containing the specified image
//**************************************************************************************
//* @author prh
//* @version 2006 1.0
//* @param imageURL - URL of an image to be used as an illustration
//* @param width - [optional] parameter to control the width in pixels of the created window; defaults to globalDefaultWidth
//* @param height - [optional] parameter to control the height in pixels of the created window; defaults to globalDefaultHeight
//* @param 
//* @return 
//* @exception
//*
//* @example cbt_illustrate('images/toolbox.jpg');
//* @example cbt_illustrate('http://somewhere.modulus.com.au/images/toolbox.jpg');
//* @example cbt_illustrate('images/toolbox.jpg',250,150);
//*
//* function cbt_information(informationURL,width,height) opens a new window with the specified URL shown
//***********************************************************************************
//* @author prh
//* @version 2006 1.0
//* @param informationURL - URL of document containing information
//* @param width - [optional] parameter to control the width in pixels of the created window; defaults to globalDefaultWidth
//* @param height - [optional] parameter to control the height in pixels of the created window; defaults to globalDefaultHeight
//* @param 
//* @return 
//* @exception
//*
//* @example cbt_information('more_information.html');
//* @example cbt_information('http://somewhere.modulus.com.au/more_information.html');
//* @example cbt_information('more_information.html', 150, 250);
//*
//* function cbt_getRandomNFromM(n,m) returns a random selection size n from an array size m
//**************************************************************************
//* @author prh
//* @version 2006 1.0
//* @param n
//* @param m
//* @return an array, size n, comprising randomly selected elements from an m sized array
//* @exception
//*
//* @example cbt_getRandomNFromM(n,m) 
//*
//* function cbt_dateTime(formatStr) returns a string representing the current date and/or time
//**************************************************************************
//* @author prh
//* @version 2006 1.0
//* @param formatStr - [optional] string representing the format required
//* formatStr may include (case is important):
//* c - replaced by date e.g.31/12/2006
//* t - replaced by time e.g. 21:33:59
//* yyyy - replaced by 4-digit year e.g. 2006
//* yy - replaced by 2-digit year e.g. 06
//* mmmm - replaced by full month name e.g. January
//* mmm - replaced by 3-character month name e.g. Jan
//* mm - replaced by leading zero month number e.g. 03
//* m - replaced by month number e.g. 3
//* dddd - replaced by full day name e.g. Monday
//* ddd - replaced by 3-character day name e.g. Mon
//* dd - replaced by leading zero day of month e.g. 09
//* hh - replaced by leading zero hour e.g. 08
//* nn - replaced by leading zero minute e.g. 05
//* ss - replaced by leading zero second e.g. 05
//* ampm - replaced by AM or PM as appropriate
//* "xx/xx" - characters quoted in single or double quotes are displayed as is and do not affect formatting
//*
//* @param 
//* @return				The formatted date/time
//* @exception
//*
//* @example cbt_dateTime();
//* @example cbt_dateTime('dddd, dd/mm/yyyy hh:nn:ss ampm EST');
//*
//* function cbt_browserName() returns the name of the user's browser
//********************************************************
//* @author prh
//* @version 2006 1.0
//* @param 
//* @return The browser name as a string
//* @exception
//*
//* @example cbt_browserName();
//*
//* function cbt_browserVersion() returns the version of the user's browser
//***********************************************************
//* @author prh
//* @version 2006 1.0
//* @param 
//* @return The browser version as a string 
//* @exception
//*
//* @example cbt_browserVersion();
//*
//* function cbt_browserOS() returns the name of the user's Operating System
//*************************************************************
//* @author prh
//* @version 2006 1.0
//* @param 
//* @returnThe Operating System name as a string
//* @exception
//*
//* @example cbt_browserOS();
//*
//* function cbt_lastModified() shows the date on which the current HTML file was last modified
//**************************************************************************
//* @author prh
//* @version 2006 1.0
//* @param 
//* @return The date/time last modified as a string
//* @exception
//*
//* @example cbt_lasModified();
//*
//* function cbt_delay() casues a delay in processing
//******************************************
//* @author prh
//* @version 2006 1.0
//* @param ms - number of milliseconds to delay
//* @param 
//* @return true;
//* @exception
//*
//* @example cbt_delay();
//*
//* function cbt_check_suggested_fields() checks that a supplied list of fields all have entries 
//*************************************************************************
//* @author prh
//* @version 2006 1.0
//* @param frm - the current form (use this)
//* @param list - comma separated list of required input field names
//* @param 
//* @return true if all required fields filled, false otherwise
//* @exception
//*
//* @example OnSubmit = "return cbt_check_required_fields(this,'some_field,some_other');"
//*
//* function cbt_check_required_fields() checks that a supplied list of fields all have entries (before allowing form submission)
//************************************************************************************************
//* @author prh
//* @version 2006 1.0
//* @param frm - the current form (use this)
//* @param list - comma separated list of required input field names
//* @param 
//* @return true if all required fields filled, false otherwise
//* @exception
//*
//* @example OnSubmit = "return cbt_check_required_fields(this,'some_field,some_other');"
//*
//* function cbt_date_picker() allows interactive selection of a date
//*****************************************************
//* @author prh
//* @version 2006 1.0
//* @param ctrl - the name of the control to which the return value is applied as a string e.g. 'F1.Q8'
//* @param 
//* @return a date in 'DD-MM-YYYY' format
//* @exception
//*
//* @example cbt_date_picker('F_1.Q8');
//* function cbt_image_picker() allows interactive selection of an image from a series of images
//*************************************************************************
//* @author prh
//* @version 2006 1.0
//* @param ctrl - the name of the control to which the return value is applied as a string e.g. 'F1.Q8'
//* @param imageList - comma separated list of image names to include e.g. 'images/circle.gif,images/square.gif'
//* @return the stripped name of the selected image, e.g. 'circle'
//* @exception
//*
//* @example cbt_image_picker('F_1.Q9','images/circle.gif,images/square.gif');
//* function cbt_sound_picker() allows interactive selection of an sound from a series of sounds.
//*************************************************************************
//* @author prh
//* @version 2006 1.0
//* @param ctrl - the name of the control to which the return value is applied as a string e.g. 'F1.Q8'
//* @param soundList - comma separated list of sound names to include e.g. 'sounds/cork.au,sounds/ice.au'
//* @return the stripped name of the selected image, e.g. 'cork'
//* @exception
//*
//* @example cbt_sound_picker('F_1.Q9','sounds/cork.au,sounds/ice.au'); Note that when clicking on the sound to hear it,
//* @example the resultant action depends on how the user's browser and OS are configured.
//*
//* General & Generic Library functions
//**************************************************************************
//*
//* These functions are low-level functions, typically used by higher-level functions but which might 
//* be useful to a CBT developer in occassional circumstances.
//*
//**************************************************************************
//* function cbt_before(token,str) returns that part of str before token
//********************************************************
//* @author prh
//* @version 2006 1.0
//* @param token - a string to search for
//* @param str a string to search in
//* @return that part of str before the token
//* @exception
//*
//* @example cbt_before('/','images/circle.gif') returns 'images'
//*
//* function cbt_after(token,str) returns that part of str after token
//********************************************************
//* @author prh
//* @version 2006 1.0
//* @param token - a string to search for
//* @param str a string to search in
//* @return that part of str after the token
//* @exception
//*
//* @example cbt_after('/','images/circle.gif') returns 'circle.gif'
//*
//* function cbt_greater(a,b) returns the greater value of a and b
//****************************************************
//* @author prh
//* @version 2006 1.0
//* @param a - integer or real (or string)
//* @param b - integer or real (or string)
//* @return the greater of a and b
//* @exception
//*
//* @example cbt_greater(a,b);	
//*
//* function cbt_lesser(a,b) returns the lesser value of a and b
//****************************************************
//* @author prh
//* @version 2006 1.0
//* @param a - integer or real (or string)
//* @param b - integer or real (or string)
//* @return the greater of a and b
//* @exception
//*
//* @example cbt_lesser(a,b);	
//*
//* function cbt_trim(str) rtrims leading and trailing spaces from str
//*****************************************************
//* @author prh
//* @version 2006 1.0
//* @param str - string
//* @param 
//* @return str trimmed
//* @exception
//*
//* @example cbt_trim(' and ') returns 'and'	
//* function cbt_plural() returns the plural form of a string where appropriate
//************************************************************
//* @author prh
//* @version 2006 1.0
//* @param singularstr - singular form of string
//* @param pluralstr - plural form of string 
//* @param nr - integer number under consideration
//* @return str trimmed
//* @exception
//*
//* @example cbt_plural('datum','data',2) returns 'data'		
//*
//* function cbt_invert() returns its input reversed
//*****************************************
//* @author prh
//* @version 2006 1.0
//* @param str - string to be inverted
//* @return string
//*
//* @example str = cbt_invert("ABC") --> "CBA"
//*	
//* function cbt_replaceFirst() returns a string with the first occurrence of a specified string replaced
//******************************************************************************
//* @author prh
//* @version 2006 1.0
//* @param str - string to be operated on
//* @param what - string to search for
//* @param withWhat - replacement string
//* @return string
//*
//* @example cbt_replaceFirst("AABBBBBBBCC","BB","XX") --> "AAXXBBBBBCC"		
//*
//* function cbt_replaceAll() returns a string with all occurrences of a specified string replaced
//*************************************************************************
//* @author prh
//* @version 2006 1.0
//* @param str - string to be operated on
//* @param what - string to search for
//* @param withWhat - replacement string
//* @return string
//*
//* @example cbt_replaceAll("AABBBBBBBCC","BB","XX") --> "AAXXXXXXBCC"	
//*
//* function cbt_padWithStrRight() returns a string padded to a specified minimum length with a specified char or string
//*******************************************************************************************
//* @author prh
//* @version 2006 1.0
//* @param str - string to be operated on
//* @param nr - (minimum) resulting string length
//* @param withStr - padding string
//* @return string
//*		
//* @example cbt_padWithStrRight("ABC",4,"XXX"); --> "ABCXXX"
//*
//* function cbt_padWithStrLeft() returns a string left padded to a specified minimum length with a specified char or string
//**********************************************************************************************
//* @author prh
//* @version 2006 1.0
//* @param str - string to be operated on
//* @param nr - (minimum) resulting string length
//* @param withStr - padding string
//* @return string
//*		
//* @example cbt_padWithStrLeft("ABC",4,"XXX"); --> "XXXABC"
//*
//* function cbt_cookiesAvailable() returns true if cookies are available
//*******************************************************
//* @author prh
//* @version 2006 1.0
//* @param 
//* @return Boolean true or false
//*		
//* @example cbt_cookiesAvailable();		
//*
//* function cbt_getCookie() returns a cookie of a specified name
//****************************************************
//* @author prh
//* @version 2006 1.0
//* @param name - string representing the cookie to retrieve
//* @return Boolean true or false
//*		
//* @example cbt_getCookie('shazam');	
//*
//* function cbt_setCookie() sets a cookie with an expiry period
//**************************************************
//* @author prh
//* @version 2006 1.0
//* @param name - string representing the cookie to set
//* @param value - dtring representing value to set
//* @param daystoexpire - integer number of days until expiry
//* @return Boolean true or false
//*		
//* @example cbt_setCookie('shazam','123',99);
//*
//* function cbt_killCookie() kills a named cookie
//***************************************
//* @author prh
//* @version 2006 1.0
//* @param name - string representing the cookie to kill
//* @param 
//* @return N/A
//*		
//* @example cbt_killCookie('shazam');
//*
//* function cbt_version() returns our version
//************************************
//* @author prh
//* @version 2006 1.0
//* @return version string
//*		
//* @example cbt_killCookie('shazam');
//*