Introdução

Module metadata are used to describe how various views behave in the module. The main use of this is providing field and layout information but this can also be used to filter subpanels and to describe what fields are used in the search.

Location 

Module metadata can be found in:

modules/<TheModule>/metadata/

Customising 

Usually studio is the best way of customising metadata. Even when you do wish to make customisations that are not possible through studio it can be simpler to set everything up in studio first. This is particularly true for layout based metadata. However if you are customising metadata it is as simple as placing, or editing, the file in the custom directory. For example to override the Accounts detailviewdefs (found in modules/Accounts/metadata/detailviewdefs.php) we would place (or edit) the file in custom/modules/Accounts/metadata/detailviewdefs.php. One exception to this rule is the studio.php file. The modules metadata folder is the only location checked - any version in custom/modules/<TheModule>/metadata/studio.php is ignored.

Different metadata 

detailviewdefs.php 

detailviewdefs.php provides information on the layout and fields of the detail view for this module. This file uses the same structure as editviewdefs.php. Let’s look at an example for a fictional module ABC_Vehicles:

<?php
$viewdefs ['ABC_Vehicles'] ['DetailView'] = array (
 'templateMeta' => array (
     'form' => array (
         'buttons' => array (
             'EDIT',
             'DUPLICATE',
             'DELETE',
             'FIND_DUPLICATES'
         )
     ),
     'maxColumns' => '2',
     'widths' => array (
         array (
             'label' => '10',
             'field' => '30'
         ),
         array (
             'label' => '10',
             'field' => '30'
         )
     ),
     'includes' => array (
         array (
             'file' => 'modules/ABC_Vehicles/ABC_VehiclesDetail.js'
         )
     )
 ),
 'panels' => array (
     'LBL_ABC_VEHICLES_INFO' => array (
         array (
             array (
                 'name' => 'name',
                 'comment' => 'The Name of the Vehicle',
                 'label' => 'LBL_NAME',
             ),
             'reg_number'
         ),
         array (
             array (
                 'name' => 'type',
                 'label' => 'LBL_TYPE',
             ),
             array (
                 'name' => 'phone_fax',
                 'comment' => 'The fax phone number of this company',
                 'label' => 'LBL_FAX'
             )
         ),
         array (
             array (
                 'name' => 'registered_address_street',
                 'label' => 'LBL_REGISTERED_ADDRESS',
                 'type' => 'address',
                 'displayParams' => array (
                     'key' => 'registered'
                 )
             ),
         ),
     ),
     'LBL_PANEL_ADVANCED' => array (
      array (
             array (
                 'name' => 'assigned_user_name',
                 'label' => 'LBL_ASSIGNED_TO'
             ),
             array (
                 'name' => 'date_modified',
                 'label' => 'LBL_DATE_MODIFIED',
                 'customCode' => '{$fields.date_modified.value} '
                         + '{$APP.LBL_BY} '
                         + '{$fields.modified_by_name.value}',
             )
         ),
     ),
  )
);
?>

We see that line 2 defines an array $viewdefs['ABC_Vehicles']['DetailView'] which places a DetailView entry for the module ABC_Vehicles into $viewdefs (DetailView will be EditView or QuickCreateView as appropriate). This array has two main keys defined here:

templateMeta 

The templateMeta key provides information about the view in general. The ['form']['buttons'] entries define the buttons that should appear in this view.

panels 

The panels entry defines the actual layout of the Detail (or Edit) view. Each entry is a new panel in the view with the key being the label for that panel. We can see in our example that we have 2 panels. One uses the label defined by the language string LBL_ABC_VEHICLES_INFO, the other uses LBL_PANEL_ADVANCED.

Each panel has an array entry for each row, with each array containing an entry for each column. For example we can see that the first row has the following definition:

array(
  array (
     'name' => 'name',
     'comment' => 'The Name of the Vehicle',
     'label' => 'LBL_NAME',
  ),
  'reg_number',
),

This has an array definition for the first row, first column and a string definition for the first row, second column. The string definition is very straightforward and simply displays the detail (or edit, as appropriate) view for that field. It will use the default label, type, etc. In our example we are displaying the field named reg_number.

The array definition for the first row, first column is a little more complex. Each array definition must have a name value. In our example we are displaying the name field. However we also supply some other values. Values most commonly used are:

'displayParams' => array(
    'rows' => 2,
    'cols' => 30,
),

editviewdefs.php 

editviewdefs.php provides information on the layout and fields of the edit view for this module. This file uses the same structure as detailviewdefs.php. Please see the information on detailviewdefs.php.

