Designing a custom app

Functional design

We recommend considering the following aspects of the design of the widget.

View & edit mode
The widget can be displayed in pages in view and edit mode. Consider if you need to make some fields read-only in view. Also consider the performance especially on the view. You can get the mode from the component attribute mode.

Declaring settings
You can declare settings with the WidgetSDK (, however consider what settings should be presented in the right configuration panel. Just don't make the config panel too long.

One widget vs multiple ones
This is a good design question, if you widget performs, for example ticket creation and listing functions, should it be one or two different widgets. Consider the use-case and add, for example, a configuration item to change between the different modes if you choose to have multiple modes in one widget.

Authorization flows
Your widget may require oAuth flow or similar. Always consider the different cases where user is unauthorised or requires more permissions and display a clear message to the users what they need to do.

Bundle size
The webpack.config we provide in the React example taps directly into the React, Styled Components and Happeouikit running in the main app. Therefore using these is going to ensure small bundle size for the widget.

Error reporting
The WidgetSDK provides error reporting possibility, this sends a report to Happeo, which we can expose to the developers. Consider using this when necessary.

If you do need to import a lot of additional libraries, try to keep the bundle as small as possible. The bundles are cached to the user browsers for 14 days, but still if the browser is loading a 2mb bundle on widget start, the first load is going to be long.

UI Design

For developers using React, we recommend checking Happeo UIKIt. It contains a lot of components that you can utilise directly. Also if the documentation is poor on some of the components, let us know and we'll get it sorted.

Consideration for Popover widgets
If your widget implements a popover (for example, a chat button, support button, etc.) then it is advisable to expose settings that will allow the page editor to position the popover element on the page. For example, developers can expose a settings called "align" and provide "left" or "right" options that allow the page editor to align the popover item on the bottom left or right edge of a page.

Multiple features in a widget
If your widget implements a broad range of features, it is recommended to provide a "toggle" setting for each feature. For example if your widget displays an article and then you implement commenting on article as a new feature, consider adding "Enable comments on articles" checkbox setting which should be generally disabled by default. This way the user experience is consistent and page viewers do not suddenly see drastic changes to the widget layout (which might disrupt the structure of a page).