PERSCOM.io offers powerful widgets that allow the integration of your organizational data into another website for display. Each widget is a snippet of HTML that can be injected into your website.
Choosing The Widget
Each widget uses the same HTML code snippet to display the data. However, to set which widget you would like outputted, you must set the
data-widget attribute to the intended Widget ID. The available options are listed below.
The following widgets are currently available. Each widget is identified by a Widget ID that is passed to the
Authentication and Authorization
Each widget requires the creation of an API key. Generating an API key is a simple process that can be accomplished in your Dashboard. Creation and management of API keys requires the
manage:api permission. Contact your account administrator if you cannot access the API section within your Dashboard.
Depending on the widget you intend to display, the API key will need specific scopes assigned. You can visit the individual widget page for a list of the required API key scopes needed to properly display the widget.
Second, each widget requires your PERSCOM ID which can be found in the general settings area of your Dashboard.
These two items will be inserted into the widget when you add them to your website. Failure to add these values with result in an authentication error when viewing the widget.
Click here for more documentation on the API.
The widget accepts several options to customize the output of the data.
|apikey||yes||string||The API key used to authenticate the request.|
|limit||no||integer||Adding the limit option will control how many results are returned from the widget. By default, the widget will return 15 results. When morethan 15 results are present, the table will be presented with a pagination option. Increase or decrease the limit to fit your website needs.|
|perscomid||yes||integer||The ID of your PERSCOM.io account used to authenticate the request.|
|resource||no||integer||The ID of a specific resource that will be returned such as a specific form. The API key used to authenticate the request.|
|timezone||no||string||The timezone any date object should be translated to. The ID of a specific resource that will be returned such as a specific form. The API key used to authenticate the request.|
|widget||no||string||The ID of the widget you would like to output. The ID of a specific resource that will be returned such as a specific form. The API key used to authenticate the request.|
Including An Option
Each option must be prefixed with
data- within the HTML snippet. For example, to specify the
apikey option, the parameter must be set as
data-apikey="xxx". See Choosing The Widget for an example.
The widgets are embedded within an
iframe HTML element that prevents the host website from overriding and altering the styling of the widget. While this may seem like a disadvantage, it helps prevent the unwanted style changes to the widget that can happen by the hosting website. However, the widget is wrapped in a parent div that may be customized to alter how the
iframe is embedded within your website. See the example below on how to customize the
In the following example, we are going to adjust the height of the parent div to fit the widget appropriately. The CSS is added just above the code snippet for it to take affect.
Externally Accessing The Widget
The PERSCOM.io widget can be accessed outside of the HTML code snippet that you used to post within your website. To see your widget live, without embedding it in a website, you can visit the URL's below. Make sure to set APIKEY and PERSCOMID to the correct values.
The PERSCOM.io Widget project is open source and actively looking for developers to participate. If you have experience with frontend frameworks such as React, we encourage you to contribute.
You can view the project on Github.