CreateStructureOnly – minimal page scaffold

The CreateStructureOnly helper in AgentToolPage is a minimal building block used by the TypeStack Agent. Instead of creating a full page (structure, translation, page, grid, content), this helper focuses on just two tables:

• cms_structure
• cms_structure_translations

This is useful for debugging and for simple scenarios where we only need a new menu / structure item with a title and slug. If this minimal insert works reliably, the same logic can be used as a stable foundation for full page creation.

The helper is exposed through the Agent as a dedicated operation: sTool = "page" with sMode = "create-structure-only". It can be called from the Magic prompt using JSON with aOperations.

API contract – CreateStructureOnly

Invocation via Agent / Magic prompt

The operation is triggered with:

• sTool: "page"
• sMode: "create-structure-only"
• aArgs: arguments for the structure, translation, and cache context

Example JSON payload for the Magic prompt:

{ "aOperations": [ { "sTool": "page", "sMode": "create-structure-only", "aArgs": { "iInstanceID": 70, "sTitle": "Gerards Testpagina – alleen structure", "sSubtitle": "", "sDescription": "Test vanuit CreateStructureOnly", "iParentStructureID": 1 } } ]
}

Supported arguments (aArgs)

• iInstanceID (int, strongly recommended)
  The instance in which the new structure must be created.
  Required for correct database writes and for clearing the route/website cache. You can obtain this value through the env tool.
• sTitle (string, optional but recommended)
  Used as translation_title. If omitted, a generic "New Agent Structure" is used.
• sSubtitle (string, optional)
  Stored in translation_subtitle.
• sDescription (string, optional)
  Stored in translation_description.
• sCase (string, optional)
  If provided, used as translation_case (slug). If omitted, the system auto-generates a slug via GenerateSlug().
• iParentStructureID (int, optional)
  Parent structure ID for the new structure. Defaults to 1, which is typically the root menu item.

Context from session

Additional context is resolved from the active CMS session:

• iSubstanceID – the active substance (frontend site variant)
• iLanguageID – the current language (defaults to 1)

If iInstanceID or iSubstanceID cannot be resolved, the helper aborts and returns an error.

Database writes

1. Insert into cms_structure

A new structure row is added with the following values:

• structure_parent_id = iParentStructureID
• structure_substance_id = iSubstanceID
• structure_type_id = 2
• structure_route_id = 0
• structure_link_url = NULL
• structure_link_type_id = 1
• structure_icon, structure_css, structure_class = NULL
• structure_order = 9999
• structure_status_id = 1
• structure_hidden = 0

2. Insert into cms_structure_translations

A language-specific translation row is added:

• translation_structure_id = new structure_id
• translation_title = sTitle
• translation_case = sCase or auto-generated slug
• translation_subtitle = sSubtitle
• translation_description = sDescription
• translation_language_id = resolved iLanguageID
• translation_structure_status_id = 1

Website cache & routing

After creating a structure and translation, the Agent will clear the frontend website cache for the correct instance. This mirrors the internal behaviour of TypeStack's CMS_Page::SavePage().

The Agent calls:

\Cache::ClearWebsiteCache($iInstanceID);

Without this step, the page will exist in the database but the router will not recognise the slug until the CMS saves the page manually.

Response format & debugging

The helper returns structured debug information for analysis.

Successful response example

{ "bSuccess": true, "sTool": "page", "sMode": "create-structure-only", "sMessage": "Structure + translation created successfully (CreateStructureOnly).", "iStructureID": 123, "iTranslationID": 456, "aArgs": { "iInstanceID": 70, "sTitle": "Gerards Testpagina – alleen structure", "iParentStructureID": 1 }, "aDebug": [ "Resolved instance = 70, substance = 1, language = 1", "Insert cms_structure OK", "Insert cms_structure_translations OK", "Website cache cleared for instance 70" ]
}

Common failure scenarios

1. Incorrect or missing iInstanceID

If the wrong instance ID is provided, the page will appear in the CMS but not on the frontend, because the wrong router cache is cleared.

2. Missing substance or language context

Occurs when the Agent is invoked outside an active CMS session.

3. Invalid JSON input

When pasting JSON, ensure the Magic prompt does not HTML-encode quotes or line breaks.

Next steps – from structure-only to full pages

Once CreateStructureOnly works reliably, the same arguments (especially iInstanceID) power the full CreatePage() operation.

Full page creation includes:

• structure + translation
• cms_pages entry
• template slide generation
• initial content placement
• cache clearing (mandatory)

If a page exists in the CMS but not the frontend, it is always cache-related and never a database error.

CreatePage – full automated page creation

The CreatePage helper in AgentToolPage performs the full automated creation of a frontend page inside a TypeStack instance. Unlike CreateStructureOnly, which only inserts a structure and a translation, the full page workflow includes:

