Conventions used in this document:

• Any text that is in this font is considered code, a literal value, the name of a file, folder, MySQL table, MySQL field, or a value in a MySQL field.
• Any text that is surrounded by angle brackets like  <this>  means that you should substitute it for your own value.
  Example: vconsole/modules/<module>/ means that you should substitute <module> for your own value like invoices for the Manage Invoices module.
• Any text that is surrounded by square brackets like  [this]  means that it is optional.
  Example: check_email($email, $error[, $dnscheck]);  means that [, $dnscheck] is optional
• When you see ... in the code font, this means that you can add 1 or more items at that point. Do not actually include ... in your code.
  

Creating Your Data Structure.
The data structure should be specified as the $pm array. This is a multi-dimensional array that is handed off to the propertiesmanager() function. This array should define all the main components, all your tabs, fields in each tab, and how to validation these fields. Here is the format for the $pm array. (Remember the conventions used here as defined up top.) IMPORTANT: If you have the VConsole Developer Toolkit for Dreamweaver® installed, then you don't have to copy and paste this data structure into your php files. You can simply place your cursor at the correct place in the php file and choose the appropriate insert option from the VConsole drop down menu.

Do not actually include the square brackets [] or the three dots ... from the code above in your code. The square brackets define optional parameters in the data structure and the three dots means that you can insert 1 or more entries at that point. (Remember the conventions used here as defined up top). OK, now we will go over what each parameter should contain. (There are a lot of them)

• Main Properties Manager Parameters. These parameters configure the main part of the propertiesmanager. What you put here is shown in every tab of the propertiesmanager.
   
  • <title> - This should contain the title to show above the tabs. This is shown on every tab. In module files, this is shown as the module title, and in action files, this is shown at the top of the floating div. See items 1 and 3 in the diagram above. Something like New Invoice is appropriate.
     
  • <image> - This should contain an image name as required by the getimage() php function. This is not a file path. You can bring up your vconsole/showimages.php file in a browser to view a list of images that can be shown. You can even add your own images (See Customizing Look & Feel for more information.) This image is shown to the left side of the properties title and information. See item 2 in the diagram above.
     
  • <info> - This should contain information about the properties. Perhaps you can put what the user is currently doing. Something like You are currently adding an invoice is appropriate. This is shown under the properties title and to the right of the properties image. See item 4 in the diagram above.
     
