Faster Sugar integrations using Building Blocks

What are Sugar Integration Building Blocks?

This is a new effort to create an open source library of re-usable common components that can be easily adapted by developers interested in integrating applications with Sugar 7.  This project is focused on the needs of SugarCRM ISVs and Technology partners that want to build integrations and get them listed on Sugar Exchange quickly and painlessly so they can be offered to Sugar customers.

This new open source project is hosted on Github at https://github.com/sugarcrm/BuildingBlocks and is accepting contributions from the Sugar Developer community.

Watch this project because more and more components and examples will be added in the coming months.

Contextual Frame Dashlet Package

One of the first building blocks is an easy to use iframe dashlet that passes contextual information about the current page to the iframe using URL parameters.  In the current package, the context that is passed is the record id (when there is one) and the module name.  The external endpoint can then use that context to create an appropriate UI to present in the iframe.

This dashlet can be easily used to create a lightweight UI integration with an external application.  It can be deployed as-is for a Proof of Concept or demonstrations or it can be easily customized for additional tailored capability.



It also happens to be a good example of a Dashlet that uses a configuration page in order to manage settings such as the base URL and the frame's height.



Out of the box, we've used httpbin.org  and the //httpbin.org/get endpoint to conveniently show you precisely what arguments get passed via the iframe as part of the request.  In this case, you can see from these details that the request came from a user viewing an Opportunity record.

Building the Dashlet Configuration Page

We will now deconstruct this dashlet a bit in order to better understand how the configuration page shown above works. Note that we have added a namespace prefix to the dashlet which is a good practice for custom packages and custom views installed into base platform to avoid name conflicts.

Dashlet Metadata

xyz_contextual-iframe.php

<?php
/**
* Copyright 2015 SugarCRM Inc.  Licensed by SugarCRM under the Apache 2.0 license.
*/
$viewdefs['base']['view']['xyz_contextual-iframe'] = array(
//Dashlet metadata
'dashlets' => array(
array(
'label' => 'LBL_XYZ_IFRAME_DASHLET_LABEL',
'description' => 'LBL_XYZ_IFRAME_DASHLET_DESCRIPTION',
'config' => array(
// Default config values
'url' => '//httpbin.org/get',
'frameHeight' => '100%',
            ),
'preview' => array(),
'filter' => array(),
        ),
    ),
//View metadata for Dashlet Config page
'config' => array(
'fields' => array(
array(
'name' => 'url',
'label' => 'LBL_XYZ_IFRAME_DASHLET_URL_LABEL',
'type' => 'text',
            ),
array(
'name' => 'frameHeight',
'label' => 'LBL_XYZ_IFRAME_DASHLET_IFRAME_HEIGHT_LABEL',
'type' => 'text',
            ),
        ),
    ),
);

Our dashlet metadata now contains two different sections.  One part is the Dashlet metadata and the other is the View metadata that we will specifically use for our configuration page.

The dashlet config array above is used to define our configuration values as well as their defaults.  This will be used to populate each dashlet's settings.  Each dashlet instance has and maintains it's own settings object that is derived from the config defined in metadata.

The config view metadata contains a standard Sugar fields array that will make it easier for us to define the configuration user interface.

Dashlet JavaScript

xyz_contextual-iframe.js

({
/**
     * Copyright 2015 SugarCRM Inc.  Licensed by SugarCRM under the Apache 2.0 license.
*/
    plugins: ['Dashlet'],

/**
     * Record ID that is in context
*/
    record: undefined,

/**
     * Module used
*/
    moduleName: undefined,

/**
     * Base URL for iFrame (retrieved via config)
*/
    url: undefined,

/**
     * Height for iFrame element
*/
    frameHeight: undefined,

/**
     * Overriding initDashlet to setup values needed to render our contextual dashlet
*/
initDashlet: function(view) {
var ctx = this.context;
var model = ctx.get("model");
if (!_.isEmpty(model)) {
this.record = ctx.get("model").get("id");
        }
this.moduleName = ctx.get("module");
this.url = this.settings.get("url");
this.frameHeight = this.settings.get("frameHeight");
    }

});

The controller here is quite straight forward.  It reads the current context and settings and sets them on the current view object as a convenience for the Handlebars template that we will use to render the iframe.

Multiple Dashlet Templates

dashlet-config.hbs

{{!--
Copyright 2015 SugarCRM Inc.  Licensed by SugarCRM under the Apache 2.0 license.
--}}
<div class="record">
{{#each dashletConfig.config.fields}}
        <div class="row-fluid panel_body">
            <div class="record-cell">
                <div class="record-label">{{str label}}</div>
{{field ../this model=../this.settings template=../this.action}}
            </div>
        </div>
{{/each}}
</div>

xyz_contextual-iframe.hbs
{{!--
Copyright 2015 SugarCRM Inc.  Licensed by SugarCRM under the Apache 2.0 license.
--}}
<iframe frameborder="0" width="100%" height="{{frameHeight}}" src="{{url}}?{{#if record}}&record={{record}}{{/if}}&{{#if moduleName}}moduleName={{moduleName}}{{/if}}"></iframe>

xyz_contextual-iframe.hbs is clearly what you would expect it to be but you may be surprised to see dashlet-config.hbs. When you define a config in your metadata then the Sugar Dashlet framework will rely on the dashlet-config that you provide for your user interface. In this case, our config template relies on Sugar 7 Record CSS and the Handlebars helper called the field helper (defined within sidecar/src/view/hbs-helpers.js) in order to build the Sidecar fields for our user interface seen above. All we need to do is pass it our fields array from the view's metadata and provide it the settings as the base model that these Sidecar fields manipulate. This pattern is handy because it allows you to create a configuration interface that is consistent with core parts of the Sugar 7 UI like the Record view, core dashlets, etc.Click here to access the code and deployable package manifest