Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Import & Export

Bloqs 5.5 lets you export selected bloq definitions to a JSON file and re-import them into another ExpressionEngine site. Use it to move bloqs from local to production, between staging sites, or to share a set of bloqs with another project. Only the definitions are exported (the bloq types, their fields, settings, nesting rules, and component structure). Entry content is never exported; it stays in the entries on each site.

BoldMinded is not responsible for data loss when using this feature.

Backup your database before running imports.

Exporting

On the Bloqs listing screen, each row has a checkbox. Select one or more definitions, choose Export from the bulk-action bar that appears, and submit. Your browser downloads a JSON file named bloqs-definitions-N.json.

The export is self-contained and human-readable. Because the receiving site won't share the same database IDs, every cross-reference is rewritten into a portable form:

  • Bloq groups are exported by name.

  • Nesting rules ("can be a child of...") are exported as shortnames.

  • Component child bloqs are referenced by shortname.

Example export

{
  "bloqs_export_version": 1,
  "source": {
    "bloqs_version": "5.5.0"
  },
  "block_definitions": [
    {
      "shortname": "hero",
      "name": "Hero",
      "instructions": "A full-width hero banner.",
      "group": "Layout",
      "deprecated": 0,
      "deprecated_note": "",
      "preview_image": "",
      "preview_icon": "image",
      "is_component": 0,
      "is_editable": 0,
      "settings": {
        "nesting": {
          "root": "any",
          "child_of": ["section"],
          "no_children": "y"
        }
      },
      "atom_definitions": [
        {
          "shortname": "headline",
          "name": "Headline",
          "instructions": "",
          "order": 0,
          "type": "text",
          "settings": { "field_fmt": "none", "col_required": "y" }
        },
        {
          "shortname": "related",
          "name": "Related Entry",
          "instructions": "",
          "order": 1,
          "type": "relationship",
          "settings": { "channels": ["3"], "authors": [], "limit": "1" }
        }
      ]
    }
  ]
}

A component bloq also carries a component_children array listing the child bloqs by shortname along with their tree position (order, depth, parent_id, lft, rgt, cloneable).

The bloqs_export_version field is the format version. A site running an older version of Bloqs refuses a file whose version is newer than it understands.

Importing

Use the Import screen to upload an exported file. You upload the file and choose options, then see a preview of exactly what will happen. Nothing is written until you confirm.

The import options

Definition File (required): the JSON file you exported.

Preserve Site-Specific Settings (off by default): when off, field settings that reference site-specific IDs are reset to safe defaults. Turn it on only when the target site shares the same channel, upload-directory, and field IDs as the source, such as a local-to-production sync of the same site. See "The site-specific settings rule" below.

Update Existing Definitions (off by default): when off, a matching shortname is imported as a renamed copy. When on, matching bloqs are updated in place. See "Adding vs. updating" below.

Remove Atoms Not In File (off by default, only applies when "Update Existing" is on): deletes fields on the target that aren't in the file. This is destructive, since deleting a field also deletes its content in every entry that uses it. The preview shows which fields would be deleted and how many entries would lose content.

The preview

Before committing, you get a dry-run summary:

  • Will be created: definitions that don't exist on the target.

  • Will be updated: existing definitions updated in place (only when "Update Existing" is on).

  • Renamed to avoid collisions: definitions whose shortname already exists and will get a numeric suffix.

  • Fields needing reconfiguration: fields whose site-specific settings will be reset.

  • Atoms to be deleted: fields that will be removed, each with the count of affected entries.

The rules: adding, updating, deleting

Adding (the default)

With "Update Existing" off, every definition is created new. If a shortname already exists on the target (whether from another bloq or a native channel field), the imported copy gets a unique suffix: hero becomes hero_2, then hero_3. An import can never overwrite existing data this way; the worst case is a renamed duplicate. References within the import (nesting, component children) are rewired to point at the renamed copies.

Updating (opt-in)

With "Update Existing" on, a definition whose shortname matches one on the target is updated in place. This updates the bloq and its fields:

  • The bloq's own properties (name, instructions, group, deprecation, preview image/icon, component flags, nesting settings) are overwritten from the file.

  • Each field is matched by shortname within that bloq:

    • A field on both is updated in place, keeping its existing database ID. Since entry content is tied to that ID, no content is lost.

    • A field in the file but not on the target is created.

    • A field on the target but not in the file is left untouched by default.

Deleting (explicit, destructive)

An import never deletes anything unless you ask. The only deletion path is "Remove Atoms Not In File", available only in update mode. When enabled, fields on the target but absent from the file are deleted, and deleting a field cascades to its content in every entry. The preview lists each field with its entry-usage count. Whole definitions are never deleted by an import; to remove a bloq, use the delete action on the Bloqs listing (which is blocked while the bloq is in use).

The site-specific settings rule

Some field types store references identified by site-local IDs: relationship fields point at channels, categories, statuses, and authors; file and Assets fields point at upload directories. These IDs are meaningless on a different site.

Unless "Preserve Site-Specific Settings" is on, the importer resets these references to safe empty defaults for the affected types (relationship, file, file_grid, assets). The field is imported intact and usable, just unconfigured for those references, which you reconnect on the target. The preview lists every affected field. The rest of a field's settings (label, limits, required, formatting) are always preserved.

Turn this option on only when the target's IDs match the source's, typically a local-to-production sync of the same site.

The renamed_from nuance

The importer matches definitions and fields by shortname. If you rename headline to title in the source and import with "Update Existing" on, the importer can't tell title is the old headline. It sees headline as gone and title as new, so it creates a new empty title and leaves the old field alone.

To handle a rename, add a renamed_from property by hand to that entry in the JSON before importing. It tells the importer: if you can't find my current shortname, look for this old one and update that record in place.

With this and "Update Existing" on, the importer finds the existing headline field, updates it in place (keeping its ID and all entry content), and changes its shortname to title. The same works at the bloq level: "renamed_from": "hero" with "shortname": "hero_banner" updates the existing hero bloq and renames it.

Notes on renamed_from:

  • It's matched only as a fallback. The current shortname is tried first, so it's harmless to leave in a file you re-import.

  • It's supplied by hand. Bloqs doesn't auto-detect renames or write renamed_from into exports, because the database keeps no rename history.

  • It works safely with "Remove Atoms Not In File": a field matched via renamed_from has its old shortname treated as accounted for, so the remove step won't delete it.

Within a single site you never need renamed_from. Just rename the field in the control panel; content is tied to the field's ID, so nothing is lost. renamed_from exists only for cross-site imports, where the two sites share no ID and the shortname is the only stable key.

Last updated