Introduction
GridBuddy is a highly configurable application for managing and editing data in Salesforce.com. Requirements that fall outside of out-of-box behavior can be easily met with GridBuddy’s robust extension capabilities via GridBuddy’s JavaScript and CSS integration API. This can be used to create highly tailored experiences, from small changes like hiding buttons, to more complex changes like querying the back-end for information and then constructing custom validation rules that are enforced on the front-end. This document outlines steps for creating and integrating extensions in your GridBuddy instance.
Various extensions and actions are available for you to use in GridBuddy. Each article will include a note that clarifies whether the code requires modification or if it is ready to use as-is. Please note that for every custom code component you create, a new GB Global Meta record gets created.
Creating Extensions
Extensions can be integrated in Grid Wizard > Manage Extensions (called ‘Manage Custom Code’ in versions prior to 7.0) from the Grid Wizard landing page:
Here, CSS and JavaScript components can be defined using the text editor on the screen. The extension modules can either be standalone CSS or JavaScript snippets which you would apply on a grid-by-Grid basis, or they can be defined as Global CSS and Global JavaScript (which are automatically inherited by all grids).
Once a standalone extension component has been defined, it can be applied to any grid by going to Step 1 of the Grid Wizard and adding the extension component to the “Selected CSS” or “Selected JavaScript” section.
Note: When multiple extensions components are applied to a single grid, they will trigger in the order in which they are applied to the grid, from top to bottom.
Developing & Deploying Extensions
A recommended best practice is to develop extensions in a Sandbox environment. This is especially true for more complex extensions, and if the extension involves additional components such as Visualforce pages or Apex classes. Once the extension is ready to be deployed, create a Change Set that includes all the custom resources, and then deploy the Change Set to the production org.
Developing Your Own Extensions: Grid Front-End Architecture
For development-savvy organizations, this section outlines the grid’s front end architecture that can be manipulated through the extensions framework.
The Grid is rendered primarily using JavaScript with the help of jQuery (since GridBuddy version 3.39, GridBuddy uses jQuery version 1.11.2). jQuery can be accessed using the jQuery or jq namespace.
There are certain GridBuddy global JavaScript variables and objects that are available to use for customizations and that provide access to the grid meta data and record data. These global objects can be manipulated before the Grid is done rendering to affect the display of existing records. There are also strategies for manipulating new records that appear after the Grid has loaded (for example, when creating new data).
JavaScript and CSS changes should take advantage of the various selectors available throughout the Grid, for maintenance purposes. For example (this is not an exhaustive list):
- Grid data rows (tr tag) have the class “dr”, short for data row
- Grid data rows (tr tag) for new records have the class “nr”, short for new row
- Grid data rows (tr tag) have an “id” attribute populated with the Salesforce record id
- Grid header and data columns (td) have a dynamic name attribute corresponding to the field’s order within the row. This name value corresponds to a property available in one of the GridBuddy global JavaScript objects (MetaCol) that exposes the Grid’s meta data.
- Related sections are wrapped in a row (tr tag) with the class “cr”, short for child row
- Related data rows (tr tag) are wrapped in a table with the class “childTable”, and a dynamic name attribute corresponds to the order of the child object amongst all child objects on the grid
- There are classes specific to data type widgets and more.
Main GridBuddy JavaScript Objects
Grid Info
Every object on the grid, whether parent or child, has an equivalent GridInfo object created for it. It contains the object’s metadata needed for various grid functions, including CRUD access, list of fields represented as MetaCol objects, etc.
Some commonly used properties on a GridInfo instance:
- gridName - object label
- fullyQualifiedObjectName - gridbuddy formatted object API name including the foreign key to the parent, in case the object is a child, unrelated, or junction
- gridApiName - object API name
- metaColumns - array list of MetaCol objects for this object
- isParentInfo - returns true if the gridId property is ‘p’
- objId - identifier for the object’s table names
- isDeletable
- isCreatable
- isUpdateable
MetaCol
Every field on the grid has an equivalent MetaCol object created for it. It contains the field’s metadata, including CRUD access, identifier information, data type functions, etc.
Some commonly used properties and functions on a MetaCol instance:
- colIndex
- fieldName - API name
- fieldLabel - label
- fieldId - used on the name attribute of cells (TDs)
- colDataType
- readOnly
- createable
- updateable
- summaryType
- aggregable
- isTypeID()
- isTypeBoolean()
- isTypeText()
- isTypeTextArea()
- isTypeURL()
- isTypeMultiPicklist()
- isTypeSinglePicklist()
- isTypePicklist()
- isTypeCurrency()
- isTypeDouble()
- isTypeInteger()
- isTypePercent()
- isTypeEmail()
- isTypePhone()
- isTypeDate()
- isTypeDateTime()
- isTypeReference()
- isRecordTypeField()
- isReadOnly() - returns true if grid and field are read-only
Common Global JavaScript Variables
|
Variable |
Type |
Description |
|
currentLocale |
String |
Locale code, empty if US |
|
filteringByParent |
Boolean |
Indicates if the grid is being filtered by the parent ID. If true there will be an ID URL parameter, and the grid will hide the parent record and only show the related records. |
|
filterParentField |
String |
If the grid is being filtered by fpf / fpv parameters, this indicates the field API name that’s part of the filter |
|
ownerId |
String |
ID of the current User. |
|
multiCurrency |
Boolean |
Indicates if the org has multi-currency enabled. |
|
sId |
String |
Session ID |
|
localeDigitSep |
String |
The thousands separator character based on the locale. |
|
localeDecimalSep |
String |
The decimal separator character based on the locale. |
|
gridInfoMap
|
Object (Map) |
Holds a map of GridInfo objects, where the key is the object key and value is the GridInfo object instance. The object key is:
p = parent object 1-4 = related (child) object in sequential order |
|
profileId |
String |
18-character user’s profile ID |
|
profileId15Char |
String |
15-character user’s profile ID |
|
userId |
String |
User’s ID (since v4.10) |
Common JavaScript Functions
|
Function |
Return Type |
Description |
|
getDataTable(pTableName) |
jQuery object |
Returns the table with the specified name as a jQuery object |
|
getFirstDataRow(pDataTable)
|
jQuery object |
Returns the first data row of the table, versus the first row which might be the header. |
|
getParentGridInfo()
|
GridInfo |
Returns the GridInfo object for the parent object |
|
getChildGridInfo(objectName)
|
GridInfo |
Gets the child GridInfo object based on the specified object API name. |
|
getRowId(pCellElement) |
String |
Returns the Id attribute of the row the specified cell belongs to |
|
isFieldCell(pCellName) |
Boolean |
Returns true if the spcified cell is a field cell, as opposed to the “select” cell or last column cell which is a filler |
|
getMetaCol(pJqueryElem, pGridInfo)
|
MetaCol |
Finds the MetaCol object corresponding to a field on the grid using the specified jquery element (pJqueryElem), which should be an element within a cell (TD), and the GridInfo object to which the field belongs. |
|
getMetaColByCellName(pCellName, pGridInfo) |
MetaCol |
Finds the MetaCol using the cell’s (TD) name and GridInfo |
|
getMetaColByColIdx(pGridInfo, metaColIdx) |
MetaCol |
Finds the MetaCol based on the GridInfo and specified column index |
|
getMetaColByFieldName(pGridInfo, fieldName) |
MetaCol |
Finds the MetaCol based on the GridInfo and field’s API name |
|
getGridInfo(pJqueryElem)
|
GridInfo |
Finds the GridInfo object using the specified jquery element, which should be within the object’s table |
|
getGridInfoByName(gridTableName)
|
GridInfo |
Finds the GridInfo object using the object’s table’s name attribute, which is mapped to GridInfo’s objId attribute. |
|
getGridInfoByApiName(objectApiName)
|
GridInfo |
Finds the GridInfo object using the object’s API name, which is mapped to the GridInfo’s gridApiName attribute. |
|
GBRowHelper.getParentCol(jQueryElem)
|
jQuery object |
Finds the enclosing parent cell (TD). |
|
GBRowHelper.getParentRow(jQueryElem)
|
jQuery object |
Finds the enclosing parent row (TR). |
|
GBRowHelper.getParentRowForChildRow(childRow)
|
jQuery object |
Finds the parent object row (TR) for the given related child row (TR). |
|
GBRowHelper.getParentTable(jQueryElem)
|
jQuery object |
Finds the enclosing parent table. |
|
GBHelpers.getParamValue(paramName) |
String |
Finds the value of the URL parameter name, or blank if the parameter isn’t present. |
