Themes FAQ

The following serves as guidance for developers building and maintaining their site using the Themes 2.0 design system.

As a developer using Themes, how do I...

Get Started on Local Development

You can use the following guides to get started on local development by configuring your feature pack and running PageBuilder Engine locally:

Access the Arc Blocks Repository

Click the button to go to the public blocks repository:

Arc Blocks Repository

You can eject (fork) blocks from this repository to customize within your own bundle as needed.

Access the Themes Starter Repository

You can view the Themes Starter repository in our Arc XP Github organization. Click the button to go to the Themes Starter repository:

Themes Starter Repository

Use the Themes Starter Repository to Migrate from Custom to Themes Blocks

This guide enables you to update your mocks/siteservice/api/v3/website file, environment/index.json file, and the resizerURL in your blocks.json file. You also add the themes-provisioning.js file to the .gitignore file so it is not included in the repo you initialize.

To use the Themes Starter repository, follow these steps:

On your terminal, clone the starter bundle into your desired directory using the following command:
```
git clone https://github.com/arcxp/Themes-V2-Starter.git {directory}
```
Navigate to the folder where you cloned the repository:
```
cd {directory}
```
Add a valid .npmrc file to the root directory of your project.
Ensure you have the .env file in the root directory of your project.
Create a developer token in the sandbox environment of your Arc XP organization.
Paste the token value in the ACCESS_TOKEN variable of the .env file
On the terminal, run the following command from the root directory of your project:
```
node themes-provisioning.js configure-bundle
```

Find and Set the Image Resizer v2 Token Version

To use the latest image resizer, you must add new environment variables to your environment .json files:

The RESIZER_TOKEN_VERSION value must match the currently enabled SSM version for your organization’s secret from the Organization > Get HMAC Keys section of the Delivery API documentation. If you are unable to locate your organization’s token version through this method, contact your Technical Account Manager (TAM).
Once you know your organization’s token value, you must set that as the RESIZER_TOKEN_VERSION in the environment/*.json file of your feature pack.
See Introduction to Resizer v2 for more details.

Set Environment Variables for Your Themes Repository

See the required environment settings you need to configure in the /environment directory of your repository.

Add a Custom Font

You can manage fonts through the Blocks Styling token method. You can set the fonts as comma-separated values within parentheses in your alias.json file. For example:

{
  "default": {
    "font-family-primary": "('Merriweather Sans', sans-serif)"
  }
}

Declare a New Font Family

Custom font files should be included in the /resources/ directory. To declare a new font family:

Set the font family via css.
Load the css file via the output type.

The following section provide examples of the contents of each file.

fonts.css

@font-face {
  font-family: 'MyFont';
  src: ...; //file in resources folder or cdn url
....

output-types/default.jsx

import './fonts.css'

alias.json

{
  "default": {
    "font-family-primary": "('MyFont', sans-serif)"
  }
}

Eject (Fork) a Block

For full details on ejecting a Themes block as a starter for your custom needs, see Ejecting (Forking) an Arc Block.

Use Block Styling on Custom Blocks

For full details on applying Themes 2.0 block styling capabilities to custom blocks, see Creating a Custom Block with Styling.

Update Blocks for AMP Compatibility

Due to the updates in the page experience ranking by Google, AMP is not supported out-of-the-box on Arc XP components, blocks, and pages. You may build a custom block to your specific requirements and will need to create a custom output type to meet the AMP HTML specification.

For more details, see PageBuilder Engine Best Practices: AMP.

Internationalize Your Site

For full details on Themes supported languages and site properties, see Internationalization.

Set Site Properties

To set site properties in your bundle, see Migrating from Theme Settings UI to PageBuilder Deployer

For more information about site properties that are not supported out-of-the-box, see:

Add or Remove Blocks from Your Bundle

You can add or remove blocks from your bundle by changing your blocks.json file of your feature pack.

Complete a Deployment

To complete a deployment using PageBuilder Deployer, see see Migrating from Theme Settings UI to PageBuilder Deployer