functions/options.php

   1 <?php
   2
   3 /**
   4  * options.php
   5  *
   6  * Functions needed to display the options pages.
   7  *
   8  * @copyright 1999-2017 The SquirrelMail Project Team
   9  * @license http://opensource.org/licenses/gpl-license.php GNU Public License
  10  * @version $Id$
  11  * @package squirrelmail
  12  * @subpackage prefs
  13  */
  14
  15 /**
  16  * SquirrelOption: An option for SquirrelMail.
  17  *
  18  * @package squirrelmail
  19  * @subpackage prefs
  20  */
  21 class SquirrelOption {
  22     /**
  23      * The original option configuration array
  24      * @var array
  25      */
  26     var $raw_option_array;
  27     /**
  28      * The name of this setting
  29      * @var string
  30      */
  31     var $name;
  32     /**
  33      * The text that prefaces setting on the preferences page
  34      * @var string
  35      */
  36     var $caption;
  37     /**
  38      * Whether or not the caption text is allowed to wrap
  39      * @var boolean
  40      */
  41     var $caption_wrap;
  42     /**
  43      * The type of INPUT element
  44      *
  45      * See SMOPT_TYPE_* defines
  46      * @var integer
  47      */
  48     var $type;
  49     /**
  50      * Indicates if a link should be shown to refresh part
  51      * or all of the window
  52      *
  53      * See SMOPT_REFRESH_* defines
  54      * @var integer
  55      */
  56     var $refresh_level;
  57     /**
  58      * Specifies the size of certain input items
  59      *
  60      * See SMOPT_SIZE_* defines
  61      * @var integer
  62      */
  63     var $size;
  64     /**
  65      * Text that follows a text input or
  66      * select list input on the preferences page
  67      *
  68      * useful for indicating units, meanings of special values, etc.
  69      * @var string
  70      */
  71     var $trailing_text;
  72     /**
  73      * Indicates that the widget's "trailing text"
  74      * should be displayed in a smaller sized font
  75      *
  76      * @var boolean
  77      */
  78     var $trailing_text_small;
  79     /**
  80      * Text that overrides the "Yes" label for boolean
  81      * radio option widgets
  82      *
  83      * @var string
  84      */
  85     var $yes_text;
  86     /**
  87      * Text that overrides the "No" label for boolean
  88      * radio option widgets
  89      *
  90      * @var string
  91      */
  92     var $no_text;
  93     /**
  94      * Some widgets support more than one layout type
  95      *
  96      * @var int
  97      */
  98     var $layout_type;
  99     /**
 100      * Indicates if the Add widget should be included
 101      * with edit lists.
 102      *
 103      * @var boolean
 104      */
 105     var $use_add_widget;
 106     /**
 107      * Indicates if the Delete widget should be included
 108      * with edit lists.
 109      *
 110      * @var boolean
 111      */
 112     var $use_delete_widget;
 113     /**
 114      * associative array, treated the same as $possible_values
 115      * (see its documentation below), but usually expected to
 116      * have its first value contain a list of IMAP folders, an
 117      * array itself in the format as passed back by
 118      * sqimap_mailbox_list(). Used to display folder selector
 119      * for possible values of an associative edit list option
 120      * widget
 121      *
 122      * @since 1.5.2
 123      * @var array
 124      */
 125     var $poss_value_folders;
 126     /**
 127      * text displayed to the user
 128      *
 129      * Used with SMOPT_TYPE_COMMENT options
 130      * @var string
 131      */
 132     var $comment;
 133     /**
 134      * additional javascript or other widget attributes added to the
 135      * user input; must be an array where keys are attribute names
 136      * ("onclick", etc) and values are the attribute values.
 137      * @var array
 138      */
 139     var $aExtraAttribs;
 140     /**
 141      * script (usually Javascript) that will be placed after (outside of)
 142      * the INPUT tag
 143      * @var string
 144      */
 145     var $post_script;
 146
 147     /**
 148      * The name of the Save Function for this option.
 149      * @var string
 150      */
 151     var $save_function;
 152
 153     /* The various 'values' for this options. */
 154     /**
 155      * default/preselected value for this option
 156      * @var mixed
 157      */
 158     var $value;
 159     /**
 160      * new option value
 161      * @var mixed
 162      */
 163     var $new_value;
 164     /**
 165      * associative array, where each key is an actual input value
 166      * and the corresponding value is what is displayed to the user
 167      * for that list item in the drop-down list
 168      * @var array
 169      */
 170     var $possible_values;
 171     /**
 172      * disables html sanitizing.
 173      *
 174      * WARNING - don't use it, if user input is possible in option
 175      * or use own sanitizing functions. Currently only works for SMOPT_TYPE_STRLIST.
 176      * @var bool
 177      */
 178     var $htmlencoded=false;
 179     /**
 180      * Controls folder list limits in SMOPT_TYPE_FLDRLIST and
 181      * SMOPT_TYPE_FLDRLIST_MULTI widgets as well as the optional
 182      * embedded folder lists provided for inputting values for
 183      * the SMOPT_TYPE_EDIT_LIST and SMOPT_TYPE_EDIT_LIST_ASSOCIATIVE
 184      * :idgets.
 185      * See $flag argument in sqimap_mailbox_option_list() function.
 186      * @var string
 187      * @since 1.5.1
 188      */
 189     var $folder_filter='noselect';
 190
 191     /**
 192      * Constructor (PHP5 style, required in some future version of PHP)
 193      * @param array $raw_option_array
 194      * @param string $name
 195      * @param string $caption
 196      * @param integer $type
 197      * @param integer $refresh_level
 198      * @param mixed $initial_value
 199      * @param array $possible_values
 200      * @param bool $htmlencoded
 201      */
 202     function __construct
 203     ($raw_option_array, $name, $caption, $type, $refresh_level, $initial_value = '', $possible_values = '', $htmlencoded = false) {
 204         /* Set the basic stuff. */
 205         $this->raw_option_array = $raw_option_array;
 206         $this->name = $name;
 207         $this->caption = $caption;
 208         $this->caption_wrap = TRUE;
 209         $this->type = $type;
 210         $this->refresh_level = $refresh_level;
 211         $this->possible_values = $possible_values;
 212         $this->htmlencoded = $htmlencoded;
 213         $this->size = SMOPT_SIZE_NORMAL;
 214         $this->trailing_text = '';
 215         $this->trailing_text_small = FALSE;
 216         $this->yes_text = '';
 217         $this->no_text = '';
 218         $this->comment = '';
 219         $this->layout_type = 0;
 220         $this->use_add_widget = TRUE;
 221         $this->use_delete_widget = TRUE;
 222         $this->poss_value_folders = '';
 223         $this->aExtraAttribs = array();
 224         $this->post_script = '';
 225
 226         //Check for a current value.
 227         if (isset($GLOBALS[$name])) {
 228             $this->value = $GLOBALS[$name];
 229         } else if (!empty($initial_value)) {
 230             $this->value = $initial_value;
 231         } else {
 232             $this->value = '';
 233         }
 234
 235         /* Check for a new value. */
 236         if ( !sqgetGlobalVar("new_$name", $this->new_value, SQ_POST ) ) {
 237             $this->new_value = NULL;
 238         }
 239
 240         /* Set the default save function. */
 241         if ($type != SMOPT_TYPE_HIDDEN
 242          && $type != SMOPT_TYPE_INFO
 243          && $type != SMOPT_TYPE_COMMENT) {
 244             $this->save_function = SMOPT_SAVE_DEFAULT;
 245         } else {
 246             $this->save_function = SMOPT_SAVE_NOOP;
 247         }
 248     }
 249
 250     /**
 251      * Constructor (PHP4 style, kept for compatibility reasons)
 252      * @param array $raw_option_array
 253      * @param string $name
 254      * @param string $caption
 255      * @param integer $type
 256      * @param integer $refresh_level
 257      * @param mixed $initial_value
 258      * @param array $possible_values
 259      * @param bool $htmlencoded
 260      */
 261     function SquirrelOption
 262     ($raw_option_array, $name, $caption, $type, $refresh_level, $initial_value = '', $possible_values = '', $htmlencoded = false) {
 263         self::__construct($raw_option_array, $name, $caption, $type, $refresh_level, $initial_value, $possible_values, $htmlencoded);
 264     }
 265
 266     /** Convenience function that identifies which types of
 267         widgets are stored as (serialized) array values. */
 268     function is_multiple_valued() {
 269         return ($this->type == SMOPT_TYPE_FLDRLIST_MULTI
 270              || $this->type == SMOPT_TYPE_STRLIST_MULTI
 271              || $this->type == SMOPT_TYPE_EDIT_LIST
 272              || $this->type == SMOPT_TYPE_EDIT_LIST_ASSOCIATIVE);
 273     }
 274
 275     /**
 276      * Set the value for this option.
 277      * @param mixed $value
 278      */
 279     function setValue($value) {
 280         $this->value = $value;
 281     }
 282
 283     /**
 284      * Set the new value for this option.
 285      * @param mixed $new_value
 286      */
 287     function setNewValue($new_value) {
 288         $this->new_value = $new_value;
 289     }
 290
 291     /**
 292      * Set whether the caption is allowed to wrap for this option.
 293      * @param boolean $caption_wrap
 294      */
 295     function setCaptionWrap($caption_wrap) {
 296         $this->caption_wrap = $caption_wrap;
 297     }
 298
 299     /**
 300      * Set the size for this option.
 301      * @param integer $size
 302      */
 303     function setSize($size) {
 304         $this->size = $size;
 305     }
 306
 307     /**
 308      * Set the trailing_text for this option.
 309      * @param string $trailing_text
 310      */
 311     function setTrailingText($trailing_text) {
 312         $this->trailing_text = $trailing_text;
 313     }
 314
 315     /**
 316      * Set the trailing_text for this option.
 317      * @param string $trailing_text
 318      */
 319     function setTrailingTextSmall($trailing_text_small) {
 320         $this->trailing_text_small = $trailing_text_small;
 321     }
 322
 323     /**
 324      * Set the yes_text for this option.
 325      * @param string $yes_text
 326      */
 327     function setYesText($yes_text) {
 328         $this->yes_text = $yes_text;
 329     }
 330
 331     /**
 332      * Set the no_text for this option.
 333      * @param string $no_text
 334      */
 335     function setNoText($no_text) {
 336         $this->no_text = $no_text;
 337     }
 338
 339     /* Set the "use add widget" value for this option. */
 340     function setUseAddWidget($use_add_widget) {
 341         $this->use_add_widget = $use_add_widget;
 342     }
 343
 344     /* Set the "use delete widget" value for this option. */
 345     function setUseDeleteWidget($use_delete_widget) {
 346         $this->use_delete_widget = $use_delete_widget;
 347     }
 348
 349     /* Set the "poss value folders" value for this option.
 350        See the associative edit list widget, which uses this
 351        to offer folder list selection for the values */
 352     function setPossValueFolders($poss_value_folders) {
 353         $this->poss_value_folders = $poss_value_folders;
 354     }
 355
 356     /**
 357      * Set the layout type for this option.
 358      * @param int $layout_type
 359      */
 360     function setLayoutType($layout_type) {
 361         $this->layout_type = $layout_type;
 362     }
 363
 364     /**
 365      * Set the comment for this option.
 366      * @param string $comment
 367      */
 368     function setComment($comment) {
 369         $this->comment = $comment;
 370     }
 371
 372     /**
 373      * Set the extra attributes for this option.
 374      * @param array $aExtraAttribs
 375      */
 376     function setExtraAttributes($aExtraAttribs) {
 377         $this->aExtraAttribs = $aExtraAttribs;
 378     }
 379
 380     /**
 381      * Set the "post script" for this option.
 382      * @param string $post_script
 383      */
 384     function setPostScript($post_script) {
 385         $this->post_script = $post_script;
 386     }
 387
 388     /**
 389      * Set the save function for this option.
 390      * @param string $save_function
 391      */
 392     function setSaveFunction($save_function) {
 393         $this->save_function = $save_function;
 394     }
 395
 396     /**
 397      * Set the folder_filter for this option.
 398      * @param string $folder_filter
 399      * @since 1.5.1
 400      */
 401     function setFolderFilter($folder_filter) {
 402         $this->folder_filter = $folder_filter;
 403     }
 404
 405     /**
 406      * Creates fields on option pages according to option type
 407      *
 408      * This is the function that calls all other createWidget* functions.
 409      *
 410      * @return string The formated option field
 411      *
 412      */
 413     function createWidget() {
 414         global $color;
 415
 416         // Use new value if available
 417         if (!is_null($this->new_value)) {
 418             $tempValue = $this->value;
 419             $this->value = $this->new_value;
 420         }
 421
 422         /* Get the widget for this option type. */
 423         switch ($this->type) {
 424             case SMOPT_TYPE_PASSWORD:
 425                 $result = $this->createWidget_String(TRUE);
 426                 break;
 427             case SMOPT_TYPE_STRING:
 428                 $result = $this->createWidget_String();
 429                 break;
 430             case SMOPT_TYPE_STRLIST:
 431                 $result = $this->createWidget_StrList();
 432                 break;
 433             case SMOPT_TYPE_TEXTAREA:
 434                 $result = $this->createWidget_TextArea();
 435                 break;
 436             case SMOPT_TYPE_INTEGER:
 437                 $result = $this->createWidget_Integer();
 438                 break;
 439             case SMOPT_TYPE_FLOAT:
 440                 $result = $this->createWidget_Float();
 441                 break;
 442             case SMOPT_TYPE_BOOLEAN:
 443                 $result = $this->createWidget_Boolean();
 444                 break;
 445             case SMOPT_TYPE_BOOLEAN_CHECKBOX:
 446                 $result = $this->createWidget_Boolean(TRUE);
 447                 break;
 448             case SMOPT_TYPE_BOOLEAN_RADIO:
 449                 $result = $this->createWidget_Boolean(FALSE);
 450                 break;
 451             case SMOPT_TYPE_HIDDEN:
 452                 $result = $this->createWidget_Hidden();
 453                 break;
 454             case SMOPT_TYPE_COMMENT:
 455                 $result = $this->createWidget_Comment();
 456                 break;
 457             case SMOPT_TYPE_FLDRLIST:
 458                 $result = $this->createWidget_FolderList();
 459                 break;
 460             case SMOPT_TYPE_FLDRLIST_MULTI:
 461                 $result = $this->createWidget_FolderList(TRUE);
 462                 break;
 463             case SMOPT_TYPE_EDIT_LIST:
 464                 $result = $this->createWidget_EditList();
 465                 break;
 466             case SMOPT_TYPE_EDIT_LIST_ASSOCIATIVE:
 467                 $result = $this->createWidget_EditListAssociative();
 468                 break;
 469             case SMOPT_TYPE_STRLIST_MULTI:
 470                 $result = $this->createWidget_StrList(TRUE);
 471                 break;
 472             case SMOPT_TYPE_STRLIST_RADIO:
 473                 $result = $this->createWidget_StrList(FALSE, TRUE);
 474                 break;
 475             case SMOPT_TYPE_SUBMIT:
 476                 $result = $this->createWidget_Submit();
 477                 break;
 478             case SMOPT_TYPE_INFO:
 479                 $result = $this->createWidget_Info();
 480                 break;
 481             default:
 482                 error_box (
 483                     sprintf(_("Option Type '%s' Not Found"), $this->type)
 484                     );
 485         }
 486
 487         /* Add the "post script" for this option. */
 488         $result .= $this->post_script;
 489
 490         // put correct value back if need be
 491         if (!is_null($this->new_value)) {
 492             $this->value = $tempValue;
 493         }
 494
 495         /* Now, return the created widget. */
 496         return $result;
 497     }
 498
 499     /**
 500      * Creates info block
 501      * @return string html formated output
 502      */
 503     function createWidget_Info() {
 504         // return sq_htmlspecialchars($this->value);
 505         // like COMMENT, allow HTML here
 506         return $this->value;
 507     }
 508
 509     /**
 510      * Create string field
 511      *
 512      * @param boolean $password When TRUE, the text in the input
 513      *                          widget will be obscured (OPTIONAL;
 514      *                          default = FALSE).
 515      *
 516      * @return string html formated option field
 517      *
 518      */
 519     function createWidget_String($password=FALSE) {
 520         switch ($this->size) {
 521             case SMOPT_SIZE_TINY:
 522                 $width = 5;
 523                 break;
 524             case SMOPT_SIZE_SMALL:
 525                 $width = 12;
 526                 break;
 527             case SMOPT_SIZE_LARGE:
 528                 $width = 38;
 529                 break;
 530             case SMOPT_SIZE_HUGE:
 531                 $width = 50;
 532                 break;
 533             case SMOPT_SIZE_NORMAL:
 534             default:
 535                 $width = 25;
 536         }
 537
 538 //TODO: might be better to have a separate template file for all widgets, because then the layout of the widget and the "trailing text" can be customized - they are still hard coded here (also, we have <small> tags here; don't want HTML here!)
 539         if ($password)
 540             return addPwField('new_' . $this->name, $this->value, $width, 0, $this->aExtraAttribs) . ' ' . ($this->trailing_text_small ? '<small>' : '') . sm_encode_html_special_chars($this->trailing_text) . ($this->trailing_text_small ? '</small>' : '');
 541         else
 542             return addInput('new_' . $this->name, $this->value, $width, 0, $this->aExtraAttribs) . ' ' . ($this->trailing_text_small ? '<small>' : '') . sm_encode_html_special_chars($this->trailing_text) . ($this->trailing_text_small ? '</small>' : '');
 543     }
 544
 545     /**
 546      * Create selection box or radio button group
 547      *
 548      * When $this->htmlencoded is TRUE, the keys and values in
 549      * $this->possible_values are assumed to be display-safe.
 550      * Use with care!
 551      *
 552      * Note that when building radio buttons instead of a select
 553      * widget, if the "size" attribute is SMOPT_SIZE_TINY, the
 554      * radio buttons will be output one after another without
 555      * linebreaks between them.  Otherwise, each radio button
 556      * goes on a line of its own.
 557      *
 558      * @param boolean $multiple_select When TRUE, the select widget
 559      *                                 will allow multiple selections
 560      *                                 (OPTIONAL; default is FALSE
 561      *                                 (single select list))
 562      * @param boolean $radio_buttons   When TRUE, the widget will
 563      *                                 instead be built as a group
 564      *                                 of radio buttons (and
 565      *                                 $multiple_select will be
 566      *                                 forced to FALSE) (OPTIONAL;
 567      *                                 default is FALSE (select widget))
 568      *
 569      * @return string html formated selection box or radio buttons
 570      *
 571      */
 572     function createWidget_StrList($multiple_select=FALSE, $radio_buttons=FALSE) {
 573 //FIXME: Currently, $this->htmlencoded is ignored here -- was removed when changing to template-based output; a fix is available as part of proposed centralized sanitizing patch
 574
 575         // radio buttons instead of select widget?
 576         //
 577         if ($radio_buttons) {
 578
 579             global $br, $nbsp;
 580             $result = '';
 581             foreach ($this->possible_values as $real_value => $disp_value) {
 582                 $result .= addRadioBox('new_' . $this->name, ($this->value == $real_value), $real_value, array_merge(array('id' => 'new_' . $this->name . '_' . $real_value), $this->aExtraAttribs)) . $nbsp . create_label($disp_value, 'new_' . $this->name . '_' . $real_value);
 583                 if ($this->size != SMOPT_SIZE_TINY)
 584                     $result .= $br;
 585             }
 586
 587             return $result;
 588         }
 589
 590
 591         // everything below applies to select widgets
 592         //
 593         switch ($this->size) {
 594 //FIXME: not sure about these sizes... seems like we could add another on the "large" side...
 595             case SMOPT_SIZE_TINY:
 596                 $height = 3;
 597                 break;
 598             case SMOPT_SIZE_SMALL:
 599                 $height = 8;
 600                 break;
 601             case SMOPT_SIZE_LARGE:
 602                 $height = 15;
 603                 break;
 604             case SMOPT_SIZE_HUGE:
 605                 $height = 25;
 606                 break;
 607             case SMOPT_SIZE_NORMAL:
 608             default:
 609                 $height = 5;
 610         }
 611
 612         return addSelect('new_' . $this->name, $this->possible_values, $this->value, TRUE, $this->aExtraAttribs, $multiple_select, $height, !$this->htmlencoded) . ($this->trailing_text_small ? '<small>' : '') . sm_encode_html_special_chars($this->trailing_text) . ($this->trailing_text_small ? '</small>' : '');
 613
 614     }
 615
 616     /**
 617      * Create folder selection box
 618      *
 619      * @param boolean $multiple_select When TRUE, the select widget
 620      *                                 will allow multiple selections
 621      *                                 (OPTIONAL; default is FALSE
 622      *                                 (single select list))
 623      *
 624      * @return string html formated selection box
 625      *
 626      */
 627     function createWidget_FolderList($multiple_select=FALSE) {
 628
 629         switch ($this->size) {
 630 //FIXME: not sure about these sizes... seems like we could add another on the "large" side...
 631             case SMOPT_SIZE_TINY:
 632                 $height = 3;
 633                 break;
 634             case SMOPT_SIZE_SMALL:
 635                 $height = 8;
 636                 break;
 637             case SMOPT_SIZE_LARGE:
 638                 $height = 15;
 639                 break;
 640             case SMOPT_SIZE_HUGE:
 641                 $height = 25;
 642                 break;
 643             case SMOPT_SIZE_NORMAL:
 644             default:
 645                 $height = 5;
 646         }
 647
 648         // possible values might include a nested array of
 649         // possible values (list of folders)
 650         //
 651         $option_list = array();
 652         foreach ($this->possible_values as $value => $text) {
 653
 654             // list of folders (boxes array)
 655             //
 656             if (is_array($text)) {
 657               $option_list = array_merge($option_list, sqimap_mailbox_option_array(0, 0, $text, $this->folder_filter));
 658
 659             // just one option here
 660             //
 661             } else {
 662               $option_list = array_merge($option_list, array($value => $text));
 663             }
 664
 665         }
 666         if (empty($option_list))
 667             $option_list = array('ignore' => _("unavailable"));
 668
 669
 670         return addSelect('new_' . $this->name, $option_list, $this->value, TRUE, $this->aExtraAttribs, $multiple_select, $height) . ($this->trailing_text_small ? '<small>' : '') . sm_encode_html_special_chars($this->trailing_text) . ($this->trailing_text_small ? '</small>' : '');
 671
 672     }
 673
 674     /**
 675      * Creates textarea
 676      * @return string html formated textarea field
 677      */
 678     function createWidget_TextArea() {
 679         switch ($this->size) {
 680             case SMOPT_SIZE_TINY:  $rows = 3; $cols =  10; break;
 681             case SMOPT_SIZE_SMALL: $rows = 4; $cols =  30; break;
 682             case SMOPT_SIZE_LARGE: $rows = 10; $cols =  60; break;
 683             case SMOPT_SIZE_HUGE:  $rows = 20; $cols =  80; break;
 684             case SMOPT_SIZE_NORMAL:
 685             default: $rows = 5; $cols =  50;
 686         }
 687         return addTextArea('new_' . $this->name, $this->value, $cols, $rows, $this->aExtraAttribs);
 688     }
 689
 690     /**
 691      * Creates field for integer
 692      *
 693      * Difference from createWidget_String is visible only when javascript is enabled
 694      * @return string html formated option field
 695      */
 696     function createWidget_Integer() {
 697
 698         // add onChange javascript handler to a regular string widget
 699         // which will strip out all non-numeric chars
 700         if (checkForJavascript())
 701            $this->aExtraAttribs['onchange'] = 'origVal=this.value; newVal=\'\'; '
 702                     . 'for (i=0;i<origVal.length;i++) { if (origVal.charAt(i)>=\'0\' '
 703                     . '&& origVal.charAt(i)<=\'9\') newVal += origVal.charAt(i); } '
 704                     . 'this.value=newVal;';
 705
 706         return $this->createWidget_String();
 707     }
 708
 709     /**
 710      * Creates field for floating number
 711      * Difference from createWidget_String is visible only when javascript is enabled
 712      * @return string html formated option field
 713      */
 714     function createWidget_Float() {
 715
 716         // add onChange javascript handler to a regular string widget
 717         // which will strip out all non-numeric (period also OK) chars
 718         if (checkForJavascript())
 719            $this->aExtraAttribs['onchange'] = 'origVal=this.value; newVal=\'\'; '
 720                     . 'for (i=0;i<origVal.length;i++) { if ((origVal.charAt(i)>=\'0\' '
 721                     . '&& origVal.charAt(i)<=\'9\') || origVal.charAt(i)==\'.\') '
 722                     . 'newVal += origVal.charAt(i); } this.value=newVal;';
 723
 724         return $this->createWidget_String();
 725     }
 726
 727     /**
 728      * Create boolean widget
 729      *
 730      * When creating Yes/No radio buttons, the "yes_text"
 731      * and "no_text" option attributes are used to override
 732      * the typical "Yes" and "No" text.
 733      *
 734      * @param boolean $checkbox When TRUE, the widget will be
 735      *                          constructed as a checkbox,
 736      *                          otherwise it will be a set of
 737      *                          Yes/No radio buttons (OPTIONAL;
 738      *                          default is TRUE (checkbox)).
 739      *
 740      * @return string html formated boolean widget
 741      *
 742      */
 743     function createWidget_Boolean($checkbox=TRUE) {
 744
 745         global $oTemplate, $nbsp;
 746
 747
 748         // checkbox...
 749         //
 750         if ($checkbox) {
 751             $result = addCheckbox('new_' . $this->name, ($this->value != SMPREF_NO), SMPREF_YES, array_merge(array('id' => 'new_' . $this->name), $this->aExtraAttribs)) . $nbsp . create_label(($this->trailing_text_small ? '<small>' : '') . $this->trailing_text . ($this->trailing_text_small ? '</small>' : ''), 'new_' . $this->name);
 752         }
 753
 754         // radio buttons...
 755         //
 756         else {
 757
 758             /* Build the yes choice. */
 759             $yes_option = addRadioBox('new_' . $this->name, ($this->value != SMPREF_NO), SMPREF_YES, array_merge(array('id' => 'new_' . $this->name . '_yes'), $this->aExtraAttribs)) . $nbsp . create_label((!empty($this->yes_text) ? $this->yes_text : _("Yes")), 'new_' . $this->name . '_yes');
 760
 761             /* Build the no choice. */
 762             $no_option = addRadioBox('new_' . $this->name, ($this->value == SMPREF_NO), SMPREF_NO, array_merge(array('id' => 'new_' . $this->name . '_no'), $this->aExtraAttribs)) . $nbsp . create_label((!empty($this->no_text) ? $this->no_text : _("No")), 'new_' . $this->name . '_no');
 763
 764             /* Build the combined "boolean widget". */
 765             $result = "$yes_option$nbsp$nbsp$nbsp$nbsp$no_option";
 766
 767         }
 768
 769         return ($result);
 770     }
 771
 772     /**
 773      * Creates hidden field
 774      * @return string html formated hidden input field
 775      */
 776     function createWidget_Hidden() {
 777         return addHidden('new_' . $this->name, $this->value, $this->aExtraAttribs);
 778     }
 779
 780     /**
 781      * Creates comment
 782      * @return string comment
 783      */
 784     function createWidget_Comment() {
 785         $result = $this->comment;
 786         return ($result);
 787     }
 788
 789     /**
 790      * Creates a (non-associative) edit list
 791      *
 792      * Note that multiple layout types are supported for this widget.
 793      * $this->layout_type must be one of the SMOPT_EDIT_LIST_LAYOUT_*
 794      * constants.
 795      *
 796      * @return string html formated list of edit fields and
 797      *                their associated controls
 798      */
 799     function createWidget_EditList() {
 800
 801         global $oTemplate;
 802
 803         switch ($this->size) {
 804             case SMOPT_SIZE_TINY:
 805                 $height = 3;
 806                 break;
 807             case SMOPT_SIZE_SMALL:
 808                 $height = 8;
 809                 break;
 810             case SMOPT_SIZE_MEDIUM:
 811                 $height = 15;
 812                 break;
 813             case SMOPT_SIZE_LARGE:
 814                 $height = 25;
 815                 break;
 816             case SMOPT_SIZE_HUGE:
 817                 $height = 40;
 818                 break;
 819             case SMOPT_SIZE_NORMAL:
 820             default:
 821                 $height = 5;
 822         }
 823
 824         if (empty($this->possible_values)) $this->possible_values = array();
 825         if (!is_array($this->possible_values)) $this->possible_values = array($this->possible_values);
 826
 827 //FIXME: $this->aExtraAttribs probably should only be used in one place
 828         $oTemplate->assign('input_widget', addInput('add_' . $this->name, '', 38, 0, $this->aExtraAttribs));
 829         $oTemplate->assign('use_input_widget', $this->use_add_widget);
 830         $oTemplate->assign('use_delete_widget', $this->use_delete_widget);
 831
 832         $oTemplate->assign('trailing_text', $this->trailing_text);
 833         $oTemplate->assign('trailing_text_small', $this->trailing_text_small);
 834         $oTemplate->assign('possible_values', $this->possible_values);
 835         $oTemplate->assign('current_value', $this->value);
 836         $oTemplate->assign('select_widget', addSelect('new_' . $this->name, $this->possible_values, $this->value, FALSE, !checkForJavascript() ? $this->aExtraAttribs : array_merge(array('onchange' => 'if (typeof(window.addinput_' . $this->name . ') == \'undefined\') { var f = document.forms.length; var i = 0; var pos = -1; while( pos == -1 && i < f ) { var e = document.forms[i].elements.length; var j = 0; while( pos == -1 && j < e ) { if ( document.forms[i].elements[j].type == \'text\' && document.forms[i].elements[j].name == \'add_' . $this->name . '\' ) { pos = j; i=f-1; j=e-1; } j++; } i++; } if( pos >= 0 ) { window.addinput_' . $this->name . ' = document.forms[i-1].elements[pos]; } } for (x = 0; x < this.length; x++) { if (this.options[x].selected) { window.addinput_' . $this->name . '.value = this.options[x].text; break; } }'), $this->aExtraAttribs), TRUE, $height));
 837 // NOTE: i=f-1; j=e-1 is in lieu of break 2
 838         $oTemplate->assign('checkbox_widget', addCheckBox('delete_' . $this->name, FALSE, SMPREF_YES, array_merge(array('id' => 'delete_' . $this->name), $this->aExtraAttribs)));
 839         $oTemplate->assign('name', $this->name);
 840
 841         switch ($this->layout_type) {
 842             case SMOPT_EDIT_LIST_LAYOUT_SELECT:
 843                 return $oTemplate->fetch('edit_list_widget.tpl');
 844             case SMOPT_EDIT_LIST_LAYOUT_LIST:
 845                 return $oTemplate->fetch('edit_list_widget_list_style.tpl');
 846             default:
 847                 error_box(sprintf(_("Edit List Layout Type '%s' Not Found"), $this->layout_type));
 848         }
 849
 850     }
 851
 852     /**
 853      * Creates an associative edit list
 854      *
 855      * Note that multiple layout types are supported for this widget.
 856      * $this->layout_type must be one of the SMOPT_EDIT_LIST_LAYOUT_*
 857      * constants.
 858      *
 859      * @return string html formated list of edit fields and
 860      *                their associated controls
 861      */
 862     function createWidget_EditListAssociative() {
 863
 864         global $oTemplate;
 865
 866         switch ($this->size) {
 867             case SMOPT_SIZE_TINY:
 868                 $height = 3;
 869                 break;
 870             case SMOPT_SIZE_SMALL:
 871                 $height = 8;
 872                 break;
 873             case SMOPT_SIZE_MEDIUM:
 874                 $height = 15;
 875                 break;
 876             case SMOPT_SIZE_LARGE:
 877                 $height = 25;
 878                 break;
 879             case SMOPT_SIZE_HUGE:
 880                 $height = 40;
 881                 break;
 882             case SMOPT_SIZE_NORMAL:
 883             default:
 884                 $height = 5;
 885         }
 886
 887
 888         // ensure correct format of current value(s)
 889         //
 890         if (empty($this->possible_values)) $this->possible_values = array();
 891         if (!is_array($this->possible_values)) $this->possible_values = array($this->possible_values);
 892
 893
 894         $oTemplate->assign('name', $this->name);
 895         $oTemplate->assign('current_value', $this->value);
 896         $oTemplate->assign('possible_values', $this->possible_values);
 897         $oTemplate->assign('poss_value_folders', $this->poss_value_folders);
 898         $oTemplate->assign('folder_filter', $this->folder_filter);
 899
 900         $oTemplate->assign('use_input_widget', $this->use_add_widget);
 901         $oTemplate->assign('use_delete_widget', $this->use_delete_widget);
 902
 903         $oTemplate->assign('checkbox_widget', addCheckBox('delete_' . $this->name, FALSE, SMPREF_YES, array_merge(array('id' => 'delete_' . $this->name), $this->aExtraAttribs)));
 904
 905 //FIXME: $this->aExtraAttribs probably should only be used in one place
 906         $oTemplate->assign('input_key_widget', addInput('add_' . $this->name . '_key', '', 22, 0, $this->aExtraAttribs));
 907         $oTemplate->assign('input_value_widget', addInput('add_' . $this->name . '_value', '', 12, 0, $this->aExtraAttribs));
 908
 909         $oTemplate->assign('select_height', $height);
 910
 911         $oTemplate->assign('aAttribs', $this->aExtraAttribs);
 912
 913         $oTemplate->assign('trailing_text', $this->trailing_text);
 914         $oTemplate->assign('trailing_text_small', $this->trailing_text_small);
 915
 916         switch ($this->layout_type) {
 917             case SMOPT_EDIT_LIST_LAYOUT_SELECT:
 918                 return $oTemplate->fetch('edit_list_associative_widget.tpl');
 919             case SMOPT_EDIT_LIST_LAYOUT_LIST:
 920                 return $oTemplate->fetch('edit_list_associative_widget_list_style.tpl');
 921             default:
 922                 error_box(sprintf(_("Associative Edit List Layout Type '%s' Not Found"), $this->layout_type));
 923         }
 924
 925     }
 926
 927     /**
 928      * Creates a submit button
 929      *
 930      * @return string html formated submit button widget
 931      *
 932      */
 933     function createWidget_Submit() {
 934
 935         return addSubmit($this->comment, $this->name, $this->aExtraAttribs) . ($this->trailing_text_small ? '<small>' : '') . sm_encode_html_special_chars($this->trailing_text) . ($this->trailing_text_small ? '</small>' : '');
 936
 937     }
 938
 939     /**
 940      *
 941      */
 942     function save() {
 943         $function = $this->save_function;
 944         $function($this);
 945     }
 946
 947     /**
 948      *
 949      */
 950     function changed() {
 951
 952         // edit lists have a lot going on, so we'll always process them
 953         //
 954         if ($this->type == SMOPT_TYPE_EDIT_LIST
 955          || $this->type == SMOPT_TYPE_EDIT_LIST_ASSOCIATIVE)
 956             return TRUE;
 957
 958         return ($this->value != $this->new_value);
 959     }
 960 } /* End of SquirrelOption class*/
 961
 962 /**
 963  * Saves the option value (this is the default save function
 964  * unless overridden by the user)
 965  *
 966  * @param object $option object that holds option name and new_value
 967  */
 968 function save_option($option) {
 969
 970     // Can't save the pref if we don't have the username
 971     //
 972     if ( !sqgetGlobalVar('username', $username, SQ_SESSION ) ) {
 973         return;
 974     }
 975
 976     // if the widget is a selection list, make sure the new
 977     // value is actually in the selection list and is not an
 978     // injection attack
 979     //
 980     if ($option->type == SMOPT_TYPE_STRLIST
 981      && !array_key_exists($option->new_value, $option->possible_values))
 982         return;
 983
 984
 985     // all other widgets except TEXTAREAs should never be allowed to have newlines
 986     //
 987     else if ($option->type != SMOPT_TYPE_TEXTAREA)
 988         $option->new_value = str_replace(array("\r", "\n"), '', $option->new_value);
 989
 990
 991     global $data_dir;
 992
 993     // edit lists: first add new elements to list, then
 994     // remove any selected ones (note that we must add
 995     // before deleting because the javascript that populates
 996     // the "add" textbox when selecting items in the list
 997     // (for deletion))
 998     //
 999     if ($option->type == SMOPT_TYPE_EDIT_LIST) {
1000
1001         if (empty($option->possible_values)) $option->possible_values = array();
1002         if (!is_array($option->possible_values)) $option->possible_values = array($option->possible_values);
1003
1004         // add element if given
1005         //
1006         if ((isset($option->use_add_widget) && $option->use_add_widget)
1007          && sqGetGlobalVar('add_' . $option->name, $new_element, SQ_POST)) {
1008             $new_element = trim($new_element);
1009             if (!empty($new_element)
1010              && !in_array($new_element, $option->possible_values))
1011                 $option->possible_values[] = $new_element;
1012         }
1013
1014         // delete selected elements if needed
1015         //
1016         if ((isset($option->use_delete_widget) && $option->use_delete_widget)
1017          && is_array($option->new_value)
1018          && sqGetGlobalVar('delete_' . $option->name, $ignore, SQ_POST))
1019             $option->possible_values = array_diff($option->possible_values, $option->new_value);
1020
1021         // save full list (stored in "possible_values")
1022         //
1023         setPref($data_dir, $username, $option->name, serialize($option->possible_values));
1024
1025     // associative edit lists are handled similar to
1026     // non-associative ones
1027     //
1028     } else if ($option->type == SMOPT_TYPE_EDIT_LIST_ASSOCIATIVE) {
1029
1030         if (empty($option->possible_values)) $option->possible_values = array();
1031         if (!is_array($option->possible_values)) $option->possible_values = array($option->possible_values);
1032
1033         // add element if given
1034         //
1035         $new_element_key = '';
1036         $new_element_value = '';
1037         $retrieve_key = sqGetGlobalVar('add_' . $option->name . '_key', $new_element_key, SQ_POST);
1038         $retrieve_value = sqGetGlobalVar('add_' . $option->name . '_value', $new_element_value, SQ_POST);
1039
1040         if ((isset($option->use_add_widget) && $option->use_add_widget)
1041          && ($retrieve_key || $retrieve_value)) {
1042             $new_element_key = trim($new_element_key);
1043             $new_element_value = trim($new_element_value);
1044             if ($option->poss_value_folders && empty($new_element_key))
1045                 $new_element_value = '';
1046             if (!empty($new_element_key) || !empty($new_element_value)) {
1047                 if (empty($new_element_key)) $new_element_key = '0';
1048                 $option->possible_values[$new_element_key] = $new_element_value;
1049             }
1050         }
1051
1052         // delete selected elements if needed
1053         //
1054         if ((isset($option->use_delete_widget) && $option->use_delete_widget)
1055          && is_array($option->new_value)
1056          && sqGetGlobalVar('delete_' . $option->name, $ignore, SQ_POST)) {
1057
1058             if ($option->layout_type == SMOPT_EDIT_LIST_LAYOUT_SELECT) {
1059                 foreach ($option->new_value as $key)
1060                     unset($option->possible_values[urldecode($key)]);
1061             }
1062             else
1063                 $option->possible_values = array_diff($option->possible_values, $option->new_value);
1064         }
1065
1066         // save full list (stored in "possible_values")
1067         //
1068         setPref($data_dir, $username, $option->name, serialize($option->possible_values));
1069
1070     // Certain option types need to be serialized because
1071     // they are not scalar
1072     //
1073     } else if ($option->is_multiple_valued())
1074         setPref($data_dir, $username, $option->name, serialize($option->new_value));
1075
1076     // Checkboxes, when unchecked, don't submit anything in
1077     // the POST, so set to SMPREF_OFF if not found
1078     //
1079     else if (($option->type == SMOPT_TYPE_BOOLEAN
1080            || $option->type == SMOPT_TYPE_BOOLEAN_CHECKBOX)
1081           && empty($option->new_value))
1082         setPref($data_dir, $username, $option->name, SMPREF_OFF);
1083
1084     // For integer fields, make sure we only have digits...
1085     // We'll be nice and instead of just converting to an integer,
1086     // we'll physically remove each non-digit in the string.
1087     //
1088     else if ($option->type == SMOPT_TYPE_INTEGER) {
1089         $option->new_value = preg_replace('/[^0-9]/', '', $option->new_value);
1090         setPref($data_dir, $username, $option->name, $option->new_value);
1091     }
1092
1093     else
1094         setPref($data_dir, $username, $option->name, $option->new_value);
1095
1096
1097     // if a checkbox or multi select is zeroed/cleared out, it
1098     // needs to have an empty value pushed into its "new_value" slot
1099     //
1100     if (($option->type == SMOPT_TYPE_STRLIST_MULTI
1101       || $option->type == SMOPT_TYPE_BOOLEAN_CHECKBOX)
1102      && is_null($option->new_value))
1103         $option->new_value = '';
1104
1105 }
1106
1107 /**
1108  * save function that does not save
1109  * @param object $option
1110  */
1111 function save_option_noop($option) {
1112     /* Do nothing here... */
1113 }
1114
1115 /**
1116  * Create hidden 'optpage' input field with value set by argument
1117  * @param string $optpage identification of option page
1118  * @return string html formated hidden input field
1119  */
1120 function create_optpage_element($optpage) {
1121     return addHidden('optpage', $optpage);
1122 }
1123
1124 /**
1125  * Create hidden 'optmode' input field with value set by argument
1126  * @param string $optmode
1127  * @return string html formated hidden input field
1128  */
1129 function create_optmode_element($optmode) {
1130     return addHidden('optmode', $optmode);
1131 }
1132
1133 /**
1134  * @param array $optgrps
1135  * @param array $optvals
1136  * @return array
1137  */
1138 function create_option_groups($optgrps, $optvals) {
1139     /* Build a simple array with which to start. */
1140     $result = array();
1141
1142     /* Create option group for each option group name. */
1143     foreach ($optgrps as $grpkey => $grpname) {
1144         $result[$grpkey] = array();
1145         $result[$grpkey]['name'] = $grpname;
1146         $result[$grpkey]['options'] = array();
1147     }
1148
1149      /* Create a new SquirrelOption for each set of option values. */
1150     foreach ($optvals as $grpkey => $grpopts) {
1151         foreach ($grpopts as $optset) {
1152             /* Create a new option with all values given. */
1153             $next_option = new SquirrelOption(
1154                     $optset,
1155                     $optset['name'],
1156                     $optset['caption'],
1157                     $optset['type'],
1158                     (isset($optset['refresh']) ? $optset['refresh'] : SMOPT_REFRESH_NONE),
1159                     (isset($optset['initial_value']) ? $optset['initial_value'] : ''),
1160                     (isset($optset['posvals']) ? $optset['posvals'] : ''),
1161                     (isset($optset['htmlencoded']) ? $optset['htmlencoded'] : false)
1162                     );
1163
1164             /* If provided, set if the caption is allowed to wrap for this option. */
1165             if (isset($optset['caption_wrap'])) {
1166                 $next_option->setCaptionWrap($optset['caption_wrap']);
1167             }
1168
1169             /* If provided, set the size for this option. */
1170             if (isset($optset['size'])) {
1171                 $next_option->setSize($optset['size']);
1172             }
1173
1174             /* If provided, set the trailing_text for this option. */
1175             if (isset($optset['trailing_text'])) {
1176                 $next_option->setTrailingText($optset['trailing_text']);
1177             }
1178
1179             /* If provided, set the trailing_text_small for this option. */
1180             if (isset($optset['trailing_text_small'])) {
1181                 $next_option->setTrailingTextSmall($optset['trailing_text_small']);
1182             }
1183
1184             /* If provided, set the yes_text for this option. */
1185             if (isset($optset['yes_text'])) {
1186                 $next_option->setYesText($optset['yes_text']);
1187             }
1188
1189             /* If provided, set the no_text for this option. */
1190             if (isset($optset['no_text'])) {
1191                 $next_option->setNoText($optset['no_text']);
1192             }
1193
1194             /* If provided, set the poss_value_folders value for this option. */
1195             if (isset($optset['poss_value_folders'])) {
1196                 $next_option->setPossValueFolders($optset['poss_value_folders']);
1197             }
1198
1199             /* If provided, set the layout type for this option. */
1200             if (isset($optset['layout_type'])) {
1201                 $next_option->setLayoutType($optset['layout_type']);
1202             }
1203
1204             /* If provided, set the use_add_widget value for this option. */
1205             if (isset($optset['use_add_widget'])) {
1206                 $next_option->setUseAddWidget($optset['use_add_widget']);
1207             }
1208
1209             /* If provided, set the use_delete_widget value for this option. */
1210             if (isset($optset['use_delete_widget'])) {
1211                 $next_option->setUseDeleteWidget($optset['use_delete_widget']);
1212             }
1213
1214             /* If provided, set the comment for this option. */
1215             if (isset($optset['comment'])) {
1216                 $next_option->setComment($optset['comment']);
1217             }
1218
1219             /* If provided, set the save function for this option. */
1220             if (isset($optset['save'])) {
1221                 $next_option->setSaveFunction($optset['save']);
1222             }
1223
1224             /* If provided, set the extra attributes for this option. */
1225             if (isset($optset['extra_attributes'])) {
1226                 $next_option->setExtraAttributes($optset['extra_attributes']);
1227             }
1228
1229             /* If provided, set the "post script" for this option. */
1230             if (isset($optset['post_script'])) {
1231                 $next_option->setPostScript($optset['post_script']);
1232             }
1233
1234             /* If provided, set the folder_filter for this option. */
1235             if (isset($optset['folder_filter'])) {
1236                 $next_option->setFolderFilter($optset['folder_filter']);
1237             }
1238
1239             /* Add this option to the option array. */
1240             $result[$grpkey]['options'][] = $next_option;
1241         }
1242     }
1243
1244     /* Return our resulting array. */
1245     return ($result);
1246 }
1247