Creating Subpanels with Custom Results in Sugar 7.5

dranneysugarcrm —  May 18, 2015

This post is targeted at beginner to intermediate Sugar Developers who want to add a subpanel to a module which returns custom results.

This post assumes some basic knowledge of Sugar 7 development, Sugar 7 administration, PHP, and SQL.  This article will hopefully be useful to those who have done some Sugar 7 development but are not necessarily experts.

The example in this post was created on an out-of-the-box installation of Sugar Professional with the generated demo data.  But this technique should work on any on-premise Sugar 7 instance.

An acknowledgement

I recently needed to add a subpanel to a module which returned rows matching some unusual criteria.  The requirement for this subpanel didn’t match the standard one-to-many or many-to-many relationship with another module that a subpanel usually reflects.  I researched ways to do this and came across an excellent blog post on the subject by Shane Dowling.  Following what he had written I was able to accomplish my task.  This post is an attempt to make this technique accessible to those who are less familiar with Sugar 7 development.

Concerning Subpanels

When a one-to-many or many-to-many relationship exists between two modules this will typically be indicated by the presence of a subpanel in one or both of the modules.  For example, there is a default one to many relationship between Accounts and Contacts.  As a result, when you bring up an Account record you will see a “Contacts” subpanel which displays every contact associated with that account.  Likewise, when you create a custom one-to-many or many-to-many relationship between two modules in Studio – a similar subpanel will be created for you in the appropriate modules.  That subpanel will then display all the related rows.

That is pretty powerful alone but there are times you need something more specialized.  This post will show you a way to create a custom subpanel to display rows which match whatever criteria you need.

An Example Scenario

Let’s say that at your company the technical support folks are also sales people and upper management has issued a mandate that the support engineer needs to make some positive mention of any open opportunity currently in the pipeline.  Yeah, I wouldn’t want to work there either, but let’s just say that’s the case.  A support person could bring up a separate tab in his browser and search for all open opportunities but that’s inconvenient.  Instead it would be nice if there were a subpanel on the current case that the support person could look at to see all currently open opportunities.

Let’s create a custom subpanel in the Cases module which does exactly that.

Since you can’t accomplish this with a regular custom relationship, it’s probably time to use some custom code.

Step 1: Create a Custom Relationship

This technique involves overriding certain parts of a relationship’s functionality.  To do that you first need a relationship to override.  You can create the various files and subpanels yourself, but I find it easier to start by creating the initial relationship through Studio.  Go into Studio > Cases > Relationships and create a custom one-to-many relationship between Cases and Opportunities.

Initial custom one-to-many relationship

The primary module should be the module in which you want the subpanel to appear and the related module should be the module whose rows you want to display.  For our example, Cases is the primary module because we want the subpanel to appear in the Cases record view and Opportunities is the related module because we want the subpanel to display opportunities.

Once you’ve saved and deployed the relationship a new subpanel will appear in the Cases module.  It probably has a weird title, and shows no rows, but hey, it’s there which saves us some work.

Step 2: Customize the Relationship’s Behavior

When you created that relationship, among all the other things that Studio did, it also created the file custom/Extension/modules/Cases/Ext/Vardefs/cases_opportunities_1_Cases.php.  This file contains the metadata for the relationship which tells the system how to handle it and probably looks something like this:

To get the behavior we want we need to update this file to point at some custom relationship code we’re going to write later. To do this we’ll make use of two fields which do not appear in generated code, namely “link_file” and “link_class”. We are also going to change the “relationship” value to a blank:

These changes tell Sugar 7 to use the OpportunitiesForCaseLink class to handle the relationship you just created rather than the regular code it would normally use. Notice that the path in “link_file” is relative to the Sugar directory.

Step 3: Customize the Subpanel’s Title

By default the subpanel is going to have a generic title like “Opportunities” which isn’t specific enough.  So we need to change it. First, create the file custom/Extension/modules/Cases/Ext/Language/en_us.opportunities_for_cases_subpanel.php:

Then re-edit custom/Extension/modules/Cases/Ext/Vardefs/cases_opportunities_1_Cases.php and change the ‘vname’ parameter to have the same value as the index you just created in $mod_strings.

Now, to make it actually show up correctly, edit custom/Extension/modules/Cases/Ext/clients/base/layouts/subpanels/cases_opportunities_1_Cases.php which was created automatically by Studio previously

Step 4: Override the Relationship Code

Now we have to actually write the custom code that will handle the relationship. Normally Sugar will use an internal class called Link2 to handle the custom relationship. We’re going to extend that class and override certain methods so that it implements the custom behavior we want.

First, let’s create a basic version of this file in the same location we specified in the “link_file” value in the relationship metadata above, namely custom/modules/Cases/OpportunitiesForCaseLink.php. Likewise, note that the class name in this file matches the “link_class” value as well:

Once you put that in place, if you run a Quick Repair & Rebuild and then bring up a single case you should see the new “All Open Opportunities” subpanel and it should show all opportunities in the system.  We’ll get into the details in a bit but first let’s break down this large class a bit to make it clear how it works:

