In this article, you will find all there is to know about custom widgets and how to create and utilise them within your Happeo intranet
Table of contents
- What are custom widgets and what are their use cases?
- How do custom widgets work?
- How to create a custom widget
- What happens if you disable or delete a custom widget that has already been added to a Page?
- Why are custom widgets only accessible to administrators?
What are custom widgets and what are their use cases?
Custom widgets are widgets within Pages that allow users (admins) to add third-party applications that integrate with Happeo.
- An example of an application includes a website that can communicate with Happeo and fetch information from Happeo.
A platform admin can choose to create a custom widget if they wish to refrain from all security that, for example, the iframe widget holds with regards to being secured in a sandboxed environment.
- With this, it is important to note that a custom widget is an insecure iframe that is not secured in a sandboxed environment to allow certain webpages to access Happeo that would otherwise not be possible through the iframe widget.
- If you would like to learn about some use cases for the custom widgets you can visit this link.
How do custom widgets work?
Below you will find information about the way custom widgets work, how to create a website that can communicate with Happeo and how that communication should be established:
- Custom widgets are given a unique ID which is required in communication
- Custom widgets can be located wherever but need to have a fixed URL that is combined with the ID to ensure secure communication
- Like any other iframe, custom widgets use the postMessage to send messages to the parent (e.g., Happeo)
- Message origin and ID is verified against allowed IDs and sources
- All custom widgets get allowed scopes
- All custom widget activities are recorded
As an example of how custom widgets are loaded in Happeo:
How to create a custom widget
To create a custom widget you must be the platform admin or have admin rights.
With this in place, you can navigate to the Admin settings by clicking on the avatar on the top, right-hand side of the menu and then click on “Custom widgets”.
From there, you can click on “Add custom widget” which will direct you to the Custom widgets creation page.
You can then proceed to add the widget name and enter the widget URL. To ensure that the URL works, please note the following:
The workability of the URL you wish to add depends on the server hosting the domain. For example, that domain might have some security settings in place that could prevent the page from loading in:
- Any sandboxed iframes
- Iframes secured with different sandbox attributes
- Any kind of iframes
To test if the URL will indeed be displayed in the custom widget you can navigate to this link, remove everything in the field and enter the following:
<iframe src="https://www.[your domain]" title="[your domain title]"></iframe>
From there, click on “Run” in the top, left menu and if the URL you entered appears on the right-hand preview, it will also work as a custom widget URL in Happeo. If, however, the URL preview does not appear, it will also not work as a custom widget URL in Happeo.
- It is also important to note that when you type the URL into the custom widget URL field, “https://” must be added before the domain. For example, instead of “hs.fi” or “www.hs.fi”, it should be “https://hs.fi” or “https://www.hs.fi”.
Additionally, if you enter the URL incorrectly in any other way than what was presented above (such as a spelling error), you will be notified of it in the custom widget preview.
With regards to the email address scope, when this is selected, the domain which is added as a custom widget URL can fetch the email address associated with the Happeo account that is accessing the specific Page in which the custom widget resides.
- For example, an admin has created a custom widget with “hs.fi” as the custom widget URL and that custom widget resides in the Page called “News”. All users who visit the “News” Page will have their email address associated with their account fetched and processed by hs.fi.
Please note that as of now the email address scope is the only available scope meaning that it is automatically selected. In the future, however, more options will be available such as organisation scope and a more in-depth user info scope that includes more than just a user’s email address.
Once you’ve added in all the necessary fields and click on “Add widget” you will be directed back to the Custom widgets panel within the Admin settings and will receive a confirmation of the creation of the widget on the bottom left corner.
If you wish to edit, disable or delete the custom widget you can do so by clicking on the three dots next to the widget where you will be presented with the appropriate options.
- Note that if you, for example, edit the widget you will also receive a confirmation of that action on the bottom left corner. This goes the same for disabling or deleting widgets.
Lastly, once you’ve established a generous list of custom widgets and would like to search for a specific one, you can most definitely do so by searching for the widget in the search bar within the custom widgets panel.
What happens if you disable or delete a custom widget that has already been added to a Page?
If you decide to disable or delete a custom widget that has already been added to a Page, the preview of that widget will be shown as follows within that specific Page:
These widgets can of course be removed from the Page by the Page editor(s) if they wish to do so.
Why are custom widgets only accessible to administrators?
The reason why only platform admins can create custom widgets as opposed to, for example, Page owners/editors as well is that due to custom widgets being insecure iframes that are not in a secured sandboxed environment, there is a higher risk of security issues emerging if a large number of users are utilising this tool.
With this in mind, having a limited number of users that have access to this tool is much safer and more secure. All security risks are now the responsibility of the admin user creating/updating such a widget.