Custom Widgets

This feature allows you to create custom user interface objects that you can then use within your dashboards, dashlets, workspaces, or even floating panels.

Out-of-the-box FreeAgent CRM provides a wide range of Widgets ready to use such as diverse chart types, email, phone, meeting widgets, and many more.  Check the widget library for the full list.

User Permissions: Only Administrators can create Custom Widgets.

Navigate to Custom Widgets

Open the menu and navigate to Settings > Advanced > Custom Widgets.  You can also use the search function to get there faster, start typing 'Custom Widgets'.

Create a Custom Widget

To create a new Custom Widget, click the 'Add Custom Widget' button. 

1. Name

Required. Give your Widget a name. 

2. Icon

Choose an icon for your widget.

3. Type

There are three types to choose from.

Fusion Charts

If you're using Fusion Charts you can include them in custom widgets. As soon as you select Fusion Charts as your widget type the Configuration screen will adjust to ask for the needed information. You will need to define the Data Source. 

iFrame

For iFrames, you will have to specify the URL, the integration it belongs to, and any additional parameters required.

These widgets show content from an external website. This website will need to communicate with FreeAgent using the FreeAgent Applet Library. Using the Applet Library, the external website will be able to query and modify your FreeAgent tenant.

React

Use React to create custom components that can be displayed in a widget. See further below for an example.

4. Placement

There are various options for widget placement. Some of the options will change based on the type of widget you're creating. You can select one or all of the options available for placement. 

5. Properties

Can be used to define additional parameters for your Widget. It allows admins to add extra fields in the widget create/edit modal. Those values will be sent to the custom widget code.

How to create an iFrame Widget

Add FAClient initialization to Website

In order for the website to properly show up as an iFrame on FreeAgent, it must initialize an instance of FAAppletClient defined in the Applet Library. Use the following code to do so.

import { FAAppletClient, params } from"[PATH TO APPLET LIBRARY]";
const FAClient = new FAAppletClient({ appletId: params.appletId });

Create iFrame Custom Widget

Navigate to the custom widgets page on FreeAgent. To do this, you must be an admin. Open the navbar then Admin Settings -> User Interface -> Custom Widgets. Click the “Add Custom Widget” button on the top right. A form will appear.

On this form, to create an iFrame widget, select iFrame for the “Type” field. Then add the URL of the external website to the “URL” Field under “Configuration”. Optionally, parameters can be added in JSON format to the “Params” field. These parameters will be passed to the external website in the “params” variable from the code in step 1.

After hitting save and, depending on what the “Placement” field was set to, the widget can be shown in a floating panel, dashboard, dashlet, or workspace. If an issue is encountered when trying to show the widget, try clicking the browser refresh button and trying again.

React

These widgets use FreeAgent react components to create a custom component that can be rendered as a widget. Check ReactCustomCodeRenderer.js to see which components are available and add some if necessary. Instead of initializing an instance of FAAppletClient, react widgets are passed “context.clientAPI”, which is functionally identical. 

To create a react widget, click Add Custom Widget on the Custom Widgets page. Then select the React type. The Custom Component field is the custom code that will define the React component that you are creating. It contains a function that should return a React component to be rendered. 

The parameters passed to it are applet, React, and context. applet contains the applet information as well as the values that the properties are set to. React widgets use properties (like the Fusion chart widgets) to set a custom configuration. See below for an example pulled from a Fusion Chart widget

The React variable allows you to use all the functions of the React library. Context contains two important properties. context.components are all the FA components that are available to the applet, and context.clientAPI is the FAAppletClient equivalent for React widgets. 

Available API's

Create an instance of the FAAppletClient using the below code.

import { FAAppletClient, params } from"[PATH TO APPLET LIBRARY]";
const FAClient = new FAAppletClient({ appletId: params.appletId });

FAClient will have the below APIs available to it. Each one will take one parameter “payload”, a JSON object, if necessary.

const payload = {
  entity:"employee"
};
FAClient.listEntityValues(payload);

Event Listeners

Using the FAAppletClient, event listeners can also be created using the following code.

import { FAAppletClient, params } from"[PATH TO APPLET LIBRARY]";
const FAClient = new FAAppletClient({ appletId: params.appletId });
FAClient.on("[EVENT NAME]", [SOME FUNCTION]);

Using the .on() function, event listeners can be created that respond to events from app actions, and some default events listed below.