Managing Lists

Overview

There are three ways to manage lists in Sugar: by using Studio in the application, by directly modifying the list's language strings, and via the code-level Dropdown Helper. This page explains all three methods.

Managing Lists With Studio

If you know the name of the list you would like to edit, you can access the application's dropdown editor by navigating to Admin > Dropdown Editor. Alternatively, navigate to a field that uses the list (Admin > Studio > {Module} > Fields > {field_name}) and click "Edit" under the Dropdown List field:
edit-ddlist

For information on using the dropdown editor, please refer to the Developer Tools documentation in the Administration Guide.

Directly Modifying Lists

There are two ways to directly modify the language strings. The first way is to modify the custom language file, located at ./custom/include/language/<language key>.lang.php.

If you are developing a customization to be distributed and you want to be able to create new or override existing list values, you will need to work within the extension application directory. To do this you will create the following file: ./custom/Extension/application/Ext/Language/<language key>.<unique name>.php.

The file will contain your override values. Please note that within this file you will set each label index individually. An example of this is:

  <?php

$app_list_strings['LIST_NAME']['Key_Value'] = 'My Display Value';

Once the file is created with your adjustments, navigate to Admin > Repair > Quick Rebuild & Repair. This will compile all of the Extension files from ./custom/Extension/application/Ext/Language/ to ./custom/application/Ext/Language/<language key>.lang.ext.php.

Managing Lists With Dropdown Helper

You can use the dropdown helper to manage lists at the code level. This example demonstrates how to add and update values for a specific dropdown list:

  require_once 'modules/Studio/DropDowns/DropDownHelper.php';

$dropdownHelper = new DropDownHelper();

$parameters = array();
$parameters['dropdown_name'] = 'example_list';

$listValues = array(
    'Key_Value_1' => 'Display Value 1',
    'Key_Value_2' => 'Display Value 2',
    'Key_Value_3' => 'Display Value 3'
);

$count = 0;
foreach ($listValues as $key=>$value) {
    $parameters['slot_'. $count] = $count;
    $parameters['key_'. $count] = $key;
    $parameters['value_'. $count] = $value;
    //set 'use_push' to true to update/add values while keeping old values
    $parameters['use_push'] = true;
    $count++;
}

$dropdownHelper->saveDropDown($parameters);

This is a generic code snippet that can be embedded into any PHP functionality in SugarCRM—for example, as part of a pre- or post-execution step in an MLP, or as an API endpoint.

Integrating Dropdown Helper with an API Endpoint

The following example, creates a new Administration endpoint and levarages the DropdownHelper to update its key/values

Create a new file at: ./custom/Extension/modules/Administration/Ext/clients/base/api/DropdownHelperApi.php

  <?php
require_once 'modules/Studio/DropDowns/DropDownHelper.php';

class DropdownHelperApi extends AdministrationApi
{
    /**
     * @return array
     */
    public function registerApiRest()
    {
        return [
            'updateDropdownByCode' => [
                'reqType' => 'GET',
                'path' => ['Administration', 'updateDropdownByCode', '?'],
                'pathVars' => ['', '', 'name'],
                'method' => 'updateDropdownByCode',
                'shortHelp' => 'Gets modules that whose names and icons can be changed',
                'longHelp' => 'modules/Administration/clients/base/api/help/ModuleNamesAndIconsApiGet.html',
                'exceptions' => ['SugarApiExceptionNotAuthorized']
            ]
        ];
    }

    public function updateDropdownByCode(ServiceBase $api, array $args)
    {
        $this->ensureAdminUser();

        $dropdownName = $args['name'];

        $dropdownHelper = new DropDownHelper();

        $parameters = array();
        $parameters['dropdown_name'] = $dropdownName;

        $listValues = array(
            'Key_Value_1' => 'Display Value 1',
            'Key_Value_2' => 'Display Value 2',
            'Key_Value_3' => 'Display Value 3'
        );

        $count = 0;
        foreach ($listValues as $key=>$value) {
            $parameters['slot_'. $count] = $count;
            $parameters['key_'. $count] = $key;
            $parameters['value_'. $count] = $value;
            //set 'use_push' to true to update/add values while keeping old values
            $parameters['use_push'] = true;
            $count++;
        }

        $dropdownHelper->saveDropDown($parameters);

        return $parameters;

    }
}