listviewdefs.php 

The listviewdefs.php file for a module defines what fields the list view for that module will display. Let’s take a look at an example:

$listViewDefs ['AOR_Reports'] =
array (
  'NAME' =>
  array (
    'width' => '15%',
    'label' => 'LBL_NAME',
    'default' => true,
    'link' => true,
  ),
  'REPORT_MODULE' =>
  array (
    'type' => 'enum',
    'default' => true,
    'studio' => 'visible',
    'label' => 'LBL_REPORT_MODULE',
    'width' => '15%',
  ),
  'ASSIGNED_USER_NAME' =>
  array (
    'width' => '15%',
    'label' => 'LBL_ASSIGNED_TO_NAME',
    'module' => 'Employees',
    'id' => 'ASSIGNED_USER_ID',
    'default' => true,
  ),
  'DATE_ENTERED' =>
  array (
    'type' => 'datetime',
    'label' => 'LBL_DATE_ENTERED',
    'width' => '15%',
    'default' => true,
  ),
  'DATE_MODIFIED' =>
  array (
    'type' => 'datetime',
    'label' => 'LBL_DATE_MODIFIED',
    'width' => '15%',
   'default' => true,
  ),
);

To define the list view defs we simply add a key to the $listViewDefs array. In this case we add an entry for AOR_Reports This array contains an entry for each field that we wish to show in the list view and is keyed by the upper case name of the field. For example, the REPORT_MODULE key refers to the report_module field of AOR_Reports.

popupdefs.php 

popupdefs.php provides information on the layout, fields and search options of the module popup that is usually used when selecting a related record.

Let’s look at the default popupdefs.php for the Accounts module:

$popupMeta = array(
  'moduleMain' => 'Case',
  'varName' => 'CASE',
  'className' => 'aCase',
  'orderBy' => 'name',
  'whereClauses' =>
      array('name' => 'cases.name',
              'case_number' => 'cases.case_number',
              'account_name' => 'accounts.name'),
  'listviewdefs' => array(
      'CASE_NUMBER' => array(
          'width' => '5',
          'label' => 'LBL_LIST_NUMBER',
          'default' => true),
      'NAME' => array(
          'width' => '35',
          'label' => 'LBL_LIST_SUBJECT',
          'link' => true,
          'default' => true),
      'ACCOUNT_NAME' => array(
          'width' => '25',
          'label' => 'LBL_LIST_ACCOUNT_NAME',
          'module' => 'Accounts',
          'id' => 'ACCOUNT_ID',
          'link' => true,
          'default' => true,
          'ACLTag' => 'ACCOUNT',
          'related_fields' => array('account_id')),
      'PRIORITY' => array(
          'width' => '8',
          'label' => 'LBL_LIST_PRIORITY',
          'default' => true),
      'STATUS' => array(
          'width' => '8',
          'label' => 'LBL_LIST_STATUS',
          'default' => true),
      'ASSIGNED_USER_NAME' => array(
          'width' => '2',
          'label' => 'LBL_LIST_ASSIGNED_USER',
          'default' => true,
         ),
      ),
  'searchdefs'   => array(
      'case_number',
      'name',
      array(
          'name' => 'account_name',
          'displayParams' => array(
              'hideButtons'=>'true',
              'size'=>30,
              'class'=>'sqsEnabled sqsNoAutofill'
          )
      ),
      'priority',
      'status',
      array(
          'name' => 'assigned_user_id',
          'type' => 'enum',
          'label' => 'LBL_ASSIGNED_TO',
          'function' => array(
              'name' => 'get_user_array',
              'params' => array(false))
          ),
    )
);

The popupdefs.php specifies a $popupMeta array with the following keys:

quickcreatedefs.php 

quickcreatedefs.php provides information on the layout and fields of the quick create view for this module (this is the view that appears when creating a record from a subpanel). This file uses the same structure as detailviewdefs.php. Please see the information on detailviewdefs.php.

searchdefs.php 

The search defs of a module define how searching in that module looks and behaves.

Let’s look at an example.

