What is a VConsole module? Well, VConsole was designed to handle multiple administration tasks such as managing invoices, managing clients, managing inventory, managing service calls, etc. Each one of these tasks can be a module. When a user logs into VConsole, they are shown a list of modules that they can click on. These modules are always shown in the top navigation bar as a series of graphical buttons. Not all the buttons on the top navigation bar have to be modules. Some buttons can be actions which can be described as sub tasks underneath modules. Each module can have 0 or more actions underneath it. For example: Under the "Manage Invoices" module, there can be actions like "New Invoice", "Edit Invoice", and "Delete Invoice".

You can create a different module for every departments' functions at a company. The great thing is that the module icon is only shown if the user has access to at least 1 action under the module. If the module has no actions under it, then the module is shown to everyone. VConsole comes with a few built in modules that control the basic functions of VConsole, like User Administration, Group Administration, Account Administration, Managing Favorites, Changing Passwords, and Updating Profiles. You can learn more about the built in modules here.

So how do you create your own modules? Creating modules is very simple. All you have to do is create a database record in the vc_modules table and create the supporting folders and files for the module in the vconsole/modules/ folder. Modules can be arranged in a hierarchical manner which means that modules can be underneath modules, which can be underneath modules, and so on. You can create as many modules as you want. There are several fields in the vc_modules database table so we will go over each field in detail. Then we will go over the details of the supporting folders and files. Here goes.....

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
  

Details of the vc_modules table fields.

• module - Required. Primary Key. Must be unique in the table. Must contain an alphanumeric string no larger than 20 characters. Must start with a letter. Must contain only lowercase letters and numbers. No other characters are allowed.
  This is the module id of the module and must match the name of the module's folder in the vconsole/modules/ folder. Each module must have a unique module id in this field.
   
• backmodule - Optional. If entered, it must match the id of another module as in the module field.
  This is the module id of a module to go to when the user user clicks on the back button. If entered, VConsole will go to this module when the user clicks "Up A Level". If not entered, then VConsole will go to the parent module (if any) when the user clicks "Up A Level".
   
• version - Required. Must contain a string no longer than 10 characters.
  This is the version of the module. Although there is no pre-defined or required format for this field, we recommend that you enter 1.0 and increment the version number whenever you make changes to the module php files. This field is meant to help you keep track of module revisions.
   
• button - Optional. Must contain an alphanumeric string no larger than 20 characters. Must start with a letter. Must contain only lowercase letters and numbers. No other characters are allowed.
  This is the name of the button graphic to show in the top navigation bar. This is not a file path, this should be a button name as required by the getimage() function. This must be the name of a button, not an icon. If not entered, the default "module" button will be shown.
   
• type - Required. Must be either WM, PM, DM, or BA
  This is the type of module that this module is. Here is a list of the accepted module types:
  • WM - This is a wizardmanager module. Wizardmanager modules will present a wizard to the user. The wizard must contain 1 or more steps and each step must contain 1 or more form field. The purpose of this module type is to take the user through a step by step wizard and collect information from the user. Once the user has finished the wizard, their input is returned to you so that you can do something with it. (For more information on the wizardmanager module type, click here)
  • PM - This is a propertiesmanager module. Propertiesmanager modules will present a a series of properties tabs to the user. Each property tab can have 1 or more form fields in it. The purpose of this module type is to allow the user to make changes to either a record or some type of other data. The properties tabs allow you to separate form fields in to categories. Once the user clicks on the save button, their input is returned to you so that you can do something with it. (For more information on the propertiesmanager module type, click here)
  • DM - This is a datamanager module. Datamanager modules present the user with a list of data records. They can manage these records via actions and they can do all sorts of other things like sort, filter, search, arrange, customize, etc... The purpose of this module type is to allow the user to view, add, and modify their data records such as invoices, contacts, inventory, etc. This type of module can also have actions which can be wizardmanager actions or propertiesmanager actions. This allows the user to perform actions on their data records. There are also several types of display types so that the user can easily access the data records that they are looking for. (For more information on the datamanager module type, click here)
  • BA - This is a basic module. Basic modules can do whatever you want them to do or they can just be a container module that contains other modules. Since you write the code on basic modules, the functionality is up to you.
     
• lft - Required. Must be unique between both the lft and rgt columns in the table. Must contain a positive whole number.
  This is the left part of the module hierarchy. The module hierarchy determines where in the hierarchical tree that this module is displayed. The hierarchy is derived using a Nested Set Model. Please see "Managing Hierarchical Data" to get a better idea of how this field works. Basically, every module should have a left lft and right rgt value which sets their start and end values in the hierarchy. Any module that has its left and right values in between the left and right values of another module is considered a child of that module.
   
• rgt - Required. Must be unique between both the lft and rgt columns in the table Must contain a positive whole number.
  This is the right part of the module hierarchy. The module hierarchy determines where in the hierarchical tree that this module is displayed. The hierarchy is derived using a Nested Set Model. Please see "Managing Hierarchical Data" to get a better idea of how this field works. Basically, every module should have a left lft and right rgt value which sets their start and end values in the hierarchy. Any module that has its left and right values in between the left and right values of another module is considered a child of that module.
   
