TypeStack Magic – Page & Content Operations

The TypeStack Magic Agent can create and update pages, structure, translations, grids and content using a single JSON payload. This document describes how to use the page tool modes via the Magic prompt.

1. Core Concepts

  • Structure first: every page lives under a cms_structure row (menu item / tree node).
  • Translations: titles, subtitles, descriptions and slugs live in cms_structure_translations.
  • Pages: the actual page row (template, status) lives in cms_pages, linked via page_structure_id.
  • Grids & slides: cms_page_grid connects a page to one or more slides from the template.
  • Content: HTML blocks live in cms_content, usually per slide per page.

The most important relationship is:

iStructureID + iPageID = full page context (menu + page + content)

Most operations accept either iStructureID or iPageID (or both). If only one is provided, the Agent resolves the other based on the database.

2. Available Modes for the page Tool

  • create-page – create structure, translation, page, grid and optional content in one go.
  • create-structure-only – create only a new structure node + translation (no page/content).
  • update-translation – update title, subtitle, description and slug for a structure.
  • update-structure – move a structure node, change status or order.
  • update-page – change template and/or status of a page.
  • update-grid – reorder existing cms_page_grid rows.
  • update-content – replace or append HTML content on a specific slide of a page.

All modes are invoked via the Magic prompt using an aOperations array:

{ "aOperations": [ { "sTool": "page", "sMode": "...", "aArgs": { ... } } ]
}

3. Creating a New Page (create-page)

create-page creates:

  • cms_structure (menu item)
  • cms_structure_translations (title, slug, etc.)
  • cms_pages (page row)
  • cms_page_grid rows based on the chosen template
  • optional cms_content rows via the content helper
{ "aOperations": [ { "sTool": "page", "sMode": "create-page", "aArgs": { "iInstanceID": 70, "sTitle": "TypeStack Magic – Agent Playground", "sSubtitle": "A live lab for AI-assisted pages", "sDescription": "A playground page where the Agent can create and update structure, translations, templates and content using JSON instructions.", "sCase": "typestack-magic-agent-playground", "sContentHTML": "<h1>Welcome to the Agent Playground</h1>\n<p>This page was created entirely by the TypeStack Magic Agent. The menu item, page record, template grid and this content block were all generated from a single JSON operation.</p>\n<p>Use this page as a safe space to test new operations, layouts and content flows without touching any core classes.</p>", "iParentStructureID": 1, "iTemplateID": 1 } } ]
}

The Agent:

  1. Inserts a new row into cms_structure under structure_parent_id = iParentStructureID.
  2. Creates the translation row with sTitle, sCase, sSubtitle and sDescription.
  3. Creates the page row in cms_pages with page_template_id = iTemplateID.
  4. Builds grid rows in cms_page_grid from the chosen template.
  5. Delegates to the content helper to inject sContentHTML into the designated content slide.

4. Updating Translations (update-translation)

update-translation manages everything in cms_structure_translations for a given structure + language:

  • translation_title
  • translation_case (slug)
  • translation_subtitle
  • translation_description

You can refer to the page by iStructureID or iPageID. If only one is provided, the Agent resolves the other. The language defaults to the current frontend language, unless you pass iLanguageID.

{ "aOperations": [ { "sTool": "page", "sMode": "update-translation", "aArgs": { "iStructureID": 79, "sTitle": "TypeStack Magic – Agent Playground", "sSubtitle": "A live lab for AI-powered pages", "sDescription": "This page is used as a live playground for TypeStack Magic. The Agent can update structure, translations, templates and content on top of the existing TypeStack core – without touching the core classes.", "sCase": "typestack-magic-agent-playground" } } ]
}

If a translation row already exists for this structure + language, it is updated. Otherwise, a new translation row is inserted.

5. Updating Structure (update-structure)

update-structure updates the cms_structure row for a page:

  • structure_parent_id (move in the menu tree)
  • structure_status_id (active/inactive)
  • structure_order (sorting within the parent)
{ "aOperations": [ { "sTool": "page", "sMode": "update-structure", "aArgs": { "iStructureID": 79, "iParentStructureID": 1, "iStructureStatusID": 1, "iOrder": 950 } } ]
}

This keeps the tree consistent: the page stays linked to the same structure, while the structure itself moves or changes status.

6. Updating the Page Row (update-page)

update-page modifies the cms_pages row associated with a structure:

  • page_template_id via iTemplateID
  • page_status_id via iStatusID

You can pass either iStructureID, iPageID or both:

  • If only iPageID is given, the Agent resolves iStructureID from page_structure_id.
  • If only iStructureID is given, the Agent looks up the corresponding page_id.
  • If both are given, the Agent validates that they actually belong together.
{ "aOperations": [ { "sTool": "page", "sMode": "update-page", "aArgs": { "iStructureID": 79, "iTemplateID": 1, "iStatusID": 1 } } ]
}

