Introduction To PHP Functions.
The core of VConsole is built on a series of powerful PHP functions that allow you to do all sorts of things. Unlike the javascript functions, the PHP functions are designed for you to actually use them in your module, function, and action files. In addition, you can even create your own PHP libraries that can be included in VConsole. (See Building PHP Libraries for more information.)

PHP Function Code Hints And Color Coding.
If you are using Dreamweaver® to code your PHP module and action files, and you have the VConsole Developer Tools Extension installed, you may notice that you will get code hints when calling these functions. The great thing about this is that you can see at a glance what arguments are required and what they should be. You can also recognize a VConsole function easily because all VConsole built in functions are color coded purple. Also, you get lots of great features with the toolkit that allow you to quickly create your VConsole application like dialog boxes for creating datamanager fields or field filters and lots more. Check out the "Developing With Dreamweaver" section for more details.

Built In PHP Functions.
All the functions listed below show the function name along with a brief description of what the function does, what the arguments should be, what is returned, and any other valuable information. When specifying each function, we also provide a list of arguments along with data types. Any argument that is encapsulated in square brackets is optional. Here is a list of all the data types and what they mean:

• string - The parameter is expected to be a string.
• int - The parameter is expected to be an integer or whole number.
• bool - The parameter is expected to be true or false. You can pass any value, but the only thing that matters is if it evaluates to true or false.
  
• varref - The parameter is expected to be a variable. This variable may be populated, overwritten, or modified by the function and can be read and used once the function returns.
  
• array - The parameter is expected to be an array. What the array should contain or the structure of the array depends on the function.
  
• float - The parameter is expected to be a floating point number. Basically any number with or without a decimal point.
  
• choice - The parameter is expected to be 1 of a predefined set of choices. The valid choices are shown in the code hint.
  
• arrayref - The parameter is expected to be an array. This array may be populated, overwritten, or modified by the function and can be read and used once the function returns.
  
• regex - The parameter is expected to be a regular expression that can be passed to preg_match() as the first parameter.
• mixed - The parameter is expected to be any type of data that is understood by the print_r() php function. It can be a variable, an array, a multi-dimensional array, or an object.
  
• void - No parameters are expected
  
  Record IDs - Many of the functions in this section refer to record ids (or record id). A record id is the value of the primary key field in the MySQL table for the record in question. The MySQL primary key field does not have to be named "id"
   
   
   
• build_pageselector(int $current_page, int $total_pages)
  • Description - Returns the HTML code for a drop down menu. This drop down menu is build based on the arguments passed.
  • Used - This function is no longer used as of Version 4.5-4 but is still available for developers to use.
    • $current_page - int. Should be the current page that you want to show as selected in the drop down list.
    • $total_pages - int. Should be the total number of pages that you want to show in the drop down list.
  • Returns - string. The HTML code that contains the drop down list. This can be output directly to the browser.
    <?php
    $pages = build_pageselector(2, 5);
    // Now pages contains HTML for a drop down list
    ?>
    
     
• check_browser_compat(void)
  • Description - Checks that the current browser is compatible with the software. (This check will vary depending on what browsers your current VConsole version supports.)
  • Used - This function is called on every access to the software. You can also customize this function in the vconsole/functions/common/check_browser_compat.php file.
  • Arguments - None
  • Returns - bool. false if the browser is compatible. If the browser is not compatible, the function sets an error message and exits.
    <?php
    check_browser_compat()
    // If we get to here, then the browser
    // is compatible.
    ?>
    
     
• check_email(string $email, varref &$error[, bool $dnscheck=true])
  • Description - Runs a validation check on an email address to make sure that it is valid.
  • Used - This function is called when creating new users to check that their email address is valid. You can use it anywhere in your modules.
  • Arguments
    • $email - string. The email address to check
    • $error - varref. A variable that will contain the error message if the email address fails to validate.
    • $dnscheck - bool. Optional. If set to true (default) then the domain part of the email address is checked for a valid MX or A DNS record. If $PARAMS['EMCHKOFF'] is set to 1, then DNS checks are never performed.
  • Returns - bool. true if the email address is valid or false if not. If set to false, then $error will contain an explanation as to why validation failed.
    <?php
    if (!check_email('test@test.com', $error, true)) {
      // Address is not valid
      echo $error;
    } else {
      // Address is valid
      echo 'Success';
    }
    ?>
    
     
• check_email_domain(string $email, varref &$error[, bool $dnscheck=true])
  • Description - Runs a validation check on the domain part of an email address. In fact, you don't even have to pass the first part of the email address. However, it must have the @ symbol. So you can pass @domain.com or test@domain.com. The only thing that is checked is the @domain.com.
  • Used - This function is not used anywhere in the default VConsole coding.
  • Arguments
    • $email - string. The email address or @domain to check
    • $error - varref. A variable that will contain the error message if the domain fails to validate.
    • $dnscheck - bool. Optional. If set to true (default) then the domain part of the address is checked for a valid MX or A DNS record. If $PARAMS['EMCHKOFF'] is set to 1, then DNS checks are never performed.
  • Returns - bool. true if the domain is valid or false if not. If set to false, then $error will contain an explanation as to why validation failed.
    <?php
    if (!check_email_domain('@test.com', $error, true)) {
      // Domain is not valid
      echo $error;
    } else {
      // Domain is valid
      echo 'Success';
    }
    ?>
    
     
• check_action_permission([string $module=false][, string $action=false][, bool $return=false])
  • Description - Checks the current user's permission to a certain action.
  • Used - This function is called every time a user attempts to access a module action if the action does not have the "alwaysallow" field set to 1
  • Arguments
    • $module - string. Optional. Set this to the name of the module that you want to check access to. If not set, it defaults to the current module ($_SESSION['module']). This should match the module field in the vc_modules-actions table.
    • $action - string. Optional. Set this to the name of the action that you want to check access to. If not set, it defaults to the current action ($_REQUEST['action']). This should match the action field in the vc_modules-actions table.
    • $return - bool. Optional. If set to true, the function returns true or false depending on whether the user has access. If set to false, the function will only return if the user has access.
  • Returns - bool. true if the user has access or false if the user doesn't. If the $return argument is set to false, and the user does not have access, an error message is displayed and the program exits.
    <?php
    if (!check_action_permission(false, false, true)) {
      echo "No Access to the current action";
    } else {
      echo "You have access";
    }
    ?>
    
     
• check_module_permission([string $module=false][, bool $return=false])
  • Description - Checks the current user's permission to a module. The user MUST have access to at least 1 action for the module or the module must not define any actions for this to return true.
  • Used - This function is called on every access to the interface.
  • Arguments
    • $module - string. Optional. Set this to the name of the module that you want to check access to. If not set, it defaults to the current module ($_SESSION['module']).
    • $return - bool. Optional. If set to true, the function returns true or false depending on whether the user has access. If set to false, the function will only return if the user has access.
  • Returns - bool. true if the user has access or false if the user doesn't. If the $return argument is set to false, and the user does not have access, an error message is displayed and the program exits.
    <?php
    if (!check_module_permission(false, true)) {
      echo "No Access to the current module";
    } else {
      echo "You have access";
    }
    ?>
    
     
• check_permissions(void)
  • Description - Checks the current module ($_SESSION['module']) to see if permission is required. If so, then it calls the check_action_permission() and check_module_permission() functions to check permissions on the current module and action.
  • Used - This function is called on every access to the interface.
  • Arguments - None
  • Returns - bool. true if the module did not require a permissions check (nochkperm set to 1) or false otherwise. A false return means that the user had access to the module and action. If the user does not have access, an error is displayed and the program exits.
    <?php
    if (check_permissions()) {
      // No check made the module doesn't require it.
      echo 'No permission check required';
    } else {
      // The user has access
      echo 'You have access';
    }
    ?>
    
     
• create_main_menu(array $menus[, array $rightclickmenus=false][, bool $returnfirstmenu=false])
  • Description - This function is responsible for creating the top main drop down menus as well as all the right click menus.
  • Used - This function is used whenever the application builds or changes drop down menu items.
  • Arguments
    • $menus - array. A multi-dimensional array that describes what menus to create for the main top menu. See the example for the data structure definition.
    • $rightclickmenus - array. Optional. A multi-dimensional array that describes what menus to create for the right click menus
    • $returnfirstmenu - bool. Optional. If set to true, then just the HTML menu content for the first menu will be returned.
  • Returns - string. If $returnfirstmenu is set to true, then this returns just the HTML menu content for the first menu. If not, then false is returned.
  • If $returnfirstmenu is set to false, then the $OUT['TOPMENU'] and $OUT['MENUSYSTEM'] variables are populated with the entire HTML menu data.
    <?php
    $menus = array(
      // file is the menu id and how I show it.
      // using the javascript vsMenuShow() function.
      'file' => array(
        // title not used for right click menus
        'title' => 'File',
        // help not used for right click menus
        'help' => 'This shows when you are over the title',
        'menuitems' => array(
          // First Menu Item
          array(
            // Image tag as required by getimage()
            'image' => 'icon_ok',
            'label' => 'Label',
            'active' => 0, // Active by default?
            'link' => 'link',
            // 'after', 'before', 'both', or false
            'separator' => 'after',
            // format as a header, not a menu item?
            'header' => true, // or false
            'menuitems' => array(
              // Sub Menu items
            )
          ),
          // Second Menu Item Here ...
        )
      ),
      // Next Menu
    );
    
    // Get the first menu only
    $menu = create_main_menu($menus, false, true);
    // Now $menu contains the menu HTML.
    ?>
    
     
• createXFDF(string $file, array $keys_values[, string $enc='UTF-8'])
  • Description - Takes an associative array and returns an XFDF formatted string that points to a PDF file. The return value should be written out to disk and then used to populate a PDF form.
  • Used - This function is used when generating a PDF form from a datamanager record.
  • Arguments
    • $file - string. The path to the PDF file that contains the form that you want to populate.
    • $keys_values array. The associative array that contains the key / value pairs to populate the PDF form with. Keys should be named after form field names and values will be the populated value of the form field.
    • $enc - String. Optional. The encoding attribute of the <?xml> tag.
  • Returns - string. The XFDF formatted output that can be written out to file to create the XFDF file.
    <?php
    // Create the key / value pairs.
    $fields = array(
      'field1' => 'Value 1',
      'field2' => 'December 31st',
      'field3' => 'WOW, This is great.'
    );
    // Get the XFDF string.
    $xfdf = createXFDF('test.pdf', $fields);
    $fh = fopen('tmp/test.xfdf', 'w');
    fwrite($fh, $xfdf);
    fclose($fh);
    // The file tmp/test.xfdf can now be
    // used to populate test.pdf form.
    ?>
    
     
