Fusion Library

What is a shared folder?

The shared folder is used for the Activator Design System to hold all the files and assets that can be shared between documents in a project, brand or presentation.

Any document related to this Design System can access the content of it through ../shared/ path in the HTML. A document can only be related to and reference one shared folder.

Veeva Vault Promomats Setup

In Vault, a shared folder is a Multichannel Slide document with the multichannel property ‘Shared Resource’ set to ‘Yes’. 

This enables the document to be shared across a presentation, or even multiple presentations. It will no longer work as a normal slide, but instead as a folder of assets that other slides can access and use in the content.

What is Anthill’s Fusion Library?

The Activator Design System package provided by Anthill contains libraries and a build system for setting up web components and any other JavaScript and CSS code needed for a project in Activator. It also comes packed with Anthill’s official Activator content components, e.g. popups, sliders etc. The library inside the Design System package that enables communication with Activator, and contains all standard components, is called Fusion Library.

All source code is in plain text and can be read and manipulated by any developer familiar with web technologies.

Any content that should be compatible with Activator, i.e. editable, should have an Activator Design System folder related to it.

How do I get it?

A Design System folder is often shared in relation to a specific project. However, Anthill’s standard Design System folder can be obtained by contacting Anthill.

It is also possible to download source code of any editable document from Activator via its ‘Sharing’ menu. The shared folder is included in the download and can be used to create new Design Systems, or update existing ones. It’s important to be aware of the version the Design System is built on though. More about that in the next section.

What is included?

The following is the default folder structure of Activator Design System. It might differ slightly for folders that have already been prepared for a specific project.

The file structure is based on a Progressive Web Application template with Redux state management. It contains all necessary dependencies to develop web components with Google’s Lit library.

Dependencies, and also version of the Activator Design System, is defined in the package.json file. It’s possible to add custom dependencies to this file as needed.

What is required?

The Fusion library is built on NodeJS and that is the only requirement. It should work with any recent release from NodeJS 12 and up. Please see the official NodeJS website for instructions on how to install on different operating systems:

https://nodejs.org/ 

How do I set it up?

Once you have the Design System folder on your computer, run the following in a command line application:

npm install

This will install all dependencies specified in the package.json file. Now it’s ready to be used for further development.

How do I add assets to my project?

Simply add any assets to the assets/ folder and they will be available in the slides that have a relationship to the shared resource. Here is an example of how an image could be referenced in a slide:

<img src=”../shared/assets/images/logo.png” alt=”Logo”>

It’s possible to drag and drop images and other assets to Activator UI, and select to have them added to the Design System.

Custom Fonts

When adding a custom font to the assets/fonts/ folder, it should also be setup as a font-face in CSS. Recommendation is to add it to src/styles/typography.css file. Example:

@font-face {
  font-family: Roboto;
  font-weight: 400;
  font-display: swap;
  src: url('../../assets/fonts/Roboto-Regular.ttf');
}

Also ensure the CSS file you add it to is imported to the src/main.css file or it will not be included in the build. Example:

@import "./styles/typography.css";

In order to make the font available via the Activator UI, it also needs to be added to the src/config.json file. Here is an example where above font is added with a normal font-weight:

"fonts": [
    {
      "propName": "font-family",
      "propValue": "Roboto",
      "inner": [
        {
          "propName": "font-weight",
          "propValue": "400",
          "inner": [
            {
              "propName": "font-style",
              "propValue": "normal",
              "src": "Roboto-Regular"
            }
          ]
        }
      ]
    }
]

See src/config.json for more examples.

How do I add custom stylesheets and scripts?

All new code files should be added to the src/ folder. In the src/ folder there are specific folders for different types of files; scripts/, styles/. and vendor/.

Then there are two files where the added files should be imported so that they are included in the build:

• main.css - import and build stylesheets

• main.js - import and build scripts

Both files have examples on how to import files.

How do I compile the source code?

Compiling the source code in the src/ folder is simply done by running the following command from the root of the shared folder:

npm run build

This will generate a dist/ folder with main.css and main.js files. These files will be referenced from the slides in the HTML.

How do I export the Design System to Activator?

After you have made updates to the Design System, you can create a zip archive and upload it to Activator. If you have made any changes in the src/ folder, or if the /dist folder is missing, you should first compile the source code. See the section ‘How do I compile the source code?’ for instructions.

To create the zip archive, run the following command in a command line:

npm run export [name]

The command ensures there is a folder called exports containing the created folder, which is either named from the command, or from the date and time it was created. In this created folder is a zip archive with the name shared.zip.

The [name] parameter is, in other words, optional.

