Sugar 5.1 brought many improvements to the Sugar application framework.  In this release, we introduced a new method for creating custom relationships in Studio and Module Builder called the Relationship Editor. This new editor consolidates the functionality of the old “relationship fields” which worked as basic one-to-many relationships as well as the many-to-many relationships that are produced from creating relationships in the 5.0 Module Builder.

As there have been questions regarding how to use this new editor and how exactly it works, this article will cover the inner workings of the Relationship Editor.

(more…)

Following quickly on the heels of the Sugar Developer Guide, you will now find the Sugar entity relationship diagrams available online.  The Sugar Community Edition ER diagram is available here and the diagrams for Professional and Enterprise editions are availble along with the software here.

One of the many code re-factoring changes we’ve made with Sugar 5.1 is to consolidate the number of entry points into the application as well as rerouting the current entry points through the MVC framework. An entry point is a PHP file that can be called either via URL or command line to actually invoke a Sugar process.  For instance when calling the home page of the application via URL or starting the scheduler via command line.  Consolidating the entry points has also helped us secure the application better and improve quality by making sure each request goes through the same initialization code.

Backwards compatibility with custom code
It does however present some backwards compatibility problems.  Most notably you will need to update your code if you have custom code that relies on a deprecated entry point such as a custom Quote template that may have called pdf.php which is no longer a stand-alone entry point. In these cases, you will need to change the URL reference as described below:

1. Look for the entry point file name in the include/MVC/Controller/entry_point_registry.php. It will be the in the ‘file’ key in the sub-array.
2. Make note of the key of that array. So for the pdf.php entry point, it appears in include/MVC/Controller/entry_point_registry.php as:

   'pdf' => array('file' => 'pdf.php', 'auth' => true),

   So we will want to use the ‘pdf’ part in the next step.

3. Change the URL reference from the current reference to one in the form of:

   index.php?entryPoint=<<entrypoint>>

   So for the above pdf.php example, we would change our references from

   pdf.php

   to:

   index.php?entryPoint=pdf

The only remaining entry points in 5.1 that aren’t using this new index.php URL pattern (and therefore continue to be valid entry points) are:

• campaign_tracker.php – used by the Campaign Management module for tracking campaign responses. Deprecated as of Sugar 5.1.0.
• cron.php – used by the Windows Scheduler Service or the cron service on Linux and Unix for executing the Sugar Scheduler periodically.
• index.php – default entry point into the Sugar application
• install.php – used for initial install
• maintenance.php – invoked when the application is down for maintenance.
• metagen.php – Deprecated as of Sugar 5.1.0.
• silentUpgrade.php – used for silent installer
• soap.php – entry point for all SOAP calls
• vcal_server.php – used for syncing information to Outlook

One of the best parts of using Sugar has to be customizing it. You don’t want to use a software package if it can’t meet your needs, and no two people or businesses have the same set of requirements. Sugar provides some really neat tools when it comes to customization, and in 5.1 they have been made even better.

There are a lot of really cool additions to the 5.1 developer tool set, and I’d thought I’d take a minute to quickly go over a couple of them.

Once you open up Module Builder in 5.1, you will notice the addition of two new templates, File and Sale. The File template is for document-based modules such as resumes, photos, or any other files you need to work with. Sale is based on the opportunities module and is designed to store information on sales and possible future sales.

After you have created a new module, you may also notice a few more new things. One that I would like to point out is under layouts, we have added Sugar Dashlet views. Starting in 5.1, your new custom modules will have Sugar Dashlets available straight out of Module Builder. You can edit the Sugar Dashlet layouts in the same manner as standard list and search views.

Finally, I’d like to touch on the area of integrations. In previous versions of Sugar, there wasn’t an easy way to integrate with existing web based systems from Studio or Module Builder. Certainly you can find many tutorials on how to add custom logic hooks to do this, but there hasn’t been a way to do integrations writing any code. In 5.1, this has changed with the addition of Link fields and iFrames with auto-generated URLs.
I’ll show how this is used with a fairly simple example, adding a Google map to the DetailView of a company. In this case my new “Partners” module which is based on the company template.

