Visual Studio Code for Create

The Visual Studio Code for Create Extension is used to quickly create, preview, and export Templates to Choreograph Create.

In seven easy steps, the wizard will output all source files with direct links to assets and code snippets required for a functional Advertising Template. These features are available to you within the environment you use to develop, preview, and test your Templates.

Index

• Getting started
  • Installation guide
  • Customizing your Visual Studio Code user interface
  • Creating a template boilerplate
• Features
  • Boilerplate generation
  • Mapping of dynamic content
  • Previewing
  • Exporting
• Dependencies
  • Choreograph account
  • Preview plugin
• Output
• Support

Getting started

Installation guide

1. Open your Visual Studio Code editor.
2. Open the Extensions Panel on Visual Studio Code's Activity Bar.

   Shortcuts: CMD + SHIFT + X for Mac, CTRL + SHIFT + X for Windows

3. Search for Visual Studio Code for Create in the Extension Panel in Visual Studio Code and install it from there.
4. Your Extension should be successfully installed. A new icon for the Extension should appear at the bottom of Visual Studio Code's Activity Bar.

   Note: The icon will look like four circles in a similar pattern to ::.

Customizing your Visual Studio Code user interface

You can customize your Visual Studio Code User Interface layout by moving the Choreograph Extension to wherever you want, by simply dragging the Extension's Icon to your desired location within Visual Studio Code. This has the benefit of allowing you to have your workspace open at the same time as the Extension.

Note: You can reset the extension's location by right-clicking on its icon or title, then selecting reset location.

Possible configurations are:

1. No customization

   The Extension view in a separate view in the Primary Side Bar, separate from your Explorer view.

2. Dragging your extension into the Explorer View

   A combination of your Explorer view and the extension view on the Primary Side Bar.

3. Dragging your extension onto the Secondary Side Bar

   The Extension view on Secondary Side Bar separate from your Explorer view.

Creating a template boilerplate

1. Click the new icon to open the Extension, which should appear on the bottom of Visual Studio Code's Activity Bar.
2. Push the Get started button in the Primary Side Bar.
3. Complete the wizard to generate your first Template Boilerplate.

   Note: See the Boilerplate Generation section for a step-by-step guide to the wizard.

4. Edit the look and feel of your Template within your development environment.
5. Map your dynamic content

   Note: See the Mapping of dynamic content section for a guide to mapping your dynamic content.

6. Export your Template directly to Choreograph Create, or as a .zip and upload it to your desired location.

   Note: You can find your Templates in Choreograph Create within Manage, in the Templates section directly under your selected Advertiser. The most recent uploads will be displayed at the top of the list.

Features

Boilerplate generation

A simple wizard will output the perfect boilerplate for your Advertising Template, including all required metadata, configurations, and JavaScript dependencies. The wizard has the following steps:

1. Get started

   Choose to start a new template or convert template to a Choreograph Create template, which will be the start point of the wizard

   Note: Convert a template to a Choreograph Create template will copy your files into a new workspace where we inject the information selected in the rest of the wizard steps.

2. Workspace

   Choose your local workspace selection where your Template files will be developed.

   Note: The convert template step will first request template source folder and will copy your files into the new choosen workspace where we inject the information selected in the rest of the wizard steps.

3. Template Name

   Give the Template your desired name, which will be the reference used to find it once uploaded.

4. Creative size

   Set the dimensions of your Advertising Template

5. Advertiser selection

   Connect to an Advertiser to easily import assets and data.

   Note: You are able to switch Advertisers at any point in the process.

6. Placeholder creation

   Quickly create new and/or import placeholders directly from existing Adsets and automatically generate the correct configuration in Template.json, which will be generated upon preview or export.
   Quickly create new and/or import placeholders directly from feeds and/or existing rule-based Adsets and automatically generate the correct configuration in Template.json, which will be generated upon preview or export.
   Basically, the placeholder creation step provides 3 options to create placeholders and provides the possibility to mix them. The options are:
   

   • Import from feed

     As feed source (.csv or .json) you can choose a local feed or you choose a public URL to a feed. After you have chosen your feed source, you have classify the feed content and click columns you want to use in your template and define the placeholder type e.g. text, image, video, audio or click. Classifying can be done in bulk by selecting the columns, choose the placeholders type in the dropdown, and confirm it by pressing the button Set selected placeholders type.

   • Import from Create
   • Create manually

7. Fonts

   Import fonts from Advertisers to generate easy font usage in CSS and HTML, which will be injected in the markup and CSS upon preview or export.

   Note: Switching Advertisers after selecting Choreograph Create as font source will cause the font from the original Advertiser to be removed. You are only able to upload a Template using a custom font from an Advertiser if the Advertiser has the correct license for the font.

Mapping of dynmamic content

There are 2 ways to map your dynamic content:

1. Basic mapping of dynamic content
2. Advanced mapping of dynamic content

1. Basic mapping of dynamic content Add data-placeholder attributes to the elements that should contain dynamic content.

