Skip navigation
All Places > Developer > Blog > 2017 > November

SugarCRM is on a mission to empower our users to delight their customers. To that end, we are pleased to introduce the first phase of visual restyling, and give some tips on how to work with the new UX.

Our process in developing the new UX

Sugar 7 introduced the Sidecar framework with massive user interface improvements (called SugarUX) and a modernized architecture. Since then, we have been working hard on the next iteration of SugarUX built on the Sidecar framework. Our guiding principles came from our customers and their feedback on Sidecar. A competitive analysis and feedback from customers revealed three concerns; cluttered complicated UX, inefficient unguided layout, and a drab outdated user interface.


The SugarCRM User Experience team (led by Brian Ng) launched a rigorous heuristic evaluation of the web and mobile Sugar products. Issues were identified as we evaluated key use cases and new solutions were documented. This thorough understanding of the product, customers, and the industry has helped us identify which issues to address first.


Dark gray text on light gray background led to poor legibility. Heavy blacks and gray linen added to the dated look and feel.

Sugar Mobile had a dark and drab visual design. Buttons for key actions were positioned differently on key screens.


Establishing Goals

With an understanding of the problems, we set goals for ourselves.

  • Improve design for over 100 usability issues, prioritized by impact to the user's ability to get their job done.
  • Establish a clean and modern visual design language, with rules documented in a style guide.
  • Ensuring our products are accessible by all, meeting Web Content Accessibility Guidelines (WCAG) compliancy.


Guiding Principles for our new Design

We established three design principles: Clear, Consistent and Efficient. These principles guided all of our decision making. Establishing principles helped to resolve differences of opinions and to focus on user frustrations.We determined what colors and fonts would positively affect our use cases and still reflect our brand.



We have adopted Open Sans as the Sugar UX base font. It’s an open source font optimized for web and mobile interfaces with text heavy layouts. It’s known for its open, neutral type shape and friendly appearance. For colors, we have selected a color palette that is friendlier, modern and brighter.


We also selected a set of colors and fonts that would positively affect our use cases and still reflect the SugarCRM brand. Finally, we tested concepts in the real world, with real users in key flows to observe how they played out in practice.



Mobile has a bright appearance and color placed in strategic locations to help users identify groups of information.



  • First revealed at SugarCon to over 1000 attendees where customers gave feedback.
  • A new visual design language, documented in a Style Guide (coming soon), empowering customers and partners to implement SugarUX consistently on our product.
  • Launch of the new SugarUX on our Sugar Mobile apps, available already on the the Apple App Store and Google Play.



Coming in Winter ‘18!


The first phase of our new UX is coming in Winter '18 release and we want to make sure the Sugar Developer community is first to give it a test drive. If you have built any Sidecar components or customizations (Dashlets, custom views or layouts, etc.) then you should verify that they display properly in new UX. As with all code level customizations, it is up to Sugar developers to make sure that you fix your code so that your customizations display properly in the new UX.


From implementation perspective, these changes have been made entirely in CSS where we've adjusted the styling for existing CSS classes. So, areas of concern would be in places where you have overridden the styling for Sugar's core CSS classes or have introduced your own CSS through the use of ./custom/themes/custom.less. The majority of customizations that simply use our existing CSS classes are expected to adopt new styling without errors.


As usual, we will be running an invitation only technical Preview program for the Winter '18 (On-Demand only) release. If you want to make sure that your organization is considered for this preview then please e-mail and mention your interest in test driving the new Sugar UX!


Building your new Skin test plan

We have referred to this effort as the “new skin” because this first phase primarily involves changes to CSS and no significant changes to default HTML structure for any of our Sidecar Components.


How do you make sure your customizations are still pixel perfect? What follows below are some tips for you and your team to build a test plan.


Exploratory Testing

We recommend devoting a fixed amount of time to doing some exploratory testing in order to make sure your customizations look great in the new skin. How much time? It depends on how much UI you have. For example, it should not take you longer than a few minutes to test a custom Dashlet and uncover any bugs that you may want to address.


Guidelines for Testers

