Incorporating Widgets into the App

Web Toolkit IDE

The Platform comes with a built-in IDE for developing and managing Page and Extension Widgets. The widget design supports a view/controller paradigm which is reflected in the tabs used to input HTML, CSS and Javascript.

Use the HTML tab for both standard HTML as well as BPUI tag library development.

 

The Javascript tab is used for program logic and to bind data objects to HTML and BPUI tag Elements.

 

Use the CSS tab to organize CSS classes referenced in HTML.

Preview your work in the “Preview” tab while in Edit mode.

For debugging you can use the browser’s standard development tools to look at console output, javascript errors, etc.

Page Widgets

Page Widgets are widgets that are used to override different areas of the application. These can come in the form of a modal or view override or a node or domain override.

Modal Overrides

A modal or view override is to the ability to override the following four standard application modes:

  • Record: the read-only view of a selected record invoked by default when a record is selected from a list.
  • Edit: The Record in Edit mode invoked by clicking the “Edit” button.
  • New: Mode for creating a new record invoked by clicking the “New” button.

 

To override a standard mode for a particular Entity, navigate to Setup>Develop>Entities and select the Entity for whose Mode you wish to Override. Under the Selected Entity, choose the “Buttons and Actions” element in the left hand menu.

Here you wll see a list of Modes and Buttons that are available for customization. Select the mode you wish to override or select “New” to create a new Button or Action. In the screenshot below, we have selected to override the “Edit” button in the Invoice Entity with a widget called “InvoiceEdit”.

Here we can also specify additional filter criteria for when this override will take effect as well as criteria logic for grouping. We can also further limit the invocation of the widget to certain Roles under the Security sub-menu.


Custom Buttons and Actions

The standard button bar for a given node comes with the modal buttons mentioned above (“Edit”, “New”) as well as an Action menu that will appear when there are standard or custom “Actions” defined for a particular Entity. You can define custom buttons or actions that will surface a custom page widget when selected using the “Buttons and Actions” tool under the selected “Entities” menu item as described above. TO create a new Button or Action, select “New” in the Buttons and Actions area.

In the screenshot above, we are creating a new action menu option for the Invoice Entity that allows the user with the “BRM_ACCOUNT_ADMIN” role to create an invoice on the fly, manually. This option would manifest in the Invoice action menu as the screenshot below depicts:



If the “Button” option were chosen when creating the new “Button or Action”, the option would manifest as a button as the screenshot below depicts.



When your custom button or action is selected or clicked, the widget will display in the detail section of the Entity node where it is defined as follows:

 

Node Overrides

You can choose to override an entire Entity Node with a Page Widget, replacing all standard, UI features and functionality. these features include List view, Record View, Edit, New, Actions, Search, and Dashboards. This selection will not influence the API for the selected Entity and all Workflow and validation rules defined for the selected Entity will remain active regardless of the override.

To override an Entity’s UI completely navigate to Setup>Develop>Entities and select “Edit” for the Entity of interest.

Select the Page widget form the “Page” Lookup and click “Submit”. 

Now when you navigate to the Invoice Entity node the InvoiceEdit widget will display without list, search or record buttons.

 

Extension Widgets

Extension widgets are intended to “extend” the functionality of the standard User Interface. Use an extension widget to present a google map representation of an account’s address or embed a chart or graph of customer product usage into the standard page. You can also use Extension Widgets to alter or introduce processing before and after the standard Submit and Delete actions by inserting toolkit code into the Delete and Submit buttons.

For example, you could call an address verification API to validate that an address exists before saving the account record, interrupting the standard submit function with an error if the address verification fails. You could also leverage an extension widget to call an external service notifying them of the deletion of a record for a real-time integration triggered by the user deletes records via the UI.

Standard Page Layout

You can add enriched functionality to standard, BillingPlatform pages by embedding custom, Extension Widgets to the detail, Edit or New Page Layout for a given Entity. Once you have created your Extension Widget, add it to an Entity Page Layout by going to Setup>Develop>Entity and selecting an Entity. Click the Fields Node and then Click “New”.



Choose the “EXTENSION_WIDGET” data type and look up your widget in the “Extension Widget” lookup field.

The following are a list of attributes and definitions that will influence the behavior and/or display of your widget.

 

Attribute

Description

Active

ACTIVE  will render the Widget on the Page. DEACTIVATED will Hide the Widget.

Visible

Determines if the Widget is Visible or not. It is possible to add a Widget that is pure Javascript without any display in which case you would uncheck the “Visible” flag.

Column Span

The BP UI renders in a two-column layout to support Controls with Labels. Choose “1” to display the Widget with its associated Label in a two-column layout. Choose “2” to span both label and value columns with the output of your widget.

Height

Used to specify the allowable height of your widget.

Scrollable

Used to set whether scrollbars will appear if your widget exceeds the specified Height.

Display Mode

There are three Display modes for the selected record view: New/Copy, Edit, and Detail. Select which modes are relevant for your Widget to display in. Remember that the Submit function does not necessarily apply to your widget.

