Conventions used in this document:

• Any text that is in this font is considered code, a literal value, or 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.
  

The datamanager data structure (the $dms array). This is the full structure of the $dms array: (Remember the conventions used here as defined up top)

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)

• <module_id> - This should be the module id as defined in the vc_modules table in the module field for the module. This should also match the name of the module folder. Make sure that you set this correctly. Unexpected results can occur if you don't.
   
• <mysql_table> - This should be the name of the MySQL table that contains the records that you want to manage with this datamanager module.
   
• <mysql_tableindex> - This should be the name of the MySQL field in the MySQL table (defined by <mysql_table>) that is the primary key for the table. This field should be an auto increment field. (See creating the MySQL data table above)
   
• <edit_permission> - If defined, this should be the name of the action that the user is required to have permission to in order to perform inline edits to data fields. This parameter is ignored if you have no inline edit definitions in your data structure. (See below)
   
• <edit_permission_function> - If defined, this should be the name of a function that should determine whether the user can perform inline edits to data. This parameter is ignored if you have no inline edit definitions in your data structure. (See below) If this parameter is defined, then the <edit_permission> parameter is ignored. The function named here should be defined in your functions.php file in the vconsole/modules/<module>/ folder. (See the Inline Edit Section below)
   
• <message_if_no_items> - If defined, this should contain a message to display to the user if there are no items in the MySQL table to manage (or if search / filter conditions return no results). If not defined, then a default message is displayed to the user. HTML is OK.
   
• <allow_import> - If defined, this should be true or false. If true, then importing data from a CSV file is allowed and you must specify an <import_field> parameter for every field you want to be able to import. (See Importing From CSV below)
   
• <import_permission> - If defined, this should be the name of the action that the user is required to have permission to in order to perform CSV file imports. This parameter is ignored if <allow_import> is set to false or is not defined. We recommend setting this to the name of the action that is usually used to add new records.
   
• Group Actions. The parameters here define all the group actions for the data manager. Group actions are displayed in the "Group Operations" drop down menu and are displayed when the user selects multiple data records and then right clicks on one of the records. Group actions are useful for performing some type of action on multiple records at once. If you want to control access to these actions, you must define them in the vc_modules-actions table (See Managing Permissions for more info on permissions)
   
  • <groupop_label> - This should be the human readable label for this group action. Users see this in the group operations drop down menus. Although you can, we recommend not using HTML code here other than basic HTML like <em> tags.
     
  • <groupop_image> - If defined, this should be set to the name of an icon image as required by the getimage() function. This is not a file path. To summarize, you can display any icon image that is located in the vconsole/skins/vsource/icons/ folder. To display an image from this folder, you must specify icon_<name_of_icon_file_without_extension> as this parameter. So if you want to display the icon located at vconsole/skins/vsource/icons/ok.png then you will want to put icon_ok here. You can pull up the vconsole/showimages.php file in a browser to see a list of available icon images (only icon images should be used here, not button images)
     
  • <groupop_help> - If defined, this should be set to a descriptive help message that the user sees when hovering over the group action menu item for a small amount of time. This is designed to give the user a better description of what the action does. For a delete action, something like Click to delete all selected records would be appropriate.
     
  • <groupop_action> - This should be set to the action that should be executed when the user clicks on the group action item in the drop down menu. There should also be an action file located at vconsole/modules/<module>/actions/<groupop_action>.php. The name of this file should match what you put in this parameter and the file will be executed when the user clicks on the action item in the drop down menu. (Or in the top navigation bar if the group action is displayed there as well). Learn more about datamanager actions here.
     
  • <groupop_confirm> - If defined, this should be set to a descriptive message that is shown to the user when they click on the group action item in the drop down menu. The purpose of this parameter is to give the user a chance to cancel the operation before it is actually performed (They can click on OK to continue the operation or on Cancel to cancel the operation). The contents of this parameter is passed to the confirm() javascript function so no HTML is allowed here. If you want to display a new line character, use \\n where you want to display the new line.
     
  • <groupop_conftype> - If defined, this should be set to a javascript formatted regular expression that the user must type in and match in order to perform the operation. Example: /yes/i means that the user MUST type in yes or Yes or YES, etc... to confirm the operation. Use this on sensitive actions when you want to be absolutely sure that the user wants to perform the action. If this parameter is defined, then you must also define the <groupop_confirm> parameter which should tell the user what to type in order to confirm the action. You will get a javascript error if you define an invalid javascript regular expression here. Explaining how to create a javascript regular expression is beyond the scope of this publication. You should search for javascript regular expressions if you need more information and you are interested in using this parameter.
     
  • <groupop_separator> - If defined, this can be set to either false, true, 'before', 'after', or 'both'. If set to true, it creates a separator after. This parameter controls whether a menu separator is created and where it is placed.
     
  • <groupop_extra> - If defined, this must contain a message to display to the user (passed as the first argument to the javascript doPrompt() function.) that will prompt them for input. What the user types in the prompt box is passed to your action file as $_REQUEST['extra']. Use this if you need input from the user in order to perform this action. (You can also get input from the user within the action file if it is a wizardmanager or propertiesmanager formatted action file.) This parameter is only used to collect a basic string parameter from the user. If you need more complex input from the user, you can create the action file as a wizardmanager or propertiesmanager formatted action file. (See Datamanager Actions for more information)
     
  • <groupop_extraval> - If defined, this must contain a string of what to display by default in the javascript prompt field as specified by the <groupop_extra> parameter. This parameter requires that the <groupop_extra> parameter is also defined. When the user is prompted for input using the <groupop_extra> parameter as described above, this string is passed as the second argument to the javascript doPrompt() function which only defines the default value of the input field that is shown to the user. The user can modify this value and then the value is passed to your action file as $_REQUEST['extra'].
     
  • <groupop_ofunction> - This parameter is tricky to explain and is rarely (if ever) used. It is not used anywhere in the default coding for VConsole. If defined, this must contain the name of a javascript function that is defined in one of your own javascript files. To include one of your own javascript files in VConsole you must modify the vconsole/skins/vsource/templates/main.html file to include your javascript file. (See Javascript Functions for more information). The function defined here is executed instead of what would normally happen such as executing the action file. This function is called as follows using javascript. ofunction(<groupop_confirm>, <groupop_action>, <groupop_extra>, <groupop_extraval>, <groupop_conftype>); Use this option to execute custom javascript instead of executing the action file.
     
  • <groupop_submitform> - If defined, this can be set to either false or true. If set to true, then the form is submitted via HTML instead of AJAX. We don't recommend setting this parameter to true. Do not set to true unless you know what you are doing. You will have to make sure to re-draw the entire user interface if your action file doesn't return control to the datamanager. If your action file does return control to the datamanager, then the datamanager will re-draw the user interface for you. This parameter is ignored if <groupop_ofunction> is defined.
     