If you are testing, what are you looking for? Here are some tips.

  • Customizations only. Testing should focus on customizations that your team created.
  • CSS overrides. If you use a ./custom/themes/custom.less file or include your own CSS files, then you’ll need to pay special attention to these changes since they will likely need to be updated.
  • Scrolling. Are you able to scroll and are there things that are inaccessible even with scrolling?
  • Ellipsifying. When you shrink the window size down or reduce the available space for data on custom list views, record views, etc, do they ellipsify and show tooltips on hover?
  • Responsiveness. Resizing the browser window or switching to and from responsive-mode. Observe what happens to elements on page.
  • Orientation on tablets. Alternating display orientation between landscape and portrait modes.
  • Toggle things. Open/close drawers, menus, edit and detail mode on record views, etc.
  • Settings. Change system and profile settings that may alter how things look like date/time format, currency, etc.


Comparisons with out of the box Sugar

This post includes some example screenshots of what the new skin looks like out of the box. Comparing your customizations to the out of the box look and feel will help you identify things that you may need to change in your customizations. We encourage testers to keep two windows open while testing to compare the out of the box behavior in one window with your customizations in another window more easily.

We’re getting a head start on our New Year’s Resolutions!  We’ve given our developer community a fresh, new look, and we feel ten pounds lighter.  Let me give you a tour!


First, we’ve migrated our blog from to the Developer Community at  We’re really excited about this change as the community is now your one-stop-shop for everything related to developing on Sugar.  We’ll temporarily be putting new posts on both blogs, but please update your bookmarks now.


Second, we’ve redesigned the Developer Community to feel more modern and make it easier to find content.  

When you navigate to the community’s home page, you’ll notice 4 new buttons at the top:

Home page buttons


If you’re new to developing on Sugar (or you just need a refresher), click Getting Started with Sugar.  On this page you’ll learn how to get setup, trained, and certified.  You’ll also learn how to integrate with and create add-ons for Sugar.

Getting Started


If you want to leverage the Sugar Mobile Application Configuration Service or our Mobile SDK, click Getting Started with Mobile.  This subspace has its own documentation as well as a place for you to ask and answer questions.  If you’re a mobile developer, you’ll definitely want to follow the Mobile Developers space.


If you’re feeling helpful, click Answer a Question to browse questions from your fellow community members and share your expertise.


If you want to learn something new, click Try a Tutorial.  You’ll be able to get your hands in the code on a variety of topics including the REST API, Advanced Workflow, the Mobile SDK, and Quotes.



If you continue scrolling down the home page, you’ll see Recent Activity with all of the latest community content as well as a form where you can sign up for Developer News to receive the latest Sugar Developer news, webinars, and surveys straight to your e-mail inbox (I highly recommend signing up if you haven’t already!).


If you browse the home page’s right column, you’ll see a set of helpful widgets.  At the top, you’ll find a search box where you can search the developer community.  Next, you’ll see our latest Tweets (you may want to follow us on Twitter if you haven’t already).  If you continue scrolling, you’ll find the Developer Tools widget.  This is one of my favorite pieces of the community as it has all of our favorite resources listed in one place!

Developer Tools Widget


Be sure to check out the last widget:  Top Participants.  We hope to see your name there!


We hope you enjoy our new look!  Have suggestions on how we can improve the community?  Let us know in the comments below!

In Sugar 8 / Spring '18, Sugar administrators can now configure API platforms using the Administration panel. The Platform extension is still available if you want to register a custom API platform as part of a Module Loadable Package.

Sugar uses platforms to support the needs of multiple Sugar clients.  The Sugar REST API uses the platform parameter to indicate which platform is being used.  If you’d like a refresher on what the platform parameter is and how to use it, check out this blog post.  In Sugar 7.9, we added a new Platform extension that we advised developers to start using in the Sugar 7.9 Migration Guide.  The Platform extension allows you to indicate a particular custom platform should be allowed when the disable_unknown_platforms configuration setting is on.


Changes coming in Winter '18 release

In the Winter '18 release, we will be preventing REST API access to Sugar from unknown platform types. Sugar has a configuration setting disable_unknown_platforms that controls whether or not unregistered platforms are allowed to be used when logging in using the REST API. The current default value for disable_unknown_platforms is false. In the Winter '18 release, we will be changing the default to true, which is how it is already reflected in the documentation. If your integration uses a custom platform, this custom platform will need to be registered in each Sugar instance or your integration will break!


How do I know if I'm affected? New