Note that we’re extending the Link2 class which is built into Sugar. As stated above that’s the class that handles these sorts of custom relationships. The class name must match the “link_class” value you provide in the relationship metadata.

This overrides a method from Link2. It returns the plural form of the related module name. Since this extension is just for the use of our special relationship, we can simply hardcode the value.

You don’t have to change anything with this method. However it does show something important. The “+” button you see on the right side of the subpanel is used to create new related records. This functionality won’t work once we’ve customized the Link2 class.

Generally it is a best practice to use custom subpanels in a read-only capacity.

Disabling the buttons on the subpanel can be accomplished by adding the ‘disabled’ CSS class to each button element.

The above method gets handed a SugarQuery object which will ultimately get executed to return the rows which are displayed in our custom subpanel. If you’re unfamiliar with SugarQuery then you should get familiar with it because it’s awesome. There is a very helpful blog entry on SugarQuery which is a great place to start. The SugarQuery object coming into this method is a basic query against the related module (in our case opportunities) which returns the appropriate columns. We want to take that basic query and change it so that it only returns the rows we care about. We’ve implemented this behavior in joinRaw().

Note that joinRaw() is passed the return value of this method.  This method generates a SQL string which is a JOIN to a table subquery. The SugarQuery object above will be joined to the results of this query, so only opportunities with an id matching the results of this query will show up in the subpanel.

Step 5: Modify the query as desired

Right now this will return every opportunity in the system so we need to change it to match our custom criteria.  The requirements given to us state that the subpanel should show every open opportunity in the system.  That means we need to adjust our query.

As seen earlier we are handed a SugarQuery object which will later be executed to give us our results.  That being the case, let’s simply alter the SugarQuery object to fit the requirements.

To restrict the results to only open opportunities we use the where() method of the SugarQuery object along with the notIn() method.

You can use other parts of SugarQuery to affect the results as well.  Review time is coming up, so let’s exceed expectations by ordering by the expected closed date showing the most recent first:

See what I did there?  I’m telling you SugarQuery is your friend.  Learn about it.  You won’t regret it.

Step 5 (Part 2): Using Raw SQL

Let’s say that after a few weeks, and after enough complaints from the support organization, management has finally realized that having support people comment on random open opportunities is silly.  They have decided that support folks should only comment on any open opportunities for the account associated with the current case.

While this is a boon to support, it kind of makes your life more difficult.  The account associated with a case is a simple field in the cases table (account_id).  However, the association between an account and an opportunity is stored in a separate table (accounts_opportunities) so it’s not obvious how you’d handle that in SugarQuery.  There’s likely a way, but the deadline is pressing and you’re not that good at SugarQuery yet.

The good news is that you’re not limited to using SugarQuery.  As you may have guessed the purpose of the getCustomJoin() method is to provide raw SQL we can inject into our SugarQuery object.  That means you can use whatever crazy SQL you need to fine tune the results of your query.

You should use SugarQuery abstraction whenever possible and descend into raw SQL only when absolutely necessary.

SugarQuery takes care of all sorts of background elements of a query such as team membership, whether or not rows are deleted, etc.  It exists to make your life easier, so you should use it if you can.  But when you cannot, the raw SQL option is available to you.

In this case we want to modify the results to only show us open opportunities for the account associated with the current case.  So let’s change the method to the following:

There are a few things to take note of in this code:

First, notice how we now use a combination of SugarQuery modifications and raw SQL.  This means you can do as much as possible through SugarQuery and relegate only the really weird stuff to raw SQL.  Do you see that “accounts_opportunities.deleted = 0” bit?  That’s the sort of annoying detail SugarQuery takes care of for you.

Second, it uses $this->focus->account_id. $this->focus is a SugarBean object for the current Case. The Link2 class makes this available to you so you can use field values from current Case in building your query.

Third, notice the SQL we surround our query with. It joins the results of our custom query back to the root query provided in SugarQuery object. A good way to visualize what’s going on here is to think about it this way:

Here’s the plain vanilla query that comes into buildJoinSugarQuery():

You then add to that query via getCustomJoin():

When you apply this technique to your particular situation be careful with the SQL that follows the close parenthesis as it must match the context of the root query.  In our example I deliberately aliased to my_custom_id in the custom SQL to illustrate this need.

The custom SELECT statement you provide can get as long and goofy as you want, but keep in mind database performance impact and potential SQL dialect differences when writing raw SQL. The SELECT I wrote for the custom subpanel in my real world project involved four different SELECTs UNIONed together (don’t ask). Just remember that this query must return only the set of record ids (opportunity ids in this case) that match rows you want to populate the subpanel.

The final Subpanel

The final Subpanel

To get it all to work you need to do another Quick Repair and Rebuild. Once that’s done, bringing up a specific case will reveal the subpanel and it should now only show opportunities which are open and under the same account as the current case.

I also renamed the title of the subpanel to better match what it shows, which is always a good practice.  To do this just change the text as we did in Step 3 above.

You’re Done!

