Conventions used in this document:

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

Introduction:
Datamanager type modules are pretty straight forward. You simply build a data structure in the dms.php file and hand that off to the datamanager() function. The datamanager() function then handles everything from there including a feature rich GUI interface for the user. The datamanager() function never returns so make sure that you do everything that you want to do in the module file before calling the datamanager() function. Things that are handled by a datamanager module are:

• Displays rows of data to the user.
• Displays up to 5 different display types including list, icon, calendar, map, and report display types. Each display type displays data records in a different way.
• Sorts data in ascending or descending order.
• Handles "Displaying Additional Records" options for larger data sets.
• Handles Single Record and Multiple Records operations. (Single and Group Operations)
• Handles text, date, and value searching operations.
• Handles displaying data columns in an order that is defined by the user.
• Handles drag and drop column rearrangement operations.
• Handles column resize operations.
• Handles column behavior operations.
• Handles vertical and horizontal column alignment operations.
• Handles custom view management and switching operations.
• Handles filtering operations.
• Handles record coloring operations.
• Handles the creation and management of extra fields.
• Handles inline edit operations.
• Handles toolbar customization operations.
• Handles document attachment operations.
• Displays a list of legend definitions.

The datamanager() function is responsible for generating the management section for the built in "User Manager" module in VConsole. The output of the datamanager() function depends on the data structure that is passed to it. That data structure is made up of several components. A list of those components are outlined below. Here is a figure of all the different areas of the data manager.

1. The main menu bar. This bar contains a bunch of drop down menus as well as the display switching buttons.
2. The top toolbar. This toolbar contains a list of module buttons as well as some optional action buttons and some miscellaneous buttons such as the "Customize Toolbar" button and the "Up a Level" button. When a user clicks on a button in this toolbar, the appropriate module is executed (if it is a module button) or the appropriate action is executed (if it is a module action) or the miscellaneous action is performed (if it is a miscellaneous button).
3. The display switching buttons. A user clicks on these buttons in order to switch to the desired display type. The display types are: List, Icon, Calendar, Map, and Report. Each display type is responsible for displaying data to the user in a different way. This is similar to the Windows® PC explorer or MacOSX® finder in that there are different ways that you can display folders and files. Check out all the different display types to see what each looks like.
4. The "Customize Toolbar" miscellaneous button. When a user clicks on this button, a wizardmanager is displayed that allows the user to customize the buttons in the toolbar.
5. The top toolbar expand / collapse button. When a user clicks on this button, the top toolbar will collapse or expand. This is handy if a user wants to minimize the space that is taken up by the top toolbar.
6. The module name. The name of the module is displayed here as in the vc_modules.name MySQL field for the module. If you want to customize what is displayed here, simply set the global $OUT['SCREENTITLE'] variable in your main.php file for the module or set the vc_modules.name field for the desired module.
7. Total matching records indicator. This area is located both at top and bottom of the record list and tells you exactly how many records match your search and filter criteria. If you don't have any filters or searches set, then this number will be the total number of records available. NOTE: it is possible that this number may not reflect the total number of records in the data table. The queries that you pass to the datamanager determine how many records are available for viewing and can be customized to show only a subset of all the records of a table or tables.
8. The header row. This row contains a list of column names and does some pretty complex things. Users can right click a header column to change its behavior or alignment or to add / remove columns and more. Users can also drag and drop columns to rearrange them and they can even resize them or click on them to sort by that column. Also, each column may or may not have filtering capabilities. There are also some built in columns like the select all, color, and attachment columns which are not defined by you.
9. The document attachment column. This column is displayed if you have purchased the document management option for VConsole. It simply shows which records have attachments. You can click on the icons in this column to manage attachments for a particular record.
10. Data Records. Each data record is displayed in this area. You may notice that some are white, some are green, and some are red. A user can color any record a number of different colors by right clicking on the record and selecting the desired color. (Record coloring is only available if the data table contains a vccolor field.)
11. The legend area. Legend entries (if any) are displayed here. As you see, there are no legend entries for the module in the illustration above, but if there were any, they would display here.

