Creating a Layout and View for a Module in SugarCRM 7

Since we are completing rewriting SugarChimp for SugarCRM 7 we figured this would be a good opportunity to share how to create a module from scratch. More specifically, in this series we will cover how to create a nice onboarding process for a new user just getting started with the integration. To start, lets create our first layout and view in the new Sidecar framework. We will skip the creation of a bare bones module since that process is still the same in 7.

Like many integrations, SugarChimp requires some configuration upon installation. We want this experience to be as easy and straightforward as possible. To accomplish that goal we will be building a configuration wizard that walks the user through setting the integration. To start, we will take advantage of the built-in routing in 7. Since this is a custom view and not a typical record or list view we will take advantage of the layout route. (NOTE: there is no upgrade-safe or customization-aware way to add your own custom routes yet.) Based on the routes available to us, our desired URL path will be /#SugarChimp/layout/setup. The /layout route is great for your own custom routes.

SugarCRM 7 Layouts

Layouts define the structure of your page. Within a layout you can embed views, fields, and even nested layouts. Layouts can be a great way to reuse previously defined components.

/modules/YOURMODULE/clients/base/layouts/setup/setup.php

In this case, we just want to get something to show up so we keep it simple by referencing a custom view which is defined next...

SugarCRM 7 Views

Views are a big jump from the old view.detail.php/view.edit.php way of doing things. Now you define your js controller and one or more Handlebars templates although you may not necessarily need either. It is important to note that the Sidecar framework utilizes Backbone.js. Backbone.js is a lightweight library that brings a more passive derivative of Model-View-Controller (MVC) to javascript called Model-View-Presenter (MVP). You can learn more about the differences between the two on Martin Fowler's GUI Architectures post.

/modules/YOURMODULE/clients/base/views/setup/setup.js

The “className” is a space separated list of classes that get applied to the container for this view. The contents of that container will be define our template. Sidecar uses Handlebars for its templating system. If you aren't familiar with it yet you will be soon. It's a simple, yet powerful way to dynamically generate HTML on the client side.

/modules/YOURMODULE/clients/base/views/setup/setup.hbs

Once these files are done then run a Quick Repair and Rebuild. In fact, always run a Quick Repair and Rebuild after any .js or .hbs edit. Once that is done hit the /#YOURMODULE/layout/setup URL. You should then see your new layout/view:

The Quick Repair and Rebuild can be a pain in the you-know-what though and can really eat up your time if you use a typical iterative approach to development. I've found that what works best for me is to make my edits in the .js and .hbs and then copy them over to the cache directly. For your js controller, edit and replace in the appropriate place in /cache/api/metadata/metadata_base_private.php. For your hbs template edit /cache/javascript/base/components_{random-guid}.js. This process has took a 5-10 minute edit/refresh process down to just a few seconds. That adds up fast!

On the next post we'll dig more into our controller to create the basis for a configuration wizard. Until then, check out the excellent Sugar Developer Guide 7.1.