• name - Required. Must be a human readable string up to 255 characters.
  This is the module name. The user will see this under the button in the top navigation bar. We recommend keeping this name short but descriptive. Something like: Manage Invoices
   
• help - Optional. Must be a human readable string up to 255 characters.
  This is the module help. This will be shown to the user when the user hovers over the module button. We recommend describing what the module does in 2 sentences or less. Something like: Click to view, add, remove, or modify invoices.
   
• nochkperm - Boolean. Must be set to 1 or 0.
  If set to 1, then action permissions are not checked before the main module file is executed. If set to 0, (recommended) then the module action permissions are checked before the main module file is executed. If the module has no entries in the vc_modules-actions table, then this parameter is ignored. If you do have actions for the module in the vc_modules-actions table and you want to check permissions manually, then set this to 1.
   
• hidden - Boolean. Must be set to 1 or 0.
  If set to 1, then the module is not shown in the module hierarchy. No button for the module will be shown and the button field is ignored. If set to 0 (default), then the module is shown in the hierarchy as normal. One reason to hide a module is that you want to create your own link to the module, perhaps in a data record field, however, you can use it any way you want. We will leave it to you to use your imagination.
  

Details of the vconsole/modules/ folder (Supporting folders and files for each module)

• Each module must have its own folder in the vconsole/modules/ folder. The folder must be named the same as the module field in the vc_modules table. This folder is called the module folder. We will refer to this folder as either the module folder or the vconsole/modules/<module> folder (<module> should match what is in the module field in the vc_modules table for the module). All supporting files for the module should be located in the vconsole/modules/<module> folder. Each module type requires different supporting files and folders. However, although all module types have a different set of files and folders, all modules, regardless of type, require the main.php file ( located at vconsole/modules/<module>/main.php ). This file is executed whenever someone clicks on the module button in the top navigation bar. We will go over each module type and what files / folders they depend on.
   
• The Wizardmanager Module Type: WM
  • This module type requires only the main.php file inside the vconsole/modules/<module>/ folder. The main.php file should be a wizardmanager formatted file and is executed when a user clicks on the module button in top navigation bar. (See The Wizardmanager for more information on what should be contained in the main.php file.)
     
• The Propertiesmanager Module Type: PM
  • This module type has the same requirements as the wizardmanager module type which is only the main.php file inside the vconsole/modules/<module>/ folder. The main.php file should be a propertiesmanager formatted file and is executed when a user clicks on the module button in the top navigation bar. (See The Propertiesmanager for more information on what should be contained in the main.php file.)
     
• The Datamanager Module Type: DM
  • This module type requires several files and folders. Here is a full list:
    • vconsole/modules/<module>/main.php - This file is the main module file and is executed whenever someone clicks on the module button in the top navigation bar. The purpose of this file is to check permissions to records, process actions, and pass control to the datamanager() function.
    • vconsole/modules/<module>/dms.php - This file should return the datamanager structure (which is a multi-dimensional array) that is required by the datamanager. In this file, you should simply build the datamanager structure which should include the appropriate MySQL queries, field nodes, actions, and more. For more information on the format of this file, please see The Datamanager.
    • vconsole/modules/<module>/functions.php - This file should contain a list of functions that is referenced in the dms.php file. You can use functions in this file to format fields in the datamanager. For example: if you have a simple 1 / 0 field in MySQL but you don't want to display a 1 or 0 to the user, you can specify a format for the field so that you can display Yes or No instead of 1 or 0. You do this by specifying the format parameter for the field in the dms.php file and defining the function in this file (functions.php). It is important to know that the functions that you define in this file are not available until the datamanager() function is called (which never returns anyway). If you want the functions in this file to be available to you in your main.php file, you will have to call the require_once() php function in your main.php file like so:  require_once("vconsole/modules/{$_SESSION['module']}/functions.php");  (Important: Do not use require or include as this will result in a php error when the datamanager function is called. You must use require_once())
    • vconsole/modules/<module>/actions/ - This is a folder that should contain all the actions for the module. Whenever someone executes an action, the appropriate action file which should be located in this folder is executed.
       
• The Basic Module Type: BA
  • This module type does not require any files or folders. If you don't create any files or folders for modules of this type, then only child modules are displayed in the top navigation bar (if any exist). If you want to write your own php code and display something custom to the user, you will simply have to create the vconsole/modules/<module>/main.php file. This file is executed when the user clicks on the module button in the top navigation bar. Anything that you output in the main.php file is shown in the main area of the interface. IMPORTANT: Do not exit in your main.php file. You must return control to VConsole in order for your output to be displayed in ther main area of the interface. If you exit, unexpected results could occur like nothing being shown even though you have output something to the browser.

That's it. Once you have created the MySQL entry in the vc_modules table and the supporting files / folders, your module is created and recognized in VConsole. However, your module will not actually do anything until you define the appropriate PHP code for it to do so. Read on...