This keeps the relation iStructureID + iPageID consistent while changing the presentation template or status.

7. Updating Grid Order (update-grid)

update-grid updates one or more rows in cms_page_grid to change the order of slides within a page. It takes an array of updates with iGridID and iOrder:

{ "aOperations": [ { "sTool": "page", "sMode": "update-grid", "aArgs": { "aGridUpdates": [ { "iGridID": 2258, "iOrder": 1 }, { "iGridID": 2259, "iOrder": 2 } ] } } ]
}

Each entry translates to a simple:

UPDATE cms_page_grid
SET grid_order = :iOrder
WHERE grid_id = :iGridID;

8. Updating Content (update-content)

update-content replaces (or appends) HTML content for a single slide on a page. It works in two phases:

  1. Optional: deactivate existing content rows on the slide.
  2. Insert a new cms_content row with the provided HTML.

Required parameters:

  • iPageID – the page ID
  • iSlideID – the slide ID used in cms_page_grid
  • sContentHTML – the new HTML content

Optional:

  • bReplaceAllOnSlide – if true, all existing active rows on that slide are set to content_status_id = 0 before inserting the new row.
{ "aOperations": [ { "sTool": "page", "sMode": "update-content", "aArgs": { "iPageID": 68, "iSlideID": 36, "bReplaceAllOnSlide": true, "sContentHTML": "<h1>Agent Playground – Updated Content</h1>\n<p>This slide is now fully controlled by the TypeStack Magic Agent. All previous content blocks on this slide were deactivated, and this fresh HTML block was inserted as a new content row.</p>\n<p>You can repeat this operation as often as you like to experiment with layouts, messaging and structure – the Agent will keep the history of content rows in the database.</p>" } } ]
}

Internally, the Agent:

  1. Optionally sets content_status_id = 0 for all active rows on that page + slide.
  2. Determines content_initial_id by looking at the latest existing row for that page + slide.
  3. Inserts a new cms_content row with HTML, basic sizing and timestamps.

9. Example: Full Update Flow for an Existing Page

The following example shows a complete update flow for an existing page linked to structure_id = 79:

  1. Update the translation (title, subtitle, description, slug).
  2. Make sure the structure is active and correctly positioned.
  3. Set the correct template and page status.
  4. Replace the main content on the designated content slide.
{ "aOperations": [ { "sTool": "page", "sMode": "update-translation", "aArgs": { "iStructureID": 79, "sTitle": "TypeStack Magic – Agent Playground", "sSubtitle": "A live lab for AI-powered pages", "sDescription": "A safe playground where the TypeStack Magic Agent can create and update structure, translations, templates and content using JSON instructions on top of the existing core.", "sCase": "typestack-magic-agent-playground" } }, { "sTool": "page", "sMode": "update-structure", "aArgs": { "iStructureID": 79, "iParentStructureID": 1, "iStructureStatusID": 1, "iOrder": 950 } }, { "sTool": "page", "sMode": "update-page", "aArgs": { "iStructureID": 79, "iTemplateID": 1, "iStatusID": 1 } }, { "sTool": "page", "sMode": "update-content", "aArgs": { "iPageID": 68, "iSlideID": 36, "bReplaceAllOnSlide": true, "sContentHTML": "<h1>Agent Playground</h1>\n<p>This page is fully managed by the TypeStack Magic Agent. Structure, translations, templates and content can all be controlled through a single JSON instruction in the Magic prompt.</p>\n<p>Use this playground to iterate on new page types, layouts and content flows without touching core classes or manual CMS forms.</p>\n<h2>What you can test here</h2>\n<ul>\n <li>Moving the page around in the menu tree with <code>update-structure</code>.</li>\n <li>Renaming the page and changing its slug with <code>update-translation</code>.</li>\n <li>Switching templates or toggling status with <code>update-page</code>.</li>\n <li>Reordering slides and replacing content blocks with <code>update-grid</code> and <code>update-content</code>.</li>\n</ul>\n<p>Everything remains consistent with the existing TypeStack core – the Agent only talks to the database the way the CMS already expects it.</p>" } } ]
}

With these operations, the Agent can safely manage pages end-to-end: from menu structure and SEO texts to templates, slide ordering and rich HTML content – all by sending structured JSON into the Magic prompt.

10. Recommended workflow for creating and activating pages

To avoid accidentally creating multiple versions of the same page (for example with identical slugs), it is important to follow a clear workflow when using the create-page mode.

10.1 What create-page does by default