• currency(float $amount[, choice $type='USD' USD|NUM|USTR])
  • Description - Takes a number and returns formatted output. The formatted output depends on what type of output you want.
  • Used - This function is used in various places throughout the software.
  • Arguments
    • $amount - float. The number that you want to format.
    • $type - choice. Optional. The type of formatted output you would like
      • USD - US Dollars. The dollar sign prefix, then the whole number with 2 decimal places.
      • NUM - Number. The whole number with 2 decimal places.
      • USTR - US Tax rate. The whole number with 3 decimal places and the percent sign postfix
  • Returns - string. The formatted version of $amount.
    <?php
    $dollars = currency(10.020);
    // $dollars now contains '$10.02'
    ?>
    
     
• datamanager(array $data_structure[, bool $noreindex=false])
  • Description - Takes a data structure and outputs a full GUI interface for the user to manage data records from a MySQL table.
  • Used - This function is used for all datamanager type modules.
  • Arguments
    • $data_structure - array. The data structure that tells this function how to format the output to the user. (See The Datamanager for an explanation on how to create this data structure)
    • $noreindex - bool. Optional. If set to true, then re-indexing is not allowed.
  • Returns - This function does not return. (Please see The Datamanager for an example of how to use this function)
     
• datamanager_formatfield_text(array $rowdata, string $fieldname)
  • Description - This function takes the record data from a datamanager MySQL query and formats a field as text and returns the formatted text. This function converts HTML strings to html entities.
  • Used - When the user creates an extra column and that column is a plain text field.
  • Arguments
    • $rowdata - array. The associative array for the record from the datamanager MySQL query. It can also easily be just an associative array that you create.
    • $fieldname - string. The name of the MySQL field that you want to format and return. This should be the name of the key that contains the value that you want to format.
  • Returns - string. The formatted text.
    <?php
    $record['textfield'] = "<text>";
    $text = datamanager_formatfield_text($record, 'textfield');
    // $text now contains "&lt;text&gt;"
    ?>
    
     
• datamanager_formatfield_textarea(array $rowdata, string $fieldname)
  • Description - This function takes the record data from a datamanager MySQL query and formats a field as a text field but with new lines converted to <br />. It also converts HTML to html entities. It then returns the formatted text.
  • Used - When the user creates an extra column and that column is a multi-line text field.
  • Arguments
    • $rowdata - array. The associative array for the record from the datamanager MySQL query. It can also easily be just an associative array that you create.
    • $fieldname - string. The name of the MySQL field that you want to format and return. This should be the name of the key that contains the value that you want to format.
  • Returns - string. The formatted text.
    <?php
    $record['textfield'] = "<text>\n<line2>";
    $text = datamanager_formatfield_textarea($record, 'textfield');
    // $text now contains "&lt;text&gt;<br />&lt;line2&gt;"
    ?>
    
     
• datamanager_formatfield_time(array $rowdata, string $fieldname)
  • Description - This function takes the record data from a datamanager MySQL query and formats a field as human readable time 12 hour time. The field value must be a MySQL formatted time.
  • Used - When the user creates an extra column and that column is a time field.
  • Arguments
    • $rowdata - array. The associative array for the record from the datamanager MySQL query. It can also easily be just an associative array that you create.
    • $fieldname - string. The name of the MySQL field that you want to format and return. This should be the name of the key that contains the value that you want to format.
  • Returns - string. The formatted text.
    <?php
    $record['timefield'] = "13:29:00";
    $time = datamanager_formatfield_time($record, 'timefield');
    // $time now contains "1:29PM"
    ?>
    
     
• datamanager_formatfield_calendarmonth(array $rowdata, string $fieldname)
  • Description - This function takes the record data from a datamanager MySQL query and formats a field as human readable month / year. The field value must be a MySQL year / month
  • Used - When the user creates an extra column and that column is a month / year field.
  • Arguments
    • $rowdata - array. The associative array for the record from the datamanager MySQL query. It can also easily be just an associative array that you create.
    • $fieldname - string. The name of the MySQL field that you want to format and return. This should be the name of the key that contains the value that you want to format.
  • Returns - string. The formatted text.
    <?php
    $record['monthfield'] = "2008-03-01";
    $month = datamanager_formatfield_calendarmonth($record, 'monthfield');
    // $month now contains "Mar 2008"
    ?>
    
     
• datamanager_formatfield_number(array $rowdata, string $fieldname)
  • Description - This function takes the record data from a datamanager MySQL query and converts it into its numerical value
  • Used - When the user creates an extra column and that column is a number field.
  • Arguments
    • $rowdata - array. The associative array for the record from the datamanager MySQL query. It can also easily be just an associative array that you create.
    • $fieldname - string. The name of the MySQL field that you want to format and return. This should be the name of the key that contains the value that you want to format.
  • Returns - number. The numerical value
    <?php
    $record['numberfield'] = "23";
    $num = datamanager_formatfield_number($record, 'numberfield');
    // $num now contains 23
    ?>
    
     
• datamanager_formatfield_color(array $rowdata, string $fieldname)
  • Description - This function takes the record data from a datamanager MySQL query and formats a field as a color coded div. The field value must be a 6 character color code.
  • Used - When the user creates an extra column and that column is a color field.
  • Arguments
    • $rowdata - array. The associative array for the record from the datamanager MySQL query. It can also easily be just an associative array that you create.
    • $fieldname - string. The name of the MySQL field that you want to format and return. This should be the name of the key that contains the value that you want to format.
  • Returns - string. The HTML color coded div
    <?php
    $record['color'] = "FF0000";
    $color = datamanager_formatfield_color($record, 'color');
    /* $color now contains "<div style=\"background:#FF0000; color:#FF0000; width:100%; height:100%;\" onmouseover=\"mouse_move('Color Code: #FF0000');\" onmouseout=\"mouse_move();\">#FF0000</div>" */
    ?>
    
     
• datamanager_formatfield_wysiwyg(array $rowdata, string $fieldname)
  • Description - This function takes the record data from a datamanager MySQL query and strips HTML tags, and then returns the first 100 characters of that string.
  • Used - When the user creates an extra column and that column is a Rich Text field.
  • Arguments
    • $rowdata - array. The associative array for the record from the datamanager MySQL query. It can also easily be just an associative array that you create.
    • $fieldname - string. The name of the MySQL field that you want to format and return. This should be the name of the key that contains the value that you want to format.
  • Returns - string. The formatted text.
    <?php
    $record['wysiwyg'] = "<strong>Testing</strong>";
    $text = datamanager_formatfield_wysiwyg($record, 'wysiwyg');
    // $text now contains "Testing"
    ?>
    
     
• datamanager_formatfield_wysiwyg_help(array $rowdata, string $fieldname)
  • Description - This function takes the record data from a datamanager MySQL query and formats a field for display in a hover help box.
  • Used - When the user creates an extra column and that column is a Rich Text field.
  • Arguments
    • $rowdata - array. The associative array for the record from the datamanager MySQL query. It can also easily be just an associative array that you create.
    • $fieldname - string. The name of the MySQL field that you want to format and return. This should be the name of the key that contains the value that you want to format.
  • Returns - string. The formatted text. (This function returns the exact text as in the value of the array. No change is made. This function does not do anything at this time)
     
• datamanager_formatfield_checkbox(array $rowdata, string $fieldname)
  • Description - This function takes the record data from a datamanager MySQL query and formats a field as a checkbox image. The field value is formatted according to whether it evaluates to true or false.
  • Used - When the user creates an extra column and that column is a Checkbox field.
  • Arguments
    • $rowdata - array. The associative array for the record from the datamanager MySQL query. It can also easily be just an associative array that you create.
    • $fieldname - string. The name of the MySQL field that you want to format and return. This should be the name of the key that contains the value that you want to format.
  • Returns - string. The formatted text.
    <?php
    $record['cbfield'] = "1";
    $cb = datamanager_formatfield_checkbox($record, 'cbfield');
    // $cb now contains an image tag of the icon_checked image.
    ?>
    
     
• datamanager_formatfield_phone(array $rowdata, string $fieldname)
  • Description - This function takes the record data from a datamanager MySQL query and formats a field as a phone number. The field value must contain at least 1 digit.
  • Used - When the user creates an extra column and that column is a Phone field.
  • Arguments
    • $rowdata - array. The associative array for the record from the datamanager MySQL query. It can also easily be just an associative array that you create.
    • $fieldname - string. The name of the MySQL field that you want to format and return. This should be the name of the key that contains the value that you want to format.
  • Returns - string. The formatted text.
    <?php
    $record['phonefield'] = "1234567890";
    $phone = datamanager_formatfield_phone($record, 'phonefield');
    // $phone now contains "(123) 456-7890"
    // Along with a skype integrated click to call button.
    ?>
    
     
• datamanager_formatfield_email(array $rowdata, string $fieldname)
  • Description - This function takes the record data from a datamanager MySQL query and formats a field as an email address along with a clickable mailto: icon. The field value must be a valid email address
  • Used - When the user creates an extra column and that column is an Email field.
  • Arguments
    • $rowdata - array. The associative array for the record from the datamanager MySQL query. It can also easily be just an associative array that you create.
    • $fieldname - string. The name of the MySQL field that you want to format and return. This should be the name of the key that contains the value that you want to format.
  • Returns - string. The formatted text.
    <?php
    $record['email'] = "test@test.com";
    $email = datamanager_formatfield_email($record, 'email');
    // $email now contains the email address along with
    // a clickable mailto: icon
    ?>
    
     
• datamanager_formatfield_url(array $rowdata, string $fieldname)
  • Description - This function takes the record data from a datamanager MySQL query and formats a field as a URL along with a go to icon link. The field value must be a valid URL
  • Used - When the user creates an extra column and that column is a URL field
  • Arguments
    • $rowdata - array. The associative array for the record from the datamanager MySQL query. It can also easily be just an associative array that you create.
    • $fieldname - string. The name of the MySQL field that you want to format and return. This should be the name of the key that contains the value that you want to format.
  • Returns - string. The formatted text.
    <?php
    $record['url'] = "http://www.test.com";
    $url = datamanager_formatfield_url($record, 'url');
    // $url now contains the url along with a
    // Go-to icon link.
    ?>
    
     
• datamanager_formatfield_hasattachments(array $rowdata, array $dms)
  • Description - This function checks to see if the record specified by $rowdata contains any attachments. If so, it returns a paper clip icon along with the complimentary javascript / links.
  • Used - Used in any datamanager module that has the attachments column shown.
  • Arguments
    • $rowdata - array. The associative array for the record from the datamanager MySQL query.
    • $dms - array. The data structure that is created and returned by the dms.php file in a datamanager module. This must be the data structure for the current module.
  • Returns - string. The HTML code that contains the paper clip and supporting javascript / links.
    <?php
    // Assume that $record contains a record from
    // the MySQL table for the current module
    // and that $dms contains the data structure
    // for the current module.
    
    $attach = datamanager_formatfield_hasattachments($record, $dms);
    // If the record defined by $record has document attachments
    // then $attach contains the HTML string that
    // shows the paper clip icon and supporting javascript / links.
    ?>
    
     