• Creating Your Property Tabs. Each of the parameters below can be specified for each tab of the propertiesmanager. The code above shows only a single tab, but you can create more tabs at line 96 (notice the [...]) by simply adding more arrays as defined from lines 7 - 95. Each tab consists of a tab name, instructions for the tab, and an array of fields to show.
   
  • <tab> - This parameter should be set to the human readable name of the tab. Remember, your users see this.
     
  • <instructions> - This parameter should be set to a human readable message that tells the user what to do in this tab. This parameter is optional but you should include it for clarification to the user. Something like Please fill out the form below is appropriate.
     
  • <tab_name> - If you want to separate your fields for the step into a set of sub tabs, then you can specify an array of 1 or more sub tab names. This parameter should simply be a string of what the user will see for each sub tab that you want to display. For example: If you want to display 3 sub tabs ("General", "Contact Info", and "Advanced"), Then you will simply define 'subtabs' => array('General', 'Contact Info', 'Advanced')
     
  • Creating Fields For the User. This is the main reason for even creating a properties manager. You must have some fields that the user can fill in and provide their input. After all, you want to do something with that data once the propertiesmanager() function has returned that data to you. Each tab can have 1 or more fields. In the code above, we only show a single field. In real life, you will probably want to define more than 1 field per tab. You can create more fields at line 93 (notice the [...]) by simply adding more arrays as defined from lines 15 - 92. Each field consists of several parameters that determine how the field looks, behaves, and what type of input is allowed.  The following parameters apply to each field in the properties manager.
     
    • <field_type> - This parameter defines the type of field to show. Valid options are:
      • text - Text Field - A plain text field, same as <input type="text">
      • password - Password Field - A password field, same as <input type="password">
      • textarea - Text Area Field - A multi-line text field, same as <textarea></textarea>
      • wysiwyg - WYSIWYG Field - A rich text editor field. The rich text field will generate valid HTML code. The text editor is powered by TinyMCE. The editor can be controlled by changing the vconsole/javascript/wysiwyg.js file. (See the TinyMCE website for documentation on how to configure the look, feel, and functionality of TinyMCE)
      • list - Drop Down List - A drop down list where you can control the choices. The choices for the drop down list can be generated via a SQL statement, via a pre configured drop down list in the vc_ddlists table or via an array that you define.
      • radio - Radio Button Set - A set of radio buttons where you can control the choices. The choices for the radio button set can be generated via a SQL statement, via a pre configured drop down list in the vc_ddlists table or via an array that you define.
      • file - File Upload Field - A field that allows the user to upload files to the server for processing by your Propertiesmanager Script. Files are uploaded to the vconsole/tmp/ directory and parameters can be accessed using the $data array that is returned by the propertiesmanager() function. You can even validate the file before the propertiesmanager allows the upload to be successful.
      • checkbox - Checkbox - A checkbox that can be turned on or off, same as <input type="checkbox">
      • calendar - Calendar Field - A user friendly calendar field. When the field gets focus, a popup calendar is displayed that allows the user to select a date. The value is returned in MySQL date format. YYYY-MM-DD
      • calendarmonth - Month / Year Field - A user friendly month / year selector. When the field gets focus, a popup selector is displayed that allows the user to select the month / year. The value is returned in MySQL date format. YYYY-MM
      • calendartime - Calendar Field + Time - A user friendly calendar + time field. When the field gets focus, a popup calendar (with time selections) is displayed that allows the user to select a date / time. The value is returned in MySQL date format. YYYY-MM-DD HH:MM:SS
      • timepicker - Time Field - A user friendly time selector field. When the field gets focus, a popup time selector is displayed that allows the user to select a time. The value is returned in MySQL time format. HH:MM:SS
      • colorselector - Color Selector - A user friendly color selector field. The field can be set to web safe colors only or to a full smooth color spectrum. When the field gets focus, a popup color selector is displayed that allows the user to select a color. The value is returned as a 6 character CSS color code.
      • selector - Datamanager Selector Field - A field that allows the user to select a single record from a datamanager module. When selecting a record, the user has searching, sorting, and filtering capabilities so that they can easily find the record that they want. This field type was designed to address the issue of too many items in a drop down list. If you want to build a drop down list that has 10,000 choices, that may not be the best experience for the user. The better choice is to use this type of field. In order to use this field type, you MUST have created a datamanager module that manages the records that you want the user to select from.
      • blank - Blank Field - A field that allows you to simply put a label without any actual field. You can put HTML in the label for the field which gives you great flexibility over the overall look / feel of the properties interface. A common use is to use a blank field to put a photo or maybe a horizontal line between fields. Use your imagination.
      • general - General Field - This field is almost the same as a blank field with 1 small difference. A blank field only allows you to specify the label while the actual field is simply output as &nbsp;  So the label gets output, and where the field would normally go, (depending on the label position) you get a simple space. A general field allows you to specify the contents of the label as well as what you would like where the field would normally go. You can actually create special fields, or whatever you want with this type of field. You specify the code where the field would usually go by specifying the default value of the field. (IMPORTANT: The contents of any manually created fields will not be in the $data array as normally expected. You will have to use html_print_r($GLOBALS); to see if / when it gets submitted and then you will have to store the input somewhere for retrieval once the propertiesmanager() function returns)
      • tree - Tree Field - This field will present the user with an expandable / collapsable tree that looks and feels just like a folder explorer interfce. The branches of the tree are stored in the vc_trees table (unless treetable is specified). The user can select 1 or more branches or nodes depending on the settings for the field and the settings in the vc_trees table. If the user selects a certain branch, you can also specify behaviors like disabling parent branches or child branches or both. See "Creating Tree Fields" below for more information on how to create tree fields.
      • choicebuilder - Choice Builder Field - This field allows you to embed several sub fields into it and then give the user the ability to add / remove choices. Each choice contains the full set of embedded fields. OK, so let me give an example.
        • Let's say you want to give the user the ability to add / remove events from a calendar. And each event should have a start date, end date, and also should have a description. The best way to do this is to use a choicebuilder field.
        • Simply embed a start date calendar field, an end date calendar field, and a regular text field as sub fields in the choicebuilder.
        • Now the user can add / remove events. Each time they click on "Add Option" they get 3 fields. Start Date, End Date, and Description.
        • Each sub field can be validated just like regular fields and the user can insert above, insert below, and remove any set of fields.
        • When the datamanager returns, the values can be accessed via: $data['<field_name>_'.<choice>] where <choice> is the choice number.
        • The return value for this field type is the number of choices that the user input.
           
    • <field_name> - This should be set to the name of the field. You should not have any spaces or special characters here. This is input into the field as <input name="<field_name>">.   This is also the $data array key where you can get the input value from the user.
      IMPORTANT: You cannot set this parameter to any of the following for any field or unexpected results may occur. The following names are reserved to be used by VConsole.
      • wizard_in_progress
      • ajax
      • item
      • next
      • cancel
      • uploadfiles
      • delcbrow
      • addcbrow
      • wmbuttons
      • action
      • getdata
      • sort
      • page
      • rev
      • task
      • id
      • selector
      • lname
      • vname
      • selectordef
      • misc
      • display
      • selectorargs
      • reindex
      • extra
      • extra2
      • movecol
      • dropcol
      • bcol
      • fcol
      • bcolaction
      • treeop
      • treeid
      • branchid
      • ptab
      • stab
         
      
      
    • <field_label> - This is the label for the field that the user will see. HTML is OK.
       
    • <field_labelpos> - This parameter determines where the field label is placed in relation to the field. The choices are above, below, before, and after. above, means that the label will be placed above the field, while before means that the label will be placed before the field, and so on. If not specified, it defaults to after.
       
    • <field_pack> - This parameter determines how to place the field in relation to the previous field. The choices are: (If not specified, it defaults to samerow)
      • nextrow - Place the field on the beginning of the next row
      • samerow - Place the field inline with the previous field (On the same row)
         
    • <fieldspan> - The number of fields you want this field to span. In other words, lets say that you have 2 fields on a single row (pack => 'samerow') and the next field is on the next row (pack => 'nextrow') And there are no more fields on this new row, then you should set the fieldspan to 2 so that the field that is on the next row spans the column width of both upper fields. Example:
      ----- wrong -----
      
      ------------------------------------------------------------------------------
      | Field 1:                             | Field 2:                            |
      | (fieldspan => 1, pack => nextrow)    | (fieldspan => 1, pack => samerow)   |
      ------------------------------------------------------------------------------
      | Field 3:                             |
      | (fieldspan => 1, pack => nextrow)    |
      ----------------------------------------
      
      
      ----- right -----
      
      ------------------------------------------------------------------------------
      | Field 1:                             | Field 2:                            |
      | (fieldspan => 1, pack => nextrow)    | (fieldspan => 1, pack => samerow)   |
      ------------------------------------------------------------------------------
      | Field 3:                                                                   |
      | (fieldspan => 2, pack => nextrow)                                          |
      ------------------------------------------------------------------------------
      
       
    • <field_prepend> - If set, this string will be shown right before the field. One reason for using this is to put a dollar ($) sign to indicate that you want dollars but without the dollar sign. HTML is OK.
       
    • <field_postpend> - If set, this string will be shown right after the field. One reason for using this is to put a percent (%) sign to indicate that you want a percentage. HTML is OK.
       
    • <merge> - This should be set to true or false. If set to true, then the field label and field will share a table cell otherwise they will be in separate table cells. We recommend setting this to false so that all your fields and labels line up nicely.
       
    • <field_help> - This will be displayed when the user hovers over the field for a moment. (HTML is OK)
       
    • <subtab> - This parameter should be set to the sub tab index or sub tab name for thesub tab that you want the field to appear under. This parameter is ignored unless an array of sub tabs is set as specified by the <tab_name> parameter above. You can set this parameter to a number or a string. If set to a number, then the field will be placed under that sub tab. In other words, if set to 1, then the field will be placed under the first sub tab, if set to 2, then the field will be placed under the 2nd sub tab, etc.. If this parameter is set to a string, then it must match the name of the sub tab that you want to place the field under as specified in the <tab_name> parameter. If it doesn't match any of the sub tab names, then the field is placed under the 1st sub tab. (IMPORTANT: Sub tabs are not the same as tabs. Each main tab can have 0 or more sub tabs defined as subtabs => array(<list_of_subtabs>). The sub tabs that we mention here refer to sub tabs only if the subtabs => array(<list_of_subtabs>) contains at least 1 tab for the current main tab.
       
    • Field specific parameters. Most of the parameters below can only be used with a certain field type as specified in the <field_type> parameter above. However, some of the parameters can be used with more than 1 field type. In each of the parameters below, we will specify which field types that each parameter can be used with.
       
      • <default_value> - Can be used with all field types. This should be set to whatever you want the default value to be for the field. If the field is a drop down list, radio button, datamanager selector field, or any other field in which the actual input value is restricted, then the default value must be a valid input value or it will be ignored. For example. If you have a drop down list with the choice values of "Choice 1" and "Choice 2" and this parameter is set to "Hamburger" then it will be ignored.
         
      • <checked_value> - Can only be used with checkbox fields. This should be set to the value that is returned when the checkbox is checked.
         
      • <field_lineup> - Can only be used with radio fields. This is the orientation for the radio buttons. You should set this to either horizontal or vertical. If horizontal is set, then the radio buttons are lined up side by side. Likewise, if vertical is set, then the radio buttons are stacked on top of each other in a vertical fashion.
         
      • <color_type> - Can only be used with colorselector fields. This is the type of color selector that you want to display to the user. You should set this to either websafe or smooth. If websafe is set, then only the 256 web safe colors can be selected. If smooth is set, then the user is presented with an interface that allows the selection of the full spectrum of colors.
         
      • <default_choices> - Can only be used with choicebuilder fields. This parameter determines the default number of choices that are displayed to the user. This parameter must be set to a positive whole number and must be between (or equal to ) <min_choices> and <max_choices> (You can enter 0 to not display any choices by default.)
         
      • <min_choices> - Can only be used with choicebuilder fields. This parameter determines the minimum number of choices that the user is allowed to have. This parameter must be set to a positive whole number and must be less than or equal to <default_choices> and must be less than or equal to <max_choices> (You can enter 0 for no minimum)
         
      • <max_choices> - Can only be used with choicebuilder fields. This parameter determines the maximum number of choices that the user is allowed to have. This parameter must be set to a positive whole number and must be greater than 0 and must be greater than or equal to <default_choices> and must be greater than or equal to <min_choices> (You cannot set this to 0)
         
      • <selector_module> - Can only be used with selector fields. You should set this to the module name that you would like the user to select records from. The module should have a folder in the vconsole/modules/ folder and should have a dms.php file that defines the data structure for the datamanager module.
         
      • <selector_show> - Can only be used with selector fields. This should be set to the MySQL field name in the data table for the selector module (specified by <selector_module>) that you want to show when the user selects a record from the datamanager module. This cannot be a fictional field that is derived from the Data Query for the selector module. This has to be the name of an actual MySQL field. For technical purposes and for clarification, we are posting the SQL statement that occurs when a selector field is generated by the Propertiesmanager.
        db_query("SELECT `{$fd['selectorshow']}` FROM `{$dms['table']}` WHERE `{$fd['selectorval']}` = " . db_quote($value), $dbr);
        Where $fd['selectorshow'] is this parameter and $dms['table'] is the data table for the selector module as specified in the dms.php file for the selector module, and $fd['selectorval'] is the <selector_value> parameter (below) and $value is the <default_value> parameter (above). The best thing to do here is to have a look at the MySQL table for the module that you want to select records from and find out what field you want to show to the user when they select a record. Then put that field name here.
         
      • <selector_value> - Can only be used with selector fields. This should be set to the MySQL field name in the data table for the selector module that you want to be passed back in as a value when the user selects a record from the datamanager module. Have a look at the <selector_show> parameter above to get a better technical view of how this works. This should be the name of an actual MySQL field and in most cases should match the $dms['tableindex'] parameter (primary key) as specified in the dms.php file for the module that you want to select records from.
         
      • <selector_value> - Can only be used with selector fields. This should be set to the MySQL field name in the data table for the selector module that you want to be passed back in as a value when the user selects a record from the datamanager module. Have a look at the <selector_show> parameter above to get a better technical view of how this works. This should be the name of an actual MySQL field and in most cases should match the $dms['tableindex'] parameter (primary key) as specified in the dms.php file for the module that you want to select records from.
         
      • <treeid> - Can only be used with tree fields. This should be set to the treeid field in the vc_trees table (or whatever table is specified by the treetable parameter). Each tree field should have its own unique treeid and can contain 1 or more branches in the vc_trees table. For dynamic trees that are created on the fly when the user accesses them, we recommend setting the treeid to the login id of the current user 'treeid' => $GLOB['login']['id'] - This will ensure that there is no overlap in trees. Also, if multiple trees are dynamically generated in the same interface, then add an identifier to the treeid like: 'treeid' => $GLOB['login']['id'] . 'tree1'  - For static trees that are already created in the vc_trees table, simply provide the treeid as specified in the treeid MySQL field. See "Creating Tree Fields" below for more information on how to create tree fields.
         
      • <treetable> - Can only be used with tree fields. If left blank or not specified, this field will default to vc_trees. When specified, this field should be set to the name of a MySQL table that has the same structure as the vc_trees table. This is the table that branches for the tree are pulled from. The branches in this table are arranged in a hierarchical order using the lft, rgt, and depth fields. (See Managing Hierarchical Data - Nested Set Model for more information on how the branches should be structured) See "Creating Tree Fields" below for more information on how to create tree fields.
         
      • <fieldsetid> - Can only be used with tree or choicebuilder fields. If set, then the fieldset tag that is wrapped around the tree or choicebuilder field will have this id set as <fieldset id="fieldsetid">. While this parameter is not normally required, you may want to set it so that you can customize the css style for the fieldset tag or any of its children.
         
      • <defaultselected> - Can only be used with tree fields. If set, this should be a number greater than 0. The defaultselected parameter should contain an array of selected branch ids as specified by the id field in the vc_trees table. This parameter should contain those branch ids, one id per array element. For example let's say that you want branch 3 and branch 6 to be selected by default. Simply set 'defaultselected' => array(3, 6) See "Creating Tree Fields" below for more information on how to create tree fields.
         
      • <defaultexpanded> - Can only be used with tree fields. If set, this should be a number greater than 0. The defaultexpanded parameter should contain an array of branch ids that should be expanded by default as specified by the id field in the vc_trees table. This parameter should contain those branch ids, one id per array element. For example let's say that you want branch 3 and branch 6 to be expanded by default. Simply set 'defaultexpanded' => array(3, 6) See "Creating Tree Fields" below for more information on how to create tree fields.
         
      • <choices> - Can only be used with list or radio fields. This parameter defines the choices for a drop down list or radio button set. This parameter can be 1 of 3 things.
        • It can be the id of a drop down list as defined in the vc_ddlists table. For example: setting this parameter to states will show a list of states. (Check the vc_ddlists table for confirmation) By default, states is the only drop down list that is defined in the vc_ddlists table. You can define your own drop down lists in this table and they will be recognized by this parameter.
        • It can be a SQL query that returns a list of options to show in the drop down list. The SQL query should return 3 fields (in this order). Label, Value, and Default. The Label field will be shown to the user. Whatever is in the Value field will be returned as the value of the field. And the Default field is not required, but if returned, should be set to 1 for the default choice and 0 for all the rest of the choices. The Default value that is returned by the SQL query is overridden by the <default_value> parameter above. Here is an example of a valid SQL query.
          SELECT `Name`, `Value`, `Default` FROM `choices` ORDER BY `Name`
        • It can also be an array of choice arrays. You simply define this parameter as an array of arrays. Each array should have a label and value parameter. Here is the structure (and it can serve as an example)
          'choices' => array( array('label' => 'Choice 1', 'value' => 1), array('label' => 'Choice 2', 'value' => 2) )
          This example only shows 2 choices, but you can add as many choices as you want.
           
      • <treecolumns> - Can only be used with tree fields. This parameter defines an array of columns for the tree field and can have up to 9 columns. The values of the columns are specified in the vc_trees table by col1val, col2val, col3val, etc... This parameter should contain 1 array element for each column that you want to display in the tree field. Each of those array elements should also be an array and should contain type and label keys. Here is an example of 2 columns 1 for Name and 1 for File Size.
        'columns' => array(
          array('type' => 'text', 'label' => 'Name'),
          array('type' => 'filesize', 'label' => 'File Size')
        )
        This gives you 2 columns for your tree field. The label parameter should be the plain text label of the column that is shown at the top of the tree. The type parameter should be any of the following:
        • text - Specifies a plain text column. The value from the column field will be displayed as is.
        • date - Specifies a date column. The value from the column field will be read as a MySQL date field and displayed in human readable format to the user. For example, if the column value is 2008-12-01, then it will be displayed as Dec 1st, 2008
        • datetime - Specifies a date / time column. Like the date column type, the value from the column field will be read as a MySQL datetime field and displayed to the user in human readable format.
        • number - Specifies a number field. The value from the column will be displayed as a number and will be right aligned.
        • taxrate - Specifies a taxrate field. The value from the column will be displayed as a tax rate. The percent sign will be added and the column will be right aligned.
        • currency - Specifies a currency field. The value from the column will be displayed as a dollar amount. The dollar sign will be added and the column will be right aligned.
        • filesize - Specifies a file size field in bytes. The value will be displayed in human readable format in either Bytes, KiloBytes, MegaBytes, GigaBytes, or TeraBytes. (Whichever is closest) and the column will be right aligned.
        See "Creating Tree Fields" below for more information on how to create tree fields.
         
      • <treeops> - Can only be used with tree fields. This parameter defines an array of right click operations or menu items for the tree field. Each menu item can also contain unlimited sub menu items. If this parameter is set, then when the user right clicks on any branch in the tree, the menu that is defined here will be shown so that you can allow the user to perform operations in branches such as "Delete This Branch", "Add New Branch", or whatever. Here is the structure that you should define for this parameter:
        'treeops' => array(
          array(
            'image' => 'name_of_image', /* Name of an image as required by the getimage() php function. */
            'label' => 'label', /* Label to show like 'Delete this item' */
            'active' => true, /* or false */
            'link' => "javascript:myFunction();", /* When the user clicks in this menu item */
            'separator' => 'before', /* or 'after' or 'both' or false */
            'menuitems' => array(
              /* Sub menu items go here and are optional*/
              array(
                'image' => 'name_of_image',
                'label' => 'label',
                'active' => false
                'link' => "javascript:myFunction2();",
                'separator' => false,
                'menuitems' => array( /* Go deeper if you need to. */ )
              ),
              [...]
            )
          ),
          [...]
        )
        
        
        You should create 1 element in the array for each menu item that you want to show to the user. Also, a common question may be "How do I know what branch the user right clicked on?" That value will be stored in a hidden input field in the form. To access the branch id that the user clicked on, you must create your own custom defined javascript function in the vconsole/javascript/customscripts.js file. In that function, you can get the treeid and branch id at:
        document.formwm.treeid.value;
        document.formwm.branchid.value;
        respectively. To create sub menu items, simply create another duplicate array within the menuitems array and go as many levels deep as you need to go. All the parameters shown above are optional. See "Creating Tree Fields" below for more information on how to create tree fields.
             
      • <name_of_attribute> - Can be used with all fields. This will be inserted into the field tag as <name_of_attribute>="<value_of_attribute>". Some common attributes are:
        • size - (Specifies the size in characters for a text field)
        • rows - (Specifies the number of rows to show for a multi line / textarea field)
        • cols - (Specifies the number of columns to show for a multi line / textarea field)
        • style - (Specifies the style attribute of the field)
        • onfocus - (Specifies a javascript function or code to execute when the field gets focus)
        • onblur - (Specifies a javascript function or code to execute when the field loses focus)
        • onchange - (Specifies a javascript function or code to execute when the field changes. For use with drop down lists only.)
        • onclick - (Specifies a javascript function or code to execute when the field is clicked.)
        • Basically, you can put any attribute name here that would normally go in the field type that you specified.
          
          Important: do not use the following values as this will cause problems with VConsole:
          id, name, type, value, onmouseover, onmouseout, class, fieldtype, txtname, readonly.
          Also, do not use onfocus when you have the <field_type> parameter set to calendar, calendartime, timepicker, colorselector, selector, or calendarmonth as this will cause these field types to malfunction.
           
      • <value_of_attribute> - This will be inserted into the field tag as <name_of_attribute>="<value_of_attribute>"
         
      • <embedded_fields> - Can only be used with choicebuilder fields. This parameter is simply a list of embedded fields and uses the same format as the rest of the fields. You cannot embed another choicebuilder field in a choicebuilder field. Also, you cannot name (<field_name> parameter) any embedded field the same as any other field. Each <field_name> parameter for each field, embedded or not, must contain a unique name. If you want to embed 2 text fields, then you could do that like this: (Also, we will show a better example below.)
        
        'fields' => array(
          array(
            'type' => 'text',
            'name' => 'field1',
            'label' => 'Text Field 1',
          ),
          array(
            'type' => 'text',
            'name' => 'field2',
            'label' => 'Text Field 2',
          )
        ),
        
         
      • Validating User Input. Perhaps one of the best functions of the Properties Manager is its ability to validate fields. This saves tons of valuable coding time. If you want the user to only be able to type in numbers in a field, no problem. If you want to make sure that the user types in at least 5 characters and that there is at least 1 number in there, no problem. The validation engine that is built into VConsole is powerful. Let's see just how powerful it is. The parameters below allow you to validate the field. Also, it is worth mentioning that fields that are restricted in their input anyway are validated by default. There is no need to specify validation (other than the <required> parameter) for drop down lists, color selectors, radio button sets, datamanager selector fields, checkboxes, tree fields, or calendar type fields.
         
        • <required> - If defined, this should be set to either true or false. If set to true, then a value is required to be input by the user. If set to false, then no value is required.  Also, if set to false, then a blank choice is added to drop down lists and radio button sets so that the user can select a blank choice. It is important to know that if the user enters the number 0, this is treated as a value and will not fail validation (even though 0 evaluates to false) if this parameter is set to true. If the user does not enter a value and this parameter is set to true, then an error message is displayed and they are given another chance to correct their errors. (You can control the error message using the <failure_msg> parameter below.)
           
        • <content_type> - If defined, this parameter defines the content type that is allowed to be input by the user. In other words, this parameter performs common validations to the user's input data. This parameter is useful for validating common values such as phone numbers, email addresses, urls, and more. Here is a full list of the choices and what they allow (or disallow) the input value from the user to be:
          • false - No content type validation is performed
          • text - Allows basic text (Spaces, a-z A-Z 0-9 -._,#()&). (  RegExp: If match -  /[^\w\s\d\-\.\_\,\#\(\)\&]/i  then fail the validation.)
          • email - Allows valid email addresses. No regular expression matching is done. The email address is checked using the check_email() function. If the EMCHKOFF parameter is set to a false value in the vc_console-params table, then an MX record is checked to make sure that the domain part of the email address is valid. (Make sure to set EMCHKOFF to a true value in the vc_console-params table if you do not want this behavior or if you are running VConsole in an environment that is not connected to the internet.)
          • emailordomain - Allows valid email addresses or @domain (the email address without the part before the @). The same rules apply as for the Email Address type. The EMCHKOFF parameter controls whether an actual MX record lookup is performed.
          • number - Allows numbers only. No other character is allowed. (  RegExp:  If match -   /\D/i   then fail the validation.)
          • mtime - Allows for a military time value only in the format of  HH:MM (  RegExp:  If not match   /^\d{2}\:\d{2}$/  then fail the validation. Also, the digit values are checked for the valid range of hours and minutes.)
          • currency - Allows for currency (no dollar sign) and 2 decimal places. Negative values are not allowed. (  RegExp:  If not match   /^\d*\.?\d{0,2}$/   then fail the validation.)
          • currencyoffset - Allows for currency (no dollar sign) and 2 decimal places. Negative values are allowed. (  RegExp:  If not match   /^\-?\d*\.?\d{0,2}$/   then fail the validation.)
          • decimal2 - Allows for numbers and up to 2 decimal places. Negative values are not allowed. The regular expression is the same as Currency (2 decimal places), but with a different error message upon failed validation.
          • decimaloffset - Allows for just about any number including negatives and up to 15 decimal places. (  RegExp:  If not match   /^\-?\d*\.?\d{0,15}$/  then fail the validation.)
          • taxrate - Allows for numbers and up to 4 decimal places. Negative values are not allowed. (  RegExp:  If not match   /^\d{0,2}\.?\d{0,4}$/   then fail the validation.)
          • phone - Allows phone numbers. Dashes, country code, and parenthesis are allowed. (No + in country code) (  RegExp:  If not match   /^\d{0,2}[\-\s]?\(?\d{3}\)?[\-\s]?\d{3}\-?\d{4}$/   then fail the validation.)
          • url - Allows for valid http, https, or ftp URLs only. (  RegExp:  If not match   /^(http|https|ftp):\/\/(([A-Z0-9][A-Z0-9_-]*)(\.[A-Z0-9][A-Z0-9_-]*)+)(:(\d+))?\/?/i   then fail the validation.)
          • an - Allows for alpha-numeric characters only. (  RegExp:  If match   /[^a-zA-Z0-9]/   then fail the validation.)
          • anl - Allows for lower case alpha-numeric characters only. (  RegExp:  If match   /[^a-z0-9]/   then fail the validation.)
          • anu - Allows for upper case alpha-numeric characters only. (  RegExp:  If match   /[^A-Z0-9]/   then fail the validation.)
          • colorcode - Only 6 digit CSS style color codes are are allowed. The leading pound sign is optional. (  RegExp:  If not match   |^#?[0-9a-fA-F]{6}|   then fail the validation.)
          • password - Allows for alpha-numeric characters as well as - _ @ $ !. At least 1 character and 1 digit must be present. (  RegExp:  If match   |[^a-zA-Z0-9\-\_\@\$\!]|  then fail the validation. Also, if not match   /[a-z]/i   then fail the validation. Also, if not match   /[0-9]/   then fail the validation.)
          • ipv4 - Allow only valid IPV4 addresses. (  RegExp:  If not match   |^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$|   then fail the validation. Also, checks are done to make sure that each octet does not go over 255.)
          • ipv4wild - Allow only valid IPV4 addresses. Not all octets need to be specified. (No * is allowed) (  RegExp:  If not match   |^(\d{1,3})\.(\d{1,3})?\.?(\d{1,3})?\.?(\d{1,3})?$|  then fail the validation. Also, checks are done to make sure that each octet does not go over 255.)
          • ipv6 - Allow only valid IPV6 addresses.
            (  RegExp:  If not match   |^([0-9a-f]{1,4})\:([0-9a-f]{1,4})\:([0-9a-f]{1,4})\:([0-9a-f]{1,4})\:([0-9a-f]{1,4})\:([0-9a-f]{1,4})\:([0-9a-f]{1,4})\:([0-9a-f]{1,4})$|   then fail the validation. )
          • ipv6wild - Allow only valid IPV6 addresses. Not all octets need to be specified. (No * is allowed)
            (  RegExp:  If not match   |^([0-9a-f]{1,4})\:([0-9a-f]{1,4})?\:?([0-9a-f]{1,4})?\:?([0-9a-f]{1,4})?\:?([0-9a-f]{1,4})?\:?([0-9a-f]{1,4})?\:?([0-9a-f]{1,4})?\:?([0-9a-f]{1,4})?$|  then fail the validation.)
             
        • <min_length> - If defined, this parameter must be set to a positive whole number. This parameter determines the minimum required number of characters that the input value from the user must be. If not set or if set to 0 or false, then no minimum length requirement is enforced on the input value from the user.
           
        • <max_length> - If defined, this parameter must be set to a positive whole number. This parameter determines the maximum allowed number of characters that the input value from the user must not exceed. If not set or if set to 0 or false, then no maximum length requirement is enforced on the input value from the user.
           
        • <min_number> - If defined, this parameter must be set to a positive whole number. This parameter determines the minimum numeric value that the input value from the user must evaluate to. You should only set this parameter if a number is expected from the user. If not set or if set to 0 or false, then no minimum numeric value is enforced on the input from the user.
           
        • <max_number> - If defined, this parameter must be set to a positive whole number. This parameter determines the maximum numeric value that the input value from the user can evaluate to. You should only set this parameter if a number is expected from the user. If not set or if set to 0 or false, then no maximum numeric value is enforced on the input from the user.
           
        • <match_regexp> - If defined, this parameter must be set to a Perl formatted regular expression as required by the PHP preg_match() function. This parameter defines a regular expression that the input value from the user MUST match in order to validate successfully. For example: If you want the user to type in any variation of yes like Yes, YES, yEs, etc... then you can set this parameter to /^yes$/i   (Discussing regular expressions is beyond the scope of this publication. Please see the documentation on the preg_match() function on the php.net web site in order to learn more about how to define regular expressions.)
           
        • <match_failmsg> - If defined, this parameter must be set to a human readable message that is shown to the user if the input string does not match the regular expression defined in <match_regexp>. This parameter is ignored if <match_regexp> is not defined or is set to false.
           
        • <nomatch_regexp> - If defined, this parameter must be set to a Perl formatted regular expression as required by the PHP preg_match() function. This parameter defines a regular expression that the input value from the user MUST NOT match in order to validate successfully. For example: If you don't want the user to type in any numbers, then you can set this parameter to /[0-9]/   (Discussing regular expressions is beyond the scope of this publication. Please see the documentation on the preg_match() function on the php.net web site in order to learn more about how to define regular expressions.)
           
        • <nomatch_failmsg> - If defined, this parameter must be set to a human readable message that is shown to the user if the input string does matches the regular expression defined in <nomatch_regexp>. This parameter is ignored if <nomatch_regexp> is not defined or is set to false.
           
        • <truesql> - If defined, this should be set to a SQL statement that must return a single value that evaluates to true in order for validation to succeed. This parameter will be PHP eval'd before it is executed as SQL so make sure that if you want any variables eval'd during the propertiesmanager() function, escape the dollar sign (Remember, the $WIZARD variable contains all the previous and current data entries while the propertiesmanager() function is executing) and make sure that you enclose your SQL in single quotes in the double quoted string. For example:
          'truesql' => "'SELECT DATE(NOW()) > DATE('.db_quote(\$WIZARD['date']).')'"
          This would make sure that the date field is set no later than today.
          ALWAYS PROTECT AGAINST SQL INJECTION ATTACKS. You do this by passing any data through the db_quote() function before passing it to MySQL. Only advanced users should use this parameter because if you get it wrong, you will get errors.
           
        • <truesql_failmsg> - If defined, this parameter must be set to a human readable message that is shown to the user if the SQL query defined by <truesql> returns a false value. This parameter is ignored if <truesql> is not defined or is set to false.
           
        • <falsesql> - If defined, this should be set to a SQL statement that must return a single value that evaluates to false in order for validation to succeed. This parameter will be PHP eval'd before it is executed as SQL so make sure that if you want any variables eval'd during the propertiesmanager() function, escape the dollar sign (Remember, the $WIZARD variable contains all the previous and current data entries while the propertiesmanager() function is executing) and make sure that you enclose your SQL in single quotes in the double quoted string. For example:
          'falsesql' => "'SELECT DATE(NOW()) > DATE('.db_quote(\$WIZARD['date']).')'"
          This would make sure that the date field is set later than today.
          ALWAYS PROTECT AGAINST SQL INJECTION ATTACKS. You do this by passing any data through the db_quote() function before passing it to MySQL. Only advanced users should use this parameter because if you get it wrong, you will get errors.
           
        • <falsesql_failmsg> - If defined, this parameter must be set to a human readable message that is shown to the user if the SQL query defined by <falsesql> returns a true value. This parameter is ignored if <falsesql> is not defined or is set to false.
           
        • <failure_msg> - If defined, this parameter must be set to a human readable message that is shown to the user if any part of the validation process fails for the input field. If not defined, then generic messages will be output to the user. The generic messages are smart enough to let the user know what they are doing wrong. For example: If the user types in 3 characters and the field requires at least 5. The failure message will tell the user to type in at least 5 characters.
           
        • <recid> - If defined, you should set this to the unique primary key for an existing record that is currently reflected in the fields that are displayed to the user. For example: If the user is editing a record in a MySQL table you should set this parameter to the value of the unique primary key for the record that the user is editing. Currently, this parameter is only used for checking for duplicate values in a MySQL table. (See <unique_tableindex> below. You will want to set this value if you need to validate that the value of the field is unique in a MySQL table. Setting this parameter will exclude the record at <recid> so that the user doesn't get an error message if they leave the value the same.
           
        • <valid_ext> - This parameter can only be used with file field types. This parameter can be a list of 1 or more file extensions. When a user uploads a file using the file field type, the validation engine can make sure that the file name ends in one of the extensions that you provide here. If at least 1 extension is defined here, then the file must contain at least 1 of these valid extensions or validation will fail.
           
        • <invalid_ext> - This parameter can only be used with file field types. This parameter can be 1 or more file extensions. When a user uploads a file using the file field type, the validation engine can make sure that the file does not match one of the extensions that you provide here. If the file matches any extension defined here, then validation will fail.
           
        • <min_filesize> - This parameter can only be used with file field types. This parameter, if set, should be set to the minimum allowed file size in bytes. If the file that the user uploads is smaller in file size than what you set here, then validation fails. Remember, that 1KB is 1024 Bytes and 1MB is 1024 KB, etc.... This parameter expects the minimum allowed file size in bytes. If set to 0 or if not set, then no minimum byte size is enforced.
           
        • <max_filesize> - This parameter can only be used with file field types. This parameter, if set, should be set to the maximum allowed file size in bytes. If the file that the user uploads is larger in file size than what you set here, then validation fails. Remember, that 1KB is 1024 Bytes and 1MB is 1024 KB, etc.... This parameter expects the maximum allowed file size in bytes. If set to 0 or if not set, then no maximum byte size is enforced. WARNING: We recommend setting this to a reasonable value. The reason is because if a user attempts to upload a file that is too big for HTTP to handle, unexpected results could occur.
           
        • Confirming That 2 Fields Match - In some cases, you may want the user to re-type a field for confirmation purposes. Luckily, VConsole has the capability to do just that. The parameters below define what field must match this one in order for it to validate. IMPORTANT: Do not specify these parameters in both fields that must match. You should only specify these parameters in the field that should be considered the confirmation field (since the confirmation field usually comes after the regular field). Confirmation cannot be used with tree fields, choicebuilder fields, file fields, blank fields, or general fields.
           
          • <conf_field> - This should be the name of the field (as specified in the <field_name> parameter) that you want to match against.
             
          • <conf_failmsg> - This is optional, but if set, should contain a human readable message to show to the user if the 2 fields fail to match.
             
        • Checking For Duplicate Values In the MySQL Data Table - The parameters defined here are used to check the MySQL data table for unique values. For example: If you have a data table that has a name field and you want to make sure that all the records in this field are unique and that there are no duplicates, you can use the unique parameters below to make sure that the user does not enter a value that is already taken in the table. If you define the unique array, then you must define the first 3 parameters below.
           
          • <unique_table> - This parameter must be set to the name of a MySQL table to check for duplicate values.
             
          • <unique_tableindex> - This parameter must be set to the primary key for the MySQL table. (This parameter is ignored unless $pm['recid'] is specified which is not covered in the specification above.) The reason for this parameter is to make sure that, if the user is editing a record from a table, and you want them to be able to keep the value the same, that they don't get a failure message stating that a duplicate value exists. Since the user is editing an existing record, we want to exclude that record from duplicate checking so that the field validates while keeping it the same value. This parameter along with $pm['recid'] does just that. So, if you want to use this parameter, then set $pm['recid'] to the value of the primary key for the record that you are editing and set this parameter to the name of the MySQL field that is the primary key for the table.
             
          • <unique_fieldname> - This parameter must be set to the name of the MySQL field to check for duplicate values.
             
          • <unique_failmsg> - If defined, this parameter must be a human readable message that is shown to the user if any duplicates are found in the table.