Export Sections

This page is generated from HOOKS.md in the Typography Stylist source. Edit it there — edits made here are kept, but they stop this page from being updated until the conflict is resolved.

Since 2.3.5 (#205). Settings → Typography Stylist → Export & Import writes one JSON file in sections and imports it on another site. A section is registered with the typost_export_sections filter as an array:

KeyTypeDescription
idstringKey in the file’s sections object. Letters, digits and _, starting with a letter.
labelstringName shown in the export and import UI.
capabilitystringNeeded to export the section (default manage_options). Import always needs manage_options.
optionsstring[]The typost_* options the section carries. The export registry test reads this list.
exportcallablefn( Typost_Export_Fonts $fonts, array $args ): array{data: mixed, notes?: string[]}|WP_Error. $args['items'] holds the ids the author picked, when the section offers items.
previewcallablefn( mixed $data, Typost_Export_Fonts $fonts ): array|WP_Error. What the import UI shows. Return rows for choices (see “Rows” below), or items (each with a name) for a plain list. notes (string[]) shows under the section heading, warnings (string[]) in “Check before you import”.
importcallablefn( mixed $data, array $choices, Typost_Export_Fonts $fonts, bool $dry_run ): array|WP_Error. Return groups ([{heading, items: string[]}]) and warnings (string[]) for the result page.
itemscallable, optionalfn(): array{id, name, parent?}[]: the things the author can pick on export. parent is the id the item needs with it; the UI says it is added.
fontKeyscallable, optionalfn( mixed $data ): array<string, string[]>: file font key → names of the items that use it, for the preview’s “Used by”. Also decides which fonts import: a font that only left-out sections use is not imported. Without it, your section’s fonts import as chosen even when the author leaves the section out.
priorityint, optionalImport order, lower first (default 50). Core uses 10 (Feature Visibility), 15 (variable font axes), 20 (paragraph styles), 30 (presets) and 40 (options): per-font settings import before the styles whose warnings read them.

Rows. A section that asks the author something returns rows from preview, and the import page renders them with no code of its own:

return array(
    'rows'  => array(
        array(
            'key'      => 'typost_my_extension_toolbar', // reaches import as $choices[ key ]
            'name'     => __('Add a My Extension button', 'my-extension'),
            'detail'   => '',            // optional, under the name
            'note'     => '',            // optional, under the name, read with the select
            'current'  => __('Off', 'my-extension'), // optional: "On this site" column
            'incoming' => __('On', 'my-extension'),  // optional: "In the file" column
            'choices'  => array(
                array('value' => 'keep',  'label' => __('Keep the value on this site', 'my-extension')),
                array('value' => 'apply', 'label' => __('Use the value in the file', 'my-extension')),
            ),
            'choice'   => '', // '' = no default: the author must choose before import
        ),
    ),
    'notes' => array(),
);

The page sends the answers as choices.sections[id][key] = value. A row with choice '' blocks the import until it is answered, in the page and in your import callback: return a WP_Error from the dry run when an answer is missing, because a client other than the page can leave it out.

Settings stored per font go through the font map like a style’s font. Write them under $fonts->key_for_font_id( $id ), and return those keys from fontKeys, so the fonts travel with the settings. For the preview row and the result, use core’s helpers, so every per-font section asks the same question: Typost_Export_Settings::font_settings_row( $key, $fonts, $current, $incoming, $has_own ), Typost_Export_Settings::font_settings_choice( $choices, $key, $has_own ) and Typost_Export_Settings::font_settings_groups( $label, $applied, $kept, $missing ). The choice starts on “keep” when the font this site maps to has settings of its own, else on “use the settings in the file”. $fonts->file_font_name( $key ) names a font of the file.

File format:

{
  "format": "typost-export",
  "version": 1,
  "plugin": "2.3.5",
  "exported": "2026-10-28",
  "fonts": { "f1": { "source": "adobe", "name": "Proxima Nova", "family": "Proxima Nova", "kit": "abc1234", "cssUrl": "https://use.typekit.net/abc1234.css" } },
  "sections": { "paragraphStyles": [ { "key": "s1", "name": "Body", "basedOn": null, "properties": { "fontId": "f1", "lineHeight": 1.5 } } ] }
}

A newer version is rejected, and a section the receiving site does not know is listed as not imported while the rest of the file imports.

Rules for a section:

  • Never write a site ID. A font ID, a style ID, an attachment ID or a term ID only means something on the site that made it. For a font, call $fonts->key_for_font_id( $id ) on export and write the key it returns (null = the font no longer exists); on import, $fonts->import_font_id( $key ) gives the font ID on this site, 0 when it is not there. Give your own references file-local keys, the way paragraph styles write s1 and basedOn: "s1".
  • Write nothing on a dry run. Import calls import twice: first with $dry_run = true for every section, then, after fonts are added, with false. A WP_Error from either call stops the import, so return every error from the dry run. A file a section rejects must save nothing.
  • Sanitize every value as the code that saves it today does: the file comes from another site.
  • List your options in options, or add them to Typost_Export::NOT_EXPORTED with the reason. tests/Unit/ExportRegistryTest.php fails when an option uninstall.php deletes is in neither list, so a new option cannot ship without a decision about export.
  • Never change existing data unless the author chose to. Paragraph styles and presets skip an item whose name exists unless the author picks “Overwrite”. An option that differs on this site has no default: the author must choose.

Sections in core and the bundled modules:

SectionHoldsChoices
featureVisibilityHidden OpenType features per font, by font key.Per font: use the file’s settings, or keep this site’s.
variableFontsVariable font axes and the variable / hide-weights flags per font, by font key.Per font, as Feature Visibility.
paragraphStylesStyles with their Based On links.Per style: add, skip, add with a new name, overwrite.
presetsThe stored presets (name, features, description). Features this site does not know are dropped.Per preset: add, skip, add as “Name (2)”, overwrite.
optionsEvery setting on the Options and Accessibility tabs, plus extension checkboxes. Option names are the keys.Per option that differs here: keep, or use the file’s value. No default.

The font order (typost_font_order) is not exported: it orders the whole font list of one site.

REST routes (all POST, rate-limited like every typost/v1 write):

  • typost/v1/export — {sections: string[], allFonts: bool, sectionArgs: {id: {items: []}}} → {file, notes, filename}. Needs edit_posts, the capability of each section, and manage_options for allFonts.
  • typost/v1/import/preview — {fileText} → fonts (status found, ambiguous, addable or not_found, with candidates, usedBy names and the sections that use the font), each section’s preview, unknownSections, siteFonts. Needs manage_options. Saves nothing.
  • typost/v1/import — {fileText, choices: {fonts: {key: {action: 'map'|'add'|'none', target?}}, sections: {id: choices}, include: string[]}} → {fonts: {added, notFound}, sections: {id: result}, notImported}. Needs manage_options. A font or section choice left out takes the preview’s default. A font that only sections missing from include use is not imported (no choice needed, nothing added); a font that no section uses imports as chosen.

Fonts are matched by Adobe Fonts project and family, then WordPress Font Library slug and family, then family, then display name (case-insensitive). When more than one font matches at the first step that finds any, the font is “ambiguous” and the author must pick. Adobe Fonts families and font definitions can be added from the file (Typost::add_adobe_font_entry(), Typost::add_manual_font_entry()); a Library font is adopted. Uploaded font files are never in the file.