• Single Actions. The parameters here define all the single record actions for the data manager. Single actions are displayed when the user right clicks on a single data record. Single actions are useful for performing some type of action on a single data record. If you want to control access to these actions, you must define them in the vc_modules-actions table (See Managing Permissions for more info on permissions)
   
  • <singleop_label> - This should be the human readable label for this single action. Users see this in the drop down menu when they right click on a single item. Although you can, we recommend not using HTML code here other than basic HTML like <em> tags.
     
  • <singleop_image> - If defined, this should be set to the name of an icon image as required by the getimage() function. This is not a file path. To summarize, you can display any icon image that is located in the vconsole/skins/vsource/icons/ folder. To display an image from this folder, you must specify icon_<name_of_icon_file_without_extension> as this parameter. So if you want to display the icon located at vconsole/skins/vsource/icons/ok.png then you will want to put icon_ok here. You can pull up the vconsole/showimages.php file in a browser to see a list of available icon images (only icon images should be used here, not button images)
     
  • <singleop_help> - If defined, this should be set to a descriptive help message that the user sees when hovering over the single action menu item for a small amount of time. This is designed to give the user a better description of what the action does. For a delete action, something like Click to delete this record would be appropriate.
     
  • <singleop_action> - This should be set to the action that should be executed when the user clicks on the single action item in the drop down menu. There should also be an action file located at vconsole/modules/<module>/actions/<singleop_action>.php. The name of this file should match what you put in this parameter and the file will be executed when the user clicks on the action item in the drop down menu. (Or in the top navigation bar if the single action is displayed there as well). Learn more about datamanager actions here.
     
  • <singleop_confirm> - If defined, this should be set to a descriptive message that is shown to the user when they click on the single action item in the drop down menu. The purpose of this parameter is to give the user a chance to cancel the operation before it is actually performed (They can click on OK to continue the operation or on Cancel to cancel the operation). The contents of this parameter is passed to the confirm() javascript function so no HTML is allowed here. If you want to display a new line character, use \\n where you want to display the new line.
     
  • <singleop_conftype> - If defined, this should be set to a javascript formatted regular expression that the user must type in and match in order to perform the operation. Example: /yes/i means that the user MUST type in yes or Yes or YES, etc... to confirm the operation. Use this on sensitive actions when you want to be absolutely sure that the user wants to perform the action. If this parameter is defined, then you must also define the <singleop_confirm> parameter which should tell the user what to type in in order to confirm the action. You will get a javascript error if you define an invalid javascript regular expression here.
     
  • <singleop_separator> - If defined, this can be set to either false, true, 'before', 'after', or 'both'. If set to true, it creates a separator after. This parameter controls whether a menu separator is created and where it is placed.
     
  • <singleop_extra> - If defined, this must contain a message to display to the user (passed as the first argument to the javascript doPrompt() function.) that will prompt them for input. What the user types in the prompt box is passed to your action file as $_REQUEST['extra']. Use this if you need input from the user in order to perform this action. (You can also get input from the user within the action file if it is a wizardmanager or propertiesmanager formatted action file.) This parameter is only used to collect a basic string parameter from the user. If you need more complex input from the user, you can create the action file as a wizardmanager or propertiesmanager formatted action file. (See Datamanager Actions for more information)
     
  • <singleop_extraval> - If defined, this must contain a string of what to display by default in the javascript prompt field as specified by the <singleop_extra> parameter. This parameter requires that the <singleop_extra> parameter is also defined. When the user is prompted for input using the <singleop_extra> parameter as described above, this string is passed as the second argument to the javascript doPrompt() function which only defines the default value of the input field that is shown to the user. The user can modify this value and then the value is passed to your action file as $_REQUEST['extra'].
     
  • <singleop_ofunction> - This parameter is tricky to explain and is rarely (if ever) used. It is not used anywhere in the default coding for VConsole. If defined, this must contain the name of a javascript function that is defined in one of your own javascript files. To include one of your own javascript files in VConsole you must modify the vconsole/skins/vsource/templates/main.html file to include your javascript file. (See Javascript Functions for more information). The function defined here is executed instead of what would normally happen such as executing the action file. This function is called as follows using javascript. ofunction(<singleop_confirm>, <singleop_action>, <singleop_extra>, <singleop_extraval>, <singleop_conftype>); Use this option to execute custom javascript instead of executing the action file.
     
  • <singleop_submitform> - If defined, this can be set to either false or true. If set to true, then the form is submitted via HTML instead of AJAX. We don't recommend setting this parameter to true. Do not set to true unless you know what you are doing. You will have to make sure to re-draw the entire user interface if your action file doesn't return control to the datamanager. If your action file does return control to the datamanager, then the datamanager will re-draw the user interface for you. This parameter is ignored if <singleop_ofunction> is defined.
     
