Fusion Shared Resource

In this document we’ll look at Anthill Activator’s Fusion shared resources. It is targeting content developers.

What is a shared resource?

A shared resource is a Multichannel Slide document in Veeva Vault PromoMats with the multichannel property ‘Shared Resource’ set to true.

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.

Any slide can set a reference to this shared resource, and in the HTML it becomes accessible through ../shared/ path. A slide can only reference one shared resource.

What is Anthill’s Fusion Shared Resource?

The Fusion Shared Resource 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. It also comes packed with Anthill’s official Activator content components, e.g. popups, sliders etc.

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 a Fusion Shared Resource related to it.

How do I get it?

A Fusion Shared Resource is often shared in relation to a specific project. However, Anthill’s standard shared resource can be obtained by contacting Anthill.

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

What is included?

The following is the default folder structure of Fusion Shared Resource. It might differ slightly for shared resources 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-element library.

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

What is required?

The Fusion Shared Resource 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/

Please note that you might experience problems with NodeJS 17. It will be resolved in upgrade

How do I set it up?

Once you have the shared resource on your computer, run the following in a command line application:

npm install

NONE

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”>

HTML

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

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');
}

CSS

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";

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"
            }
          ]
        }
      ]
    }
]

JSON

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

CODE

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 shared resource to Activator?

After you have made updates to the shared resource, 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]

TEXT

The command ensures there is a folder called exports containing the created folder, which is either named from the command, or from the data 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 shared resource (if you are currently working on content)
Update an existing shared resource (browse to find the one to update)
Create a new shared resource

It is also possible to manually compress the files in the shared resource 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 resource folder and compress them with your tool of choice.

What are layouts?

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

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

Usually layouts are kept simple and include header, footer and columns.

How do I add new layouts?

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

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

The Fusion component Content Area was created specifically for building layouts. It makes it easy to create columns that aren’t draggable.

What are slide fragments?

Slide fragments are snippets of HTML that can be shared between slides using the same shared resource. 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 shared resource 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 Shared Resource 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 a Fusion Shared Resource to the latest version?

Since version 1.10.0 of Activator, there will be a label, next to where a shared resource 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 shared resource 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 shared resource <1.9.0, then there will simply be an error message:

Shared resource 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!