In order to avoid conflicting with end-user sessions, some REST API integrations specify a different “platform” during login. Developers have often employed this technique to prevent integrations from interrupting or conflicting with active end-user sessions.


Below is an example of a login request that uses a custom platform:


POST /rest/v10/oauth2/token
  "platform":"<SOME VALUE>"


Registering a new platform for an integration


Integrations must register any custom platforms they plan to use. For compatibility with Sugar On-Demand, we recommend creating a Module Loadable package that includes a simple Platform extension.


./custom/Extension/application/Ext/Platforms/<integration name>.php



* A valid platform name requires:

* - Max length of 127 characters

* - Valid characters are: a-z, A-Z, 0-9 - (hypen) _ (underscore)


$platforms[] = '<integration platform name>';

We recognize that is a change in assumption since it involves an installation of a package where previously no package had to be installed at all. We are working on an alternative approach as we roll out additional Identity Management (IdM) functionality that would allow for more convenient configuration of integrations.


Example Module Loadable Package

An example module loadable package has been added to the UnCon github repository. This package can be used as a template for those needing help understanding how to construct a package that will enable their API integration.

Are you ready to build an integration with Sugar but not sure where to start?  You've come to the right place!


When you want to access or interact with information stored in Sugar, the REST API is a great place to start.  In this tutorial, you'll learn how to authenticate to the Sugar REST API.  Then you'll learn how to perform create, read, update, and delete (aka CRUD) operations.


Watch the video tutorial below or view the text-based tutorial at


Have you ever found yourself wishing you could create a custom Sidecar user interface within your Sugar instance? Maybe you want to allow users to visit a URL that displays a custom view.


It turns out that creating a linkable URL (or route) to within the Sugar client is fairly simple. In this post, I'll walk you through how to implement a new route in your Sugar instance that displays an alert.


What is a Route?


Sidecar utilizes the Backbone Router as the method for controlling client-side navigation within the Sugar application. The Router will take the current URL in the browser (the route) and call the appropriate callback function.  The callback could do something like display an alert or load a Sidecar Layout or View.  The Router will pass information included in the route like a module name and a record identifier to the callback function.


Most of the routes are already set up for you. For example, visiting a Sugar instance URL that ends with "#Home" will load the default dashboard layout. Visiting a URL that ends with "#Accounts/<id>" will load the Account record view for the record with the appropriate identifier.


Creating your own route


When you decide to create your own route, the first thing you'll want to do is decide what your custom route should be. In this example, we'll use "helloWorld" as our custom route, meaning that the full URL will be http://yourSugarInstance/#helloWorld.


Next, you need to decide what should happen when someone accesses the route. Let's display an alert message that says, "Hello, fabulous person!"


Now that we know what we want to do, it's time to code!


Create a new file in your Sugar directory:  ./custom/javascript/customRoutes.js:"router:init", function(){
    //Register the route #helloWorld
    SUGAR.App.router.route("helloWorld", "Hello World", function() {'message-id', {
            level: 'info',
            messages: 'Hello, fabulous person!',
            autoClose: false


This code registers the custom "helloWorld" route during the "router:init" event.  This code could exist in a file with any name at any location.


The next thing we need to do is create a JSGrouping extension that will tell Sugar we have created custom routes.


Create a new file in your Sugar directory: ./custom/Extension/application/Ext/JSGroupings/myCustomRoutes.php:

foreach ($js_groupings as $key => $groupings) {
    $target = current(array_values($groupings));
    //if the target grouping is found
    if ($target == 'include/javascript/sugar_grp7.min.js') {
        //append the custom JavaScript file
        $js_groupings[$key]['custom/javascript/customRoutes.js'] = 'include/javascript/sugar_grp7.min.js';


Before we can try our custom route, we need to run Quick Repair.  Login to Sugar as an administrative user and navigate to Administration > Repair > Quick Repair and Rebuild.


Now we're ready to test.  Navigate to http://yourSugarInstance/#helloWorld.  Unless you missed a step, the alert you created will appear!Note:  you may need to refresh the page once to pull in the updated JavaScript in order for the alert to appear. It's a good idea to disable your browser cache when doing JavaScript development too.


If you want to take things a step further and display an iframe for a custom route as seen in the screenshot below, check out the Canvas IFrame Building Block example.


For more detailed information on creating custom routes including how to designate new route patterns, see the Developer Guide.