The shared.zip file is ready for Activator and you can simply drag and drop it to the application. You’ll may receive up to three options of how Activator should handle it:

• Update the current Design System (if you are currently working on content)

• Update an existing Design System (browse to find the one to update)

• Create a new Design System

It is also possible to manually compress the files in the shared folder and drag and drop the resulting archive. Currently only zip archives are supported but Activator will support other compression types in the future. Simply select all files inside the shared folder and compress them with your tool of choice.

What are templates?

Templates are HTML designs that are used when creating new Vault documents from Activator. Currently it’s possible to create templates for Approved Email Templates, Slides and Briefs.

Templates can contain any HTML code, including web components. It’s also possible to include JavaScript, CSS and assets.

Usually templates are kept simple and include header, footer and columns with more detailed structures provided via layouts.

How do I add new templates?

Currently there isn’t a template editor/creator in Activator so the best way to create a new template is to build a normal document in Activator and copy the source code to a new folder in the appropriate templates folder. Slide and brief templates are added to an index.html file in the slide/templates and brief/templates folder respectively, and email templates are added to mjml.html file in email/templates folder. Other files can be added as necessary. 

Each template should have a thumbnail file, thumb.png, to make it easy to identify in the UI.

Although standard HTML can be used in templates, it’s advised against since it will not be editable in Activator. Instead use web components built using the Fusion library. 

What are layouts and helpers?

Layout and helpers are similar to templates but instead of used to create new documents, they are used to quickly add new content to a document, i.e. think of them as templates for pieces of content.

What is the difference between a helper and a layout?

Layouts are generic content items that are meant to be used as templates for creating sections of content. Helpers, on the other hand, already contain all the proper assets and text and are intended to be used as they are. Often helpers are created by using a layout and populating it with the correct text and assets, e.g. from a content module.

How do I create a layout or helper?

What are slide fragments?

Slide fragments are snippets of HTML that can be shared between slides using the same Design System. The main benefit of slide fragments is that they are defined in one place so if a fragment is updated, all instances of it are also updated. Slide fragments can be as complex as needed and include several states and layers.

How do I add new slide fragments?

There is currently no way of creating slide fragments directly in the Activator UI, instead create a new folder with an index.html file in fragments/ folder. The name of the folder will be the name of the fragment in the UI. Add a thumb.png to the folder to make it easy to preview.

It’s possible to add an empty index.html and use the slide fragment editor to build it as desired. See the section below on how to do that.

How do I update slide fragments?

Fragments are listed in the Design System view. Double-click one of the fragments to open the editor for it. With the editor you can make any updates to the fragment you wish, like when working with a slide.

The changes might not appear right away when you preview a fragment in a slide. This is because of browser caching. To see the changes, open the Network tab in developer console and make sure the Disable cache checkbox is selected. Refresh the slide with the developer console still open.

What are web components?

Web components are a set of web platform APIs that allow you to create new custom, reusable, encapsulated HTML tags to use in web pages and web apps. Custom components and widgets build on the Web Component standards, will work across modern browsers, and can be used with any JavaScript library or framework that works with HTML.

• https://www.webcomponents.org/introduction

How do I add new components?

New custom components are added to the src/components/slide folder. At minimum a custom component is a folder with an index.js file.

Fusion Library includes all necessary dependencies to build powerful components based on Google’s lit-element library (https://lit-element.polymer-project.org/).

The web components in src/fusion/slide folder shouldn’t be changed, but they can be used for inspiration or to extend them.

How can I configure what components are included?

Web components in the src/components and src/fusion/slide are automatically included in the build by default. However, it is possible to exclude components that are not needed by configuring the fusion.json file.

In the image above both Fusion and custom components are excluded from the build. It means the code for those components will not be part of the dist/main.js and dist/main.css files when built.

How do I upgrade Fusion Library to the latest version?

Since version 1.10.0 of Activator, there will be a label, next to where a Design System version is listed, if an upgrade exists.

Click this and the upgrade dialog will be presented.

From here it’s possible to open a list of all documents that will be affected by the update. It’s also possible to open a new tab with a changelog document.

When clicking ‘Upgrade’ Activator will try to upgrade the Design System with the latest Fusion library.

It is possible that the upgrade fails if there has been changes to files that we need to upgrade. In that case the upgrade needs to be done manually.

A log file will be generated specifying which files are preventing the automatic upgrade. 

Note: if it is a really old Design System <1.9.0, then there will simply be an error message:

Design System older than 1.9.0 will have to be manually upgraded.

Do NOT make any changes to the files in the ‘fusion’ folder. This will make the auto upgrade fail!