From 667c22f0bc66a0ce5dd8a90780899804b2c56a99 Mon Sep 17 00:00:00 2001 From: Zhongwei Li Date: Sun, 30 Nov 2025 08:50:04 +0800 Subject: [PATCH] Initial commit --- .claude-plugin/plugin.json | 12 + README.md | 3 + plugin.lock.json | 125 +++ skills/firstspirit-templating/SKILL.md | 225 ++++ .../references/firstspirit-topics.json | 605 +++++++++++ .../references/format-templates.md | 280 +++++ .../references/general-structure.md | 347 ++++++ .../references/link-templates.md | 146 +++ .../references/metadata.md | 462 ++++++++ .../references/page-templates.md | 260 +++++ .../references/rules.md | 689 ++++++++++++ .../references/script-templates.md | 242 +++++ .../references/section-templates.md | 275 +++++ .../references/snippets.md | 364 +++++++ .../references/table-templates.md | 228 ++++ .../references/template-development-basics.md | 304 ++++++ .../references/template-structure.md | 437 ++++++++ .../references/template-syntax-expressions.md | 715 +++++++++++++ .../references/template-syntax-functions.md | 479 +++++++++ .../template-syntax-instructions.md | 989 ++++++++++++++++++ .../template-syntax-system-objects.md | 804 ++++++++++++++ .../references/template-wizard.md | 420 ++++++++ .../references/variables.md | 336 ++++++ .../references/workflows.md | 313 ++++++ 24 files changed, 9060 insertions(+) create mode 100644 .claude-plugin/plugin.json create mode 100644 README.md create mode 100644 plugin.lock.json create mode 100644 skills/firstspirit-templating/SKILL.md create mode 100644 skills/firstspirit-templating/references/firstspirit-topics.json create mode 100644 skills/firstspirit-templating/references/format-templates.md create mode 100644 skills/firstspirit-templating/references/general-structure.md create mode 100644 skills/firstspirit-templating/references/link-templates.md create mode 100644 skills/firstspirit-templating/references/metadata.md create mode 100644 skills/firstspirit-templating/references/page-templates.md create mode 100644 skills/firstspirit-templating/references/rules.md create mode 100644 skills/firstspirit-templating/references/script-templates.md create mode 100644 skills/firstspirit-templating/references/section-templates.md create mode 100644 skills/firstspirit-templating/references/snippets.md create mode 100644 skills/firstspirit-templating/references/table-templates.md create mode 100644 skills/firstspirit-templating/references/template-development-basics.md create mode 100644 skills/firstspirit-templating/references/template-structure.md create mode 100644 skills/firstspirit-templating/references/template-syntax-expressions.md create mode 100644 skills/firstspirit-templating/references/template-syntax-functions.md create mode 100644 skills/firstspirit-templating/references/template-syntax-instructions.md create mode 100644 skills/firstspirit-templating/references/template-syntax-system-objects.md create mode 100644 skills/firstspirit-templating/references/template-wizard.md create mode 100644 skills/firstspirit-templating/references/variables.md create mode 100644 skills/firstspirit-templating/references/workflows.md diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..622c32b --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,12 @@ +{ + "name": "firstspirit-templating", + "description": "Comprehensive knowledge for templating in the FirstSpirit CMS, specifically focused on SiteArchitect development. Covers page templates, section templates, format templates, link templates, input components, template syntax, system objects, rules, and workflows.", + "version": "1.0.0", + "author": { + "name": "rawe", + "email": "noreply@example.com" + }, + "skills": [ + "./skills" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..b023d29 --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# firstspirit-templating + +Comprehensive knowledge for templating in the FirstSpirit CMS, specifically focused on SiteArchitect development. Covers page templates, section templates, format templates, link templates, input components, template syntax, system objects, rules, and workflows. diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..3154b60 --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,125 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:rawe/claude-dev-skills:firstspirit-templating", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "49087a05cee50a300b86c89428a05e9684b33903", + "treeHash": "7e824a12f4ec8a3589f470d88b9f28257a4da0f3dbda5466c2cc61af424dd1b4", + "generatedAt": "2025-11-28T10:27:49.001890Z", + "toolVersion": "publish_plugins.py@0.2.0" + }, + "origin": { + "remote": "git@github.com:zhongweili/42plugin-data.git", + "branch": "master", + "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390", + "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data" + }, + "manifest": { + "name": "firstspirit-templating", + "description": "Comprehensive knowledge for templating in the FirstSpirit CMS, specifically focused on SiteArchitect development. Covers page templates, section templates, format templates, link templates, input components, template syntax, system objects, rules, and workflows.", + "version": "1.0.0" + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "fda89ffd384f69d19e969833f65dec9d187662a2242ed79e9527ef388099bd28" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "6a7542a1a38106a7c9f67960ede7fbe194e5d751dbcde4a7e33f4ead3a7f2e40" + }, + { + "path": "skills/firstspirit-templating/SKILL.md", + "sha256": "86b9d4edce692ea06b2465ab36a24f50fdf742db60ec725a771e2fa3b597d347" + }, + { + "path": "skills/firstspirit-templating/references/firstspirit-topics.json", + "sha256": "0ceb0e4c95207895b753e47ffb30b4b30fd2c0c468bb352c2a77e7102cf6e35d" + }, + { + "path": "skills/firstspirit-templating/references/workflows.md", + "sha256": "e53bfb8b675d55713d7d28d9cda3a2518f7d63fcc509ef56ced257207e22cd96" + }, + { + "path": "skills/firstspirit-templating/references/snippets.md", + "sha256": "254d614724759ba9da1d4a87862304b427dbcc9d418dffdca4eaebe33f6e4b0d" + }, + { + "path": "skills/firstspirit-templating/references/template-syntax-expressions.md", + "sha256": "174364cd4e8705882929bd38178688bdb402386036fb69aad71246c3e2991687" + }, + { + "path": "skills/firstspirit-templating/references/general-structure.md", + "sha256": "0e6b13e32f6ba262d86366c84476b7743b2f04c06438436c835198a35a8b1d8c" + }, + { + "path": "skills/firstspirit-templating/references/script-templates.md", + "sha256": "e16182425af075dc018326308090effb69598563f62a9a1292501def6cd43c59" + }, + { + "path": "skills/firstspirit-templating/references/template-syntax-functions.md", + "sha256": "1b6e2e80c46ac7b35b278563a2d0145678d44d5ccb7f3edca53285404aa489aa" + }, + { + "path": "skills/firstspirit-templating/references/format-templates.md", + "sha256": "32db85fd16b5b0fccd6d4299c10bc7d11f54ce803caf29c7914ba025903ee225" + }, + { + "path": "skills/firstspirit-templating/references/section-templates.md", + "sha256": "9f079656d1302b20c2a98a59a7495e53e770c82bb028f0a7f70b84fdad34d22c" + }, + { + "path": "skills/firstspirit-templating/references/table-templates.md", + "sha256": "14100294b30f0636f5ae4fb7c710c27b88904b4e7ed595a6db5155283e2aedd4" + }, + { + "path": "skills/firstspirit-templating/references/template-development-basics.md", + "sha256": "e52a1c0ab5e6d10f177a7b6c98e7106221cf68adea708508c3401bad88f2a0e3" + }, + { + "path": "skills/firstspirit-templating/references/template-syntax-system-objects.md", + "sha256": "bf6ee00a2c308dde356b7f66c8e5e41ce532355104fa90ab9247c2d82e3ce399" + }, + { + "path": "skills/firstspirit-templating/references/link-templates.md", + "sha256": "1a4313ea13e8c1bf8f20d0adbfeae5a4b5a1253ebb192a7e1d1aa88c5acb3a27" + }, + { + "path": "skills/firstspirit-templating/references/metadata.md", + "sha256": "36ba7914edc73872fb7eb05788e09eac490483d2d4b5617f052ace9032e7ff74" + }, + { + "path": "skills/firstspirit-templating/references/template-structure.md", + "sha256": "29a2b9d4a9f6cd018f8bb6112dbd5aaae5de0ebdd31518e864c4fa681fdca081" + }, + { + "path": "skills/firstspirit-templating/references/rules.md", + "sha256": "533625b1c1db18b0245ebc402e2e3ca1e642d3596e41b6ed80c4786f7b1da40d" + }, + { + "path": "skills/firstspirit-templating/references/page-templates.md", + "sha256": "3170fd322d6a81fcd9e64abff438c4be0fcf5c45bb120229362949eeb9ec71a4" + }, + { + "path": "skills/firstspirit-templating/references/variables.md", + "sha256": "60cde41ba311bbd7fb17644024570793d5b06030eda1fea3b1ff6b1ecf0ab8fd" + }, + { + "path": "skills/firstspirit-templating/references/template-syntax-instructions.md", + "sha256": "61ed71ccc3df63841f69be7a45df690087af7ff31cca051e1bf02290d731eac6" + }, + { + "path": "skills/firstspirit-templating/references/template-wizard.md", + "sha256": "4f6bbd433998007aca3ed642889a2cc172861afdd74ff381366338142266dbdd" + } + ], + "dirSha256": "7e824a12f4ec8a3589f470d88b9f28257a4da0f3dbda5466c2cc61af424dd1b4" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file diff --git a/skills/firstspirit-templating/SKILL.md b/skills/firstspirit-templating/SKILL.md new file mode 100644 index 0000000..4f73c69 --- /dev/null +++ b/skills/firstspirit-templating/SKILL.md @@ -0,0 +1,225 @@ +--- +name: firstspirit-templating +description: This skill provides comprehensive knowledge for templating in the FirstSpirit CMS, specifically focused on SiteArchitect development. This skill should be used when working with FirstSpirit templates including page templates, section templates, format templates, link templates, input components, template syntax, system objects, rules, and workflows. The skill is organized as structured reference documentation with topics covering architecture, template types, syntax, and development practices. +--- + +# FirstSpirit Templating + +## Overview + +This skill provides comprehensive guidance for developing templates in FirstSpirit CMS using SiteArchitect. FirstSpirit uses a unique templating system that separates content, layout, and structure across multiple stores (Template Store, Content Store, Site Store, Media Store). Template development involves creating reusable components using FirstSpirit's template syntax, input components, and configuration options. + +## When to Use This Skill + +Use this skill when: +- Developing FirstSpirit templates (page, section, format, link templates) +- Working with FirstSpirit template syntax and instructions +- Configuring input components and forms in SiteArchitect +- Creating dynamic forms using rules and validation +- Implementing workflows and approval processes +- Working with FirstSpirit's store architecture +- Using system objects, variables, and functions in templates +- Debugging FirstSpirit templates + +## How to Use This Skill + +The skill organizes FirstSpirit templating knowledge into topic-specific reference files. When working on a specific aspect of FirstSpirit templating, read the relevant reference file(s) to gain detailed knowledge about that topic. + +## Reference Documentation Topics + +**IMPORTANT:** Read the reference and do not use your global knowledge about other templating systems, as FirstSpirit has its own unique concepts and syntax. + +### 1. Core Architecture + +**General Structure** (`references/general-structure.md`) +- FirstSpirit's six-store architecture (Template Store, Content Store, Site Store, Media Store, Global Settings) +- Separation of content and layout principles +- Core concepts: content-first approach, multi-user collaboration, multilingual architecture +- Best practices for organizing each store + +**Template Development Basics** (`references/template-development-basics.md`) +- Introduction to template development fundamentals +- Development tools: SiteArchitect, ContentCreator, debugging tools +- Template components overview (Forms, Rules, Snippets, Template Syntax) +- Development workflows and best practices + +**Template Structure** (`references/template-structure.md`) +- Template composition and organization +- Seven template types (page, section, format, link, scripts, database schemata, workflows) +- Five-tab structure (Properties, Form, Rules, Snippet, Template Set) +- Template development workflow from planning through deployment + +### 2. Template Types + +**Page Templates** (`references/page-templates.md`) +- Page template basics and framework structure +- Five-tab structure (Properties, Form, Rules, Snippet, Template Set) +- Input components for page configuration +- Content insertion locations for editors +- Snippet tab for preview content + +**Section Templates** (`references/section-templates.md`) +- Section template fundamentals +- Adding content to page framework +- Input components for dynamic content (text, images, tables, datasets) +- Template set architecture with CMS_HEADER and output areas +- Integration with page templates + +**Format Templates** (`references/format-templates.md`) +- Text formatting options for editors +- Section vs. individual text formatting +- Default format templates and HTML templates +- Table format templates with display rules and style application + +**Link Templates** (`references/link-templates.md`) +- Eight supported link types (internal, image, download, external, email, dataset, remote, image map) +- Five-area configuration structure +- Usage through input components (CMS_INPUT_LINK, CMS_INPUT_DOM, FS_CATALOG) +- Language handling and preview management + +**Script Templates** (`references/script-templates.md`) +- BeanShell scripting fundamentals +- Four-tab script configuration system +- Implementing custom functions +- Migration scenarios and external system integration + +**Table Templates** (`references/table-templates.md`) +- Database schema templates and abstraction layers +- Table template configuration (six configuration tabs) +- Database integration workflow from schema creation through query configuration +- Inline tables with format and style requirements + +**Workflows** (`references/workflows.md`) +- Workflow structure and configuration +- Approval and release processes +- BasicWorkflows module documentation +- Permissions, validation, and error handling + +### 3. Template Syntax + +**Instructions** (`references/template-syntax-instructions.md`) +- Complete reference for FirstSpirit template instructions +- Core instructions: $CMS_VALUE$, $CMS_SET$, $CMS_IF$, $CMS_FOR$, $CMS_SWITCH$ +- Template operations: $CMS_RENDER$, $CMS_INCLUDE$, $CMS_REF$ +- Control flow patterns and variable management +- Syntax, parameters, and usage examples for each instruction + +**Expressions and Data Types** (`references/template-syntax-expressions.md`) +- All FirstSpirit data types: Boolean, String, Number, Date, List, Map, Set +- Expression syntax and operations +- Lambda expressions and data transformations +- Type conversions and methods +- Real-world use cases for data manipulation + +**Functions** (`references/template-syntax-functions.md`) +- Template functions: editorId(), if() +- Function syntax and parameters +- ContentCreator content highlighting with editorId() +- Conditional logic with inline if() function +- Combining functions effectively + +**System Objects** (`references/template-syntax-system-objects.md`) +- Complete reference for FirstSpirit system objects +- #global (project/page/preview information) +- #field (form component access) +- #for (loop control) +- #style (table styling) +- #content (DOM Editor content) +- #this (context object) +- Practical code examples and common patterns + +**Variables** (`references/variables.md`) +- Variable identifier naming rules and conventions +- Variable definition in Form, Header, and Body areas +- Output methods using $CMS_VALUE$ and $CMS_REF$ +- Variable scope and lifecycle management +- Metadata variables with inheritance models + +### 4. Forms and Components + +**Rules and Dynamic Forms** (`references/rules.md`) +- Rules for creating dynamic forms +- Rule structure: execution timing, preconditions, value determination, handling +- Form properties manipulation +- Validation mechanisms with severity levels (SAVE, RELEASE, INFO) +- Practical examples: conditional visibility, dependent dropdowns, date validation +- Best practices for multi-language support and performance + +**Metadata** (`references/metadata.md`) +- Creating and configuring metadata templates +- System-assigned and user-defined metadata +- .meta() method for accessing metadata values +- Three inheritance modes (none, inherit, add) +- ELEMENTTYPE and TEMPLATE properties for dynamic forms +- SEO metadata and media-specific metadata examples + +**Snippets** (`references/snippets.md`) +- Snippet components: thumbnails, labels, extracts +- Snippet tab configuration +- Implementation patterns using form variables and methods +- Advanced techniques: empty checks, type validation, multilingual support +- Best practices for teaser design and preview content + +### 5. Development Tools + +**Template Wizard** (`references/template-wizard.md`) +- HTML import capabilities and automated component generation +- Form Builder functionality for reusable form templates +- Workflows for common scenarios +- Best practices for wizard-based template creation +- Limitations requiring manual SiteArchitect intervention + +## Official Documentation + +All reference files are based on official FirstSpirit documentation from e-Spirit/Crownpeak: +- **Main documentation:** https://docs.e-spirit.com/odfs/ +- **Template development:** https://docs.e-spirit.com/odfs/template-develo/ +- **Template basics:** https://docs.e-spirit.com/odfs/templates-basic/ +- **API documentation:** https://docs.e-spirit.com/odfs/access/ + +## Typical Development Workflow + +1. **Understand the architecture** - Start with `general-structure.md` and `template-development-basics.md` +2. **Choose template type** - Read the appropriate template reference (page, section, format, link) +3. **Learn the syntax** - Review template syntax instructions, expressions, and system objects +4. **Add interactivity** - Use rules and dynamic forms for advanced functionality +5. **Test and debug** - Use Template Inspector and FirstSpirit Debugger +6. **Deploy** - Follow workflow and release processes + +## Best Practices + +- **Separation of concerns**: Keep content (Content Store), layout (Template Store), and structure (Site Store) separate +- **Reusability**: Design section templates to be reusable across multiple pages +- **Multilingual support**: Always consider language handling in templates +- **Validation**: Use rules for form validation and provide clear error messages +- **Documentation**: Use meaningful variable names and add comments in templates +- **Testing**: Test templates in both SiteArchitect and ContentCreator environments +- **Performance**: Minimize complex calculations in templates; move logic to scripts or modules when appropriate + +## Common Use Cases + +### Creating a New Page Template +1. Read `page-templates.md` for structure +2. Review `input-components.md` for form elements (note: detailed component reference not included in this skill version) +3. Check `template-syntax-instructions.md` for output syntax +4. Use `snippets.md` for preview configuration + +### Building Dynamic Forms +1. Start with `rules.md` for dynamic form behavior +2. Review `variables.md` for state management +3. Check `metadata.md` for metadata integration +4. Reference `template-syntax-system-objects.md` for accessing form data + +### Working with Template Output +1. Review `template-syntax-instructions.md` for core instructions +2. Check `template-syntax-system-objects.md` for data access +3. Use `template-syntax-expressions.md` for data transformation +4. Reference `format-templates.md` and `link-templates.md` for content formatting + +## Getting Help + +When encountering issues: +1. Check the relevant reference file for detailed documentation +2. Review official FirstSpirit documentation links provided in reference files +3. Use the Template Inspector and Debugger tools in SiteArchitect +4. Verify template syntax and system object usage against the syntax references diff --git a/skills/firstspirit-templating/references/firstspirit-topics.json b/skills/firstspirit-templating/references/firstspirit-topics.json new file mode 100644 index 0000000..53b7860 --- /dev/null +++ b/skills/firstspirit-templating/references/firstspirit-topics.json @@ -0,0 +1,605 @@ +{ + "topics": [ + { + "topic_name": "general-structure", + "title": "FirstSpirit General Structure and Stores", + "description": "Overview of FirstSpirit's six-store architecture including Template Store, Content Store (Page Store/Data Store), Site Store, Media Store, and Global Content Area. Covers the separation of content and layout.", + "urls": [ + { + "url": "https://docs.e-spirit.com/odfs/templates-basic/basics/separation-cont/index.html", + "description": "Store structure in FirstSpirit - comprehensive overview of all six stores" + }, + { + "url": "https://docs.e-spirit.com/odfs/edocs/fsar/introduction/firstspirit-co/index.html", + "description": "The FirstSpirit concept - fundamental paradigms and architecture" + }, + { + "url": "https://docs.e-spirit.com/odfs/templates-basic/basics/firstspirit-par/index.html", + "description": "FirstSpirit paradigms - core concepts and design principles" + }, + { + "url": "https://docs.e-spirit.com/odfs/edocs/fsar/page-store/index.html", + "description": "Page Store documentation - main content editing area" + }, + { + "url": "https://docs.e-spirit.com/odfs/edocs/fsar/site-store/index.html", + "description": "Site Store documentation - website structure and navigation" + } + ] + }, + { + "topic_name": "template-development-basics", + "title": "Template Development Basics", + "description": "Introduction to template development in FirstSpirit including tools for developers, SiteArchitect, and ContentCreator environments.", + "urls": [ + { + "url": "https://docs.e-spirit.com/odfs/templates-basic/index.html", + "description": "Template development (basics) - main entry point for template development" + }, + { + "url": "https://docs.e-spirit.com/odfs/template-develo/index.html", + "description": "Template development (reference) - comprehensive reference documentation" + }, + { + "url": "https://docs.e-spirit.com/odfs/templates-basic/basics/tools-developer/index.html", + "description": "Tools for developers - overview of development environment and tools" + }, + { + "url": "https://docs.e-spirit.com/odfs/overview/index.html", + "description": "Welcome to FirstSpirit Developer Documentation - main documentation portal" + } + ] + }, + { + "topic_name": "template-structure", + "title": "Structure and Composition of Templates", + "description": "Overview of template composition, template tabs (Properties, Form, Rules, Template Set, Snippet), and how templates are organized.", + "urls": [ + { + "url": "https://docs.e-spirit.com/odfs/templates-basic/composition-tem/index.html", + "description": "Structure of templates - comprehensive guide to template composition" + }, + { + "url": "https://docs.e-spirit.com/odfs/templates-basic/composition-tem/page-templates/index.html", + "description": "Structure of a page template - detailed page template anatomy" + }, + { + "url": "https://docs.e-spirit.com/odfs/templates-basic/composition-tem/section-templat/index.html", + "description": "Structure of the section template - section template components" + } + ] + }, + { + "topic_name": "page-templates", + "title": "Page Templates", + "description": "Page templates provide the basic framework for a page and define the locations where editors can insert content. Includes information on page template structure, properties, forms, and rules.", + "urls": [ + { + "url": "https://docs.e-spirit.com/odfs/templates-basic/composition-tem/page-templates/index.html", + "description": "Structure of a page template - comprehensive page template guide" + }, + { + "url": "https://docs.e-spirit.com/odfs/tutorials/first-project/working-with-pa/index.html", + "description": "Working with page templates - practical tutorial" + }, + { + "url": "https://docs.e-spirit.com/odfs/tutorials/first-project/working-with-pa/input-component/index.html", + "description": "Input components of a page template - adding input fields to pages" + }, + { + "url": "https://docs.e-spirit.com/odfs/templates-basic/composition-tem/page-templates/snippet-tab/index.html", + "description": "Snippet tab in page templates - defining preview content" + } + ] + }, + { + "topic_name": "section-templates", + "title": "Section Templates", + "description": "Section templates are used to add content to the basic framework of a page. They contain input components for dynamic page content like text, tables, images, and datasets.", + "urls": [ + { + "url": "https://docs.e-spirit.com/odfs/templates-basic/composition-tem/section-templat/index.html", + "description": "Structure of the section template - comprehensive section template guide" + }, + { + "url": "https://docs.e-spirit.com/odfs/template-develo/template-wizard/creating-conten/section-templat/index.html", + "description": "Creating section templates - template wizard guide" + }, + { + "url": "https://docs.e-spirit.com/odfs/templates-basic/composition-tem/section-templat/template-set-ta/index.html", + "description": "Template set tab - configuring section template sets" + } + ] + }, + { + "topic_name": "format-templates", + "title": "Format Templates", + "description": "Format templates define text formatting options for editors. They control how formatted text content is rendered in different output channels.", + "urls": [ + { + "url": "https://docs.e-spirit.com/odfs/templates-basic/composition-tem/format-template/index.html", + "description": "Format templates - main format template documentation" + }, + { + "url": "https://docs.e-spirit.com/odfs/templates-basic/composition-tem/format-template/default-format/index.html", + "description": "Default format templates - built-in formatting options" + }, + { + "url": "https://docs.e-spirit.com/odfs/templates-basic/composition-tem/inline-tables/table-format-te/index.html", + "description": "Table format templates - formatting options for tables" + } + ] + }, + { + "topic_name": "link-templates", + "title": "Link Templates", + "description": "Link templates define how links appear within a FirstSpirit project. They are used by input components to predefine link layout and behavior.", + "urls": [ + { + "url": "https://docs.e-spirit.com/odfs/templates-basic/composition-tem/link-templates/index.html", + "description": "Link templates - comprehensive link template guide" + }, + { + "url": "https://docs.e-spirit.com/odfs/templates-basic/composition-tem/link-templates/usage/index.html", + "description": "Using link templates - practical implementation guide" + } + ] + }, + { + "topic_name": "script-templates", + "title": "Scripts and Script Templates", + "description": "Scripts allow functions that are not yet present in FirstSpirit to be implemented quickly using BeanShell. Covers script templates and scripting capabilities.", + "urls": [ + { + "url": "https://docs.e-spirit.com/odfs/templates-basic/composition-tem/scripts/index.html", + "description": "Scripts - overview of scripting in FirstSpirit" + } + ] + }, + { + "topic_name": "table-templates", + "title": "Table and Database Schema Templates", + "description": "Table templates define input components for database tables. Covers database schemata, table templates, and inline table templates.", + "urls": [ + { + "url": "https://docs.e-spirit.com/odfs/templates-basic/composition-tem/database-schema/index.html", + "description": "Database schemata - overview of database schema templates" + }, + { + "url": "https://docs.e-spirit.com/odfs/templates-basic/composition-tem/database-schema/table-templates/index.html", + "description": "Table template - creating templates for database tables" + }, + { + "url": "https://docs.e-spirit.com/odfs/tutorials/first-project/using-databases/index.html", + "description": "Using databases - tutorial on database integration" + }, + { + "url": "https://docs.e-spirit.com/odfs/templates-basic/composition-tem/inline-tables/index.html", + "description": "Templates for inline tables - inline table formatting" + } + ] + }, + { + "topic_name": "workflows", + "title": "Workflows", + "description": "Workflow templates define approval and release processes in FirstSpirit. Covers workflow structure, validation, and implementation.", + "urls": [ + { + "url": "https://docs.e-spirit.com/odfs/templates-basic/composition-tem/workflows/index.html", + "description": "Structure of workflows - comprehensive workflow guide" + }, + { + "url": "https://docs.e-spirit.com/module/basicworkflows/BasicWorkflows_Documentation_EN.html", + "description": "BasicWorkflows module - standard workflow implementations" + } + ] + }, + { + "topic_name": "input-components", + "title": "Form Input Components", + "description": "Complete reference for all FirstSpirit input components (CMS_INPUT_TEXT, CMS_INPUT_DOM, CMS_INPUT_LIST, FS_REFERENCE, etc.) used in template forms for editorial content.", + "urls": [ + { + "url": "https://docs.e-spirit.com/odfs/template-develo/forms/index.html", + "description": "Form - comprehensive form and input component reference" + }, + { + "url": "https://docs.e-spirit.com/odfs/template-develo/forms/input-component/text/index.html", + "description": "CMS_INPUT_TEXT - single line text input component" + }, + { + "url": "https://docs.e-spirit.com/odfs/template-develo/forms/input-component/dom/index.html", + "description": "CMS_INPUT_DOM - rich text / formatted text editor component" + }, + { + "url": "https://docs.e-spirit.com/odfs/template-develo/forms/input-component/list/index.html", + "description": "CMS_INPUT_LIST - list selection component" + }, + { + "url": "https://docs.e-spirit.com/odfs/template-develo/forms/input-component/number/index.html", + "description": "CMS_INPUT_NUMBER - number input component" + }, + { + "url": "https://docs.e-spirit.com/odfs/template-develo/forms/input-component/reference/index.html", + "description": "FS_REFERENCE - reference selector component" + }, + { + "url": "https://docs.e-spirit.com/odfs/template-develo/template-wizard/creating-conten/input-component/index.html", + "description": "Creating input components - using the template wizard" + }, + { + "url": "https://docs.e-spirit.com/odfs/template-develo/template-wizard/creating-forms/index.html", + "description": "Form builder - creating forms with the wizard" + } + ] + }, + { + "topic_name": "template-syntax-instructions", + "title": "Template Syntax - Instructions", + "description": "Complete reference for FirstSpirit template instructions including CMS_SET, CMS_VALUE, CMS_IF, CMS_FOR, CMS_RENDER, CMS_INCLUDE, CMS_REF, and more.", + "urls": [ + { + "url": "https://docs.e-spirit.com/odfs/template-develo/template-syntax/index.html", + "description": "Overview of the FirstSpirit template syntax - main syntax reference" + }, + { + "url": "https://docs.e-spirit.com/odfs/template-develo/template-syntax/instructions/index.html", + "description": "Instructions - comprehensive list of all template instructions" + }, + { + "url": "https://docs.e-spirit.com/odfs/template-develo/template-syntax/instructions/cms_value/index.html", + "description": "CMS_VALUE - outputting variable contents and expressions" + }, + { + "url": "https://docs.e-spirit.com/odfs/template-develo/template-syntax/instructions/cms_set/index.html", + "description": "CMS_SET - defining and assigning variables" + }, + { + "url": "https://docs.e-spirit.com/odfs/template-develo/template-syntax/instructions/cms_if/index.html", + "description": "CMS_IF - conditional logic and branching" + }, + { + "url": "https://docs.e-spirit.com/odfs/template-develo/template-syntax/instructions/cms_for/index.html", + "description": "CMS_FOR - loops and iteration" + }, + { + "url": "https://docs.e-spirit.com/odfs/template-develo/template-syntax/instructions/cms_switch/index.html", + "description": "CMS_SWITCH - case differentiation" + }, + { + "url": "https://docs.e-spirit.com/odfs/template-develo/template-syntax/instructions/cms_render/index.html", + "description": "CMS_RENDER - rendering other templates and scripts" + }, + { + "url": "https://docs.e-spirit.com/odfs/template-develo/template-syntax/instructions/cms_include/index.html", + "description": "CMS_INCLUDE - including files from Media Store" + }, + { + "url": "https://docs.e-spirit.com/odfs/template-develo/template-syntax/instructions/cms_ref/index.html", + "description": "CMS_REF - resolving references to paths and media" + } + ] + }, + { + "topic_name": "template-syntax-expressions", + "title": "Template Syntax - Expressions and Data Types", + "description": "Documentation on FirstSpirit expressions and data types including Boolean, String, Number, Date, List, Map, Set, DomElement, and more.", + "urls": [ + { + "url": "https://docs.e-spirit.com/odfs/template-develo/template-syntax/data-types/index.html", + "description": "Data types - complete data type reference" + }, + { + "url": "https://docs.e-spirit.com/odfs/template-develo/template-syntax/data-types/boolean/index.html", + "description": "Boolean data type - true/false values" + }, + { + "url": "https://docs.e-spirit.com/odfs/template-develo/template-syntax/data-types/list/index.html", + "description": "List data type - ordered, indexed collections" + }, + { + "url": "https://docs.e-spirit.com/odfs/template-develo/template-syntax/data-types/map/index.html", + "description": "Map data type - key-value pairs" + } + ] + }, + { + "topic_name": "template-syntax-functions", + "title": "Template Syntax - Functions", + "description": "Reference for FirstSpirit template functions including editorId, if, contentSelect, define, and other functions used in templates.", + "urls": [ + { + "url": "https://docs.e-spirit.com/odfs/template-develo/template-syntax/functions/instructions/editorid/index.html", + "description": "editorId(...) - enabling ContentCreator editing features" + }, + { + "url": "https://docs.e-spirit.com/odfs/template-develo/template-syntax/functions/instructions/if/index.html", + "description": "if(...) - inline conditional function" + } + ] + }, + { + "topic_name": "template-syntax-system-objects", + "title": "Template Syntax - System Objects", + "description": "Reference for FirstSpirit system objects (#global, #field, #for, #style, #content, etc.) used to access information, data, and objects within templates.", + "urls": [ + { + "url": "https://docs.e-spirit.com/odfs/template-develo/template-syntax/system-objects/index.html", + "description": "System objects - comprehensive system objects reference" + }, + { + "url": "https://docs.e-spirit.com/odfs/template-develo/template-syntax/system-objects/global/index.html", + "description": "#global - globally available system object" + }, + { + "url": "https://docs.e-spirit.com/odfs/template-develo/template-syntax/system-objects/field/index.html", + "description": "#field - accessing input component attributes" + }, + { + "url": "https://docs.e-spirit.com/odfs/template-develo/template-syntax/system-objects/for/index.html", + "description": "#for - loop context object" + }, + { + "url": "https://docs.e-spirit.com/odfs/template-develo/template-syntax/system-objects/style/index.html", + "description": "#style - style and formatting context" + } + ] + }, + { + "topic_name": "variables", + "title": "Variables in FirstSpirit", + "description": "Guide to defining, using, and outputting variables in FirstSpirit templates, metadata, and scripts.", + "urls": [ + { + "url": "https://docs.e-spirit.com/odfs/template-develo/variables/index.html", + "description": "Variables in FirstSpirit - comprehensive variable guide" + }, + { + "url": "https://docs.e-spirit.com/odfs/template-develo/variables/definition-outp/templates/index.html", + "description": "Using variables in templates - template variable usage" + }, + { + "url": "https://docs.e-spirit.com/odfs/template-develo/variables/definition-outp/metadata/index.html", + "description": "Using variables in metadata - metadata variable usage" + } + ] + }, + { + "topic_name": "rules", + "title": "Rules and Dynamic Forms", + "description": "Documentation on FirstSpirit rules for creating dynamic forms, validation, and controlling template behavior based on conditions.", + "urls": [ + { + "url": "https://docs.e-spirit.com/odfs/template-develo/rules/index.html", + "description": "Dynamic forms - rules overview and usage" + }, + { + "url": "https://docs.e-spirit.com/odfs/template-develo/rules/rules-tab/index.html", + "description": "The Rules tab - configuring rules in templates" + }, + { + "url": "https://docs.e-spirit.com/odfs/template-develo/rules/structure-a-rul/index.html", + "description": "Subcategories of rule definition - rule structure" + }, + { + "url": "https://docs.e-spirit.com/odfs/template-develo/rules/validation-vali/index.html", + "description": "Validation in rules - implementing form validation" + }, + { + "url": "https://docs.e-spirit.com/odfs/template-develo/rules/form-properties/index.html", + "description": "Defining properties for a form element - form property configuration" + } + ] + }, + { + "topic_name": "snippets", + "title": "Snippets and Preview Content", + "description": "Guide to defining snippets in templates - preview content that represents FirstSpirit objects as teasers or summaries.", + "urls": [ + { + "url": "https://docs.e-spirit.com/odfs/template-develo/snippets/index.html", + "description": "Snippets - comprehensive snippet documentation" + }, + { + "url": "https://docs.e-spirit.com/odfs/templates-basic/composition-tem/page-templates/snippet-tab/index.html", + "description": "Snippet tab - configuring snippet content in templates" + } + ] + }, + { + "topic_name": "metadata", + "title": "Metadata Templates and Properties", + "description": "Guide to creating and using metadata templates, metadata forms, and accessing metadata information in FirstSpirit.", + "urls": [ + { + "url": "https://docs.e-spirit.com/odfs/edocs/fsar/general-operati/metadata/index.html", + "description": "Metadata - SiteArchitect metadata guide" + }, + { + "url": "https://docs.e-spirit.com/odfs/template-develo/variables/definition-outp/metadata/index.html", + "description": "Using variables in metadata - metadata variable implementation" + }, + { + "url": "https://docs.e-spirit.com/odfs/template-develo/rules/form-properties/property-elemen/index.html", + "description": "ELEMENTTYPE property - accessing element type in metadata" + }, + { + "url": "https://docs.e-spirit.com/odfs/template-develo/rules/form-properties/property-templa/index.html", + "description": "TEMPLATE property - accessing template information" + } + ] + }, + { + "topic_name": "template-wizard", + "title": "Template Wizard and HTML Importer", + "description": "Guide to using the Template Wizard for creating templates, importing HTML structures, and the Form Builder.", + "urls": [ + { + "url": "https://docs.e-spirit.com/odfs/template-develo/template-wizard/index.html", + "description": "Template wizard / HTML Importer - main wizard documentation" + }, + { + "url": "https://docs.e-spirit.com/odfs/template-develo/template-wizard/creating-conten/index.html", + "description": "Creating content templates - wizard-based template creation" + }, + { + "url": "https://docs.e-spirit.com/odfs/template-develo/template-wizard/creating-forms/index.html", + "description": "Form builder - creating forms with the wizard" + } + ] + }, + { + "topic_name": "debugging", + "title": "Debugging and Template Development", + "description": "Guide to debugging FirstSpirit templates including the Template Inspector, FirstSpirit Debugger, error detection, and best practices.", + "urls": [ + { + "url": "https://docs.e-spirit.com/odfs/template-develo/debugging/index.html", + "description": "FirstSpirit debugging - comprehensive debugging guide" + }, + { + "url": "https://docs.e-spirit.com/odfs/template-develo/debugging/where-is-error/index.html", + "description": "Debugging: Where is the source of the error? - error location strategies" + }, + { + "url": "https://docs.e-spirit.com/odfs/template-develo/debugging/where-is-error/template-inspec/index.html", + "description": "Debugging: The Template Inspector - template inspection tool" + }, + { + "url": "https://docs.e-spirit.com/odfs/template-develo/debugging/where-is-error/firstspirit-deb/index.html", + "description": "The FirstSpirit Debugger - step-by-step debugging tool" + }, + { + "url": "https://docs.e-spirit.com/odfs/template-develo/debugging/are-there-error/index.html", + "description": "Debugging: Is an error present? How can errors be avoided? - error prevention" + } + ] + }, + { + "topic_name": "contentcreator", + "title": "ContentCreator Environment", + "description": "Documentation on ContentCreator - the browser-based editing environment for editors with preview editing capabilities.", + "urls": [ + { + "url": "https://docs.e-spirit.com/odfs/template-develo/contentcreator/index.html", + "description": "The ContentCreator - comprehensive ContentCreator guide" + }, + { + "url": "https://docs.e-spirit.com/odfs/template-develo/contentcreator/requirements/index.html", + "description": "ContentCreator – Prerequisites - setup requirements" + }, + { + "url": "https://docs.e-spirit.com/odfs/template-develo/contentcreator/functional-scop/index.html", + "description": "Functional scope of ContentCreator - features and capabilities" + }, + { + "url": "https://docs.e-spirit.com/odfs/plug-developmen/contentcreator/index.html", + "description": "ContentCreator Extensions - extending ContentCreator functionality" + } + ] + }, + { + "topic_name": "generation-output", + "title": "Generation and Output Channels", + "description": "Documentation on FirstSpirit generation process, output channels, multi-channel output, and content delivery.", + "urls": [ + { + "url": "https://docs.e-spirit.com/odfs/advanced-topics/generation/index.html", + "description": "Generation - comprehensive generation documentation" + }, + { + "url": "https://docs.crownpeak.com/firstspirit/ocm/", + "description": "Omnichannel Manager (OCM) 3.0 - multi-channel content management" + }, + { + "url": "https://docs.e-spirit.com/tpp/index.html.en", + "description": "Omnichannel Manager - preview editing for external applications" + } + ] + }, + { + "topic_name": "media-store", + "title": "Media Store and Media Management", + "description": "Guide to working with the Media Store, media galleries, and database schemas for media management.", + "urls": [ + { + "url": "https://docs.e-spirit.com/odfs/advanced-topics/media-galleries/index.html", + "description": "Working with media galleries - media gallery implementation" + } + ] + }, + { + "topic_name": "api-reference", + "title": "FirstSpirit API and JavaDoc", + "description": "Complete API reference documentation including Access API, Developer API, and JavaDoc for FirstSpirit development.", + "urls": [ + { + "url": "https://docs.e-spirit.com/odfs/template-develo/firstspirit-api/api-documentati/index.html", + "description": "API documentation - main API documentation portal" + }, + { + "url": "https://docs.e-spirit.com/odfs/access/index.html", + "description": "Overview (FirstSpirit Access-API) - JavaDoc for Access API" + }, + { + "url": "https://docs.e-spirit.com/odfs/access/help-doc.html", + "description": "API Help (FirstSpirit Access-API) - API help documentation" + } + ] + }, + { + "topic_name": "modules-plugins", + "title": "Module and Plugin Development", + "description": "Guide to developing FirstSpirit modules (FSM files), plugins, and extensions including module architecture and deployment.", + "urls": [ + { + "url": "https://docs.e-spirit.com/odfs/plug-developmen/index.html", + "description": "Plug-In Development - comprehensive plugin development guide" + }, + { + "url": "https://docs.e-spirit.com/odfs/plug-developmen/implementation/module-architec/index.html", + "description": "Creating a FirstSpirit Module - module architecture guide" + }, + { + "url": "https://docs.e-spirit.com/odfs/plug-developmen/implementation/module-architec/module-definiti/index.html", + "description": "Module Definition - module descriptor (XML) reference" + }, + { + "url": "https://docs.e-spirit.com/odfs/plug-developmen/implementation/deploying-modul/index.html", + "description": "Deploying Modules - module deployment guide" + }, + { + "url": "https://docs.e-spirit.com/cloud/module-development/Module_Development_FirstSpirit_Guide_EN.pdf", + "description": "Developing Modules in the Cloud - cloud module development guide (PDF)" + }, + { + "url": "https://docs.e-spirit.com/odfs/plug-developmen/examples/index.html", + "description": "Examples - plugin and module examples" + } + ] + }, + { + "topic_name": "tutorials", + "title": "FirstSpirit Tutorials and Getting Started", + "description": "Step-by-step tutorials for learning FirstSpirit including first project setup, working with templates, and using databases.", + "urls": [ + { + "url": "https://docs.e-spirit.com/odfs/tutorials/first-project/index.html", + "description": "First project tutorials - getting started guide" + }, + { + "url": "https://docs.e-spirit.com/odfs/tutorials/first-project/working-with-pa/index.html", + "description": "Working with page templates - page template tutorial" + }, + { + "url": "https://docs.e-spirit.com/odfs/tutorials/first-project/insert-content/index.html", + "description": "The page store - importing content - content management tutorial" + }, + { + "url": "https://docs.e-spirit.com/odfs/tutorials/first-project/using-databases/index.html", + "description": "Using databases - database integration tutorial" + } + ] + } + ] +} diff --git a/skills/firstspirit-templating/references/format-templates.md b/skills/firstspirit-templating/references/format-templates.md new file mode 100644 index 0000000..e81f898 --- /dev/null +++ b/skills/firstspirit-templating/references/format-templates.md @@ -0,0 +1,280 @@ +# Format Templates + +## Overview + +Format templates define text formatting options available to content editors in FirstSpirit. They enable consistent styling through DOM editor and DOM table input components, ensuring brand compliance and content consistency across all output channels. + +## Purpose and Core Concepts + +Format templates serve as the foundation for text formatting within FirstSpirit's content management system. They provide editors with predefined formatting options that maintain design consistency while preventing unauthorized styling variations. + +### Key Characteristics + +**Two Types of Formatting:** + +1. **Section Formatting**: Applied to entire paragraphs up to line breaks + - Only available when no text is highlighted + - Affects complete content blocks + - Used for structural formatting like headings and paragraphs + +2. **Individual Text Formatting**: Applied to selected text only + - Available when text is highlighted or cursor is within a string + - Used for inline styling like bold, italic, or underline + - Applies to specific character ranges + +## Configuration Structure + +Format templates utilize a two-tab configuration interface: + +### Properties Tab + +Contains all essential settings for the template including: +- Template name and identifier +- Formatting type (section vs. individual) +- Visual properties (colors, fonts, borders) +- Accessibility settings + +### Template Set Tab + +Manages formatting-specific configuration details: +- Assignment to template sets +- Channel-specific output rules +- Conversion rule associations + +## Implementation Requirements + +Three critical steps are required to create functional format templates: + +### 1. Conversion Rules + +Each template set must have a defined conversion rule that determines how formatted content is transformed for different output channels (HTML, PDF, mobile, etc.). + +### 2. Output Definition + +Formatted content visibility depends on output specifications defined for each template set. Without proper output configuration, formatted text will not appear in generated pages. + +### 3. Template Specification + +Developers must designate the format template within the form area of relevant page or section templates. This connects the formatting options to specific input components. + +## Default Format Templates + +FirstSpirit provides pre-built format templates as export files that can be imported into a project's Template Store under the "Format templates" node. + +### Critical Requirement + +**The default format templates are required in a variety of contexts for correct operation and must not be deleted.** + +### Version Comparison Templates + +Four specialized templates handle change visualization in version history: + +- `deleted` - Shows removed inline content +- `deleted_block` - Shows removed block-level content +- `inserted` - Shows added inline content +- `inserted_block` - Shows added block-level content + +These templates can be customized by adjusting properties like: +- Colors to highlight changes +- Font size and weight +- Border styles +- Background colors + +### Standard HTML Format Templates + +The system includes templates for common HTML formatting elements: + +**Text Formatting:** +- `b` - Bold text +- `i` - Italic text +- `u` - Underlined text +- `pre` - Preformatted text + +**Structure:** +- `p` - Paragraph +- `br` - Line break +- `ul` - Unordered list +- `li` - List entry + +**Tables:** +- `table` - Table container +- `tr` - Table row +- `td` - Table cell + +**Special:** +- `CMS_LINK` - Hyperlinks +- `default_style_template` - Default styling +- `default_inline_table` - Default table configuration + +### Customization + +Properties of format templates can be modified to alter display behavior in the DOM editor. This allows organizations to customize appearance while maintaining required functionality. + +## Table Format Templates + +Table format templates define how inline tables appear and function within FirstSpirit. They provide comprehensive control over visual presentation and editing constraints. + +### Purpose + +Table format templates control: +- Visual presentation of tables in the editor and frontend +- Editing constraints (row/column limits) +- Style application across different table areas +- User permissions for table modifications + +### Configuration Options + +#### Visual Presentation + +Upload a "meaningful screenshot" to show editors how the template appears in the frontend. This visual reference helps editors select appropriate templates for their content needs. + +#### Size Constraints + +Templates allow administrators to specify: +- Minimum row count +- Maximum row count +- Minimum column count +- Maximum column count + +When the "limited" checkbox is enabled: +- Editors cannot exceed specified boundaries +- Relevant buttons automatically disable when limits are reached +- Prevents table structure violations + +#### Style Application + +Each table format template uses: +- **Precisely one standard style template** for the entire table +- **Additional style templates** for individual cells, rows, or columns through display rules + +### Display Rules System + +Display rules override the standard template for specific table areas, providing granular control over table styling. + +#### Rule Configuration + +Each display rule specifies: + +1. **Application Area**: Whether it applies to rows, columns, or cells +2. **Application Scope**: + - `ALL` - All items of the specified type + - `EVEN` - Even-numbered items only + - `ODD` - Odd-numbered items only + - `FIRST` - First item only + - `LAST` - Last item only + - User-defined numbers - Specific row/column numbers +3. **Associated Style Template**: Which style template to apply +4. **Editor Permissions**: Whether editors can modify or delete affected areas + +#### Evaluation Order + +The system processes display rules using specific logic: + +1. Display rules are evaluated top-down in the defined order +2. The standard template applies to remaining cells not affected by rules +3. **Important Limitation**: Rules cannot affect ALL columns AND ALL rows simultaneously + +#### Integration with Style Templates + +Style templates work seamlessly with table format templates, allowing control over: +- Background colors +- Text alignment +- Font properties +- Borders and spacing +- Other formatting properties across different table sections + +## Best Practices + +### Naming Conventions + +Use descriptive, meaningful names for format templates that indicate: +- Purpose (e.g., "Headline Level 2", "Quote Block") +- Visual appearance (e.g., "Red Alert Text", "Centered Caption") +- Context of use (e.g., "Product Description Paragraph") + +### Template Organization + +- Group related format templates together +- Create separate templates for different content types +- Maintain consistent styling across template sets +- Document custom templates for future reference + +### Version Control Considerations + +When customizing default format templates: +- Preserve the original version comparison templates +- Document all modifications +- Test changes across all output channels +- Verify formatting appears correctly in preview and production + +### Table Template Design + +When creating table format templates: +- Provide clear screenshots showing frontend appearance +- Set reasonable size constraints that balance flexibility with design requirements +- Use display rules strategically to highlight important table areas +- Test templates with various content scenarios +- Consider accessibility requirements (headers, contrast, etc.) + +### Multi-Channel Output + +Remember that format templates must be configured for each output channel: +- Define conversion rules for HTML, PDF, mobile, and other channels +- Test formatting in all target channels +- Ensure consistent appearance across platforms +- Account for channel-specific limitations + +## Common Use Cases + +### Editorial Formatting + +Format templates enable editors to: +- Apply consistent heading styles +- Highlight important text (quotes, callouts, warnings) +- Format lists and structured content +- Create accessible, well-formatted tables +- Maintain brand guidelines without technical knowledge + +### Multi-Channel Publishing + +Format templates support: +- Responsive design across devices +- Print-optimized formatting for PDF generation +- Mobile-specific text presentation +- Channel-specific style variations + +### Workflow Integration + +Format templates integrate with: +- Content approval workflows +- Version comparison tools +- Translation management +- Multi-site content distribution + +## Technical Considerations + +### Performance + +- Minimize the number of format templates to reduce editor complexity +- Use display rules efficiently to avoid excessive processing +- Cache rendered output when possible + +### Maintenance + +- Regularly review and consolidate format templates +- Remove unused templates to simplify editor interface +- Update templates when design standards change +- Document dependencies between templates and page templates + +### Accessibility + +Ensure format templates support: +- Semantic HTML structure +- Screen reader compatibility +- Proper heading hierarchy +- Color contrast requirements +- Keyboard navigation + +## Summary + +Format templates are essential components of FirstSpirit's content management system, providing the bridge between editorial flexibility and design consistency. By properly configuring format templates, organizations can empower editors to create well-formatted content while maintaining brand standards across all output channels. Understanding the distinction between section and individual formatting, properly implementing table format templates with display rules, and maintaining the required default templates ensures a robust and user-friendly content editing experience. \ No newline at end of file diff --git a/skills/firstspirit-templating/references/general-structure.md b/skills/firstspirit-templating/references/general-structure.md new file mode 100644 index 0000000..5c0d6bd --- /dev/null +++ b/skills/firstspirit-templating/references/general-structure.md @@ -0,0 +1,347 @@ +# FirstSpirit General Structure and Stores + +## Overview + +FirstSpirit is a content management system built on a fundamental architectural principle: **strict separation of layout, content, and structure**. This separation enables independent modification of different website aspects while maintaining content reusability across the entire system. + +The core philosophy addresses the traditional challenges of website maintenance by allowing editorial teams to manage content without requiring web design expertise, while developers control layout and functionality separately. + +## Core Architecture: The Six-Store System + +FirstSpirit organizes all project data into six distinct, specialized stores. Each store has a specific purpose and is color-coded in the interface for easy identification. + +### 1. Page Store + +**Purpose:** Primary repository for editorial content where content creators work with pages and sections. + +**Key Characteristics:** +- Main editing interface for content creators +- Houses editorial content in a structured format +- Provides standard input elements (text editors, form fields, etc.) +- Enables editors to add pages, sections, and manage existing content + +**Structure and Components:** + +The Page Store supports four primary object types: + +1. **Folders** - Organizational hierarchy, typically mirroring intended website menu structure +2. **Pages** - Standard content containers that usually correspond to individual website pages +3. **Sections** - Content divisions within pages that map to specific content areas (enabling multi-column layouts) +4. **Section References** - References to existing sections for content reuse across multiple pages + +**Content Organization:** +- One page in the Page Store typically corresponds to one website page +- Each page can contain multiple sections assigned to different content areas +- Sections organize content within pages for layout flexibility +- Content includes text, images, files, and other media inserted using standard input elements + +**Relationship with Other Stores:** +- Pages align with page templates from the Template Store +- Sections align with section templates that define individualized layouts +- Content areas organize sections within pages for complex website designs + +### 2. Data Store + +**Purpose:** Manages highly structured, database-driven content. + +**Key Characteristics:** +- Designed for structured content like product catalogs, address lists, and news databases +- Accommodates custom database structures +- Supports external database integration for frequently-updated information +- Ideal for content requiring database-style querying and organization + +**Typical Use Cases:** +- Product catalogs +- Address directories +- News archives +- Event calendars +- Any content requiring complex relationships and structured data models + +### 3. Site Store + +**Purpose:** Governs the website's physical hierarchy and navigation structure. + +**Key Characteristics:** +- Maps the navigation architecture of the website +- Separates structure from layout, allowing independent modification +- Each folder represents a navigation menu level +- Subfolders automatically create new menu tiers +- Controls menu item ordering and display options + +**Structural Elements:** + +The Site Store organizes content through five main components: + +1. **Folders** - Each folder represents a menu level in website navigation +2. **Start folders** - Direct links to pages when a menu level lacks a dedicated page +3. **Page references** - Individual pages available for display in navigation +4. **Start pages** - The initial page shown when multiple pages exist at one menu level +5. **Document groups** - Containers that unite multiple page references and menu levels for unified display + +**Navigation Management:** +- Navigation points can be added, modified, or removed at any depth and time +- Automatic menu level creation occurs with each new subfolder +- Link management preserves referential integrity throughout the structure +- Navigation can be implemented through various formats (traditional HTML, JavaScript, Flash) +- Navigation appearance and positioning defined independently from structure + +**Key Advantage:** +The separation enables flexible design changes without restructuring the content hierarchy. You can completely change how navigation looks and where it appears without touching the underlying structure. + +### 4. Media Store + +**Purpose:** Central repository for all project media assets. + +**Key Characteristics:** +- Stores all media files used across the website +- Centralized management prevents duplication +- Enables reuse of media across multiple pages and templates + +**Media Types:** +- Images (JPEG, PNG, GIF, SVG, etc.) +- Videos (MP4, WebM, etc.) +- Audio files +- Documents (PDF, Word, Excel, etc.) +- Downloadable files +- Other digital assets + +### 5. Template Store + +**Purpose:** The system's core where layout design and functional specifications reside. + +**Key Characteristics:** +- Contains all templates that define how content is displayed +- Serves as the connector between all other stores +- Integrates content, media, and structure during website generation +- Defines page layouts, section layouts, and format templates + +**Integration Role:** +Templates combine elements from multiple stores during generation: +- Content from Page Store and Data Store +- Media from Media Store +- Structure from Site Store +- All unified into complete website presentations + +**Template Types:** +- Page templates (define overall page structure) +- Section templates (define content area layouts) +- Format templates (define specific output formats) +- Link templates (define how links are generated) + +### 6. Global Settings + +**Purpose:** Project-wide configurations and shared content. + +**Key Characteristics:** +- User preferences and permissions +- Project rules and workflows +- URL configuration and SEO optimization +- Reusable content elements for frequently-used page components +- Project languages and multilingual settings + +**Configuration Areas:** +- Editorial permissions (for FirstSpirit users) +- Workflow permissions (specialized editorial access) +- User permissions (for website visitors) +- Application interface locale settings +- Editing languages (for template developers) +- Project languages (for content) + +## Separation of Content and Layout + +### The Core Principle + +FirstSpirit's fundamental architecture principle states: **"strict separation of layout, content and structure."** + +This separation addresses the inefficiency of traditional website maintenance where changing a single design element required manually updating hundreds or thousands of individual HTML files. + +### How Separation Works + +**Content Layer (Page Store, Data Store):** +- Editors maintain, change, and create content like newspaper editors +- No web design expertise required +- Focus on information quality and accuracy +- Content exists independently of presentation + +**Layout Layer (Template Store):** +- Developers define templates that control presentation +- Templates can be updated without touching content +- Design changes propagate automatically across all content +- Separation enables design consistency + +**Structure Layer (Site Store):** +- Navigation hierarchy defined independently +- Menu structure can be reorganized without affecting content or layout +- Referential integrity maintained automatically + +### Benefits of Separation + +1. **Scalability:** Bulk updates propagate across multiple dependent pages automatically +2. **Maintainability:** Important changes can be made easily and efficiently +3. **Specialization:** Team members focus on their expertise (content vs. design vs. development) +4. **Reusability:** Content can be reused at any time across different contexts +5. **Flexibility:** Each area can be changed independently of others + +## Core Concepts and Paradigms + +### Content-First Approach + +FirstSpirit follows a **content-first methodology** where editorial teams manage information independent of presentation. The system treats editors as content creators rather than technical specialists, enabling them to focus on content quality. + +### Accessibility for Non-Technical Users + +The framework emphasizes accessibility through graphical interfaces, enabling important changes without requiring proficiency in web design. This democratizes content management across organizations. + +### Multi-User Collaboration + +FirstSpirit implements selective locking to prevent conflicts: + +**Parallel Operations (No Locking Required):** +- Creation of new elements +- Deletion of elements +- Copying elements +- Moving elements + +**Exclusive Operations (Edit Mode Required):** +- Editing content +- Release actions +- Any modifications requiring exclusive access + +This approach maximizes team productivity while maintaining data integrity. + +### Multilingual Architecture + +The platform supports language at three distinct levels: + +1. **Application Interface Locale:** The language of the FirstSpirit interface itself +2. **Editing Languages:** Languages available to template developers +3. **Project Languages:** Languages for content delivery to end users + +**Language Flexibility:** +- Fields can be designated as language-dependent (different content per language) +- Fields can be language-independent (same content across all languages) +- Enables efficient management of multilingual websites + +### Role-Based Access Control + +FirstSpirit implements granular permission framework where "each individual employee has precisely defined tasks." The system distinguishes between three permission categories: + +1. **Editorial Permissions:** For FirstSpirit content editors +2. **Workflow Permissions:** Specialized editorial access with approval capabilities +3. **User Permissions:** For website visitors (frontend access control) + +## Data Preservation and Versioning + +FirstSpirit provides three mechanisms to ensure information integrity: + +### 1. Versioning +- Tracks all changes over time +- Enables rollback to previous versions +- Maintains complete change history +- Supports audit trails + +### 2. Historization +- Enables temporal snapshots for generation +- Allows regeneration of website as it appeared at specific points in time +- Supports testing and preview of changes before publication + +### 3. Archiving +- Provides permanent, tamper-proof storage +- Ensures long-term data preservation +- Supports compliance and regulatory requirements + +## Integration Model: The Generation Process + +Templates serve as the integration point during website generation: + +1. **Template Selection:** System identifies appropriate template for content +2. **Content Retrieval:** Fetches content from Page Store or Data Store +3. **Media Integration:** Incorporates media from Media Store +4. **Structure Application:** Applies navigation structure from Site Store +5. **Configuration Application:** Applies settings from Global Settings +6. **Output Generation:** Produces final website files (HTML, CSS, JavaScript, etc.) + +This process combines all store elements into cohesive, complete website presentations. + +## Best Practices for Store Organization + +### Page Store Organization +- Mirror your intended site structure in folder hierarchy +- Use descriptive names for pages and sections +- Leverage section references to avoid content duplication +- Organize content logically for easy editor navigation + +### Data Store Organization +- Design schemas that match real-world data relationships +- Use appropriate data types for each field +- Consider query performance when designing structure +- Document custom schemas for maintainability + +### Site Store Organization +- Create intuitive navigation hierarchies +- Use start pages to define default landing pages +- Leverage document groups for complex navigation scenarios +- Plan for future navigation expansion + +### Media Store Organization +- Use folders to categorize media by type or purpose +- Implement consistent naming conventions +- Consider media lifecycle and archiving strategies +- Optimize media files before upload + +### Template Store Organization +- Create reusable template components +- Document template functionality for future developers +- Use consistent coding standards +- Separate presentation logic from business logic + +### Global Settings Management +- Document all project-specific configurations +- Maintain separate settings for development, staging, and production +- Version control reusable content elements +- Regularly review and update permissions + +## Developer Considerations + +### Related Concepts to Master +- Language handling within the platform +- Developer tools available (ContentCreator, SiteArchitect) +- Template composition methodologies +- Plugin development capabilities +- API integration patterns + +### Content Scaling +The system manages content scaling across websites of any size through centralized repositories, allowing bulk updates to propagate across multiple dependent pages—directly addressing the labor-intensive nature of traditional website maintenance. + +## System Statements + +Key architectural statements from FirstSpirit documentation: + +> "The individual areas can be changed independently of each other and content can be reused at any time." + +> "A Content Management System simplifies making changes to content by separating a website's content, layout and structure." + +> "The editor maintains, changes and creates editorial content just like a newspaper editor." + +These statements encapsulate FirstSpirit's core philosophy: empowering content creators while maintaining technical flexibility for developers. + +## Summary + +FirstSpirit's six-store architecture provides a robust foundation for enterprise content management: + +- **Page Store:** Editorial content and pages +- **Data Store:** Structured, database-driven content +- **Site Store:** Navigation hierarchy and structure +- **Media Store:** Centralized media assets +- **Template Store:** Layout and presentation logic +- **Global Settings:** Project-wide configuration + +The strict separation of content, layout, and structure enables: +- Independent modification of different website aspects +- Unlimited content reusability +- Scalable maintenance across large websites +- Team specialization and parallel workflow +- Multilingual content management +- Robust versioning and data preservation + +This architecture positions FirstSpirit as an enterprise-grade CMS capable of managing complex, large-scale web projects while remaining accessible to non-technical content creators. \ No newline at end of file diff --git a/skills/firstspirit-templating/references/link-templates.md b/skills/firstspirit-templating/references/link-templates.md new file mode 100644 index 0000000..9a78c66 --- /dev/null +++ b/skills/firstspirit-templating/references/link-templates.md @@ -0,0 +1,146 @@ +# Link Templates + +## Overview + +Link templates in FirstSpirit are specialized templates that implement hyperlinks within web projects. They enable consistent link formatting and behavior across an entire project. Links serve multiple purposes: facilitating site navigation, directing users to additional information, providing access to downloadable files, and connecting to external resources. + +Unlike page templates or section templates, link templates function as reusable components that are integrated into input components rather than being directly deployed. Template developers use link templates to establish standardized link handling and presentation throughout FirstSpirit projects. + +## Link Template Structure + +Each link template consists of five main configuration areas: + +### 1. Properties Tab +Contains all essential link template settings and basic configuration options. + +### 2. Form Tab +Defines input components for pages, allowing editors to configure link properties and content. + +### 3. Rules Tab +Enables conditional logic that can affect elements or properties based on specific conditions. + +### 4. Snippet Tab +Controls how pages display in overview lists and other aggregated views. + +### 5. Template Set Tab +Determines how content appears in template sets and manages template relationships. + +## Supported Link Types + +FirstSpirit supports eight distinct varieties of links, each serving different purposes: + +### 1. Internal Links +References to pages within the same FirstSpirit project, enabling navigation between project content. + +### 2. Image Links +Clickable images that function as standalone links without requiring separate target definitions. + +### 3. Download Links +Links that trigger file retrieval, allowing users to download documents, media, or other resources. + +### 4. External Links +Links to destinations outside the current FirstSpirit project, pointing to other websites or web resources. + +### 5. E-mail Links +Mailto links that open the user's default email client with a pre-populated address. + +### 6. Dataset Links +Links to database records, connecting to structured data stored in FirstSpirit databases. + +### 7. Remote Links +References to content in other FirstSpirit remote projects, enabling cross-project linking. + +### 8. Image Map Links +Mouse-sensitive images with multiple clickable regions, each potentially linking to different destinations. + +## Using Link Templates + +### Integration with Input Components + +Link templates are accessed through specialized input components in FirstSpirit. They are not deployed directly but rather integrated into forms where editors can select and configure them. + +#### Primary Input Components for Links + +**Direct Link Components:** +- `FS_CATALOG` with `type="link"` and `` +- `CMS_INPUT_LINK` + +**Components Supporting Links Among Other Content:** +- `CMS_INPUT_DOM` - Supports text, images, and links within rich content +- `CMS_INPUT_DOMTABLE` - Table-based content with embedded link support +- `CMS_INPUT_IMAGEMAP` - Image maps with clickable regions + +### Limiting Available Link Templates + +By default, all link templates in the project are available to editors for selection in input components. To restrict which link templates can be chosen, use the following approaches: + +#### For CMS_INPUT_LINK, CMS_INPUT_DOM, CMS_INPUT_DOMTABLE, and CMS_INPUT_IMAGEMAP + +Use `LINKEDITORS` and `LINKEDITOR` tags to specify allowed templates: + +```xml + + + + + + +``` + +This configuration limits the available link templates to only "internalLink" and "externalLink" templates. + +#### For FS_CATALOG + +Use `TEMPLATE` with `uid` tags to specify allowed link templates: + +```xml + + +