• MySQL Queries. These parameters define the MySQL queries that are required in order to retrieve data from the MySQL table that you are managing. These queries are arguably the most important and most flexible parameters in the datamanager structure. You can specify all sorts of cool things like table joins, SQL views, or extremely complex queries. In the examples below, we keep it simple for documentation purposes, but in your queries, you can get as complex as you need to, just make sure to test, benchmark, and optimize your queries.
   
  • <count_query> - This is a required parameter and it must contain a SQL query that returns the total number of rows that the user is allowed to see. The SQL query MUST have a WHERE clause, even if it is WHERE 1. If the user should be able to see all records in the MySQL table, then you should set this to:
    SELECT COUNT(*) FROM `<mysql_table>` WHERE 1
    where <mysql_table> is the name of the data table as defined above. (The table name is enclosed in back ticks, not single quotes. Check the MySQL SELECT syntax on the MySQL web site for documentation on how to define a MySQL Select Query.) If the <data_query> parameter (described below) contains a join to another table, then this query should also contain that same join. For example: If the <data_query> parameter contains
    SELECT `table1`.*, `table2`.* FROM `table1`, `table2` WHERE `table1`.`field1` = `table2`.`field2`
    Then this parameter should be
    SELECT COUNT(*) FROM `table1`, `table2` WHERE `table1`.`field1` = `table2`.`field2`
     
  • <data_query> - This is a required parameter and it must contain a SQL query that returns all the rows that the user is allowed to see. It should return 1 field per data column as defined by the "Data Fields" parameters described below. The SQL query MUST have a WHERE clause, even if it is WHERE 1. If the user should be able to see all records in the MySQL table, then you should set this to:
    SELECT * FROM `<mysql_table>` WHERE 1
    where <mysql_table> is the name of the data table as defined above. (The table name is enclosed in back ticks, not single quotes. Check the MySQL SELECT syntax on the MySQL web site for documentation on how to define a MySQL Select Query.) If this query contains a join to another table, then the <count_query> parameter (described above) should contain that same join. (See above for an example)
     
  • <index_query> - This is an optional parameter and, if defined, it must contain a SQL query that returns a single data row. It must be identical to the data query except that it should return a single record as specified by ||rowid|| as shown in the example. ||rowid|| should literally be part of the SQL query. (DO NOT take out ||rowid|| as the datamanager needs this) If this query is not defined correctly, then the searchindex() function will not be able to index records so that they are returned in search results. As said, this query should be identical to the <data_query> parameter with 1 small difference. It must also contain ||rowid|| in the WHERE clause. So if the <data_query> is:
    SELECT * FROM `<mysql_table>` WHERE 1
    then this parameter should be
    SELECT * FROM `<mysql_table>` WHERE 1 AND `<mysql_tableindex>` = ||rowid||
    where <mysql_table> is the name of the data table as defined above and <mysql_tableindex> is the name of the primary key for the table as defined above. If this parameter is not defined, it is automatically generated by the datamanager() function by adding AND `<mysql_tableindex>` = ||rowid|| to the end of the <data_query> parameter.
     
  • <reindex_query> - This is an optional parameter and, if defined, it must contain a SQL query that returns all the <mysql_tableindex> fields from the <mysql_table> that the user can see. This query is used to re-index the search index for this datamanager module. It is executed when the user clicks on "Reindex All Records" in the "Search Builder" drop down menu on the main menu bar. This SQL query must also contain a WHERE clause even if it is WHERE 1. If not defined, it defaults to:
    SELECT `<mysql_tableindex>` FROM `<mysql_table>` WHERE 1
    One reason to define this query is if you only want just the records that the user can see to be re-indexed instead of all records in the table. Let's say that you have a table with 10,000 records and the <data_query> is set as follows (this contains some PHP code):
    'data' => "SELECT * FROM `table1` WHERE `user` = " . db_quote($GLOB['login']['id'])
    then it only makes sense to set this parameter as follows:
    'reindex' => "SELECT `id` FROM `table1` WHERE `user` = " . db_quote($GLOB['login']['id'])
    (assuming that <mysql_tableindex> parameter is set to id) Using this logic, only the records that have the user field set to the id of the user will be re-indexed. There is no need to re-index records that the user can't see anyway. If you don't set this parameter like this, then the user will have to wait until all 10,000 records are re-indexed before he/she can begin working in the program again. I hope this makes sense. (Please see PHP Variables for more information on what the $GLOB['login']['id'] variable is. And see PHP Functions for more information on what the db_quote() php function does.)
     
