cep-vfstring v1.0.0

CEP Variable Font String

Parse Variable Font values in extensions for Adobe Creative Cloud apps, in JavaScript & ExtendScript (ES3).

npm install cep-vfstring

Getting started

If you are using ExtendScript (ES3) without any kind of build toolchain, you can include the file by copying the index.js file somewhere into your project, and using ExtendScript’s //@include statement:

//@include "./path/to/vendor/cep-vfstring/index.js"

However, you’ll almost certainly want to use some kind of build toolchain to make the development process easier.

// Load the library in the JS environment
import vfString from 'cep-vfstring'

// Using https://npm.im/cep-interface
import {
  inCEPEnvironment,
  loadExtendscript,
  evalExtendscript,
} from "cep-interface";

if (inCEPEnvironment()) {
  // Load the library in the ExtendScript environment
  loadExtendscript(
    "node_modules/cep-vfstring/index.js"
  );

  // $.global.vfString now available, ex. for use
  // in another ExtendScript file
  loadExtendscript('./another-extendscript-file.jsx')
}

API

parse

var textFontStr = "[TextFont EncodeSans_660wght_50wdth]";
vfString.parse(textFontStr);

format

vfString.format("EncodeSans", {
  wght: 835,
  wdth: 72,
});

Examples

Shouldn’t it be possible to pass the result of parse directly to format, and vice versa, like JSON.parse and JSON.stringify? Maybe. In this case I’ve optimised for use within the CEP environment, so the result of vfString.format can be immediately used to get a font.

Here’s a contrived but complete example of going from parse to format and back in ExtendScript.

ExtendScript example

//@include "./path/to/vendor/cep-vfstring/index.js"

// You’d probably actually get this from something your
// script is doing, ex. from a selected text frame
var fontString = "[TextFont EncodeSans_550wght_120wdth]"

var result = $.global.vfString.parse(fontString);

$.writeln(result.fontFamily);
// Logs: `EncodeSans`

$.writeln(result.fontVariations.wght);
// Logs: `550`

$.writeln(result.fontVariations.wdth);
// Logs: `120`

var ccFontName = $.global.vfString.format(
  result.fontFamily,
  result.fontVariations
);

$.writeln(ccFontName);
// Logs: `EncodeSans_550wght_120wdth`

var font = app.textFonts.getFontByName(ccFontName)

JavaScript example

// You’d might get this from passing some ExtendScript
// back into the JavaScript environment
let fontString = "[TextFont EncodeSans_550wght_120wdth]"

let result = vfString.parse(fontString);

console.log(result)
// Logs:
// {
//  fontFamily: "EncodeSans",
//  fontVariations: {
//    wght: 660,
//    wdth: 50
//  }
// }

let ccFontName = vfString.format(result.fontFamily, result.fontVariations)

console.log(ccFontName)
// Logs: `EncodeSans_660wght_50wdth`

Further Reading

Tag Order

OpenType Variable Font axes (ex. Weight, Width) are stored in an array. The order of that array is significant within Adobe apps, and needs to be preserved.

This library will preserve the order of the tags you pass it. For example:

let ccFontName = vfString.format('Encode Sans', {
  wght: 300,
  wdth: 500,
  CSTM: 1
})

console.log(ccFontName)
// Logs: `EncodeSans_300wght_500wdth_1CSTM`

This assumes you know the order of the axes within the font is Weight (wght), Width (wdth), and a custom axis with the tag CSTM. If the order is incorrect, the name within Illustrator or InDesign will also be incorrect.

This is obviously a non-issue in when using single-axis Variable Fonts. The starter project that uses this library also deals with it for multi-axis fonts: the font files have been dynamically read before this library is used, so the tag order is already known. However, if you are deviating from that approach, or writing a one-off script for a specific Variable Font, this is something to be aware of.

License

Apache 2.0