So how do you create all these components? You don't. The data manager handles everything for you. You simply create a data structure (which is a multi-dimensional array) and hand that off to the datamanager() function. Also, as said before in this documentation, data manager type modules depend on several files / folders as well as at least 1 MySQL table. We will go over how to create the MySQL table(s), what each file / folder should contain, and how / where to create these files / folders. Each datamanager module requires the following files and folders. All these files / folders should be located in the module folder (vconsole/modules/<module>/)

• vconsole/modules/<module>/main.php - This is the main module file. This file gets called every time someone clicks on the module button in the top navigation bar. The job of this file is to:
  • Make sure that the user has permission to the module and whatever records the user is requesting (Usually this is already done for you before the user ever gets here, but you can apply your own checking if you want
  • Parse any actions that are requested (There is a code block that does this for you in the default main.php file below. Although, you may need to modify it to your needs.)
  • Provide output to the user or pass control to a script that provides output. (This is taken care of for you in the default main.php file below as well. The last line calls the datamanager() function which never returns.)
     
• vconsole/modules/<module>/dms.php - The sole purpose of this file is to define and return the $dms data structure (a multi-dimensional array) that should be passed to the datamanager() function.
   
• vconsole/modules/<module>/functions.php - This file should contain a list of functions (IT SHOULD NOT CONTAIN ANYTHING ELSE OUTSIDE FUNCTIONS) Each function is called with a single required parameter ($record) which is the associative array that is returned from the <data_query> query (specified in the dms.php file) and an optional parameter <format_args> which is specified in each field in the dms.php file.
   
• vconsole/modules/<module>/actions/ - This folder should contain action files. Action files are parsed by the main.php file (as stated above).
   
• vconsole/modules/<module>/actions/<action>.php - You can have multiple actions for a datamanager type module. Each action should have its own file in the actions folder. <action> should contain all lower case alpha-numeric characters. No spaces are allowed and it must start with a letter and must be at least 3 characters. Actions are defined in 2 places. The first place that actions are defined is in the dms.php file under single and group actions. The second place that actions are defined is in the vc_modules-actions table. Although it is not required to define actions in this table, it is required if you want to be able to assign and control permissions to these actions. Actions should be named appropriately. If you want to define an action that adds a record, you should name the action file something like add.php.

The main.php file.
To create this file you can either copy the code from the file below or you can use the "New Datamanager Module" option in the "VConsole" drop down list if you are using Dreamweaver® and you have the VConsole Developers Toolkit installed. Although the code in the file below is the default for the main.php file, you can modify it to suit your needs. One example is that you may want to check which records a user has selected and make sure that they have permission to perform the action on those records. We recommend checking out all the available PHP functions before attempting to modify the code from the file below.

The dms.php file.
To create this file, you can either copy the code from the file below or you can use the "New Datamanager Module" option in the "VConsole" drop down list if you are using Dreamweaver® and you have the VConsole Developers Toolkit installed. Although the code below is the default for the dms.php file, you MUST modify it to meet your needs. You must create at least 1 field and must define the appropriate parameters in the file. The code in the file below is heavily commented and should give you an idea of what is required. Remember, this file should define and return a multi-dimensional array otherwise known as the datamanager data structure (this is the only purpose of this file). This data structure determines what the user sees when they go to the module. This file is the heart of the module. All your actions, data columns (or data fields), legend entries, filter definitions, and more should all be located in the data structure defined in this file.

Dreamweaver® Users: if you are using Dreamweaver® and you have the VConsole Developers Toolkit installed, then all the parameters shown below are created for you automatically using the options from the VConsole drop down menu. There is no need to copy and paste code manually into your dms.php files. All you have to do is place your cursor in the correct place in the file and select the appropriate insert option from the VConsole menu. A dialog box will be shown that allows you to specify all the necessary parameters. You can even insert descriptive comments with your parameters. With that said, using the VConsole Developers Toolkit is by far the easiest way to create dms.php data structures.

The functions.php file.
This file is optional and does not need to exist unless you have defined either the <format>, <formathelp>, <format_args>, <edit_permission_function>, or <thumbnail_function> parameters in your dms.php file data structure (see above). To create this file, you can either create it manually or you can use the "New Datamanager Module" option in the "VConsole" drop down list if you are using Dreamweaver® and you have the VConsole Developers Toolkit installed. There is no special format for this file. The file must be a PHP file that DOES NOT output anything (so the file must start with <?php and must end with ?> with no characters before or after the opening and closing php tags. All you have to do with this file is define your functions as described in the <format>, <formathelp>, <format_args>, <edit_permission_function>, and <thumbnail_function> parameters in your dms.php file data structure (see above)

This file should contain a list of functions (IT SHOULD NOT CONTAIN ANYTHING ELSE OUTSIDE FUNCTIONS) Each function is called with a single required argument ($record) which is the associative array that is returned from the <data_query> (specified in the dms.php file) and an optional parameter format_args which is specified in each field in the dms.php file. The second parameter is optional. DO NOT include it as an argument in your function if you don't specify a <format_args> parameter in a field that calls the function. It is very rare that this second parameter is needed.) Each function should return a single string. This string will be shown to the user in the datamanager. Here is an example of a function that shows meaningful text (instead of a 1 or 0 as returned by the MySQL <data_query>)

IMPORTANT: Each function name MUST BE GLOBALLY UNIQUE. This means that 2 separate modules CANNOT have a functions.php file that contains the same function name. Every function in every functions.php file throughout VConsole MUST BE DIFFERENT. You will get PHP errors if you don't follow this rule.
We suggest that you prepend the module name, then use the word _format_, and the fieldname to each function name to make sure that it is globally unique. (The recommended format for function names is: <module>_format_<field>)
Example: function invoices_format_status($record) { }

The actions folder
This folder (if present) must contain only action files. Actions are defined in the $dms array. (See Single Actions and Group Actions sections of this publication)

Action Files.
Action files must reside in the actions folder (which resides in the module folder) You must create 1 action file for each action that you define in the $dms array. (See Single Actions and Group Actions sections of this publication) To learn more about actions, please see Datamanager Actions

Special dms.php files.
If, in your dms.php data array, you define different fields depending on who is logged in, you are bound to face at least 1 problem. When a user adds or edits a record and the searchindex() function is called in order to index that record so that it is returned in search results, you may find that the record is indexed incorrectly or at least not completely. This is because a record is indexed based on the data structure that is created and returned by the dms.php file. And if the currently logged in user only has access to some of the fields because you simply don't define those fields if a restricted user is logged in, then the search index will only contain those fields. This limits the searching capabilities of non-restricted users because certain fields that they see are not searchable unless they perform a re-index. OK, so let's see an example.

In your dms.php file, lets say that you define 2 fields for regular users, but 3 fields for super users.
As you see, field3 is only defined if the user is a super user. If a non-super user adds a record and the searchindex() function is called to index the record, then only field1 and field2 will be searchable. This is because the searchindex() function does not even know about field3 because the dms.php file never defines it because the user is not a super user. So, while it may be good for non-super users, super users will not be able to search field3, even though they can see it.
 
Luckily, there is a way around this. First, and probably not the most efficient, is to define the $dms array yourself and then pass that directly to the searchindex() function. This bypasses the dms.php file and the search index is built based on the $dms array that you pass. The problem with this is the fact that the $dms array is long and bulky. It may take some time to re-define the entire data structure every time you want to call the searchindex() function. The more efficient way is to define fields based on a certain condition. In the searchindex() function, a special global variable called $GLOB['simulateadmin'] is set to true before the data structure is retrieved from the dms.php file. So, all you have to do is check $GLOB['simulateadmin'] and if it is true, then define the field. In my example above, all I need to do is change a single line. Line 46 should read:
if (($GLOB['superuser'] )||($GLOB['simulateadmin'])) {

Now, if the user is a restricted user, then the user will not be able to view the field, but when you call the searchindex() function, field3 will be indexed so that it is searchable by super users.