Note: Upon receiving the lemonpi.content/ready event, the creative-libraries, added via the boilerplate wizard, will find all elements with data-placeholder attributes and render the corresponding content to these elements. The rendering behavior depends on the type of placeholder. Upon completion, the lemonpi.content/rendered event is dispatched.

Text

The textContent of the target element is replaced.

Image

Two classes are added to the target element: .placeholder-{name} and .placeholder-image. A stylesheet is added to the start of the <head> tag, setting the desired image as the elements background-image.

Click

A .placeholder-click class and a onclick handler are added to the target element. Once clicked, a lemonpi.interaction/click event will be dispatched.

2. Advanced mapping of dynamic content

Programmatically accessing content

You can either add an event listener for the lemonpi.content/ready event, or use the higher level lemonpi.content.subscribe method. The advantage of using the lemonpi.subscribe method is that it doesn't matter when you use it. If the content is already collected upon subscribing, the callback will be called immediately. Otherwise, the callback will be called once content is collected.

// Called when lemonpi.content/ready is dispatched. You need to setup the event
// listener before this happens.
window.addEventListener("lemonpi.content/ready", (event) => {
  const content = event.detail.content
  const source = event.detail.source
  // Do stuff
})

// Called when lemonpi.content/ready is dispatched or has previously been
// dispatched. It doesn't matter when you setup this event listener.
window.lemonpi.subscribe((content, source) => {
  // Do stuff
})

Programmatically dispatching click interactions

In some cases, the default lemonpi.interaction/click that is dispatched when a click placeholder element is clicked is insufficient. You might want to programmatically determine which click placeholder should be navigated to, or you might want to add additional query parameters. In that case, you can add your own onclick handler to an element and dispatch your own lemonpi.interaction/click event.

document.body.onclick = () =>
  window.dispatchEvent(
    new CustomEvent("lemonpi.interaction/click", {
      detail: {
        placeholder: "click_url",
        query: { postcode: document.getElementById("postcode-input").value },
      },
    })
  )

Dispatching click interactions within the collection placeholder

You might want to dispatch lemonpi.interaction/click with click placeholders nested in collection placeholders. You can do this by using an Array as a selector path for the placeholder property within detail. Example detail: { placeholder: ['my_collection', 0, 'click_placeholder'] }.

It uses the following structure:

<Array<placeholderName, index, collectionItemPlaceholderName>>

document.body.onclick = () =>
  window.dispatchEvent(
    new CustomEvent("lemonpi.interaction/click", {
      detail: {
        placeholder: ["my_collection", 0, "click_placeholder"],
        query: { postcode: document.getElementById("postcode-input").value },
      },
    })
  )

Previewing

• Local preview

  The Visual Studio Code for Create extension enables easy previewing within your preferred development environment. To preview your Templates locally press the launch preview button in the Visual Studio Code for Create extension. This will open your preferred browser and shows a preview of your template with the example content you have added in the placeholder step. Any changes made to the template will directly reflect to the local preview.
  

Feed preview

When you created placeholders from a feed, you have the option to preview the variants from that feed, so locally you can already preview your variants by using the navigation at the bottom of the preview page.
Preview with dynamic content from the platform In order to preview your template with dynamic content from the platform you first have to create a local preview, see the steps Local preview. After the preview is launched copy the URL and go to your adset in Choreograph Create. Open the preview environment of your adset, and press the 3 dots in the top right corner, and press Add external template. Paste the URL in the URL input field, fill in the width and height of your template, and press Add Template. Now your template can be previewed with dynamic content from the platform.

Exporting

You can quickly create a local or direct export to Choreograph Create using the actions on the Primary Side Bar of the Extension.

Local export

Exporting locally creates a .zip package on your local machine. This .zip file can then be shared or manually uploaded.

Direct export

Exporting a Template directly to Choreograph Create will show the Export to Choreograph Create page from where you can choose your preferred folder to upload the template immediately to the selected Advertiser you have selected in the wizard step. It can be found under the same name you've given your Template in the Extension.

When a template already exists in the folder, you are able to create a new revision of the template. More information about template revision can be found here.

Dependencies

Choreograph account

The Visual Studio Code for Create Extension requires an active Choreograph Create account to be able to access adset placeholders, fonts stored on the platform and be able to upload the template directly..

Preview plugin

To preview your Templates locally press Launch preview.

Output

Some attributes required for a functional Advertising Template are injected on the moment of export due to avoid any conflicts when users edit the source files. The injected attributes include the following:

• Ad size metadata
• Creative Libraries reference
• Font reference(s)

The file output of the Extension is as follows:

Template
│
└───plugin (This folder will not be included in your export)
│   │   plugin.js
│   │   settings.json
│
└───src
    │   creativeScript.js (Starting point for your Template's Javascript)
    │   index.html (Starting point for your Template's Markup)
    │   style.css (Starting point for your Template's CSS)

Support

Please contact our support team via Zendesk.