$searchdefs ['Accounts'] = array (
     'templateMeta' => array (
         'maxColumns' => '3',
         'maxColumnsBasic' => '4',
         'widths' => array (
             'label' => '10',
             'field' => '30'
         )
     ),
     'layout' => array (
         'basic_search' => array (
             'name' => array (
                 'name' => 'name',
                 'default' => true,
                 'width' => '10%'
             ),
             'current_user_only' => array (
                 'name' => 'current_user_only',
                 'label' => 'LBL_CURRENT_USER_FILTER',
                 'type' => 'bool',
                 'default' => true,
                 'width' => '10%'
             )
         )
         ,
         'advanced_search' => array (
             'name' => array (
                 'name' => 'name',
                 'default' => true,
                 'width' => '10%'
             ),
             'website' => array (
                 'name' => 'website',
                 'default' => true,
                 'width' => '10%'
             ),
             'phone' => array (
                 'name' => 'phone',
                 'label' => 'LBL_ANY_PHONE',
                 'type' => 'name',
                 'default' => true,
                 'width' => '10%'
             ),
             'email' => array (
                 'name' => 'email',
                 'label' => 'LBL_ANY_EMAIL',
                 'type' => 'name',
                 'default' => true,
                 'width' => '10%'
             ),
             'address_street' => array (
                 'name' => 'address_street',
                 'label' => 'LBL_ANY_ADDRESS',
                 'type' => 'name',
                 'default' => true,
                 'width' => '10%'
             ),
             'address_city' => array (
                 'name' => 'address_city',
                 'label' => 'LBL_CITY',
                 'type' => 'name',
                 'default' => true,
                 'width' => '10%'
             ),
             'address_state' => array (
                 'name' => 'address_state',
                 'label' => 'LBL_STATE',
                 'type' => 'name',
                 'default' => true,
                 'width' => '10%'
             ),
             'address_postalcode' => array (
                 'name' => 'address_postalcode',
                 'label' => 'LBL_POSTAL_CODE',
                 'type' => 'name',
                 'default' => true,
                 'width' => '10%'
             ),
             'billing_address_country' => array (
                 'name' => 'billing_address_country',
                 'label' => 'LBL_COUNTRY',
                 'type' => 'name',
                 'options' => 'countries_dom',
                 'default' => true,
                 'width' => '10%'
             ),
             'account_type' => array (
                 'name' => 'account_type',
                 'default' => true,
                 'width' => '10%'
             ),
             'industry' => array (
                 'name' => 'industry',
                 'default' => true,
                 'width' => '10%'
             ),
             'assigned_user_id' => array (
                 'name' => 'assigned_user_id',
                 'type' => 'enum',
                 'label' => 'LBL_ASSIGNED_TO',
                 'function' => array (
                     'name' => 'get_user_array',
                     'params' => array (
                        0 => false
                     )
                 ),
                 'default' => true,
                 'width' => '10%'
            )
        )
    )
);

Here we setup a new array for Accounts in the $searchdefs array. This has two keys:

subpaneldefs.php 

The subpaneldefs.php file provides definitions for the subpanels that appear in the detail view of a module. Let’s look at an example:

$layout_defs['AOS_Quotes'] = array (
  'subpanel_setup' => array (
      'aos_quotes_aos_contracts' => array (
          'order' => 100,
          'module' => 'AOS_Contracts',
          'subpanel_name' => 'default',
          'sort_order' => 'asc',
          'sort_by' => 'id',
          'title_key' => 'AOS_Contracts',
          'get_subpanel_data' => 'aos_quotes_aos_contracts',
          'top_buttons' => array (
              0 => array (
                  'widget_class' => 'SubPanelTopCreateButton'
              ),
              1 => array (
                  'widget_class' => 'SubPanelTopSelectButton',
                  'popup_module' => 'AOS_Contracts',
                  'mode' => 'MultiSelect'
              )
          )
      ),
      'aos_quotes_aos_invoices' => array (
          'order' => 100,
          'module' => 'AOS_Invoices',
          'subpanel_name' => 'default',
          'sort_order' => 'asc',
          'sort_by' => 'id',
          'title_key' => 'AOS_Invoices',
          'get_subpanel_data' => 'aos_quotes_aos_invoices',
          'top_buttons' => array (
              0 => array (
                  'widget_class' => 'SubPanelTopCreateButton'
              ),
              1 => array (
                  'widget_class' => 'SubPanelTopSelectButton',
                  'popup_module' => 'AOS_Invoices',
                  'mode' => 'MultiSelect'
              )
          )
      ),
      'aos_quotes_project' => array (
          'order' => 100,
          'module' => 'Project',
          'subpanel_name' => 'default',
          'sort_order' => 'asc',
          'sort_by' => 'id',
          'title_key' => 'Project',
          'get_subpanel_data' => 'aos_quotes_project',
          'top_buttons' => array (
              0 => array (
                  'widget_class' => 'SubPanelTopCreateButton'
              ),
              1 => array (
                  'widget_class' => 'SubPanelTopSelectButton',
                  'popup_module' => 'Accounts',
                  'mode' => 'MultiSelect'
              )
          )
      )
   )
);