1. Open up your custom module’s fields, and click “Add Field”.
2. Select the IFrame field type.
3. Fill in the following data:
   • FieldName: GoogleMap
   • Display Label: Google Map
   • Generate URL: check
   • Default Value (now this is where the magic happens):
     http://maps.google.com/maps?f=q&q={shipping_address_street}+
{shipping_address_city}+
{shipping_address_state}+
{shipping_address_postalcode}+
{shipping_address_country}
   • Max Size: 255
   • IFrame Height: 400
4. Add the new field to your DetailView. Be sure to give the field a full row to itself for maximum readability. Note that adding an iFrame or a Link field that has a generated URL to an EditView will result in a read-only field that is un-editable.
5. Deploy your package and create a new record in your new module, be sure to enter a real address into the shipping address fields.
6. Save the record and view the Google map pointing to the business’ location.

The uses for generated URLs are almost endless, as you can embed links and iFrames to either internal or external systems without writing a single line of code. Feel free to post some ideas for other integrations.

With our 5.1 release approaching, one of the features that I was most looking forward to was the revamped Sugar Wireless functionality.  I’m a devoted iPhone user, and I’m usually in need of getting to information in Sugar quickly.. but I don’t want to lug my laptop around with me everywhere I go.

Prior to 5.1, Sugar’s wireless capabilities didn’t provide me with much help as a customer support person, for the simple fact that the Cases module wasn’t exposed.  Sure, I suppose I could have hacked it together at some point in the past, but knowing that we would revamp Wireless eventually, I never got around to it.  Until now!

I spent a few minutes recently seeing how functional Sugar Wireless was for a customer support person….the initial verdict was “not very”.  Yes, Cases are now available, but the absence of Notes is something of a non-starter for companies who are using Sugar Portal to manage their customer interactions (like SugarCRM Inc. ourselves).  The thinking was that Notes were primarily used as a vehicle for file attachments — a decision that I disagree with.  My support engineers use Notes as the most common method of communication with our customers; leaving it out of Wireless cripples our ability to use Wireless.

Would I let that stop me, though?  Of course not!  So I spent a little bit of time over the last couple of days looking into how to customize Sugar Wireless 5.1, and I figured I’d share my findings with the developer community.

(As an aside, I’ll mention here that I haven’t really spent a lot of time understanding MVC and much of the metadata introduced with Sugar 5.0.  I’m not a developer; if I’d filled out Clint’s Developer Survey, I would have called myself a “Fearless Hacker”.  Most of my time spent with my fingers in Sugar’s code dates back before the 5.0 days…)

I set out with the following objectives in mind:

• Modify the Cases views in Wireless to include some custom fields that we rely upon
• Add the Notes module, related to Cases
• Make it all upgrade-safe

There were a few changes that needed to be made to the 5.1 code base in order to support these objectives.  Those changes will be included in the final released version of 5.1, but are not available in 5.1 RC.  Big thanks to SugarCRM software engineer John Mertic for sneaking the necessary changes into Wireless while 5.1 is hunkering down for release.

Customizing the Cases module

First things first, get my custom fields to appear in the Cases module.  Without certain key pieces of information, it would be difficult for a support engineer to glean enough information to do anything useful.

I copied three files from SUGARROOT/modules/Cases/metadata/ to SUGARROOT/custom/modules/Cases/metadata:

• wireless.editviewdefs.php
• wireless.searchdefs.php
• wireless.subpaneldefs.php

Once there, I could edit these files in an upgrade-safe manner, since they’ll override the stock files in SUGARROOT/modules/Cases/metadata.

To wireless.editviewdefs.php, I added lines into the ‘panels’ array, like:

array(‘product_category_c’),
array(’sugar_edition_c’),
array(’sugar_version_c’),
array(‘deployment_c’),

I also added a line in read-only mode:

array(array(‘name’=>’Support_Service_Level_c’, ‘displayParams’=>array(‘wireless_detail_only’=>true,)),),

Your field names will most presumably be different than mine, but the rest of the syntax will be the same.