• datamanager_formatfield_hasattachments_help(array $rowdata, array $dms)
  • Description - If the record specified by $rowdata contains attachments, then this function returns help text that reflects the number of attachments.
  • Used - Used in any datamanager module that has the attachments column shown.
  • Arguments
    • $rowdata - array. The associative array for the record from the datamanager MySQL query.
    • $dms - array. The data structure that is created and returned by the dms.php file in a datamanager module. This must be the data structure for the current module.
  • Returns - string. A human readable text string that reflects the number of attachments for the specified record.
    <?php
    // Assume that $record contains a record from
    // the MySQL table for the current module
    // and that $dms contains the data structure
    // for the current module.
    
    $items = datamanager_formatfield_hasattachments_help($record, $dms);
    // If the record defined by $record has 3 document attachments
    // then $items contains "3 Items"
    ?>
    
     
• datamanager_getrecord(array $dms, int $rowid)
  • Description - This function gets all fields for a single record. The fields are defined by the $dms data structure.
  • Used - This function is called when the user right clicks on a record in the datamanager and selects "Show Details"
  • Arguments
    • $dms - array. The data structure that is created and returned by the dms.php file for a datamanager module.
    • $rowid - int. Must be set to the record id for the record that you want to get. The record is retrieved from the datamanager module that is defined in the $dms argument.
  • Returns - array. An associative array with field names as keys and field values as values.
    <?php
    // Assume that $dms contains the data structure
    // for a datamanager module.
    
    $record = datamanager_getrecord($dms, 2);
    // Now $record contains all the fields
    // for the record that has an id
    // of 2
    ?>
    
     
• datamanager_getselected([bool $del=false])
  • Description - This function gets an array of selected items from the datamanager. Usually, this function is called to determine which datamanager records were selected the the user attempted to perform an action.
  • Used - This function is called in just about every module action for the built in modules. When the user right clicks one or more records and then selects an action (like "Delete"), this function is called to determine what items to perform the action on.
  • Arguments
    • $del - bool. Optional. If set to true, then a list of selected items is not returned. Instead, the function will set all records to not being selected.
  • Returns - array. An array of record ids that were selected by the user. (Unless $del is set to true, then false is returned)
    <?php
    // Assume that the record ids 1, 4, and 7
    // were selected by the user in the
    // datamanager interface.
    
    $selected = datamanager_getselected();
    // Now $selected = array(1, 4, 7);
    
    // Delete selected items
    datamanager_getselected(true);
    
    // Try to get the list again.
    $selected = datamanager_getselected();
    // Now $selected = array();
    ?>
    
     
• datamanager_integrate_extrafields(arrayref &$dms[, string $module=false])
  • Description - Adds user defined extra fields to the $dms data structure.
  • Used - If the user creates 1 or more extra columns, then those extra column definitions are added to the $dms data structure within the datamanager() function.
  • Arguments
    • $dms - arrayref. Set to the current data structure as defined and returned in the dms.php file.
    • $module - string. Optional. Set to the module that you want to get extra fields for. It defaults to the current module ($_SESSION['module'])
  • Returns - bool. Always returns true.
  • After the function returns, $dms will contain the extra field definitions as well as the definitions defined in the dms.php file.
    <?php
    // Set the dms data structure into $dms
    $dms = get_dms_array($_SESSION['module']);
    
    // Append any user defined extra fields
    datamanager_integrate_extrafields($dms);
    
    // Now $dms has all the user defined extra
    // field definitions added to it.
    ?>
    
     
• db_connect([bool $return=false])
  • Description - Connects to a MySQL database.
  • Used - This function is called on every access to the software to connect to the database.
  • Arguments
    • $return - bool. Optional. If set to true and the connection fails, then the function returns false. If set to false and connection fails, the function doesn't return. Instead an error message is printed and the program exits.
  • Returns - bool. true on a successful connection or false on an unsuccessful connection (if $return is set to true)
  • This function relies on the global variables that are set in the config.php file in order to connect. If you want to connect to a different database other than the VConsole MySQL database, then do not use this function as it will invalidate the database handle. Instead, use normal database connection methods.
    <?php
    // Connect to the database.
    db_connect();
    ?>
    
     