• Data Fields. These parameters define each field or data column in the data manager. You can define as many fields here as you want and we recommend creating at least 1 data field for every field in the MySQL table (except for the primary key). We say at least 1 because you can actually create more fields depending on the data query as defined by the <data_query> SQL query. One requirement is that you do not create a field for the <mysql_tableindex> field or the vccolor field for the MySQL table. The data manager uses the primary key to create the record checkboxes.
   
  • <mysql_field> - This should be the name of a field that is returned by the MySQL data query <data_query> SQL statement. Usually, this should just be the name of a field in the MySQL table <mysql_table> but it doesn't have to be. It just has to be a field that is returned by the MySQL query. For instance, it can be a field from a table join or a MySQL calculation. For example: If your <data_query> is:
    SELECT *, (`field1` + `field2`) AS `total` FROM `table1` WHERE 1
    then you can specify this parameter as total instead of a normal table field. Also, you MUST NOT specify the <mysql_tableindex> field or the vccolor field here. The datamanager() function uses these fields internally.
    IMPORTANT: You cannot set any of the following words as this parameter. The following words are reserved for use by the system. If you specify one of the words below, unexpected results may occur. If you have a MySQL field that is named according to one of the parameters below, then modify your MySQL table or modify your <data_query> so that the actual field name does not reflect one of these parameters. You can do this using a SQL statement such as: SELECT `<field_name>` AS `<newfieldname>`
    • 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
    • vccolor
    • treeop
    • treeid
    • branchid
    • ptab
    • stab
       
  • Header Parameters. These parameters define the Header part of the data field. The header is the area that contains all the column headers.
     
    • <header_type> - This should be set to either text or icon. If set to text, then the column in the datamanager GUI is resizable. If it is set to icon, then the column in the datamanager GUI is not resizable and is only 32 pixels wide. You should use text for most of your columns. Use icon if you intend to display icons or a single character in the column for the data records.
       
    • <header_title> - This should be the human readable title of the column (column header text) that is shown to the user in the datamanager GUI. For icon header types, you should keep it short and sweet or you can set this to 'title' => getimage('icon_name') in order to display an icon to the user (See PHP functions to learn more about the getimage() php function). Although you can pass HTML, we recommend only using basic HTML like <em> tags or icon images.
       
    • <chart_title> - This parameter is a header title that is used in chart display mode and when showing record details. If left blank or not defined, then the <header_title> parameter is shown in chart display mode and when showing record details. This is useful for when you have an icon <header_type> that just has a single letter or an icon image in the <header_title>, but you want a full title in the chart and details areas. Also, chart display mode does not allow HTML for any header title so if you have HTML in your <header_title> you MUST define the plain text version in this parameter.
       
    • <header_help> - This parameter, if set, should contain a human readable message to show to the user when they hover their mouse over a header column for a short time. This should describe the column or it could simply say something like: Click to sort by this column to let the user know that they can click to sort. HTML is OK.
       
    • <sort_field> - This parameter should contain the MySQL field name to sort by. Usually, this should be set the same as <mysql_field> but, there are reasons that you may want to set it to something different. If set, then when a user clicks on the column header, the following SQL is added to the end of the <data_query> SQL statement:  
      ORDER BY <sort_field>
      So you should make sure that this makes sense in the SQL statement. If the user clicks on the column a second time, then the following SQL is added to the end of the <data_query> SQL statement:
      ORDER BY <sortfield> DESC
      If you want to sort by a field that is also a SQL reserved word such as order, then you have to enclose the field in back ticks like so:
      'sortfield' => " `<sort_field>`",
      You can also specify an array of sort fields so that the datamanager engine sorts by more than 1 field. For example:
      'sortfield; => array("`field1`", "`field2`");
      In this case, you get the following SQL added the the end of the <data_query> (Ascending and descending sort orders respectfully):
      ORDER BY `field1`, `field2`
      ORDER BY `field1` DESC, `field2` DESC
       
    • <defrev> - If defined, this should be set to either true or false. If set to true, then the default sorting order will be descending instead of ascending. So, if set to true, this parameter effectively reverses the behavior of the <sort_field> parameter. When this parameter is set to true, then on the first click of a header column, the following SQL is added to the end of the <data_query>:
      ORDER BY <sort_field> DESC
      And on the second click of a header column, the following SQL is added to the end of the <data_query>:
      ORDER BY <sort_field>
       
    • <align> - If defined, this parameter should be set to either left, right, or center (or false). This determines the default horizontal alignment for the column. Remember, that the user can always override this setting by right clicking on the column header and selecting their own horizontal alignment for the column. This parameter only determines what the user sees by default. If not set or if set to false, then it defaults to left.
       
    • <valign> - If defined, this parameter should be set to either top, bottom, or middle (or false). This determines the default vertical alignment for the column. Remember that the user can always override this setting by right clicking on the column header and selecting their own vertical alignment for the column. This parameter only determines what the user sees by default. If not set or if set to false, then it defaults to top.
       
    • <width> - If defined, this parameter should be set to a positive whole number that defines the default column width in pixels. Remember that the user can always override this setting by resizing the column. This parameter only determines what the user sees by default. If not set or if set to false, then the default column width is automatically determined by the datamanager() function. This parameter is ignored if the <header_type> parameter is set to icon. This parameter is also affected by the <behavior> parameter described below.
       
    • <header_style> - If defined, this parameter should contain text that is put into the style attribute for the header column <th> HTML tag. Here is an example of what is output to the user for the column header:
      <th style="<header_style>"><header_title></th>
       
    • <behavior> - If defined, this parameter should be set to E, W, or T.
      • If set to E (E stands for expand), then the column width is expanded to fit the widest data field in the column. So if the widest possible field in the column is wider than what is set for <width> then the <width> parameter is overridden so that the column fits all text in the column without wrapping. In other words, all the text for all fields in the column are displayed completely without word wrap. So if you have a data record that contains a long text string, the column may be extremely wide and the user may have to scroll horizontally to view the data.
      • If set to W (W stands for wrap), then the column width (as determined by <width> or what the user has resized the column to) is always respected. If a data field contains text that would be wider than <width> then the contents of that field are wrapped onto additional lines.
      • If set to T (T stands for truncate), then the column width (as determined by <width> or what the user has resized the column to) is always respected. If a data field contains text that would be wider than <width> then the contents of that field are truncated or hidden.
      • Remember that the user can always override this setting by right clicking on the column header and setting the desired column behavior. This parameter only determines what the user sees by default. If not set or if set to false, then the default column behavior is E.
         
    • <defaultview> - If defined, this parameter should be set to either true or false. If set to true, then this field is displayed to the user by default. FYI, you don't have to have every field that you define in the $dms data structure visible by default. You can actually create many fields that are not shown until the user adds the column to their view or when they switch views or apply pre-defined layouts. With that in mind, you MUST have at least 1 field with this parameter set to true or the user won't see any columns by default when they click on the module button. They would have to add all the columns that they want to see to their view manually. We recommend setting this parameter to true for more prominent or more important fields and setting this parameter to false (or not setting this parameter) for less prominent or less important fields. One common practice is grouping columns into column sets and allowing the user to quickly switch between column sets. This is possible with developer defined layouts (see the Developer Defined Layouts section below) or with custom views. The user can create their own custom views that contain the columns that they want to see. They can then quickly switch between views (which contain different column sets) via a simple drop down menu. So, while you may have many, many columns defined in the $dms data structure, you don't have to show all of them by default. Set this parameter to true for the columns that you want to show by default. Remember, the user can add or remove any column from their view at will, which obviously overrides this parameter.
       
  • Data Field Parameters. The following parameters control the data part of the data field. This is the area that actually contains data.
     
    • <data_type> - This parameter determines the behavior of the data field (the table cell that contains the actual record data) and should be set to either text, icon, date, datetime, currency, or number. It is important that you understand how this parameter works and what the restrictions are. If you set this parameter incorrectly, unexpected results could occur. This parameter is also dependent on the <header_type> parameter and is partly governed by it. If the <header_type> parameter is set to icon, then this parameter must also be set to icon. If the <header_type> parameter is set to text, then this parameter must be either text, date, datetime, currency, or number. Here is a list of all the different settings and how they behave:
      • If set to icon: The data field is not resizable and must contain an icon or a short 1 to 3 character string. This is because the data field will only be up to 32 pixels wide. (depending on whether or not the user is currently sorting by the column.) Icon fields are text searchable only.
      • If set to text: The data field is resizable. Text fields should contain text and are text searchable.
      • If set to date: The data field is resizable, text searchable, and date searchable. The SQL query defined in <data_query> MUST return a MySQL formatted date for the field. These MySQL dates are further formatted to be human readable by the datamanager() function.
      • If set to datetime: The data field is resizable, text searchable, and date searchable. The SQL query defined in <data_query> MUST return a MySQL formatted date / time for the field. These MySQL date / times are further formatted to be human readable by the datamanager() function.
      • If set to currency: The data field is resizable, text searchable, and value searchable. The SQL query defined in <data_query> MUST return a floating point number. These floating point numbers are further formatted to include the dollar sign and contain the correct number of decimal points by the datamanager() function. Also, currency fields can take advantage of the <showtotal> parameter (see below).
      • If set to number: The data field is resizable, text searchable, and value searchable. The SQL query defined in <data_query> MUST return a floating point number. Also, number fields can take advantage of the <showtotal> parameter (see below).
    • <data_help> - If defined, this should be a human readable message that the user will see when hovering their mouse over any data field in the column for a moment. This parameter is designed to give the user a short message that describes the data field. If set, then all fields in the column will display this same message. If you want each record to display a different help message depending on what is contained in the record, see the <formathelp> parameter below. HTML is OK. This parameter is ignored if the <formathelp> parameter is set.
       
    • <format> - If defined, this should be the name of a PHP function that is defined in the functions.php file (See below for more information on the functions.php file). This function name must be globally unique in VConsole. No other module or other field can have duplicate function names for this parameter. We recommend using the format: <module>_format_<mysql_field> when setting this parameter. This function should take 1 required argument which is the associative array that is returned by the mysql_fetch_assoc() php function when the <data_query> SQL statement is executed, and 1 optional argument that is specified in the <format_args> parameter. If the <format_args> parameter is not defined, then your function MUST only accept a single argument. The function should then return a string (HTML OK) of what the user should see in the field. The purpose of this parameter is to display something to the user other than what is returned by the MySQL <data_query> SQL statement for the field. For example: If you want to display an icon image or Yes / No instead of 0 / 1 to the user, set this parameter to a function name, create that function in the functions.php file, have the function evaluate the 1st argument for the record (the associative array for the record), and then have the function return what you want the user to see. For example: If you have a MySQL field called complete in the invoices module that is set to either 1 or 0 and you want to display Yes or No (respectfully) instead, then you can set this parameter to something like: invoices_format_complete. Then you can define the following function in your functions.php file:
      function invoices_format_complete($record) { if ($record['complete']) { return 'Yes'; } else { return 'No'; } }
       
    • <formathelp> - If defined, this should be the name of a PHP function that is defined in the functions.php file. (See below for more information on the functions.php file). This function name must be globally unique in VConsole. No other module or other field can have duplicate function names for this parameter. We recommend using the format: <module>_format_<mysql_field>_help when setting this parameter. This parameter works exactly the same as the <format> parameter except this parameter defines what the user should see when they hover their mouse over a data field for a short time. (Please see the <format> parameter to see how this works) If this parameter is set, then <data_help> is ignored.
       
    • <format_args> - If defined, this is passed in as the second argument to your PHP functions which are defined in the <format> and <formathelp> parameters. It is rare (if ever) that this parameter is needed. If this parameter is defined, then both functions defined in the <format> and <formathelp> parameters must accept 2 arguments. This parameter does not change how the functions defined by <format> and <formathelp> work, rather, this simply defines an extra argument to pass to these functions. You can do what you want with the argument inside the function that you define.
       
    • <exporthelp> - If defined, this should be set to true or false. If set to true, then the help text (as defined by the <data_help> or <formathelp> parameters) for this field is exported along with the field value when the user exports records to Excel®.
       
    • <showtotal> - If defined, this should be set to true or false. If set to true, then a column total is shown at the bottom of the list display when viewing data records. This parameter is ignored unless the <data_type> parameter is set to either currency or number.
       
    • <datatitle> - If defined, this parameter should be set to either true or false. If set to true, then the contents of fields in this column are shown as the title in the icon and calendar displays. You MUST have 1 (AND ONLY 1) field that has this parameter set to true. Unexpected results could occur if you don't have exactly 1 field with this parameter set to true. Usually, you would set the main human readable field (or column) to have this parameter set to true. For example. Let's say that you have 3 fields: Name, Date, and Status. In this case, we recommend setting the Name field to have this parameter set to true. IMPORTANT: the <datatitle> parameter MUST be set to true exactly once in the entire $dms data structure.
       
    • <data_style> - If defined, this parameter should contain text that is put into the style attribute for the data field column <td> HTML tag. Here is an example of what is output to the user for the data field:
      <td style="<data_style>">Contents Of Data Field</td>
      where Contents Of Data Field is the contents of the field as returned by the <data_query> SQL statement or as formatted by the function defined in the <format> parameter.
       
    • <nocustomfilter> - If defined, this should be set to true or false. If set to true, then the custom filtering capability of VConsole will not be used. Otherwise, it will. Custom filters allow the user to input their own text that is searched within the field. This parameter is ignored if the field is not a text field.
       
    • <customfilterfield> - If defined, this should be the name of a MySQL field that you want to search for the text that the user inputs when defining a custom filter. If not defined or set to false, then the <mysql_field> parameter will be used to search for the text. If the MySQL field specified here does not exist in the MySQL table, then the custom filter function will be disabled for the field.
       
    • <queryfield> - If defined, this should be a simple string that contains a SQL definition of how to obtain the field. This parameter is only valid with date and value fields (such as currency and number fields). This should be a SQL statement that can be replaced as the MySQL field name in the actual SQL data query. For example: Let's say that you have a MySQL table that has 2 number fields and you want your field to show the sum of the 2 fields. You can simply set this parameter to:  "( `num1` + `num2` )" where num1 and num2 are the 2 MySQL fields that you want added together. The same logic applies for date fields and you can even pass an entire subquery that queries another table as this parameter.
       
    • Inline Edit. The following parameters should only be defined if you want to use the "Inline Edit" feature of the data manager. The Inline Edit feature allows the user to click on any field to edit the contents of that field. By default, an inline edit field is highlighted green when the user hovers over the data field. When the user clicks on a field that has inline edit enabled, the user is presented with a form field that allows the user to edit the contents of that field. The parameters described here are almost identical to the parameters that are required by the wizardmanager() and propertiesmanager() functions for creating form fields. With this said, you can create a multitude of different form fields that enable the user to edit and manage their data. Take a look at the <inline_edit_type> parameter below to see what types of fields are possible with the inline edit feature of VConsole.
      
      IMPORTANT: You can only use the inline edit feature for fields that are actual MySQL field names in the data table. For instance, if you have a <data_query> like:
      SELECT *, (`field1` + `field2`) as `total` FROM `table1` WHERE 1
      And you have a field named total, then you cannot use inline edit on this field because total is not an actual field name in the MySQL table as defined by the <mysql_table> parameter.
       
      • <inline_edit_type> - This parameter (and all others in the $dms['data']['fields']['<mysql_field>']['data']['edit'] array) should only be defined if you want to use the "Inline Edit" feature of the data manager. This parameter defines what type of form field should be displayed to the user when they click on a field to edit it. Currently, the possible choices are: text, password, textarea, wysiwyg, list, radio, checkbox, calendar, calendarmonth, calendartime, timepicker, or colorselector. Here is a list of each type and what they do.
        • text - This shows the user a basic text form field.
        • password - This shows the user a password form field.
        • textarea - This shows the user a multi-line text box.
        • wysiwyg - This shows the user a rich text editor field.
        • list - This shows the user a drop down menu or list.
        • radio - This shows the user a radio button set.
        • checkbox - This shows the user a checkbox field.
        • calendar - This shows the user a user friendly date picker interface.
        • calendarmonth - This shows the user a user friendly year / month picker interface.
        • calendartime - This shows the user a user friendly date plus time picker interface.
        • timepicker - This gives the user a user friendly time picker interface.
        • colorselector - This gives the user a user friendly color picker interface.
        • 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.
           
      • <field_prepend> - This parameter is a simple string that should be put before the input field. This is great for specifying dollar signs or other strings that may make it clearer to the user what type of data you are looking for. For example: If you want the user to enter a domain name, you may want to set this parameter to http://www.
         
      • <field_postpend> - This parameter is a simple string that should be put after the input field. This is great for specifying percentages with a simple percent sign or other strings that may make it clearer to the user what type of data you are looking for. For example: If you want the user to enter whole dollars and no cents, you may want to set this to .00 dollars
         
      • <inline_edit_help> - This parameter defines a human readable message to show to the user when they hover their mouse over the input field for a moment. HTML is OK.
         
      • <inline_edit_checkedvalue> - This parameter is ignored unless the <inline_edit_type> parameter is set to checkbox. This parameter defines the value of the checkbox form field when it is checked.
         
      • <inline_edit_lineup> - This parameter is ignored unless the <inline_edit_type> parameter is set to radio. This parameter should be set to either horizontal or vertical. If not defined, it defaults to vertical. This parameter controls the orientation of the radio buttons in the radio button set. If set to vertical, the buttons are stacked vertically, and if set to horizontal, the buttons are displayed side by side.
         
      • <inline_edit_colortype> - This parameter is ignored unless the <inline_edit_type> parameter is set to colorselector. This parameter should be set to either websafe or smooth. If not defined, it defaults to websafe. This parameter controls what type of color selector interface is displayed to the user. If set to websafe, then only web safe colors can be selected. If set to smooth, then the full color spectrum can be selected.
         
      • <inline_edit_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.
         
      • <inline_edit_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 <inline_edit_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 Wizardmanager.
        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 <inline_edit_selector_value> parameter (below) and $value is the current value of the field. 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.
         
      • <inline_edit_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 <inline_edit_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.
         
      • <inline_edit_choices> - This parameter is ignored unless the <inline_edit_type> parameter is set to list or radio. 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 2 fields (in this order). Label and Value. The Label field will be shown to the user. Whatever is in the Value field will be set in the database when the user saves their changes. Here is an example of a valid SQL query.
          SELECT `Name`, `Value` 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.
           
      • <name_of_attribute> - 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 the VConsole:
          id, name, type, value, onmouseover, onmouseout, class, fieldtype, txtname, readonly.
          Also, do not use onfocus when you have the <inline_edit_type> parameter set to calendar, calendartime, timepicker, colorselector, 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>"
         
      • <inline_edit_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 their input is not saved. (You can control the error message using the <inline_edit_failmsg> parameter.)
         
      • <inline_edit_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.)
           
      • <inline_edit_minlength> - 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.
         
      • <inline_edit_maxlength> - 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.
         
      • <inline_edit_minnum> - 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.
         
      • <inline_edit_maxnum> - 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.
         
      • <inline_edit_match> - 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.)
         
      • <inline_edit_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 <inline_edit_match>. This parameter is ignored if <inline_edit_match> is not defined or is set to false.
         
      • <inline_edit_nomatch> - 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.)
         
      • <inline_edit_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 <inline_edit_nomatch>. This parameter is ignored if <inline_edit_nomatch> is not defined or is set to false.
         
      • <inline_edit_failmsg> - 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.
         
      • 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.
         
        • <inline_edit_uniquetable> - This parameter must be set to the name of a MySQL table to check for duplicate values. Usually, this should be set the same as <mysql_table>
           
        • <inline_edit_uniqueindex> - This parameter must be set to the primary key for the MySQL table. Usually, this should be set the same as <mysql_tableindex>
           
        • <inline_edit_uniquefield> - This parameter must be set to the name of the MySQL field to check for duplicate values. Usually, this should be set the same as <mysql_field>
           
        • <inline_edit_uniquefailmsg> - If defined, this parameter must be a human readable message that is shown to the user if any duplicates are found in the table.
           
  • Data Filters. The parameters here define a list of filters for the field. Filters should (but they don't have to) only be defined for MySQL fields that have a finite list of possible choices. When you define a filter, the user can set the column to only show data records that match the desired filter (or filters). For example: If you have a field that has 3 possible choices, then you could define 3 filters. One filter for each choice. So, let's say that the 3 choices are "Apples", "Oranges", and "Bananas". With 3 filters defined, the user can then view only records that have the field value set to "Apples" or just "Bananas" or Both "Apples" and "Oranges" etc.... That is the power of data filters. Filters let your users find the data that they want more easily. Although you can follow the recommendations to create 1 filter for each choice, you can also get creative and create dynamic filters, or filters that match records from another table, or even reverse filters that match everything but a certain value. Check the parameters below and use your imagination.
     
    • <filter_label> - This should be set to a human readable label. This is shown to the user. Something like: Show Only Bananas is appropriate here. HTML is OK
       
    • <filter_query> - This should be a string that contains a single WHERE condition and will be appended to the end of the <data_query> and <count_query> SQL queries. Do not include AND or OR either before or after the condition (Unless you enclose the condition in parenthesis and the entire statement can be read as a single SQL condition) as AND will be auto prepended in the datamanager() function. A great example of what you can put here: `enabled` = 1  This WHERE condition will be applied to end of the data and count queries. The <data_query> will then become: <data_query> AND <filter_query> when executed and the <count_query> will then become: <count_query> AND <filter_query>. Make sure that this statement makes sense when appended to the end of both the data and count queries. So let's give some good and bad examples to clear any confusion:
      • Let's say that the <data_query> is:   SELECT * FROM `table1` WHERE 1   (remember, the data query should contain a where clause no matter what)
      • And lets say that the <count_query> is:   SELECT COUNT(*) FROM `table1 WHERE 1   (The count query should contain a where clause as well)
      • And you set this parameter to:   `enabled` = 1
      • Then the SQL for each query would look like this:
        • Data Query:   SELECT * FROM `table1` WHERE 1 AND `enabled` = 1
        • Count Query:   SELECT COUNT(*) FROM `table1` WHERE 1 AND `enabled` = 1
        • THIS WORKS: Both queries make sense.
          
          
      • Now, let's say that the <data_query> is:    SELECT `table1`.*, `table2`.`label` FROM `table1`, `table2` WHERE `table1`.`id` = `table2`.`index`
      • And let's say  that the <count_query> is:    SELECT COUNT(*) FROM `table1` WHERE 1
      • And you set this parameter to:    `table2`.`enabled` = 1
      • Then the SQL for each query would look like this:
        • Data Query:    SELECT `table1`.*, `table2`.`label` FROM `table1`, `table2` WHERE `table1`.`id` = `table2`.`index` AND `table2`.`enabled` = 1
        • Count Query:    SELECT COUNT(*) FROM `table1` WHERE 1 AND `table2`.`enabled` = 1
        • THIS DOES NOT WORK. The data query makes sense, but the count query does not because there is no table2 in the from clause or in a join. (This is why we say that if the <data_query> contains a table join, then the <count_query> must contain the same join.)
        In short, the value that you put here should make sense with both the data query and the count query when AND is added to the end of those queries and then - what you enter here - is added to the end of that.
         
    • <filter_separator> - If defined, this should be set to either before, after, or both. This parameter determines what menu separators (if any) are added to the menu item and where.
       
    • <filter_chartlabel> - If specified, this value will be shown in the chart display when generating reports. If you are not licensed to use the report module or you don't have fusion charts installed, this parameter is ignored. Also, if <filter_chartfield> and <filter_chartvalue> are not specified, this parameter is also ignored. Basically, if the user builds a report using this filter, then what you specify here will be shown to the user for this filter choice. If not specified, then <filter_label> is shown instead. So why is this field even here? Well, if you look above, the <filter_label> field can contain HTML, but chart display will simply process HTML as plain text, so if you have HTML in your <filter_label> parameter, then you should define a plain text version of that label here. (Otherwise, actul HTML code will be shown in reports.) You can also use this field to show a different label in chart display than in the filter selection menu.
       
    • <filter_chartfield> - If you plan to allow users to generate charts using this filter, you will have to supply this parameter. If you are not licensed to use the report module or you don't have fusion charts installed, this parameter is ignored. Also, if <filter_chartvalue> is not specified, this parameter is also ignored. If defined, this should be set to the name of the MySQL field (It can actually be any field that is returned by the MySQL data query. I'll explain this in a moment) that the reporting engine should test against in order to include in the statistics for this filter. OK, so let's go over a quick example:
      • If your <data_query> is:   SELECT `field1`, `field2` FROM `table1` WHERE 1
      • And you set this parameter to  field1
      • Then, all the values for field1 that match the <filter_chartvalue> parameter below will be included in the statistics for this filter.
      • So if you have 5 rows that have `field1` = 'value1' and the <filter_chartvalue> parameter below is set to "value1", then the report will show a count of 5 for this filter. (I hope that this is clear. If not, please submit a support ticket)

      Also, I mentioned that this parameter can actually be any field that is returned by the MySQL data query. OK, so if you have a data query like:    SELECT `field1` as `f1`, `field2` as `f2` FROM `table2` WHERE 1   then you can set this parameter to f1 or f2. So it doesn't have to be an actual MySQL field, it just has to be a field that is returned by the MySQL data query defined in the <data_query> parameter.
       

    • <filter_chartvalue> - If you plan to allow users to generate charts using this filter, you will have to supply this parameter. If you are not licensed to use the report module or you don't have fusion charts installed, this parameter is ignored. Also, if <filter_chartfield> is not specified, this parameter is also ignored. If used, this should be set to the value that is expected for the <filter_chartfield> parameter above when this filter is applied. The MySQL field specified by the <filter_chartfield> parameter above should match this value in order to be counted in the reporting statistics for this filter. Generally, this should be set to the value of the WHERE clause defined by the <filter_query> parameter above (although there are some situations where it cannot).  For Example:
      • Let's say that the <filter_query> is set to:    `enabled` = 1
      • Then the <filter_chart_field> parameter above should be set to   enabled
      • And this parameter should be set to   1
         
      • However, if the <filter_query> is set to:   `enabled` > 0
      • Then it is impossible to generate reports based on this filter as the filter reporting only allows for a single value to be tested for equality. 
      • (Future versions may address this issue if we get enough requests for it. Please submit a support ticket if you would like to request this feature.)
      • In this case, the <filter_chartfield> parameter and this parameter should be left blank as reports will not be accurate.
         
    • <filter_help> - If defined, this parameter should be set to a human readable message that is shown to the user when the user hovers their mouse over a filter menu item for a moment. This message should describe what the filter does. Something like: Click to show all enabled records is appropriate. HTML is OK.
       
  • Importing From CSV Files. The following parameters control the import from CSV function of VConsole. If the <allow_import> parameter is not defined or is set to false, then these parameters are ignored. Likewise, if the <allow_import> parameter is set to true, then these parameters are required for each field that you want to be able to import to.
     
    • <import_field> - This should be set to the MySQL field that you want to import to for this field (from CSV). This should be set to a real MySQL field name, not just a field that is returned by the MySQL <data_query> query. Usually, this should be set the same as <mysql_field> but if <mysql_field> is set to a non real MySQL field name, then you must change this parameter so that data is imported to the correct MySQL field.
       
    • <import_type> - This should be set to either bool or text. If set to bool, then the value in the CSV file is not actually imported. Instead, it is evaluated to be true or false and if true, then 1 is imported and if false, then 0 is imported to the MySQL field defined by <import_field>. If set to text, or if not defined, then the actual value in the CSV file is imported "as is" to the MySQL table.
       
• Developer Defined Layouts. As mentions above, you can specify your own developer defined layouts that allow the user to quickly switch to different column sets. This is handy when you have many fields and you want to categorize fields so that the user is not overwhelmed by all the different data fields. Developer defined layouts are shown to the user in the View drop down menu in the top menu bar. If you do not define any custom layouts here, then the user only sees an option to apply the default layout. The default layout is defined as what the user sees the first time that they view the module. With that being said, all you do here is specify a list of fields to show when the user selects the layout. It's very simple and straight forward. You can create as many layouts as you want, but we recommend creating 10 or less or the user may be overwhelmed.
   
  • <layout_name> - This should be set to the human readable name of the layout. This is shown to the user in the layout cascading drop down menu. You should make this parameter descriptive yet short. Something like: Address Fields is appropriate. HTML is OK (we recommend only simple HTML here like icon images or <em> tags)
     
  • <name_of_field> - This should be set the same as the <mysql_field> parameter. You should list all the fields that you want to display in the layout. They will be shown to the user in the order that they are listed here. You can even list the same field more than once. List as many fields as you want the user to see when they apply the layout.
     
• <thumbnail_function> - If defined, this should be the name of a PHP function that is defined in the functions.php file (See below for more information on the functions.php file). This function name must globally unique in VConsole. No other module or other field can have duplicate function names for this parameter. We recommend using the format: <module>_thumbnail when setting this parameter. This function should take 1 required argument which is the associative array that is returned by the mysql_fetch_assoc() php function when the <data_query> SQL statement is executed. The function should then return a string of what the user should see where the thumbnail goes in icon display mode. This parameter is only relevant when the user is in icon display mode. Although this function can return whatever you want it to, it should return HTML code that displays a thumbnail to the user. (Recommended max 100px x 100px) This parameter is great for displaying thumbnail photos of clients or even thumbnail previews of PDF documents. Really, you can use this for whatever you want. (Also, see Image Manipulation for some great information on how to create thumbnail images) Here is a short code example of what the function may do. We'll leave it as an exercise to figure out what this function does.
  
  function clients_thumbnail($record) {
     if (file_exists("clientphotos/{$record['id']}_thumb.gif")) {
        return("<img src=\"clientphotos/{$record['id']}_thumb.gif\" alt=\"Photo\" />");
     } else {
        return "<strong>No Image</strong>";
     }
  }
  
   
• Configuring the "Lines To Load" Menu. The lines to load menu contains a list of "lines to load" options for the user. The more lines to load, the more records can be loaded into the datamanager at 1 time. IMPORTANT: We don't recommend configuring a setting that loads more than 500 records at once. If you do, the user's browser may become extremely sluggish and may even crash. The reason for this limitation is derived from the fact that the interface is AJAX powered which means that all the HTML code must be loaded into AJAX memory before being drawn onto the browser screen. The more HTML code that must be loaded at once, the more memory and processing resources are used up. The "Lines To Load" menu is only shown when there are more than the default number of records available for the user to view. The default number of records is set by the <ltl_default> parameter below and should not be extremely high (we recommend 50 or less). Although the interface uses AJAX and does not have to re-draw the entire user interface, the interface does have to re-draw every record every time the user performs a sort action or a filter action, or any other operation on their data. The more records that the user is viewing at once, the harder the browser has to work in order to re-draw the data records. Even though the user cannot view 500 records at a time (at least not reliably), they can perform sort, filter, and search operations which makes it easy to find the data that they want without having to scroll though all the data records anyway. That being said, you can create as many "Lines Per Page" options as you want.
   
  • <lines_to_load> - This parameter should be set to a positive whole number and defines the number of records to show when the user has selected this option.
     
  • <ltl_default> - This parameter should be set to true or false. If set to true, then this option is the default number of lines to load. Only 1 "Lines To Load" choice should have this parameter set to true.
     
• Configuring the Legend. The legend is an area where you can put images and their meanings. The purpose of this area is to give users a quick description of what all the images that you use mean. For example, if you use 3 different icons in your application, and you want the user to know what those icons mean, the place to do that is the legend area. The legend part of the data structure calls for an array of arrays, each with an image and text parameter. The image parameter should be the name of an image and the text should describe the image. Check out the parameters below.
   
  • <legend_image> - This should be the name of an image as required by the getimage() function.
     
  • <legend_text> - This should be set to text that describes the image in <legend_image>