In wireless.searchdefs.php, I added lines into the ‘layout’ array for ‘name’ and ’status’, which would make searching easier.  Especially for ‘name’, or Subject as it would appear through the UI, this is helpful if you don’t know the case number, and Wireless will obey the % wildcard in the search field.

In wireless.subpaneldefs.php, I added this block into the ’subpanel_setup’ array:

‘notes’ => array(
‘order’ => 1,
‘module’ => ‘Notes’,
‘get_subpanel_data’ => ‘notes’,
‘title_key’ => ‘LBL_NOTES_SUBPANEL_TITLE’,
),
More on this later, when we get to adding the Notes module…

Finally, with regards to the Cases module, I wanted to add the Number to the ListView for search results.  Two steps were needed for this:

1)  Create a directory SUGARROOT/custom/modules/Cases/views/ and add a view.wirelesslist.php file to that new directory.  This will allow me to subclass out the main wireless ListView:

require_once(‘include/MVC/View/views/view.wirelesslist.php’);

/**
* ViewWirelesslist extends SugarWirelessView and is the view for wireless list views.
*
*/
class CasesViewWirelesslist extends ViewWirelesslist
{
public function display(){
// print the header
$this->wl_header();
// print the select list
$this->wl_select_list();

// check for presence of parent_id — this is the subpanel list view
if (isset($_REQUEST['parent_id'])){
$this->wl_subpanel_list_view_display();
}
// normal list view display
else{
$this->wl_list_view_display();
}

// display the list view
$this->ss->display(‘custom/modules/Cases/tpls/wirelesslist.tpl’);

// print the footer
$this->wl_footer();
}
}

2)  Create a directory SUGARROOT/custom/modules/Cases/tpls/ and copy the file SUGARROOT/include/SugarWireless/tpls/wirelesslist.tpl here, as referenced in the ‘display the list view’ section above.  Then, I built out from this line:

<a href=”index.php?module={$MODULE}&action=wirelessdetail&record={$record.ID}”>{$record.NAME}</a>

To these lines:

{if $MODULE == “Cases”}
<a href=”index.php?module={$MODULE}&action=wirelessdetail&record={$record.ID}”>{$record.CASE_NUMBER}  {$record.NAME}</a>
{else}
<a href=”index.php?module={$MODULE}&action=wirelessdetail&record={$record.ID}”>{$record.NAME}</a>
{/if}

Adding the Notes module

Most of the changes necessary for Notes are upgrade-safe. First was the Cases subpaneldefs, covered above.

Next is creating Wireless metadata files for the Notes module.  Since these were being written from scratch, I copied the following files from SUGARROOT/modules/Calls/metadata/ to SUGARROOT/custom/modules/Notes/metadata:

• wireless.editviewdefs.php
• wireless.searchdefs.php
• wireless.subpaneldefs.php

Then edited those files to replace ‘Calls’ with ‘Notes’.

In wireless.editviewdefs.php:

$viewdefs['Calls']['EditView'] = array(

became

$viewdefs['Notes']['EditView'] = array(

And equivalent changes in the other two files.

Upgrade-Safe?

Up to this point, everything should be upgrade-safe. Unfortunately, there’s one step that won’t be upgrade-safe…

In the file SUGARROOT/include/MVC/Controller/wireless_module_registry.php, I needed to add Notes to the registry:

‘Notes’ => array(),

[EDIT, August 11, 2008:  John Mertic pointed out to me how to make this step upgrade-safe as well.]

One more change to make, and this one is upgrade-safe as well.  In the directory SUGARROOT/custom/include/MVC/Controller, create a file named wireless_module_registry.php, which will contain this:

<?php

?>
This controls the hyperlinks within the Wireless application to keep your browser within Wireless, instead of going back to the main Sugar application.  Without this step, the links will send you to your main Sugar application, which isn’t optimized for your mobile browser.

Conclusion

All in all, not too painful!  I did my development on a local instance, and tweaked things to the point where I was happy with the appearance, then made my changes in our production instance.  From a testing perspective, you can use your computer’s browser by logging into the mobile interface:

http://YOUR.SUGAR.SITE/index.php?module=Users&action=Login&mobile=1

I hope you find this useful.  If you come up with other ways to extend Sugar Wireless, let’s hear them!