• creating a cms_structure entry
• creating a cms_structure_translations entry
• creating a cms_pages entry
• generating cms_page_grid rows based on the chosen template
• optionally inserting cms_content for an initial slide
• clearing the website cache for the correct instance

This workflow is the equivalent of creating a page through the CMS interface, selecting a template, and saving the page — but fully automated, triggered by the Magic prompt.

API contract – CreatePage

Invocation via Magic prompt

The operation is triggered by:

• sTool: "page"
• sMode: "create-page"
• aArgs: arguments defining the new page

Example JSON payload:

{ "aOperations": [ { "sTool": "page", "sMode": "create-page", "aArgs": { "iInstanceID": 70, "sTitle": "Gerards Fietsenwinkel", "sSubtitle": "De beste fietsen in Vriezenveen", "sDescription": "Service, onderhoud en advies", "sCase": "gerards-fietsenwinkel", "sContentHTML": "<h1>Welkom bij Gerards Fietsenwinkel</h1>", "iParentStructureID": 1, "iTemplateID": 1 } } ]
}

Supported arguments (aArgs)

• iInstanceID (int, strongly recommended)
  Identifies the TypeStack instance in which the page is created. Required for correct database writes and for clearing the router/website cache. Obtainable via the env tool.
• sTitle (string)
  Display title for both the structure translation and page metadata.
• sSubtitle (string, optional)
  Added to cms_structure_translations.
• sDescription (string, optional)
  Used as a long description for the menu/page.
• sCase (string, optional)
  The slug (URL segment). If omitted, a slug is auto-generated from sTitle.
• sContentHTML (string, optional)
  HTML content to insert into one slide of the template. If no content is provided, no cms_content is inserted.
• iParentStructureID (int, optional)
  The parent structure ID. Defaults to the root item 1.
• iTemplateID (int, required)
  Determines which slides are generated in cms_page_grid.

Database writes

1. Insert into cms_structure

A new structure node is created, identical to creating a menu item manually in the CMS. Values include:

• structure_parent_id = iParentStructureID
• structure_substance_id = resolved substance
• structure_type_id = 2
• structure_order = 9999
• structure_hidden = 0

The new structure_id is returned as iStructureID.

2. Insert into cms_structure_translations

A new translation row is created for the chosen language:

• translation_structure_id = iStructureID
• translation_title, translation_case
• translation_subtitle, translation_description
• translation_language_id

3. Insert into cms_pages

A page container is created and linked to the chosen template.

• page_structure_id = iStructureID
• page_substance_id = resolved substance
• page_template_id = iTemplateID

The returned page_id is used when generating slides.

4. Generate slides via cms_page_grid

The template may define one or multiple slides (header, content, footer, …). For each enabled slide (status ID = 1), a corresponding cms_page_grid entry is generated.

Example: Template 1 may define:

• Slide 35 – Header
• Slide 36 – Content
• Slide 22 – Footer

All slides are created automatically.

5. Insert initial cms_content (optional)

If sContentHTML is provided:

• the system determines a default target slide (the middle slide for a 3-slide template)
• a cms_content row is created containing the HTML

If no HTML is provided, no cms_content is inserted.

Website cache & routing

After creating the page, slides and optional content, the Agent clears the website cache for the correct instance:

\Cache::ClearWebsiteCache($iInstanceID);

This mirrors CMS_Page::SavePage() behaviour and ensures:

• the new slug becomes instantly available
• the router rebuilds the structure tree
• menu items appear without manual cache reset

Without this step, the database would contain the new page but the frontend router would not recognise it until a manual SavePage or a backend cache clear.

Response format & debugging

The Agent returns a detailed structured response.

Successful response example

{ "bSuccess": true, "sMessage": "Page created successfully.", "iStructureID": 42, "iTranslationID": 42, "iPageID": 37, "iGridID": 2168, "iContentID": 270, "aDebug": [ "Context: iInstanceID=70, iSubstanceID=1, iLanguageID=1", "Insert cms_structure OK", "Insert cms_structure_translations OK", "Insert cms_pages OK", "Slides generated: 35, 36, 22", "Content inserted into slide 36", "Website cache cleared for instance 70" ]
}

Common failure scenarios

1. Missing or incorrect iInstanceID

The page will appear in the CMS but not on the live website if the wrong instance is used. Always ensure iInstanceID matches the current application.

2. Missing template slides

If a template has no active slides (status ID ≠ 1), the page will be created without layout. The debug output will explicitly list “No template grid row found”.

3. JSON formatting or upload issues

When pasting large JSON payloads, ensure the browser does not insert HTML entities like ".

Best practices

• Always provide iInstanceID explicitly.
• Use the env tool to verify instance/substance context.
• Include sContentHTML only for the main content slide.
• Rely on CreateStructureOnly first when debugging.
• Use clear slugs (no spaces, lowercase).

With these guidelines, CreatePage() behaves exactly like a CMS-created page — but fully automated.