Nebula Template Utils

Template-related utilities for use in Nebula and Exoplanet repos.

Table of contents

• Introducing Nebula Template Utils
• About size preset categories
  • Full preset category list
• Getting started
• Using Nebula Template Utils
• Custom labels and sizes
• Contributing and extending

Introducing Nebula Template Utils

Nebula Template Utils provides a set of tools that bridge the divide between the Exoplanet repository and the Nebula repository. Many of these tools are used in both repos and provide consistency and interoperability between the two.

Much of this README pertains to users of Exoplanet repo, but there are many more features yet to be better documented.

About size preset categories

In order for the Sesimi app to know how to display a template’s preview to a user, we need to have set at least one size preset in the template config’s sizes array.

Size preset categories—such as newspaper, bannerAd and social—contain a structured (and growing) set of sizes from which we can compile a suitable list and add it to our template config’s sizes property. Ultimately, this list of presets (containing media dimensions, default formats and descriptive labels) is presented to a user as being well-supported choices for them to select and produce media from.

Categories list

Follow this link to view a flattened table detailing every current preset.

• bannerAd.ts (HTML banner ads)
• newspaper.ts (newspaper print ads)
• ooh.ts (Billboards and outdoor signage)
• paper.ts (A-size paper, A3, A4 etc.)
• social.ts (social media ads, posts and stories)
• website (common website banners and mastheads)
• email (email)
• video (video)

An example of preset category:

const exportDefaults = `print`

export const newspaper = {
  tallTabloid: {
    sizes: {
      fullPage: {
        label: `Tall tabloid full page`,
        width: 990,
        height: 1361,
        exportDefaults,
      },
      halfPage: {
        label: `Tall tabloid half page`,
        width: 990,
        height: 661,
        exportDefaults,
      },
    },
  },

  compactTabloid: {
    sizes: {
      fullPage: {
        label: `Compact tabloid full page`,
        width: 990,
        height: 1008,
        exportDefaults,
      },
    },
  },
}

Getting started

1. Open /src//brands/[your template folder]/data/config.mjs
2. Edit the config.mjs sizes and defaultSize objects to required sizes

Have a read of this snippet:

import {defineConfig, embedSizes, allSizes} from '@myadbox/nebula-template-utils'

export default defineConfig({
  sizes: embedSizes({
    support: {
      categories: [allSizes.newspaper, allSizes.paper.iso.a.a4, allSizes.paper.us.letter],
      specific: [allSizes.paper.iso.a.a4.sizes.portrait],
    },
  }),
  defaultSize: allSizes.newspaper.compactTabloid.sizes.fullPage.label,

  // the rest of config
  // fields: [...

})

The template default gives you a head start by importing what’s necessary, all you have to do is edit what’s there so let’s look at that step by step:

defineConfig — required, do not edit

export default defineConfig({

This begins defining the object that becomes the entire JSON config data bundled with the template’s zip archive, and read by the Sesimi app to create the customised build form for the template. Wrapping the config object in this defineConfig function call enables VS Code to check your progress as you fill out the config object and alert you with red underlines when anything is incorrectly specified.

embedSizes — required, do not edit

sizes: embedSizes({
  support: {

This embeds sizes available to the user. What is set here will show in their dropdown list.

categories — optional

    categories: [allSizes.newspaper, allSizes.paper.iso.a.a4, allSizes.paper.us.letter],

To display a full category for user selection, use categories.

E.g. allSizes.newspaper will display every available newspaper option.

This can be narrowed down if you only want to display a section of the whole category.

E.g. allSizes.newspaper.tallTabloid

Another example is isolating to A4, but both portrait and landscape options:

allSizes.paper.iso.a.a4

specific — optional

    specific: [allSizes.paper.iso.a.a4.sizes.portrait],

To display a specific size only, use specific. Note that while this is marked as "optional" there must be at least one size in a config’s sizes array. This specific option is often used to provide that when only one size is supported.

E.g. allSizes.paper.iso.a.a4.sizes.portrait will display A4 portrait only.

You can add as many specific sizes as needed, separated by a comma:

E.g. allSizes.social.facebook.main.sizes.linkPost, allSizes.social.instagram.main.sizes.post will display two social media size options for the user.

defaultSize — required

defaultSize: allSizes.paper.iso.a.a4.sizes.portrait.label, // NOTE: .label is important

To give the user an initial selected size, use defaultSize. This must be appended with .label to display the label in the select.

Modifying existing presets

You can optionally modify the format and/or quality of the embedded sizes. For example, if you want, say, the bannerAd category of sizes, but your template is animated, you'll want to override the default format (JPG) to be HTML. You can do this by passing the sizes you got via embedSizes into the modifySizes function, like so:

import {defineConfig, embedSizes, modifySizes, allSizes, Format} from '@myadbox/nebula-template-utils'

// for clarity, create a variable of the embedSizes result
const sizes = embedSizes({
  support: {
    categories: [allSizes.bannerAd],
  },
})

// pass in your sizes, along with an object that will override properties of each size
const modifiedSizes = modifySizes(sizes, {format: Format.Html})

export default defineConfig({
  // add the modified sizes to the config
  sizes: modifiedSizes,
  // ... config continues ...

Custom labels and sizes (TODO)

Contributing

To publish a new version, increment the version number in package.json and then run the following from the client workspace root:

yarn nx run @myadbox/nebula-template-utils:build && node ./tools/scripts/publish.mjs @myadbox/nebula-template-utils [ insert
your new version number here] latest