In the example above we set up a definition for a module (in this case AOS_Quotes) in the $layout_defs array. This has a single key subpanel_setup which is an array of each of the subpanel definitions keyed by a name. This name should be something recognisable. In the case above it is the name of the link field displayed by the subpanel. The entry for each subpanel usually has the following defined:

subpanels 

Inside the metadata folder is the subpanels folder. This allows creating different subpanel layouts for different parent modules. For example, the Contacts module will display differently in the subpanel on an account than it will in the subpanel of a case. The files inside the subpanels folder can be named anything. All that matters is that it can be referenced in the subpanel_name of the subpaneldefs.php of the parent module. The usual subpanel file is simply called default.php. Let’s look at the modules/Accounts/metadata/subpanels/default.php file:

$subpanel_layout = array(
  'top_buttons' => array(
      array(
          'widget_class' => 'SubPanelTopCreateButton'
      ),
      array(
          'widget_class' => 'SubPanelTopSelectButton',
          'popup_module' => 'Accounts'
      ),
  ),
  'where' => '',
  'list_fields' => array (
    'name' =>
    array (
     'vname' => 'LBL_LIST_ACCOUNT_NAME',
     'widget_class' => 'SubPanelDetailViewLink',
     'width' => '45%',
     'default' => true,
    ),
    'billing_address_city' =>
    array (
      'vname' => 'LBL_LIST_CITY',
      'width' => '20%',
      'default' => true,
    ),
    'billing_address_country' =>
    array (
      'type' => 'varchar',
      'vname' => 'LBL_BILLING_ADDRESS_COUNTRY',
      'width' => '7%',
      'default' => true,
    ),
    'phone_office' =>
    array (
      'vname' => 'LBL_LIST_PHONE',
      'width' => '20%',
      'default' => true,
    ),
    'edit_button' =>
    array (
      'vname' => 'LBL_EDIT_BUTTON',
      'widget_class' => 'SubPanelEditButton',
      'width' => '4%',
      'default' => true,
    ),
    'remove_button' =>
    array (
      'vname' => 'LBL_REMOVE',
      'widget_class' => 'SubPanelRemoveButtonAccount',
      'width' => '4%',
      'default' => true,
    ),
  )
);

There are three keys in the $subpanel_layout variable for this subpanel. These are:

You can find additional technical information on Subpanels' implementation in a file on your HelloCloud instance: include/SubPanel/subpanels.txt

studio.php 

studio.php is the simplest file in metadata and it’s existence is simply used to confirm if a module should be shown in studio for user tweaking. Note that, unlike other metadata files, the file in modules/<TheModule>/metadata/studio.php will be the only one checked. A file in custom/modules/<TheModule>/metadata/studio.php will have no effect.

Code Example 

This is an example of setting up a function subpanel using Metadata.

In this example the cases module has a custom field incident_code_c which is used to track cases with the same root cause. We’ll add a subpanel to show all cases that have the same incident_code_c.

Initially we add to the subpanel_setup section of Cases by creating the following file in custom/Extension/modules/Cases/Ext/Layoutdefs/IncidentLayoutdefs.php

<?php
$layout_defs["Cases"]["subpanel_setup"]['incident_cases'] = array(
   'module' => 'Cases',
   'title_key' => 'LBL_INCIDENT_CASES',
   'subpanel_name' => 'default',
   'get_subpanel_data' => 'function:get_cases_by_incident',
   'function_parameters' =>
           array('import_function_file' => 'custom/modules/Cases/IncidentUtils.php',),
           "generate_select" => true,
);

Next we create the file which will define our get_cases_by_incident function custom/modules/Cases/IncidentUtils.php.

<?php
 function get_cases_by_incident(){
         global $db;
         //Get the current bean
         $bean = $GLOBALS['app']->controller->bean;
         $incidentCode = $db->quote($bean->incident_code_c);
         //Create the SQL array
         $ret = array();
         $ret['select'] = ' SELECT id FROM cases ';
         $ret['from'] = ' FROM cases ';
         $ret['join'] = "";
         //Get all cases where the incident code matches but exclude the current case.
         $ret['where']="WHERE cases.deleted = 0 AND cases_cstm.incident_code_c = '{$incidentCode}' AND cases.id != '{$bean->id}'";
         return $ret;
}