The create-page mode is a compound operation. A single JSON instruction can create:

  • a new cms_structure record (menu node),
  • a cms_structure_translations record (title, subtitle, description, slug),
  • a cms_pages record (page entry),
  • one or more cms_page_grid records derived from the chosen template,
  • initial cms_content rows for the main content slide (when sContentHTML is provided).

Because all these records are created at once, it is strongly recommended to:

  1. Choose a unique sCase value (slug) for each page. Reusing the same slug for multiple pages can make routing and maintenance confusing.
  2. Check if a page with the same sCase already exists before running create-page. This can be done by:
    • verifying the existing structure in the CMS dashboard, or
    • searching for the slug/route in the frontend and/or internal tools.

In future scenarios, the Agent can be extended with a dedicated “find page by slug” tool, but the recommended practice remains the same: do not blindly call create-page for slugs that may already exist.

10.2 Activating structure and page after creation

A newly created page is not always immediately visible in the site navigation. While create-page prepares all database records, you may still need to activate and position the structure and page explicitly.

After running create-page, the recommended second step is:

  1. Use update-structure to:
    • set iStructureStatusID = 1 (active), and
    • assign a suitable iOrder value to control menu position.
  2. Use update-page to:
    • ensure iStatusID = 1 (page active), and
    • optionally adjust iTemplateID if the template needs to change.

This two-step activation pattern makes the workflow predictable:

  • create-page – create all core records;
  • update-structure + update-page – activate and position the page for real-world use.
{ "aOperations": [ { "sTool": "page", "sMode": "create-page", "aArgs": { "iInstanceID": 70, "sTitle": "Docs – TypeStack Magic Overview", "sSubtitle": "Entry point for all Magic documentation", "sDescription": "Overview page that links to all documentation chapters for the TypeStack Magic Agent.", "sCase": "docs-typestack-magic-overview", "sContentHTML": "<h1>TypeStack Magic – Documentation Overview</h1>\n<p>Use this page as a starting point to explore all chapters about the TypeStack Magic Agent.</p>", "iParentStructureID": 1, "iTemplateID": 1 } }, { "sTool": "page", "sMode": "update-structure", "aArgs": { "iStructureID": 79, "iParentStructureID": 1, "iStructureStatusID": 1, "iOrder": 900 } }, { "sTool": "page", "sMode": "update-page", "aArgs": { "iStructureID": 79, "iTemplateID": 1, "iStatusID": 1 } } ]
}

In this example:

  • create-page creates the overview page and its base content;
  • update-structure activates the menu item and positions it at order 900 under the root;
  • update-page confirms template 1 and sets the page status to active.

11. Creating a documentation overview page

It is often useful to have a dedicated overview page that lists all documentation chapters and links to their individual pages. This creates a clear table of contents for users.

To create such an overview page, you can:

  1. Create a new page (for example “Docs – Magic Overview”).
  2. Fill sContentHTML with a list of chapters (<ul><li> items) linking to each detail page.
  3. Activate the structure and page using update-structure and update-page.

Example:

{ "aOperations": [ { "sTool": "page", "sMode": "create-page", "aArgs": { "iInstanceID": 70, "sTitle": "TypeStack Magic – Docs Overview", "sSubtitle": "All chapters in one place", "sDescription": "Central index page that links to all TypeStack Magic documentation chapters.", "sCase": "typestack-magic-docs-overview", "sContentHTML": "<h1>TypeStack Magic – Documentation Overview</h1>\n<p>Use this page as a starting point to explore all chapters about the TypeStack Magic Agent.</p>\n<h2>Chapters</h2>\n<ul>\n <li><a href="/typestack-magic-agent-playground">Agent Playground</a> – Try out page creation and updates in a safe environment.</li>\n <li><a href="/typestack-magic-page-operations">Page & Content Operations</a> – In-depth guide to create-page, update-structure, update-page, update-grid and update-content.</li>\n <li><a href="/typestack-magic-tools">Tools & Modes</a> – Overview of all available tools and modes used by the Agent.</li>\n</ul>\n<p>You can add or remove chapters here at any time. The Agent can also update this list via <code>update-content</code> if you prefer to manage it programmatically.</p>", "iParentStructureID": 1, "iTemplateID": 1 } }, { "sTool": "page", "sMode": "update-structure", "aArgs": { "iStructureID": 79, "iParentStructureID": 1, "iStructureStatusID": 1, "iOrder": 910 } }, { "sTool": "page", "sMode": "update-page", "aArgs": { "iStructureID": 79, "iTemplateID": 1, "iStatusID": 1 } } ]
}

This overview page acts as a hub: each list item links to an existing chapter page, and the Agent can update the list over time using update-content on the same slide. In this way, your documentation stays discoverable and consistent without manual copy-paste work in the CMS forms.