At this point you now have a working subpanel which shows only those rows which match certain criteria you need.  Also, since we can use raw SQL you have a lot of power at your disposal to customize that result set.

How To Do Debug Your SQL

There’s a great deal of flexibility available in this technique.  You can add whatever clauses you want to the table subquery.  You can also use SugarQuery functionality to alter the behavior of the SugarQuery object returned by buildJoinSugarQuery().  And you can combine the two as you wish.  As a result, when you get unexpected results it can be hard to make out exactly what went wrong.  While I was working on my particular subpanel I found it helpful to use SugarQuery‘s compileSql() (Note: deprecated in Sugar 7.7.1 and removed in 7.9.0. Use getSQL() and getParameters() instead) method to print out the actual SQL that was being generated.  That would let me know what was going on.  For example:

That will dump the (sometimes very long) SQL string into sugarcrm.log (or whatever location you previously set for your Sugar log) if your log level is Debug.  Once you format it and sort through it, it should reveal why it’s doing what it’s doing.  If nothing shows up there it’s always helpful to look at your Apache server log to see if there are additional errors in there.



Internal Applications Developer at SugarCRM

14 responses to Creating Subpanels with Custom Results in Sugar 7.5


    This post (clap clap clap)

    dranneysugarcrm July 31, 2015 at 7:50 pm

    A coworker ran into an interesting issue this technique can bring up, so she asked me to post this for her:

    This post is great but ran into an issue recently with deletion. When deleting the main module record, it attempts to delete all of the relationships including this one. Since it doesn’t actually exist, it fails on a “Call to a member function removeAll() on a non-object in data/Link2.php”.

    To fix this, add a delete() function in your custom link class. Since there is nothing to delete, I had it return true and the deletion of the main module record finishes successfully.


    In my module builder custom module, I have been working through the following two articles:
    Which work perfectly to add a flex relate field to a custom module for the purpose of relating to other custom modules. I have gotten the subpanel to display when using the custom/extension proposal in the second article, but it gets overwritten when I redeploy the module.
    There simply MUST be a way to add a custom subpanel in the same way using either the Builds or Packages directory contents, but for the life of me have been unable to find out. I dont want to add a relationship, but need to have this custom subpanel survive redeployment. Any thoughts please?


      Yes, deploying code that you’ve created from a custom module can overwrite changes you’ve made using Studio or in the custom directory. In general, it’s nice to use Module Builder to bootstrap a custom module but eventually you’ll need to manage the contents of this package manually if you are doing anything more than adding a custom module with some basic fields.

      I’d recommend including the custom code / extension with the module loadable package zip file manually. That way all these changes get deployed together safely. You may need to add ‘copy’ directives in your manifest.php within your module to make sure the custom files you include in your module loadable package are installed in the correct location.


    Is all of this needed if we simply need to modify the existing Query used to generate an existing Subpanel?

    dranneysugarcrm January 25, 2016 at 1:30 pm

    I have experimented with overriding the out-of-the-box API call made by an existing subpanel and I did get it to work. However, that approach is not recommended. It’s not necessarily upgrade safe, and it may have unanticipated side effects.

    So, yes, I believe all of this is necessary even if you’re only tweaking an existing subpanel.


    How can we show this custom subpanel to view in mobile view as well?


      I have personally never worked with the mobile platform, but I imagine this ought to work since this all takes place within metadata and backend PHP. You’d need to change the layouts in Step 3 a little by working in the “mobile” platform instead of “base”.


    Can anyone help out how the same functionality can be achieved in sugar 7.9


    It would be really helpful if (along with noting that compileSql is removed), you could inform us how to replace the (also) removed joinRaw() method.


      Hi Richard,

      Theres some more info on a different blog post.

      In particular, you’ll notice some questions in the comments.

      For example, you could replace joinRaw() with something like

      joinTable(‘table’, array(‘join_type’ => ‘LEFT’))


        Hi Matt,

        I did see that, and I think I was overcomplicating it.

        The most difficult thing which would have been helpful to have some elaboration on was the “on” condition. Here’s what I did to get the on condition to be recognised for the sake of others:

        $sugar_query->joinTable(‘destination_table’, $joinParams)->on()
        ->equalsField(‘source_table.source_link_field’, $jta . “.destination_link_field”)
        ->equals($jta . “.destination_link_field”,$variable_you_want_to_limit_by);

        I think this roughly equates to the following join in the Open opps for accounts example above:


        $sugar_query->joinRaw($this->getCustomJoin($options), $joinParams);


        $sugar_query->joinTable(‘accounts_opportunities’, $joinParams)->on()
        ->equalsField(‘’, $jta . “.opportunity_id”)
        ->equals($jta . “.account_id_id”,$this->focus->account_id);

        Thanks for the pointer, and hope the above helps someone!


Trackbacks and Pingbacks:

  1. Customizing the query used for a subpanel for Sugar 6.x « Sugar Developer Blog – SugarCRM - January 26, 2016

    […] This post does not apply to Sugar 7.x.  See an updated blog post for working with custom Sugar 7 […]