• db_query(string $query, varref &$dbresult)
  • Description - Executes a database query to the main VConsole database. (Use the mysql_query() php if you want to query any other database that you connected to)
  • Used - This function is called every time there is a query to the database.
  • Arguments
    • $query - string. The SQL query to execute. It can be any kind of query.
    • $dbresult - varref. The database result handle will be stored in the variable that you set here.
  • Returns - string. If the query is an INSERT statement, then the primary key of the record that was just inserted is returned. Otherwise true is returned.
    <?php
    // Query the database.
    db_query("SELECT * FROM `table`", $dbr);
    
    // Get the results
    while ($record = mysql_fetch_assoc($dbr)) {
      echo "Got Record: {$record['id']}<br />\n";
    }
    
    // Insert a record
    $id = db_query("INSET INTO `table` SET
       `name` = 'Test Name'", $dbr);
    // Now $id contains the primary key value
    // of the record that we just inserted.
    ?>
    
     
• db_quote(string $string[, bool $noescape=false])
  • Description - This function prepares a string for use as an argument in a MySQL query. This function prevents SQL injection. You should use it whenever you are using any kind of variable in a MySQL query.
  • Used - This function is used for just about all MySQL queries.
  • Arguments
    • $string - string. The string to format as a MySQL argument.
    • $noescape - bool. Optional. If set to true, then no escaping is done on the string. Just the string enclosed in single quotes is returned. If set to false, then the string is escaped as normal.
  • Returns - string. The escaped string, surrounded by single quotes that is safe to use as a MySQL argument.
    <?php
    // Set a variable
    $arg = "Don't worry!";
    
    // Use the variable in a MySQL query
    db_query("INSERT INTO `table` SET
      `text` = " . db_quote($arg), $dbr);
    ?>
    
     
• db_select(string $dbname)
  • Description - This function will change the database that is queried by the db_query() function. The user specified by $GLOB['dbuser'] MUST have access to the database.
  • Used - This function is not used in the default VConsole code base.
  • Arguments
    • $dbname - string. The name of the database that you want to change to.
  • Returns - bool. This function returns true on success or false on failure.
  • IMPORTANT: If you use this function to switch databases, you must switch back to the main VConsole database before you hand control off to a VConsole function. If you don't then the queries that these VConsole functions execute will be made on the new database and may produce MySQL errors. To switch back to the main VConsole database, call this function again with the argument of $DBS['vconsole']
    <?php
    $newdb = "newdatabase";
    if (db_select($newdb)) {
      // The operation succeeded
    } else {
      // The operation failed
    }
    
    // Perform some queries on
    // the new database here.
    
    // Switch back to the main VConsole
    // database when you are done.
    global $DBS;
    db_select($DBS['vconsole']);
    ?>
    
     
• debug(mixed $data)
  • Description - This function will store a string in the vc_debug database and return the id of the record. This function is normally used for debugging.
  • Used - This function was only used by VConsole developers to debug the software. It is not used in the actual release versions of VConsole.
  • Arguments
    • $data - mixed. Pass the variable, array, or object that you want to store in the vc_debug table.
  • Returns - string. The record id of the record that was stored in the vc_debug table prepended with "DEBUG CODE: "
    <?php
    // Define any array.
    $data = array(
      'type' => 'test',
      'multi' => array(
        'sub' => 2,
        'arg' => 'argument'
      )
    );
    $debug_id = debug($data);
    // The $data array is now
    // stored in the vc_debug
    // table in human readable format.
    // $debug_id contains:
    // "DEBUG CODE: <id>"
    ?>
    
     
• delete_searchindex(string $module, string $table_name[, string $table_index_field='id'])
  • Description - This function will delete any datamanager search indexes that do not exist in the data table.
  • Used - This function is used when any datamanager record is deleted.
  • Arguments
    • $module - string. The name of the module to delete search indexes for
    • $table_name - string. The name of the data table to delete search indexes for
    • $table_index_field - string. Optional. The name of the primary key for the table. Defaults to 'id'
  • Returns - bool. Always returns false.
  • IMPORTANT: If you do not call this function when a datamanager record is deleted, the search index table will continue to grow and never get any smaller. Searching speed will degrade with time.
    <?php
    // Assume that the datamanager module name is 'test'
    // Assume that the table that is managed is 'test_table'
    // Assume that the primary key is 'id'
    
    // Delete a record
    db_query("DELETE FROM `test_table` WHERE `id` = 5", $dbr);
    
    // Delete the search index for that record.
    delete_searchindex('test', 'test_table', 'id');
    ?>
    
     
• forcesecure(void)
  • Description - This function will re-direct the client's browser to a secure interface if they are not already on a secure interface.
  • Used - This function is used on every access to the software.
  • Arguments - None
  • Returns - bool. Always returns false. If the user is on an insecure connection, it will not return and instead will re-direct the client's browser to a secure connection. (https)
  • IMPORTANT: If the global variable $GLOB['forcesecure'] is set to a false value, then re-direction will not occur. In order for this function to work, you must set $GLOB['forcesecure'] to true.
    <?php
    // Force a secure connection
    global $GLOB;
    $GLOB['forcesecure'] = true;
    forcesecure();
    // If we get to here, then the user
    // is on a secure connection.
    ?>
    
     
• format_filesize(int $size_in_bytes)
  • Description - Takes the number of bytes and formats that to a human readable byte size. This function does the correct calculations and adds KB, MB, GB, and TB
  • Used - This function is used in the document management module to convert the byte size of an attachment into a human readable format.
  • Arguments
    • $size_in_bytes - int. The number of bytes to convert.
  • Returns - string. A human readable byte size in KB, MB, GB, or TB
    <?php
    // Assume that the file is 1934489220 bytes
    $size = filesize('tmp/file.zip');
    
    // Format the file size
    $hsize = format_filesize($size);
    // $hsize is now '1.80 GB'
    ?>
    
     
• format_mysqldate(string $format, string $date|'NOW()')
  • Description - This function formats a MySQL date to a human readable format as specified by $format
  • Used - This function is used for displaying any MySQL date in a human readable format.
  • Arguments
    • $format - string. A string that determines how to format the date. The following specifiers may be used in the format string. The "%" character is required before format specifier characters.
      • %a Abbreviated weekday name (Sun..Sat)
      • %b Abbreviated month name (Jan..Dec)
      • %c Month, numeric (0..12)
      • %D Day of the month with English suffix (0th, 1st, 2nd, 3rd, ?)
      • %d Day of the month, numeric (00..31)
      • %e Day of the month, numeric (0..31)
      • %f Microseconds (000000..999999)
      • %H Hour (00..23)
        
      • %h Hour (01..12)
        
      • %I Hour (01..12)
        
      • %i Minutes, numeric (00..59)
        
      • %j Day of year (001..366)
        
      • %k Hour (0..23)
        
      • %l Hour (1..12)
        
      • %M Month name (January..December)
        
      • %m Month, numeric (00..12)
        
      • %p AM or PM
        
      • %r Time, 12-hour (hh:mm:ss followed by AM or PM)
        
      • %S Seconds (00..59)
        
      • %s Seconds (00..59)
        
      • %T Time, 24-hour (hh:mm:ss)
        
      • %U Week (00..53), where Sunday is the first day of the week
        
      • %u Week (00..53), where Monday is the first day of the week
        
      • %V Week (01..53), where Sunday is the first day of the week; used with %X
        
      • %v Week (01..53), where Monday is the first day of the week; used with %x
        
      • %W Weekday name (Sunday..Saturday)
        
      • %w Day of the week (0=Sunday..6=Saturday)
        
      • %X Year for the week where Sunday is the first day of the week, numeric, four digits; used with %V
        
      • %x Year for the week, where Monday is the first day of the week, numeric, four digits; used with %v
        
      • %Y Year, numeric, four digits
        
      • %y Year, numeric (two digits)
        
      • %% A literal ?%? character
        
      • %x x, for any ?x? not listed above
    • $date - The MySQL date to format. This can be set to a MySQL date or to 'NOW()' to format the current date / time.
  • Returns - string. The formatted date.
    <?php
    // Set a MySQL formatted date.
    $date = "2007-01-12 10:32:00";
    // You can also set
    // $date = 'NOW()';
    // For the current date.
    
    // Specify a format
    $format = "%b %D, %Y at %l:%i%p";
    
    // Get the formatted date.
    $formatted = format_mysqldate($format, $date);
    // $formatted is now:
    // 'Jan 12th, 2007 at 10:32AM'
    ?>
    
     
• FusionChartsExists(void)
  • Description - This function determines whether or not Fusion Charts is available in the current installation of VConsole. In order for Fusion Charts to be available, the chart .swf files need to exist in the vconsole/FusionCharts/ folder and the current license MUST allow reporting.
  • Used - This function is used to determine whether or not to display the reporting menu items in the datamanager.
  • Arguments - None
  • Returns - bool. It returns true if the .swf files exist and the license allows reporting or false otherwise.
    <?php
    if (FusionChartsExists()) {
      // It exists
    } else {
      // Either the .swf files are
      // missing or the license does
      // not allow reporting
    }
    ?>
    
     
• gauge(string $width, int %$fill[, int %$maxsafe=false][, string $help=false])
  • Description - This function returns the HTML code for a small progress bar. (The progress bar is heavily reliant on the .css files in the skins/vsource/css/ folder to be shown correctly.) This function is perfect for showing a small progress bar within datamanager fields.
  • Used - This function is not used in the default code base.
  • Arguments
    • $width - string. The width of the progress bar in pixels or percent. Example: '150' or '90%'. If this is a percent, then the progress bar size will be dynamic.
    • $fill - int. The amount of fill in percent. (Do not include the percent sign. This should be an integer.)
    • $maxsafe - int. Optional. If set, then this is the maximum percentage that is considered safe. After the safe point, the progress bar turns red instead of green.
    • $help - string. Optional. If set, this will be shown when the user hovers over the progress bar for a moment. HTML OK.
  • Returns - string. The HTML code for the progress bar.
    <?php
    // Get a gauge
    $bar = gauge('50%', 70, 60, '70% Filled');
    // $bar now contains the HTML
    // for the progress bar. at 70% filled.
    // The bar will be red since 70 is above
    // the safe argument of 60
    ?>
    
     
• gauge_big(int $width, int %$fill)
  • Description - This function returns the HTML code for a big progress bar. The progress bar is always green and is animated.
  • Used. This function is used to generate the progress bar that follows the mouse when the interface is loading or being updated.
  • Arguments
    • $width - int. The width of the progress bar in pixels. (This progress bar does not support a dynamic width such as a percentage. It only accepts an integer of pixels.)
    • $fill - int. The amount of fill in percent. (Do not include the percent sign. This should be an integer.)
  • Returns - string. The HTML code for the progress bar.
    <?php
    // Get a gauge
    $bar = gauge_big(300, 70);
    // $bar now contains the HTML
    // for a large animated progress bar. at 70% filled.
    ?>
    
     
• generate_field(array $field, string $defaultval[, string $uploadtmpfile=false])
  • Description - This function generates the HTML code for any type of field that is used by the wizardmanager, propertiesmanager, or inline edit.
  • Used - This function is used any time the wizardmanager, propertiesmanager, inline edit is called. (You would not normally call this function directly as the wizardmanager(), propertiesmanager(), and datamanager() functions call this function internally.)
  • Arguments
    • $field - array. An array that contains the field definition for the field.
      array(
         'type' => [type],
         'name' => [name],
         'fhelp' => [field help on hover],
         'fielddata' => [fielddata array], // Different for each field
      )
    • $defaultval - string. The default value for the field
    • $uploadtmpfile - string. Optional. The path to an existing file. This argument is only used with file fields and if the file specified in this argument exists, then a simple message stating that the file has already been uploaded is postpended to the field.
  • Returns - string. The HTML code for the field.
  • Since this function is normally not called directly, we will not show an example of how to call it.
     
• generate_password([int $length=false])
  • Description - This function generates a random password of a specified length. If $length is not specified, then the length of the password will be between 8 and 16 characters. The password will always start with a letter and will always contain at least 1 letter and 1 number. The minimum length that can be specified is 2, but it is recommended to have passwords of at least 6 characters.
  • Used - This function is not used in the default installation of VConsole.
  • Arguments
    • $length - int. An integer between 2 and 50.
  • Returns - string. The password that was randomly generated.
  • The password will always start with a letter and always contain at least 1 letter and 1 number. It can contain any of the following characters: (Note that 1, l, L, o, 0,  and O are excluded to reduce the chance of confusion to end users.)
    • a-z
    • A-Z
    • 2-9
    • - _ @ $ !
       
    <?php
    // Generate a password of 20 characters.
    $password = generate_password(20);
    // Now $password contains a 20 character password.
    $password = generate_password();
    // Now $password contains a password that is between 8 and 16 characters.
    ?>
    
     
• get_config(void)
  • Description - This function simply includes the config.php file and if the file does not exist, it initiates the installation procedure.
  • Used - This is used on every access to the software.
  • Arguments - None
  • Returns - bool. Always returns false.
  • Since this function is not used except to include the config.php file (which is already included by the time your module files are executed) we will not show an example of how to call it.
     
• get_content_type(string $fileextension)
  • Description - This function returns the mime type for the file extension specified by $fileextension. The return value can be printed to the browser as the Content-type header on file downloads.
  • Used - This function is used in the document management module whenever the user downloads an attachment.
  • Arguments
    • $fileextension - string. The file extension to get the mime type of. (Do not include the dot)
  • Returns - string. The mime type that can be output in the Content-type header to the browser.
  • IMPORTANT: The extension must exist in the vc_mimetypes table. If the extension does not exist in the table, then 'application/octet-stream' is returned.
  • You can add or modify mime types by adding to or modifying the vc_mimetypes table.
    <?php
    // Get the content type for a .doc file.
    $mimetype = get_content_type('doc');
    // $mimetype is now set to:
    // 'application/msword'
    
    // If the user is downloading a file
    // Output the headers, the file,
    // then exit. Assume the file that
    // the user is downloading is file.doc
    header('Cache-Control:');
    header('Pragma:');
    header("Content-type: $mimetype");
    header("Content-Length: ".@filesize("file.doc"));
    header("Content-Disposition: attachment; filename=\"file.doc\"");
    readfile("file.doc");
    exit;
    ?>
    
     
• get_dms_array(string $module)
  • Description - This function gets the $dms data structure for a module. It does this by executing the dms.php file and then returning the data structure that is returned by the dms.php file for the module.
  • Used - This function is used on every datamanager module and in the searchindex() function to index the data for all the fields.
  • Arguments
    • $module - string. The name of the module to get the $dms data structure of. To get the data structure for the current module, pass $_SESSION['module']
  • Returns - array. The $dms data structure array that is built in the dms.php file for the specified module.
    <?php
    // Get the data structure for the current module
    $dms = get_dms_array($_SESSION['module']);
    // $dms now contains the array that is defined
    // in the dms.php file for the current module.
    ?>
    
     
• get_module_list(void)
  • Description - This function is responsible for generating the HTML for the top navigation bar. (The bar that contains the list of modules)
  • Used - This function is used on every access of the software to get the current module list that displays in the top navigation bar.
  • Arguments - None
  • Returns - string. The HTML code that is displayed in the top navigation bar.
  • Since this function is not useful other than generating the HTML code for the top navigation bar, which is generated before your module files are executed, we will not show an example of how to call it.
     
• get_params(void)
  • Description - This function is responsible for generating the $PARAMS global array. It reads every record in the vc_console-params table and returns an array of all the name - value pairs.
  • Used - This function is responsible for generating the $PARAMS global array and is called on every access to the software.
  • Arguments - None
  • Returns - array. The array of all the name - value pairs as defined in the vc_console-params table.
    <?php
    $params = get_params();
    // Now $params contains all the
    // name - value pairs as defined
    // in the vc_console-params table
    ?>
    
     
• get_url(string $url[, string $postvars])
  • Description - Gets and returns the output of a URL. PHP MUST be compiled with CURL support. (This is a requirement of the software anyway)
  • Used - This function is used in the liveupdate module for updating the software, although, it can be used to get the contents of any URL.
  • Arguments
    • $url - string. The url to get the contents of. Example: http://www.vsourceweb.com
    • $postvars - string. Optional. A url encoded string that defines the POST variables to send when retrieving the contents of the URL.
  • Returns - string. The contents of the URL. It if is a web page, then HTML is returned.
    <?php
    // Set the URL
    $url = 'http://www.vsourceweb.com';
    
    // Set some POST variables
    $post = 'var1=test1+var&var2=test2+var&var3=test3+var';
    
    // Get the url and send the POST variables to the URL
    $content = get_url($url, $post);
    
    // Now $content contains the content of the url.
    ?>
    
     
• getimage(string $imagename[, string $align='absmiddle'][, int alpha=100])
  • Description - This function returns the HTML code to display an image from the vconsole/skins/vsource/buttons/ or vconsole/skins/vsource/icons/ folders
  • Used - This function is used anytime that a button or icon image is displayed in the interface.
  • Arguments
    • $imagename - string. The name of the image. If the image is located in the vconsole/skins/vsource/buttons/ folder, then you will put the name of the image file without the extension. If the image is located in the vconsole/skins/vsource/icons/ folder, then you will put the string 'icon_' followed by the name of the image without the extension.
    • $align - string. Optional. The text to put as the align attribute for the image. If you pass 'top', then the return value becomes something like:
      <img src="path_to_image" align="top" />
    • $alpha - int. Optional. The alpha transparancy of the image from 0 to 100 with 0 being invisible and 100 being completely opaque. (The alpha is set using css and should work in all supported browsers.)
      Example: <img src="path_to_image" style="opacity:50;filter:alpha(opacity=50);" />
  • Returns - string. The HTML code that displays the image.
  • You can see a list of available image names (the $imagename argument) by pulling up vconsole/showimages.php in a browser.
  • If you want to add buttons, then you should put the image file in the vconsole/skins/vsource/buttons/ folder. Buttons should be 32 x 32 pixels. Allowed formats are: png, jpg, gif
  • If you want to add icons, then you should put the image file in the vconsole/skins/vsource/icons/ folder. Icons should be 16 x 16 pixels. Allowed formats are: png, jpg, gif
  • This function is used for getting images from image parameters in datamanager, wizardmanager, and propertiesmanager data structures.
    <?php
    $image = getimage('icon_add');
    // $image now contains
    // '<img src="skins/vsource/icons/add.png" border="0" align="absmiddle">'
    ?>
    
     
• has_permission(string $module)
  • Description - This function is depreciated and no longer functions since VConsole V4.0. Use the check_module_permission() function instead.
     
• help_format(string $helptext[, bool $breaks=true])
  • Description - This function formats any string so that it can be used as an argument in the mouse_move() javascript function. That javascript function is responsible for displaying the hovering help box.
  • Used - This function is used for just about every string that is shown in the hovering help box.
  • Arguments
    • $helptext - string. The text to show in the hovering help box. HTML and newlines are OK.
    • $breaks - bool. Optional. If set to true, (default), then newlines will be substitutes with <br />. If set to false, then newlines will be substituted with spaces. You should set this to false if attempting to format HTML.
  • Returns - string. The formatted string that can be used in the mouse_move() javascript function.
    <?php
    // Set the help string
    $help = "<strong>This should be bold</strong><br />
             This should be on the Second line.";
    
    // Format the string.
    $fhelp = help_format($help, false);
    
    // Now print out an image with the mouse_move()
    // javascript function. When the user hovers
    // over the image, then the help text will
    // be displayed in the hovering help box
    echo "<img src=\"img.gif\" onmouseover=\"mouse_move('$fhelp')\" />";
    ?>
    
     
• hierarchical_add(string $table, int $parent, varref &$err[, string $index='id'][, string|resource $dbhandle=false])
  • Description - This function adds a record to a MySQL table that contains nested set hierarchical data. (See "Managing Hierarchical Data" for more information). It will perform all the functions as described in the "Adding A Record" section including locking the table and rearranging all the lft, rgt, and optionally depth values of the table (if a depth field is present in the table). The table MUST contain a lft and rgt field in order for this function to work properly otherwise you will get a MySQL query error. The table can optionally contain a depth field to keep track of the depth of a record. (We recommend having a depth field because you will get a huge performance boost when the table has a lot of records.) Depending on how you use your hierarchical table, we also recommend indexing the lft, rgt, and depth fields.
  • Used - This function is not used in the default installation of VConsole. However, you can use it to add a record to a hierarchical data table.
  • Arguments
    • $table - string. Should be the name of the MySQL table to add the record to.
    • $parent - int. Should be the primary index of the record that should be the parent of the new record. The new record will be added as the last child of the record that is specified here.
    • $err - varref. A variable should be passed that will be populated with the error message in case of failure.
    • $index - string. Optional. If set, this should be the MySQL field name of the primary index for the table. This defaults to 'id' if not set.
    • $dbhandle - string or resource. This should be set to the database handle to use when adding the record to the table. Only advanced users should attempt to use this parameter.
  • Returns - int. This function returns the id of the primary index for the record that was added. The record is always added with no data. You should use the return value of this function to update the record with the data that you want it to have.
    <?php
    // Add a new record to the vc_trees table
    // as a child of the record at id 7
    $id = hierarchical_add('vc_trees', 7, $err);
    
    // Now the record has been added correctly and
    // $id contains the primary key for the new record
    // so that we can modify the other record fields.
    ?>
    
     
• hierarchical_delete(string $table, int $id, varref &$err[, string $index='id'][, bool $sub=true][, string|resource $dbhandle=false])
  • Description - This function deletes a record from a MySQL table that contains nested set hierarchical data. (See "Managing Hierarchical Data" for more information). It will perform all the functions as described in the "Deleting A Record" section including locking the table and rearranging all the lft, rgt, and optionally depth values of the table (if a depth field is present in the table). The table MUST contain a lft and rgt field in order for this function to work properly otherwise you will get a MySQL query error. The table can optionally contain a depth field to keep track of the depth of a record. (We recommend having a depth field because you will get a huge performance boost when the table has a lot of records.) Depending on how you use your hierarchical table, we also recommend indexing the lft, rgt, and depth fields.
  • Used - This function is not used in the default installation of VConsole. However, you can use it to delete a record from a hierarchical data table.
  • Arguments
    • $table - string. Should be the name of the MySQL table to delete the record from.
    • $id - int. Should be the primary index of the record to delete.
    • $err - varref. A variable should be passed that will be populated with the error message in case of failure.
    • $index - string. Optional. If set, this should be the MySQL field name of the primary index for the table. This defaults to 'id' if not set.
    • $sub - bool. Optional. If set to false, then all sub branches are not deleted and instead promoted to the level of the deleted branch. If set to true or not specified, then all sub branches will also be deleted.
    • $dbhandle - string or resource. This should be set to the database handle to use when performing this operation. Only advanced users should attempt to use this parameter.
  • Returns - bool. This function returns true on success or false on failure. If it returns false, then $err will be populated with a reason why.
    <?php
    // Delete the record from the vc_trees table
    // at index number 8 and delete all child
    // records as well
    if (hierarchical_delete('vc_trees', 8, $err)) {
       /* Successful Delete
          Now the record has been correctly deleted
          with all other records' lft and rgt values
          properly adjusted */
    } else {
       // Delete Failed and $err contains the reason
    }
    
    ?>
    
     
• hierarchical_moveto(string $table, int $id, int $moveto, varref &$err[, string $index='id'][, string|resource $dbhandle=false])
  • Description - This function takes care of moving a record (and all children) to a new parent in a MySQL table that contains nested set hierarchical data. (See "Managing Hierarchical Data" for more information). It will perform all the functions necessary to move a record (and all children) to a new parent including locking the table and rearranging all the lft, rgt, and optionally depth values of the table (if a depth field is present in the table). The table MUST contain a lft and rgt field in order for this function to work properly otherwise you will get a MySQL query error. The table can optionally contain a depth field to keep track of the depth of a record. (We recommend having a depth field because you will get a huge performance boost when the table has a lot of records.) Depending on how you use your hierarchical table, we also recommend indexing the lft, rgt, and depth fields.
  • Used - This function is not used in the default installation of VConsole. However, you can use it to move a record to a new parent in a hierarchical data table.
  • Arguments
    • $table - string. Should be the name of the MySQL table in which to move the record.
    • $id - int. Should be the primary index of the record to move.
    • $moveto - int. Should be the primary index of the record that the record (and all children) should be moved under. The record specified in the $id parameter will be set as the last child of the record that is specified here.
    • $err - varref. A variable should be passed that will be populated with the error message in case of failure.
    • $index - string. Optional. If set, this should be the MySQL field name of the primary index for the table. This defaults to 'id' if not set.
    • $dbhandle - string or resource. This should be set to the database handle to use when performing this operation. Only advanced users should attempt to use this parameter.
  • Returns - bool. This function returns true on success or false on failure. If it returns false, then $err will be populated with a reason why.
    <?php
    /* Move the record at index 7 and all children
       as a child of record number 20 in the vc_trees table */
    if (hierarchical_moveto('vc_trees', 7, 20, $err)) {
       /* Successful Move
          Now the record and all children have been moved
          as a child of record 20 */
    } else {
       // Move Failed and $err contains the reason
    }
    
    ?>
    
     
• hierarchical_setorder(string $table, int $id, int $order, varref &$err[, string $index='id'][, string|resource $dbhandle=false])
  • Description - This function takes care of setting the order of a record within the parent record in a MySQL table that contains nested set hierarchical data. (See "Managing Hierarchical Data" for more information). It will perform all the functions necessary to move a record (and all children) to a new order within the parent including locking the table and rearranging all the lft, rgt, and optionally depth values of the table (if a depth field is present in the table). The table MUST contain a lft and rgt field in order for this function to work properly otherwise you will get a MySQL query error. The table can optionally contain a depth field to keep track of the depth of a record. (We recommend having a depth field because you will get a huge performance boost when the table has a lot of records.) Depending on how you use your hierarchical table, we also recommend indexing the lft, rgt, and depth fields.
  • Used - This function is not used in the default installation of VConsole. However, you can use it to move a record to a new order within the parent in a hierarchical data table.
  • Arguments
    • $table - string. Should be the name of the MySQL table in which to set the order of the record.
    • $id - int. Should be the primary index of the record to set the order of.
    • $order - int. Should be a positive integer or 0. If set to 0, then the record will be set as the last child of its current parent. If set to 1 or higher, then this will be the order that will be set under the current parent. For example, if you set 1 then the record will be set as the first child of its current parent.
    • $err - varref. A variable should be passed that will be populated with the error message in case of failure.
    • $index - string. Optional. If set, this should be the MySQL field name of the primary index for the table. This defaults to 'id' if not set.
    • $dbhandle - string or resource. This should be set to the database handle to use when adding the record to the table. Only advanced users should attempt to use this parameter.
  • Returns - bool. This function returns true on success or false on failure. If it returns false, then $err will be populated with a reason why.
    <?php
    /* Set the order of record 8 in the vc_trees table
       to be the last child of its parent record. */
    if (hierarchical_setorder('vc_trees', 8, 0, $err)) {
       /* Successful
          Now the record has been set as the last
          child of its parent. */
    } else {
       // Order Failed and $err contains the reason
    }
    
    ?>
    
       
• hierarchical_nl_add(string $table, int $parent, varref &$err[, string $index='id'][, string|resource $dbhandle=false])
  • Description - This function adds a record to a MySQL table that contains nested set hierarchical data. IT DOES NOT LOCK THE TABLE like the hierarchcal_add() function does. (See "Managing Hierarchical Data" for more information). It will perform all the functions as described in the "Adding A Record" section including rearranging all the lft, rgt, and optionally depth values of the table (if a depth field is present in the table). The table MUST contain a lft and rgt field in order for this function to work properly otherwise you will get a MySQL query error. The table can optionally contain a depth field to keep track of the depth of a record. (We recommend having a depth field because you will get a huge performance boost when the table has a lot of records.) Depending on how you use your hierarchical table, we also recommend indexing the lft, rgt, and depth fields.
  • Used - This function is not used in the default installation of VConsole. However, you can use it to add a record to a hierarchical data table.
  • Arguments
    • $table - string. Should be the name of the MySQL table to add the record to.
    • $parent - int. Should be the primary index of the record that should be the parent of the new record. The new record will be added as the last child of the record that is specified here.
    • $err - varref. A variable should be passed that will be populated with the error message in case of failure.
    • $index - string. Optional. If set, this should be the MySQL field name of the primary index for the table. This defaults to 'id' if not set.
    • $dbhandle - string or resource. This should be set to the database handle to use when adding the record to the table. Only advanced users should attempt to use this parameter.
  • Returns - int. This function returns the id of the primary index for the record that was added. The record is always added with no data. You should use the return value of this function to update the record with the data that you want it to have.
     
• hierarchical_nl_delete(string $table, int $id, varref &$err[, string $index='id'][, bool $sub=true][, string|resource $dbhandle=false])
  • Description - This function deletes a record from a MySQL table that contains nested set hierarchical data. IT DOES NOT LOCK THE TABLE like the hierarchcal_delete() function does. (See "Managing Hierarchical Data" for more information). It will perform all the functions as described in the "Deleting A Record" section including rearranging all the lft, rgt, and optionally depth values of the table (if a depth field is present in the table). The table MUST contain a lft and rgt field in order for this function to work properly otherwise you will get a MySQL query error. The table can optionally contain a depth field to keep track of the depth of a record. (We recommend having a depth field because you will get a huge performance boost when the table has a lot of records.) Depending on how you use your hierarchical table, we also recommend indexing the lft, rgt, and depth fields.
  • Used - This function is not used in the default installation of VConsole. However, you can use it to delete a record from a hierarchical data table.
  • Arguments
    • $table - string. Should be the name of the MySQL table to delete the record from.
    • $id - int. Should be the primary index of the record to delete.
    • $err - varref. A variable should be passed that will be populated with the error message in case of failure.
    • $index - string. Optional. If set, this should be the MySQL field name of the primary index for the table. This defaults to 'id' if not set.
    • $sub - bool. Optional. If set to false, then all sub branches are not deleted and instead promoted to the level of the deleted branch. If set to true or not specified, then all sub branches will also be deleted.
    • $dbhandle - string or resource. This should be set to the database handle to use when performing this operation. Only advanced users should attempt to use this parameter.
  • Returns - bool. This function returns true on success or false on failure. If it returns false, then $err will be populated with a reason why.
     
• hierarchical_nl_moveto(string $table, int $id, int $moveto, varref &$err[, string $index='id'][, string|resource $dbhandle=false])
  • Description - This function takes care of moving a record (and all children) to a new parent in a MySQL table that contains nested set hierarchical data. IT DOES NOT LOCK THE TABLE like the hierarchcal_moveto() function does. (See "Managing Hierarchical Data" for more information). It will perform all the functions necessary to move a record (and all children) to a new parent including rearranging all the lft, rgt, and optionally depth values of the table (if a depth field is present in the table). The table MUST contain a lft and rgt field in order for this function to work properly otherwise you will get a MySQL query error. The table can optionally contain a depth field to keep track of the depth of a record. (We recommend having a depth field because you will get a huge performance boost when the table has a lot of records.) Depending on how you use your hierarchical table, we also recommend indexing the lft, rgt, and depth fields.
  • Used - This function is not used in the default installation of VConsole. However, you can use it to move a record to a new parent in a hierarchical data table.
  • Arguments
    • $table - string. Should be the name of the MySQL table in which to move the record.
    • $id - int. Should be the primary index of the record to move.
    • $moveto - int. Should be the primary index of the record that the record (and all children) should be moved under. The record specified in the $id parameter will be set as the last child of the record that is specified here.
    • $err - varref. A variable should be passed that will be populated with the error message in case of failure.
    • $index - string. Optional. If set, this should be the MySQL field name of the primary index for the table. This defaults to 'id' if not set.
    • $dbhandle - string or resource. This should be set to the database handle to use when performing this operation. Only advanced users should attempt to use this parameter.
  • Returns - bool. This function returns true on success or false on failure. If it returns false, then $err will be populated with a reason why.
     
• hierarchical_nl_setorder(string $table, int $id, int $order, varref &$err[, string $index='id'][, string|resource $dbhandle=false])
  • Description - This function takes care of setting the order of a record within the parent record in a MySQL table that contains nested set hierarchical data. IT DOES NOT LOCK THE TABLE like the hierarchcal_setorder() function does. (See "Managing Hierarchical Data" for more information). It will perform all the functions necessary to move a record (and all children) to a new order within the parent including rearranging all the lft, rgt, and optionally depth values of the table (if a depth field is present in the table). The table MUST contain a lft and rgt field in order for this function to work properly otherwise you will get a MySQL query error. The table can optionally contain a depth field to keep track of the depth of a record. (We recommend having a depth field because you will get a huge performance boost when the table has a lot of records.) Depending on how you use your hierarchical table, we also recommend indexing the lft, rgt, and depth fields.
  • Used - This function is not used in the default installation of VConsole. However, you can use it to move a record to a new order within the parent in a hierarchical data table.
  • Arguments
    • $table - string. Should be the name of the MySQL table in which to set the order of the record.
    • $id - int. Should be the primary index of the record to set the order of.
    • $order - int. Should be a positive integer or 0. If set to 0, then the record will be set as the last child of its current parent. If set to 1 or higher, then this will be the order that will be set under the current parent. For example, if you set 1 then the record will be set as the first child of its current parent.
    • $err - varref. A variable should be passed that will be populated with the error message in case of failure.
    • $index - string. Optional. If set, this should be the MySQL field name of the primary index for the table. This defaults to 'id' if not set.
    • $dbhandle - string or resource. This should be set to the database handle to use when adding the record to the table. Only advanced users should attempt to use this parameter.
  • Returns - bool. This function returns true on success or false on failure. If it returns false, then $err will be populated with a reason why.
       
• html_print_r(mixed $value[, bool $return=false])
  • Description - This function will output or return a <textarea> field that contains the human readable content from a variable, array, or object. It is used for quick debugging and shows the contents of $value in a browser in a way that does not require you to look at the page source.
  • Used - This function is only used for debugging in the development version of VConsole. You can also use this function for debugging.
  • Arguments
    • $value - mixed. Should be a variable, array, or object that you want to check the contents of.
    • $return - bool. Optional. If set to true, then an HTML string is returned that can be printed out to the browser for debugging. If set to false, (default) then the HTML string is printed directly to the browser.
  • Returns - string. If $return is set to true, then this function returns an HTML string that can be printed out to the browser for debugging. Otherwise it returns an empty string.
    <?php
    // Define any array.
    $data = array(
      'type' => 'test',
      'multi' => array(
        'sub' => 2,
        'arg' => 'argument'
      )
    );
    // Print out the contents
    // of the array in a way
    // that can be easily read
    // without having to look
    // at the page source
    html_print_r($data);
    ?>
    
     
• htmltotext(string $html[, int $maxwidth=false])
  • Description - This function takes HTML code and formats it as plain text. It does everything it possibly can to make sure that the plain text looks as close to the HTML as possible.
  • Used - This function is not used in the default installation of VConsole. However, you can use it for your own purposes.
  • Arguments
    • $html - string. This should be set to the HTML string that you want formatted as plain text.
    • $maxwidth - int. Optional. If set, then the plain text will have a maximum character width and wrapping will occur beyond the character width set here.
  • Returns - string. The plain text that is a result of the conversion from HTML to plain text.
       
• make_datamanager_menu(array $dms)
  • Description - This function is responsible for creating all the drop down menus that are required in a datamanager module. This includes all the top menu bar drop down menus as well as all the right click menus.
  • Used - This function is used internally in the datamanager() function to create all the associated drop down menus.
  • Arguments
    • $dms - array. The $dms data structure for the module. You can get the $dms data structure by calling the get_dms_array() function.
  • Returns - bool. This function always returns false.
  • When called, the $OUT['TOPMENU'] and $OUT['MENUSYSTEM'] variables are populated with the entire HTML menu data required by the datamanager module.
  • You usually won't ever need to call this function unless you just want to check out the $OUT['TOPMENU'] and $OUT['MENUSYSTEM'] global variables before calling the datamanager() function.
    <?php
    // Get the $dms array for the current module
    $dms = get_dms_array($_SESSION['module']);
    
    // Create the main menus
    make_datamanager_menu($dms);
    
    // Check out the $OUT variable
    global $OUT;
    html_print_r($OUT);
    ?>
    
     
• make_favorites_menu(void)
  • Description - This function is responsible for creating the data structure that is required to create the "Favorites" drop down menu. The menu is populated based on each individual user's favorite items.
  • Used - This function is called whenever the "Favorites" drop down menu needs to be created or modified.
  • Arguments - None
  • Returns - array. The data structure that is passed off to the create_main_menu() function in order to create the "Favorites" drop down menu.
  • You usually won't ever need to call this function unless you just want to check out data structure or the HTML code for the menu.
    <?php
    // Get the favorites data structure
    $favs = make_favorites_menu();
    
    // Check out the data structure
    html_print_r($favs);
    
    // Create the menu using the data structure
    $menu = create_main_menu($favs, false, true);
    
    // Check out the HTML
    html_print_r($menu);
    ?>
    
     
• make_main_menu(void)
  • Description - This function is responsible for creating all the drop down menus that are required in a non-datamanager module. This includes all the top menu bar drop down menus as well as all the right click menus.
  • Used - This function is called to initially build the top main menu when the user accesses the software. It is also called to update the top main menu when needed.
  • Arguments - None
  • Returns - bool. This function always returns false.
  • When called, the $OUT['TOPMENU'] and $OUT['MENUSYSTEM'] variables are populated with the entire HTML menu data required by the top main menu.
  • You usually won't ever need to call this function unless you just want to check out the $OUT['TOPMENU'] and $OUT['MENUSYSTEM'] global variables.
    <?php
    // Create the main menus
    make_main_menu();
    
    // Check out the $OUT variable
    global $OUT;
    html_print_r($OUT);
    ?>
    
     
• make_path_menu(void)
  • Description - This function is responsible for creating the data structure that is required to create the "Path" fly out menus (Under "Main Menu" > "Home")
  • Used - This function is called to initially build the "Path" fly out menus when the user accesses the software.
  • Arguments - None
  • Returns - array. The data structure that is passed off to the create_main_menu() function in order to create the "Path" fly out menus.
  • You usually won't ever need to call this function unless you just want to check out the data structure or the HTML code for the menu.
    <?php
    // Get the path fly out data structure
    $path = make_path_menu();
    
    // Check out the data structure
    html_print_r($path);
    
    // Create the menu using the data structure
    $menu = create_main_menu($path, false, true);
    
    // Check out the HTML
    html_print_r($menu);
    ?>
    
     
• notify_suppot(string $msg[, string|array $toemail='VSource'][, string $subject='Problem on members site'][, string $from=false][, string $vmsg=false][, bool $noerror=false])
  • Description - This function is designed to notify support of a problem with the software. When called, this function will call the debug() function and dump the entire current state of the software including all variables. It will then send an email to the address of your choice and finally, it will set an error message if you choose to do so.
  • Used - This function is not used in the default code base.
  • Arguments
    • $msg - string. A simple message to store in the vc_debug table. If this argument evaluates to false, then the debug() function is not called. Always pass something here.
    • $toemail - string|array. Optional. This variable determines where the notification email is sent. It can be a single email address or an array of email addresses.
    • $subject - string. Optional. The subject for the notification email.
    • $from - string. Optional. The from email address for the notification email.
    • $vmsg - string. Optional. If set, then this is placed in the body of the notification email.
    • $noerror - bool. Optional. If set to true, then no error is displayed to the user and the user never knows that anything happened. If set to false (default), then an error message is set that lets the user know that a problem has occurred and that support has been notified.
  • Returns - bool. Always returns true
    <?php
    // You can notify yourself
    // When something happens
    global $GLOB;
    $msg = 'User did not enter YES';
    $to = 'test@test.com';
    $subject = 'Invalid Response';
    $from = $GLOB['login']['email'];
    $vmsg = $msg;
    
    // Notify test@test.com if the user
    // did not type in yes in the field
    if (!preg_match('/yes/i', $_REQUEST['field'])) {
      notify_support($msg, $to, $subject, $from, $vmsg);
    }
    // A debug code is shown in the notification email.
    // That debug code is the id of an entry in the
    // vc_debug table. You can check out that entry
    // to see exactly what the software state was
    // when support was notified.
    ?>
    
     
• parse_template(string $template_file[, string $where='STDOUT'][, array $private=false])
  • Description - This function searches a file for variables identified as ||VARIABLE|| and substitutes the value with the corresponding key from the global associative arrays $OUT, $PARAMS, $_SESSION, and $_SERVER . (The arrays are checked in this order). Lines beginning with 0: will only be printed if a variable appears on that line and has a value in one of the mentioned arrays.
  • Used - This function is used to output the interface. All the files in the vconsole/skins/vsource/templates/ folder are used as templates.
  • Arguments
    • $template_file - string. The path to the file to use as a template.
    • $where - string. Optional. Where to output the results.
      • STDOUT - The results will be sent to the browser.
      • RETURN - The results will be returned
      • >path_to_file - The results will be written to the file at path_to_file. The file is overwritten.
      • >>path_to_file - The results will be appended to the file at path_to_file. The file is not overwritten. The results are appended to the end of the file.
    • $private - array. Optional. An associative array that contains name - value pairs to use in the variable substitution. This array will be checked before $OUT, $PARAMS, $_SESSION, or $_SERVER and if a variable match is found, it is used instead of any of the other global arrays.
  • Returns - string. If $where is set to RETURN, then the results are returned as a string, otherwise true is returned if the operation was successful or false is returned if not successful.
  • If false is returned, then $GLOB['Error_Message'] contains the error message of why the operation failed.
    <?php
    // Define a string to parse.
    $string = "This is a file that
    I want to be parsed<br />
    The first variable is ||VAR1||
    0: This line should not be output ||VAR2||
    0: This line is output. ||VAR3||
    The fourth line - ||VAR4||";
    
    // Write the string out to file.
    $file = "tmp/template.htm";
    $fh = fopen($file, 'w');
    fwrite($fh, $string);
    fclose($fh);
    
    // Set the replacement variables
    $private = array(
      'VAR1' => 'Variable 1',
      'VAR3' => 'Var3 Exists'
    );
    $OUT['VAR4'] = 'Testing 123';
    
    // Parse the template
    $results = parse_template($file, 'RETURN', $private);
    
    /* Results now contains:
    This is the file that
    I want to be parsed<br />
    The first variable is Variable 1
     This line is output. Var3 Exists
    The fourth line - Testing 123
    */
    
    // Now write this out to disk
    $success = parse_template($file, '>tmp/out.htm', $private);
    if ($success) {
      // tmp/out.html should have the same contents as $results
    } else {
      // The file write operation failed
      global $GLOB;
      set_message('error', $GLOB['Error_Message']);
    }
    ?>
    
     
• propertiesmanager(array $data)
  • Description - This function will deliver a GUI interface to the user that gives them a list of property tabs along with 1 or more form fields per tab so that the user can input data. The validated results are returned.
  • Used - This function is not used in the VConsole code base.
  • Arguments
    • $data - array. A multi-dimensional array that describes all the tabs and form fields for the properties GUI interface. (See The Properties Manager for information on how to define this array)
  • Returns - array. An array of all the field name - value pairs. The results are validated according to the validation parameters in the $data array. See The Properties Manager for an example of how to use this function.
     
• require_library(string $folder_name)
  • Description - This function will require all the php files in a folder inside the vconsole/functions/ folder.
  • Used - This function is used on every access to the software to require all the functions in the vconsole/functions/common/ folder.
  • Arguments
    • $folder_name - string. The name of the folder inside the vconsole/functions/ folder. If your php files are in the vconsole/functions/mylibrary/ folder, then set this to mylibrary
  • Returns - bool. Always returns false.
  • IMPORTANT: All the php files in your folder should only contain functions and should not output anything to the browser.
    <?php
    // Let's say that you have 3 files that contain functions
    // inside the vconsole/functions/mylibrary/ folder
    require_library('mylibrary');
    
    // Now all those functions are available.
    ?>
    
     
• searchindex(string $module, int $rowid[, array $data_manager_structure=false])
  • Description - Indexes a datamanager record so that it is found when the user performs a text search (Only used for text searching)
  • Used - Every time a datamanager record is added or modified.
  • Arguments
    • $module - string. The name of the datamanager module to perform the index for.
    • $rowid - int. The record id (primary key) for the record to index.
    • $data_manager_structure - array. Optional. The datamanager $dms data structure as defined in the dms.php file. If not provided, then the data structure is retrieved using get_dms_array($module)
  • Returns - bool. Always returns true.
    <?php
    // You want to call this function every time
    // a datamanager record is updated or added.
    $id = db_query("INSERT INTO `table` SET
      `field1` = 'test', `field2` = 'test2'", $dbr);
    
    searchindex($_SESSION['module'], $id);
    // Now the new row should be searchable.
    ?>
    
     
• send_email(string|array $to, string $subject, string $body[, string $from=false][, string $fromname=false][, string $altbody=false][, bool $html=false][, string|array $attach=false])
  • Description - Sends 1 or more emails.
  • Used - Not used in the default VConsole code base.
  • Arguments
    • $to - string|array. The email address or addresses to send email to. It be a single email address or an array of email addresses.
    • $subject - string. The subject for the email.
    • $body - string. The message body (HTML OK)
    • $from - string. Optional. If set, this will be the from email address.
    • $fromname - string. Optional. If set, this will be the from name.
    • $altbody - string. Optional. If set, this will be the plain text alternative for the email. Use to give users with older email clients a plain text alternative. (Should only be set if $html is set to true)
    • $html - bool. Optional. If set to true, the $body will be treated as HTML code. If set to false, then HTML will be treated as plain text.
    • $attach - string|array. Optional. This should be the path to a file to attach or an array of file paths to attach to the email. The file(s) must exist.
  • Returns - bool. Returns true if the email was sent successfully or false otherwise.
  • If sending fails, then an error message is set with the set_message() function.
  • If $PARAMS['USESMTP'] evaluates to false, then the PHP mail() function is used to send the email. Otherwise, an SMTP server is used to send the email. To modify the SMTP server parameters, please modify the records in the vc_console-params table. Here is a list of the parameters and what they do.
    • USESMTP - Set the value of this record to 1 to use an SMTP server or 0 to use the PHP mail() function to send the email(s)
    • SMTPSERVER - Set the value of this record to the SMTP server to use to send the email(s)
    • SMTPUSER - Set the value of this record to the SMTP user to use to login to the SMTP sever.
    • SMTPPASS - Set the value of this record to the password to use to login to the SMTP server.
    • SMTPPORT - Set the value of this record to the port to use to communicate with the SMTP server. (Usually 25)
  • Sending mail over secure SMTP is not supported at this time.
    <?php
    $to = array('test@test.com', 'test2@test.com');
    $sub = 'Testing Email';
    $bdy = "Testing Email Body<br />Second Line.";
    $frm = 'from@test.com';
    $fmn = 'Test User';
    $alt = "Testing Email Body\nSecond Line.";
    $htm = true;
    $att = array(
      'tmp/attachment1.pdf',
      'tmp/attachment2.pdf'
    );
    if (!send_email($to,$sub,$bdy,$frm,$fmn,$alt,$htm,$att)){
      // Email failed to send
    } else {
      // Email was sent to 2 email addresses
      // 2 attachments were included
    }
    ?>
    
     
• send_error(string $msg)
  • Description - This function is to be used when a fatal error occurs and the program must exit. An error message is set and output to the browser. Then the program exits.
  • Used - This function is used when a license file is invalid. You should use it for similar fatal errors.
  • Arguments
    • $msg - string. The error message to send to the user. HTML is OK.
  • Returns - This function does not return.
    <?php
    // If the user is not a super user,
    // trigger a fatal error
    global $GLOB;
    if (!$GLOB['superuser']) {
      send_error('You are not a super user!!');
    }
    // If we get here, the user is a super user.
    ?>
    
     
• send_login([string $msg=''][, string $type=false])
  • Description - This function sends the user to the login screen.
  • Used - This function is used when the user is not logged in.
  • Arguments
    • $msg - string. Optional. If set, then this message will be shown to the user on the login screen.
    • $type - string. Optional. If set, it determines what type of message $msg will be.
      • info - The message will have a green border.
      • success - The message will have a green border.
      • warn - The message will have a yellow border.
      • error - The message will have a red border.
  • Returns - This function does not return.
    <?php
    // Have the user log back in randomly
    // give them a 1 in 10 chance of not
    // having to log back in.
    $rand = rand(1, 10);
    if ($rand == 5) {
      send_login('Please log back in.');
    }
    // If we get here, then the user was
    // not randomly selected to log back in.
    ?>
    
     
• send_output(void)
  • Description - This function takes care of drawing the user interface and / or sending output to the AJAX engine. It uses some condition checking to determine what to output to the user.
  • Used - This function is used when a module file returns control to the main VConsole program. It is used to draw the interface to the browser and / or output the correct text to the AJAX engine.
  • Arguments - None
  • Returns - This function does not return.
  • You should never have to call this function as all you need to do is call return() from your module file and it is called automatically.
     
• send_stationary(string|array $toemail, string $subject, string $body[, string $fromemail=false][, string $fromname=false][, string $altbody=false][, bool $noreply=false][, string|array $attach=false])
  • Description - This PHP function works almost like the send_email() function, except that it will send a formatted email using the stationary HTML template file. See Sending Email for more information.
  • Used - This function is not used in the default code base.
  • Arguments
    • $toemail - string|array. The email address or addresses to send email to. It be a single email address or an array of email addresses.
    • $subject - string. The subject for the email.
    • $body - string. The message body in HTML (This is always interpreted as HTML)
    • $fromemail - string. Optional. The from email address.
    • $fromname - string. Optional. The from name.
    • $altbody - string. Optional. If set, this will be the plain text alternative for the email. Use to give users with older email clients a plain text alternative.
    • $noreply - bool. Optional. If set to true, then a "Do Not Reply" message is added to both the $body and $altbody arguments. (Try setting this to true to see the results)
    • $attach - string|array. Optional. This should be the path to a file to attach or an array of file paths to attach to the email. The file(s) must exist.
  • Returns - bool. Returns true if the email was sent successfully or false otherwise.
  • This function actually calls the send_email() function to send out the email(s). See the notes on that function to determine whether the email is sent using the PHP mail() function or an SMTP server.
    <?php
    $to = array('test@test.com', 'test2@test.com');
    $sub = 'Testing Email';
    $bdy = "Testing Email Body<br />Second Line.";
    $frm = 'from@test.com';
    $fmn = 'Test User';
    $alt = "Testing Email Body\nSecond Line.";
    $att = array(
      'tmp/attachment1.pdf',
      'tmp/attachment2.pdf'
    );
    if (!send_stationary($to,$sub,$bdy,$frm,$fmn,$alt,false,$att)){
      // Email stationary failed to send
    } else {
      // Email stationary was sent to 2 email addresses
      // 2 attachments were included
    }
    ?>
    
     
• set_message(choice $type info|success|warn|error, string $msg[, string $errorfield=false])
  • Description - This function adds a message to the $OUT['messages'] global variable. The $OUT['messages'] global variable can be output directly to the user. Most of the high level functions like the datamanager() function take care of outputting messages to the user without you having to output them manually.
  • Used - This function is used by any function that needs to display a message to the user.
  • Arguments
    • $type - choice. The type of message to display to the user.
      • info - A green border is shown around the message.
      • success - A green border is shown around the message.
      • warn - A yellow border is shown around the message.
      • error - A red border is shown around the message.
    • $msg - string. The message to show to the user. HTML is OK.
    • $errorfield - string. Optional. If set, then the global variable $OUT[$errorfield] will be set to class="error". This is used by the wizardmanager() and propertiesmanager() functions to highlight fields that fail validation.
  • Returns - bool. Always returns false.
    <?php
    // We want to only continue with the program
    // if the user is a super user.
    // If not, then they get an error message.
    global $GLOB, $OUT;
    
    if (!$GLOB['superuser']) {
      // Set the message and return control
      set_message('error', 'Access denied.');
      // Returning control to the main Vconsole
      // program will handle outputting messages
      // to the user.
      return();
    }
    ?>
    
     
• set_vars(void)
  • Description - This function sets a bunch of global variables
  • Used - This function is called on every access to the software.
  • Arguments - None
  • Returns - bool. Always returns false
  • There is no need to call this function unless you delete a global variable and then need to set it again.
     
• validate_field(array $field, string $val, arrayref &$msg[, int $recid=false][, string $confval=false][, array $filerec=false][, array $selected=false])
  • Description - This is the higher level function that calls the validate_input() function. This function is called by some even higher level functions - wizardmanager() and propertiesmanager(). This function validates input from a wizardmanager or propertiesmanager field.
  • Used - This function is used whenever the user submits input from a propertiesmanager or wizardmanager interface.
  • Arguments
    • $field - array. The field definition array as passed to the wizardmanager() or propertiesmanager() functions
    • $val - string. The input value to validate against.
    • $msg - arrayref. This will be populated with an array of error messages if validation fails. There will be 1 error message per failing condition. If the value must be at least 5 characters and must start with a letter, and the $value is 6we, there will be 2 error messages set.
    • $recid - int. Optional. The record id to check against. This value is used only for "unique" validations so that every record is checked for duplicates except itself.
    • $confval - string. Optional. The value of the confirmation field. This argument is only used for "confirmation field" validations. (If you want the user to type in the password twice, set this value to the value of the 2nd password field.)
    • $filerec - array. Optional. The file associative array that is retrieved from the upload record from the vc_fileuploads-files table. This argument is only used for file upload fields.
    • $selected - array. Optional. This argument is currently not used.
  • Returns - bool. If validation succeeds, then true is returned, otherwise, false is returned.
  • You should never need to call this function as it is only applicable from within the wizardmanager() and propertiesmanager() functions so we will not show an example of how to call this function.
      
• validate_input(varref &$error_msg, string $value, string $fieldname[, bool $seterror=false][, string $errorfield=false][, bool $required=false][, string $type=false][, int $minlength=false][, int $maxlength=false][, float $minnum=false][, float $maxnum=false][, regex $match=false][, regex $nomatch=false])
  • Description - This function is responsible for validating form fields that are used in the wizardmanager() and propertiesmanager() functions.
  • Used - This function is called internally from the validate_field() function. This is the low level function that takes care of validating user input.
  • Arguments
    • $error_msg - varref. This will be set to the error message if validation fails. This can be sent to the user.
    • $value - string. The value of the field to validate against. (User's input)
    • $fieldname - string. The human readable field label. Example: "First Name"
    • $seterror - bool. Optional. If true, and validation fails, then the set_message() function will be called to set the error message that is populated into the $error_msg argument. In other words, if set to true, then both $error_message is set AND set_message() is called.
    • $errorfield - string. Optional. Set to the error field argument to send to the set_message() function. See the set_message() function above.
    • $required - bool. Optional. If set to true, then the $value argument must have a string length of at least 1 in order for validation to succeed.
    • $type - string. Optional. Set to the type of validation to perform. (See The Wizardmanager for explanations on what this should be. Look for the <content_type> parameter.)
    • $minlength - int. Optional. Set to the minimum string length that $value must be in order for validation to succeed.
    • $maxlength - int. Optional. Set to the maximum string length that $value can be in order for validation to succeed.
    • $minnum - int. Optional. Set to the minimum numerical value that $value must evaluate to in order for validation to succeed.
    • $maxnum - int. Optional. Set to the maximum numerical value that $value can evaluate to in order for validation to succeed.
    • $match - regex. Optional. Set to the regular expression that $value MUST match in order for validation to succeed.
    • $nomatch - regex. Optional. Set to the regular expression that $value MUST NOT match in order for validation to succeed.
  • Returns - bool. This returns true if validation succeeded and $value conforms to all the conditions set by the other arguments. It returns false otherwise.
    <?php
    // Set a value to validate
    $value = 'val1';
    if (!validate_input($err, $value, 'Value', false, false, true, false, 5)) {
      // Fail the validation
      // Since $value only has a string length of 4, and
      // we require a minimum string length of 5, validation
      // will fail and we will get to here.
    } else {
      // We should never get to here
    }
    ?>
    
      
• validate_group(array $data[, bool $continue_after_fail=false])
  • Description - This function will call the validate_input() function over and over for each array that is passed in as $data. You can use this function to do a low level validation of a group of input values at once. It is equivilent to calling validate_input() within a loop.
  • Used - This function is not used in the default code base.
  • Arguments
    • $data - array. This argument should be an array of arrays. Each array in this array should conform to the arguments that are passed to the validate_input() function starting with the fieldname.. We will give an example below.
    • $continue_after_fail - bool. Optional. If set to true, then if a field fails to validate, validation of the rest of the fields continues. Otherwise, it stops.
  • Returns - bool. It returns true if all fields passed validation, otherwise it returns false.
    <?php
    // Set a list of fields.
    $fields = array(
      array('val1', 'Value', false, false, true, false, 3),
      array('val2', 'Value2', false, false, true, false, 5)
    );
    
    // Validate the 2 fields.
    if (validate_group($fields)) {
      // Validation succeeded for all fields.
    } else {
      // Validation failed for at least 1 field.
      // Since we can clearly see that the second
      // field is not 5 characters long, we will end
      // up here.
    }
    ?>
    
      
• validate_login(void)
  • Description - This function validates the user's login. It is responsible for checking usernames and passwords, for creating login sessions, and for making sure that a user's session is still valid on every access to the software.
  • Used - This function is used on every access to the software.
  • Arguments - None
  • Returns - bool. This function always returns false.
  • If a user's login credentials or session is not valid, then the send_login() function is called which never returns.
  • You should never need to call this function so we will not show an example.
       
• wizardmanager(array $data_structure)
  • Description - This function will deliver a GUI interface to the user that takes them step by step through a wizard process so that the user can input data. The validated results are returned.
  • Used - This function is used for creating new users, creating new groups, creating new accounts, changing passwords, and more.
  • Arguments
    • $data - array. A multi-dimensional array that describes all the steps and form fields for the wizard GUI interface. (See The Wizard Manager for information on how to define this array)
  • Returns - array. An array of all the step numbers which contain all the field name - value pairs. The results are validated according to the validation parameters in the $data_structure array. See The Wizard Manager for an example of how to use this function.
     
• XML_unserialize(string $xml)
  • Description - This function takes an XML formatted string and converts it to a PHP multi-dimensional array.
  • Used - This function is not used in the default code base.
  • Arguments
    • $xml - string. The XML formatted string to convert.
  • Returns - array. The PHP multi-dimensional array that has been converted from XML
    <?php
    // Define our XML string.
    $xml = "<?xml version=\"1.0\" ?>
    <packet version=\"1.0\">
    <get_record>
    <id>3</id>
    </get_record>
    </packet>";
    
    // Convert it to a PHP array.
    $array = XML_unserialize($xml);
    
    /* Array is now set to:
    array(
      "packet" => array(
        "get_record" => array("id" => 3)
      ),
      "packet attr" => array(
        "version" => "1.0"
      )
    )
    */
    ?>
    
     
• XML_serialize(array $data)
  • Description - This function takes a PHP multi-dimensional array and converts it to an XML formatted string.
  • Used - This function is not used in the default code base.
  • Arguments
    • $data - array. The PHP multi-dimensional array to convert to XML
  • Returns - string. The XML formatted string that has been converted from the PHP array.
    <?php
    // Define our PHP array.
    $data = array(
      "packet" => array(
        "get_record" => array("id" => 3)
      ),
      "packet attr" => array(
        "version" => "1.0"
      )
    );
    
    // Convert it to XML
    $xml = XML_serialize($data);
    
    /* Now $xml contains:
    <?xml version="1.0" ?>
    <packet version="1.0">
    <get_record>
    <id>3</id>
    </get_record>
    </packet>
    */
    ?>