Customizing a hub front end

What can be customized

You customize a hub front end using Uberflip's built-in custom code functionality, which allows you to inject code into the DOM of any page in the hub front end. Note that you are not able to directly modify the underlying HTML of the hub front end, so this mechanism influences the types of customization that are possible. In general:

• You can change the visual appearance of a hub in most aspects by injecting CSS
• You can add page elements in the hub front end by injecting HTML
• You can modify built-in page structure and functionality by injecting JavaScript to manipulate the DOM

📘

Note

In general, adding elements with HTML also requires using JavaScript to control placement of those elements.

For best results when customizing your hub front end, we recommend that you focus primarily on customizing its appearance, and limit changes to functionality where possible. Hubs are designed and tested to work in a certain way, and major changes to the out-of-the-box functionality can cause unexpected behaviors that may be difficult to troubleshoot.

Customizing look and feel

Uberflip customers often integrate their hub with their main corporate website. Hub front ends are commonly customized to match the look and feel of the main website, as well as to meet brand guidelines. All page types and elements in the hub front end have consistently-named classes, so it's simple to implement modifications using CSS. You can also flexibly set the scope of your changes, for example by applying a change to just a single page, specific pages, or all pages of a given type within the hub.

Customizing functionality

Where needed, you can make changes to the way the hub front end works by default, or add entirely new functionality. Some common examples in this category include moving page components like titles and images around, or adding components such as carousels. Another common customization is to add the header and footer of your main website to the hub. This type of customization can be achieved by taking the existing header/footer HTML and injecting it into the hub front end with JavaScript. The hub front end also contains custom, platform-specific JavaScript events, allowing you to create entirely new functionality.

📘

Note: Customizing multiple hubs

For simplicity, this handbook generally refers to hubs in the singular (i.e. "a hub" or "the hub"). It's important to note, however, that Uberflip customers can have multiple hubs in their accounts, and you may therefore need to customize more than one hub.

In terms of front end customization, hubs that belong to the same account are entirely separate: they are accessible under different domains, and front end customizations must be separately applied to each hub.

Note that content items may be shared between hubs that belong to the same account. However, because customizations are hub-specific, the item pages that represent these "shared items" will be displayed using the customizations applied to the hub where they are being viewed.

How to identify and target elements for customization

The Uberflip hub front end consists of predefined page types (categories of page templates) that contain page components (preset page elements). Both page types and page components have consistent identifiers in the DOM, in the form of specific class names, id attributes, and data attributes. You can use these identifiers to target or scope your code in various ways. For specifics, see Reference Guide: Hub front end pages, layouts and components.

In addition, the hub front end uses namespacing to avoid collisions with custom code: all Uberflip-specific identifiers are preprended with uf-, allowing you to freely choose your own class names, etc.

Customization guidelines and best practices

To set your project up for success, and avoid common problems and pitfalls, we recommend following these guidelines and best practices when developing your customizations.

General best practices

• Use the hub’s native functionality and settings to your advantage. Relying on extensive functionality changes can cause unforeseen issues when end-users build out new content experiences in the future.
• Consider writing defensive code. A single JavaScript error can cause the entire hub to break. A good approach to avoiding this is to be as specific as possible when scoping your code. Use the <body> element’s classes and id and data attributes to help you scope code to particular page types or even specific backend stream/item IDs.

Do:

• DO choose appropriate placements for custom code blocks. Placements define where custom code is injected, and inappropriate placements can cause your code to run ineffectively. You can find placement guidelines here.
• DO consider the execution order of your custom code blocks. The primary factor which determines execution order is the placement you select: placements higher in the document (e.g. Body Top) will be executed before lower ones (e.g. Body Bottom). If two or more blocks share a placement, their relative order in the table of custom code blocks determines execution order (lower ordinals are executed first). Remember to take this into account, especially with regard to dependencies between code blocks.
• DO be as specific as possible with CSS selectors. The more specific you are, the easier it will be to override the hub’s default styling.
• DO use the !important tag if necessary. This is typically bad practice, but can sometimes be necessary to overwrite default hub styling.
• DO use the hub-specific JavaScript events to execute your code. The hub has custom equivalents to standard events (such as load, scroll, resize, etc.) which are specifically designed for use with the hub front end.
• DO pay attention to the z-index of page elements. Some elements in the hub front end have a z-index set which can cause them to hide other elements, or be hidden themselves.

Don't:

• DON'T write your code in custom code blocks if possible! Custom code blocks are live, and have no version control.
• DON'T forget to scope your code to a specific page if needed. Custom code blocks will load on every page.
• DON'T assume that a page component or selector that exists on one page will exist on every page in the hub. This may cause a JavaScript error that could break all of the functionality on your hub.