Display After

This allows you to position the Widget after a particular field or at the top of the form.

Role Permissions

Aw with other fields, this setting will control which Roles will be able to see the Widget.

 

Fill in the appropriate widget settings and save. Below is an example of a google map placed on the Standard, Account Page Layout:

 

Submit and Delete Button Overrides

The platform provides the ability to add additional processing and control over submit and delete actions in the Standard UI using extension widgets. For review, submit and delete functions can be overridden using a specific javascript syntax as depicted in the following example:

BPActions.overrideSubmitButton({beforeSubmit:function () {

   /** Your Before Submit Code Goes Here **/

},afterSubmit:function () {

   /** Your After Submit Code Goes Here **/

}})

 

This Javascript is added to an Extension Widget and will be referenced when added to a specific Entity. To override the submit button with an Extension Widget,

 

General HTML Tag and Attribute Support

The toolkit is designed to work with standard HTML elements such that a blend of HTML, BPUI Tags and Javascript can be leveraged to create the most optimal User Interface components possible.

HTML Elements

The following HTML elements are supported:

a abbr address area article aside audio b base bdi bdo big blockquote body br button canvas caption cite code col colgroup data datalist dd del details dfn dialog div dl dt em embed fieldset figcaption figure footer form h1 h2 h3 h4 h5 h6 head header hr html i iframe img input ins kbd keygen label legend li link
main map mark menu menuitem meta meter nav noscript object ol optgroup option output p param picture pre progress q rp rt ruby s samp script section select small source span strong style sub summary sup table tbody td textarea tfoot th thead time title tr track u ul var video wbr

SVG elements

The following SVG elements are supported:

circle clipPath defs ellipse g line linearGradient mask path pattern polygon polyline radialGradient rect stop svg text tspan

Attributes and the Toolkit HTML

The toolkit supports all data-* and aria-* attributes as well as every attribute in the following lists.

Note: In alignment with the ReactJs library, attributes are camel-cased and the attributes class and for are className and htmlFor, respectively, to match the DOM API specification.

BPUI representation of HTML Attributes

The BP Toolkit is implemented on the JSX framework. JSX attribute names are camelCase versions of the standard HTML attribute names and in some cases substitutions for the attribute names. ex: “className” replaces the standard “class” attribute. Following is a list of JSX attributes to be used in widget extensions and pages:

accept acceptCharset accessKey action allowFullScreen allowTransparency alt async autoComplete autoFocus autoPlay cellPadding cellSpacing charSet checked classID className colSpan cols content contentEditable contextMenu controls coords crossOrigin data dateTime defer dir disabled download draggable encType form formAction formEncType formMethod formNoValidate formTarget frameBorder headers height hidden high href hrefLang htmlFor httpEquiv icon id label lang list loop low manifest marginHeight marginWidth max maxLength media mediaGroup method min multiple muted name noValidate open optimum pattern placeholder poster preload radioGroup readOnly rel required role rowSpan rows sandbox scope scoped scrolling seamless selected shape size sizes span spellCheck src srcDoc srcSet start step style tabIndex target title type useMap value width wmode

In addition, the following non-standard attributes are supported:

  • autoCapitalize autoCorrect for Mobile Safari.
  • property for Open Graph meta tags.
  • itemProp itemScope itemType itemRef itemID for HTML5 microdata.
  • unselectable for Internet Explorer.

There is also the React-specific attribute dangerouslySetInnerHTML (more here), used for directly inserting HTML strings into a component.

 

BPUI representation of SVG Attribute

The BP Toolkit is implemented on the JSX framework. JSX attribute names are camelCase versions of the standard SVG attribute names and in some cases substitutions for the attribute names. Following is a list of JSX attributes to be used in widget extensions and pages:

clipPath cx cy d dx dy fill fillOpacity fontFamily fontSize fx fy gradientTransform gradientUnits markerEnd markerMid markerStart offset opacity patternContentUnits patternUnits points preserveAspectRatio r rx ry
spreadMethod stopColor stopOpacity stroke strokeDasharray strokeLinecap strokeOpacity strokeWidth textAnchor transform version viewBox x1 x2 x y1 y2 y

 

React DOM Differences

  • All DOM properties and attributes (including event handlers) should be camelCased to be consistent with standard JavaScript style. ReactJS intentionally breaks with the spec here since the spec is inconsistent. However, data-* and aria-* attributes conform to the specs and should be lower-cased only.
  • The style attribute accepts a JavaScript object with camelCased properties rather than a CSS string. This is consistent with the DOM style JavaScript property, is more efficient, and prevents XSS security holes.
  • All event objects conform to the W3C spec, and all events (including submit) bubble correctly per the W3C spec. See ReactJS Event System for more details.
  • The onChange event behaves as you would expect it to: whenever a form field is changed this event is fired rather than inconsistently on blur. We intentionally break from existing browser behavior because onChange is a misnomer for its behavior and React relies on this event to react to user input in real time. See Forms for more details
Have more questions? Submit a request

Comments

Powered by Zendesk