JoshSweeney

SugarCRM: Adding Custom Settings to the Admin Area

Recently my GetSocial Twitter and GetSocial Twitter4Contacts modules started gaining traction on Blogs and in the Twitterverse. The more people that downloaded them the more requests I received for features and updates.

One feature that I knew was needed was the ability to configure the company account credentials in the Administration area of SugarCRM. This is where the research began.

I have made plenty of custom modules that when clicked show the list view and allow the addition of records. I have also customized these modules. However, adding areas to the Admin section that when clicked shows one screen with two fields that saves custom configuration variables was very different.

To see the functionality I am speaking of you can simply go to Admin -> License Settings or view the screenshot below.

I first started to create this area by trying to duplicate the functionality in the Email Settings. Email Settings actually uses the EmailMan module which has a standard module structure that manages the email Queue and a config section which holds the email settings. This means that when you click Admin -> Email Settings you go to EmailMan with the Config action ( index.php?module=EmailMan&action=config ). When you click Admin->Manage Email Queue you get the index action ( index.php?module=EmailMan&action=index ) and the Queue view

I duplicated this functionality to discover that it really wasn’t what I was looking for. I only wanted the functionality that was shown when the config action was called. Searching for a way to not create a full module that I didn’t need along with a config section I found the Licence Settings.

The license settings area works a little differently, it calls the Administration module and the LicenseSettings action ( index.php?module=Administration&action=LicenseSettings ). This functionality is driven by two essential files LicenseSettings.php and LicenseSettings.html under Modules/Administration. The fields that are filled out in this area get populated in the config table in the database.

The first step was to copy those files and to use them as a template to create the functionality that I needed. Once copied, I renamed them to the same name that would be called with the action which was TweetCreds. After changing the names I stripped out all of the LicenseSettings fields and added my two fields for filling in Twitter credentials.

The real issue came when I wanted to save my new fields. At first the field names where TWEETACCOUNT and TWEETPASSWORD and no matter what I did my fields would not get saved. More debugging and digging lead me to the Save.php file in the Administration module. In this file there is a foreach loop that loops through all of the POST parameters.

[code]

foreach ($_POST as $key => $val) {
$prefix = $focus->get_config_prefix($key);
if (in_array($prefix[0], $focus->config_categories)) {
if ( $prefix[0] == "license" )
{
if ( $prefix[1] == "expire_date" )
{
global $timedate;
$val = $timedate->swap_formats( $val, $timedate->get_date_format(), $timedate->dbDayFormat );
}
else
if ( $prefix[1] == "key" )
{
$val = trim($val); // bug 16860 tyoung - trim whitespace from the start and end of the licence key value
}
}

$focus->saveSetting($prefix[0], $prefix[1], $val);
}
}

[/code]

I could see that my parameters were making it this far but the loop wasn’t inserting them into the config table as expected. This leads me to the main takeaway item from this blog entry. You can’t just add fields with any name to be saved by this function. They have to follow a specific structure.

The structure that they have to follow is <Category>_<Name> . The category and name is what will get stored in the config tables first two columns ( Category, Name ). The third column ( Value ) hold the value of the variable. Once I figured this out and changed the fields to read TWEETCREDS_ACCOUNT and TWEETCREDS_PASSWORD. This still won’t work until you add the category name ( TWEETCREDS ) to the $config_categories array in Administrator.php.  This is also used by the foreach loop to do matching and to sure that the POST is not a throwaway value or a value used for some other action.

So as you can see, the naming scheme is very important when adding custom values to the config table and custom sections to the admin area.

I hope that this was a helpful post that will act as a partial guide that will assist you in adding your own custom admin sections with ease. Feel from to post and questions that you may have and I will try to provide an answer.

Tags: admin, custom, getsocial twitter, SugarCRM, twitter