zhongwei/gh-rawe-claude-dev-skills-firstspirit-templating
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 08:50:04 +08:00
commit 667c22f0bc
24 changed files with 9060 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
.claude-plugin/plugin.json Normal file
View File

@@ -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"
]
}

3
README.md Normal file
View File

@@ -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.

125
plugin.lock.json Normal file
View File

@@ -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": []
}
}

225
skills/firstspirit-templating/SKILL.md Normal file
View File

@@ -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

605
skills/firstspirit-templating/references/firstspirit-topics.json Normal file
View File

@@ -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"
}
]
}
]
}

280
skills/firstspirit-templating/references/format-templates.md Normal file
View File

@@ -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.

347
skills/firstspirit-templating/references/general-structure.md Normal file
View File

@@ -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.

146
skills/firstspirit-templating/references/link-templates.md Normal file
View File

@@ -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 `<TEMPLATES type="link"/>`
- `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
<CMS_INPUT_DOM name="contentWithLinks" hFill="yes">
<LINKEDITORS>
<LINKEDITOR name="internalLink"/>
<LINKEDITOR name="externalLink"/>
</LINKEDITORS>
</CMS_INPUT_DOM>
```
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
<FS_CATALOG name="linkCatalog" type="link">
<TEMPLATES type="link">
<TEMPLATE uid="internalLink"/>
<TEMPLATE uid="downloadLink"/>
</TEMPLATES>
</FS_CATALOG>
```
### Language Handling
Link templates have specific language-handling requirements:
- **Input components within link templates** can only be defined independently of language using the `useLanguages="no"` parameter
- **For language-dependent link content**, the parent input component (the one that includes the link template) must use `useLanguages="yes"`
This design ensures that language-specific content is managed at the appropriate level of the template hierarchy.
## Link Template Flexibility
FirstSpirit provides substantial flexibility in link template configuration:
- Default options can be freely arranged in most cases
- Linked images can function across multiple link types
- A single image can serve as an internal navigation element, external resource link, or media download trigger
- Template developers have significant control over link appearance and behavior
## Important Considerations
### Preview Functionality
After modifying link templates, preview functionality may not immediately reflect recently entered content. To resolve this issue:
1. Save the input masks again
2. This will refresh the preview to display current content
### Template Availability
When implementing input components that use link templates, consider:
- Whether all project link templates should be available
- Which specific templates are appropriate for each use case
- How to guide editors toward correct template selection through strategic limitation
## Best Practices
1. **Limit template selection** - Use LINKEDITORS or TEMPLATE tags to provide only relevant link templates for each input component
2. **Consistent naming** - Use clear, descriptive names for link templates that indicate their purpose (e.g., "internalLink", "downloadLink", "externalLink")
3. **Language planning** - Plan language-dependent content at the parent component level, keeping link template internals language-independent
4. **Testing previews** - After template modifications, always save input masks again to ensure previews reflect current content
5. **Documentation** - Document which link types are used in your project and their intended purposes for other developers and editors

462
skills/firstspirit-templating/references/metadata.md Normal file
View File

@@ -0,0 +1,462 @@
# FirstSpirit Metadata Templates and Properties
## Overview
Metadata in FirstSpirit provides additional information about objects beyond their primary content. This includes both system-assigned metadata (modification dates, version numbers, editing users) and user-defined metadata that can be customized through metadata templates.
## What is Metadata?
Metadata consists of "additional information available for an object in FirstSpirit." It serves two primary purposes:
1. **System-assigned metadata**: Automatically generated information such as:
- Last modification date
- Editing user
- Release authorization status
- Version numbers
- Integrated media counts
2. **User-defined metadata**: Custom information managed by users through the Metadata tab, requiring:
- A metadata template definition
- Appropriate permissions in Permission Management
## Metadata Template Configuration
### Creating a Metadata Template
A metadata template must be created as a **page template** in the Template Store. The setup process involves:
1. Create a page template in the Template Store
2. Define input components with unique identifiers
3. Select the template in ServerManager's project properties
4. The template becomes available across all SiteArchitect stores
Once configured, the "Metadata" tab appears in SiteArchitect, allowing editors to input content using the defined input components.
### Visual Indicators
Nodes with specifically assigned metadata display a metadata icon after the object name in the tree structure, making it easy to identify which elements have metadata configured.
## Accessing Metadata Information
### The .meta() Method
To output metadata variable content in template sets, use the system object `#global` with the `.meta()` method:
```java
$CMS_VALUE(#global.meta("metadata_identifier"))$
```
Each input component in the metadata template receives a unique identifier that is used to access its value.
### Example: Accessing Metadata Variables
```java
// Access a simple text metadata field
$CMS_VALUE(#global.meta("author"))$
// Access a date metadata field
$CMS_VALUE(#global.meta("publish_date"))$
// Access a checkbox metadata field
$CMS_VALUE(#global.meta("featured"))$
```
## Metadata Inheritance
FirstSpirit provides three inheritance options that control how metadata behaves in the content hierarchy:
### 1. No Inheritance (none)
```xml
<CMS_INPUT_TEXT name="title" inheritance="none">
<LANGINFOS>
<LANGINFO lang="*" label="Title"/>
</LANGINFOS>
</CMS_INPUT_TEXT>
```
No inheritance from parent nodes occurs. Only the metadata defined on the current node is used.
### 2. Inherit from Parent (inherit)
```xml
<CMS_INPUT_TEXT name="author" inheritance="inherit">
<LANGINFOS>
<LANGINFO lang="*" label="Author"/>
</LANGINFOS>
</CMS_INPUT_TEXT>
```
If the current node lacks metadata, the system searches parent nodes upward in the hierarchy until a value is found.
**Evaluation methods:**
- **Current node only**: Returns value if populated; empty string otherwise
- **Hierarchical inheritance**: Checks current node first, then searches parent nodes upward
### 3. Additive Inheritance (add)
```xml
<CMS_INPUT_TEXT name="keywords" inheritance="add">
<LANGINFOS>
<LANGINFO lang="*" label="Keywords"/>
</LANGINFOS>
</CMS_INPUT_TEXT>
```
Processes all nodes from root downward, aggregating metadata and outputting values separated by delimiters.
**Important**: With additive inheritance, editors see only metadata defined on the current node, not inherited metadata, which can potentially cause user errors.
## Important Constraints and Behaviors
### Language Independence
Metadata is **not language-dependent**. Only fallback definitions (`lang="*"`) apply to input component labels. This means metadata values are shared across all language variants.
### Component Behavior Limitations
Some input components cannot be emptied once populated:
- `CMS_INPUT_DOMTABLE`
- `CMS_INPUT_DOM`
- `CMS_INPUT_RADIOBUTTON`
### Metadata Status
The metadata information icon appears in the project tree only after saving an input. The Metadata tab indicates whether data has been set via checkbox status.
## ELEMENTTYPE Property
The ELEMENTTYPE property checks which element type a form was opened on, enabling dynamic form behavior based on context.
### Syntax
```xml
<PROPERTY source="#global" name="ELEMENTTYPE"/>
```
The `source` attribute must be set to `#global` since it's a system-level property.
### Supported Element Types
The property returns lowercase type names corresponding to API interface names:
**Page Store:**
- `pagestoreroot`
- `pagefolder`
- `page`
- `section`
- `sectionreference`
**Media Store:**
- `mediastoreroot`
- `mediafolder`
- `file`
- `picture`
**Site Store:**
- `sitestoreroot`
- `pagereffolder`
- `pageref`
**Global Content Area:**
- `globalcontentarea`
- `gcapage`
### Usage Context
This expression works in two areas:
1. **Value determination** (`<WITH/>` section)
2. **Preconditions** (`<IF/>` section)
### Practical Example: Conditional Metadata Display
Show specific form elements only for picture elements:
```xml
<RULE>
<WITH>
<EQUAL>
<PROPERTY source="#global" name="ELEMENTTYPE"/>
<TEXT>picture</TEXT>
</EQUAL>
</WITH>
<DO>
<PROPERTY source="#form.st_metamedia" name="VISIBLE"/>
</DO>
</RULE>
```
This rule makes the "st_metamedia" form content visible only when editing image metadata, hiding it on other element types.
### Example: Different Metadata for Different Element Types
```xml
<RULE>
<WITH>
<OR>
<EQUAL>
<PROPERTY source="#global" name="ELEMENTTYPE"/>
<TEXT>page</TEXT>
</EQUAL>
<EQUAL>
<PROPERTY source="#global" name="ELEMENTTYPE"/>
<TEXT>section</TEXT>
</EQUAL>
</OR>
</WITH>
<DO>
<PROPERTY source="#form.st_content_metadata" name="VISIBLE"/>
</DO>
</RULE>
```
This shows content-specific metadata fields only for pages and sections.
## TEMPLATE Property
The TEMPLATE property retrieves the reference name (UID) of the template associated with template-based elements like pages, sections, and datasets.
### Syntax
```xml
<PROPERTY source="#global" name="TEMPLATE"/>
```
### Key Characteristics
**Source Attribute**: Must use `source="#global"` since this is a universally applicable property.
**Scope Behavior**:
- When applied to a page, it returns page template information even if executed within nested components (like paragraphs in FS_CATALOG)
- For metadata, it returns information about the element where the metadata was defined
### Usage Contexts
This property works within:
- Value determination sections (`<WITH/>`)
- Precondition definitions (`<IF/>`)
### Example: Storing Template Information
```xml
<RULE when="ONLOCK">
<WITH>
<PROPERTY name="TEMPLATE" source="#global"/>
</WITH>
<DO>
<PROPERTY name="VALUE" source="template_id"/>
</DO>
</RULE>
```
This rule captures the template identifier during lock operations and assigns it to a value property.
### Example: Template-Specific Metadata Fields
```xml
<RULE>
<WITH>
<EQUAL>
<PROPERTY source="#global" name="TEMPLATE"/>
<TEXT>news_article</TEXT>
</EQUAL>
</WITH>
<DO>
<PROPERTY source="#form.st_article_metadata" name="VISIBLE"/>
</DO>
</RULE>
```
This displays article-specific metadata fields only when the page uses the "news_article" template.
## Practical Metadata Usage Examples
### Example 1: Basic Metadata Template
```xml
<CMS_INPUT_TEXT name="st_title" inheritance="inherit">
<LANGINFOS>
<LANGINFO lang="*" label="Page Title"/>
</LANGINFOS>
</CMS_INPUT_TEXT>
<CMS_INPUT_TEXTAREA name="st_description" inheritance="inherit">
<LANGINFOS>
<LANGINFO lang="*" label="Meta Description"/>
</LANGINFOS>
</CMS_INPUT_TEXTAREA>
<CMS_INPUT_TEXT name="st_keywords" inheritance="add">
<LANGINFOS>
<LANGINFO lang="*" label="Keywords"/>
</LANGINFOS>
</CMS_INPUT_TEXT>
<CMS_INPUT_CHECKBOX name="st_noindex" inheritance="none">
<LANGINFOS>
<LANGINFO lang="*" label="No Index"/>
</LANGINFOS>
</CMS_INPUT_CHECKBOX>
```
### Example 2: Accessing Metadata in HTML Output
```html
<head>
<title>$CMS_VALUE(#global.meta("st_title"))$</title>
<meta name="description" content="$CMS_VALUE(#global.meta("st_description"))$">
<meta name="keywords" content="$CMS_VALUE(#global.meta("st_keywords"))$">
$CMS_IF(#global.meta("st_noindex"))$
<meta name="robots" content="noindex, nofollow">
$CMS_END_IF$
</head>
```
### Example 3: Conditional Metadata Based on Element Type and Template
```xml
<!-- Show SEO fields only for pages -->
<RULE>
<WITH>
<EQUAL>
<PROPERTY source="#global" name="ELEMENTTYPE"/>
<TEXT>page</TEXT>
</EQUAL>
</WITH>
<DO>
<PROPERTY source="#form.st_seo_section" name="VISIBLE"/>
</DO>
</RULE>
<!-- Show image-specific fields only for pictures -->
<RULE>
<WITH>
<EQUAL>
<PROPERTY source="#global" name="ELEMENTTYPE"/>
<TEXT>picture</TEXT>
</EQUAL>
</WITH>
<DO>
<PROPERTY source="#form.st_image_metadata" name="VISIBLE"/>
</DO>
</RULE>
<!-- Show article metadata only for news template -->
<RULE>
<WITH>
<AND>
<EQUAL>
<PROPERTY source="#global" name="ELEMENTTYPE"/>
<TEXT>page</TEXT>
</EQUAL>
<EQUAL>
<PROPERTY source="#global" name="TEMPLATE"/>
<TEXT>news_article</TEXT>
</EQUAL>
</AND>
</WITH>
<DO>
<PROPERTY source="#form.st_article_fields" name="VISIBLE"/>
</DO>
</RULE>
```
### Example 4: Media Metadata Template
```xml
<!-- Common fields for all media -->
<CMS_INPUT_TEXT name="st_copyright" inheritance="inherit">
<LANGINFOS>
<LANGINFO lang="*" label="Copyright"/>
</LANGINFOS>
</CMS_INPUT_TEXT>
<!-- Picture-specific fields -->
<CMS_MODULE name="st_image_details">
<LANGINFOS>
<LANGINFO lang="*" label="Image Details"/>
</LANGINFOS>
<CMS_INPUT_TEXT name="st_photographer">
<LANGINFOS>
<LANGINFO lang="*" label="Photographer"/>
</LANGINFOS>
</CMS_INPUT_TEXT>
<CMS_INPUT_DATE name="st_photo_date">
<LANGINFOS>
<LANGINFO lang="*" label="Photo Date"/>
</LANGINFOS>
</CMS_INPUT_DATE>
<RULES>
<RULE>
<WITH>
<EQUAL>
<PROPERTY source="#global" name="ELEMENTTYPE"/>
<TEXT>picture</TEXT>
</EQUAL>
</WITH>
<DO>
<PROPERTY source="#module" name="VISIBLE"/>
</DO>
</RULE>
</RULES>
</CMS_MODULE>
```
### Example 5: Accessing Metadata with Fallback
```java
// Access metadata with fallback value
$CMS_SET(author, #global.meta("st_author"))$
$CMS_IF(!author.empty)$
<meta name="author" content="$CMS_VALUE(author)$">
$CMS_ELSE$
<meta name="author" content="Default Author">
$CMS_END_IF$
```
## Permissions and Editing
### Permission Requirements
Users can only modify metadata in edit mode with special permissions assigned through Permission Management. Without proper permissions, the Metadata tab will be read-only or unavailable.
### Accessing Metadata in Edit Mode
1. Open an element in edit mode
2. Navigate to the Metadata tab
3. Input or modify metadata values
4. Save to persist changes
The Metadata tab indicates whether data has been set via checkbox status, providing visual feedback on which fields contain values.
## Best Practices
1. **Use inheritance wisely**: Choose the appropriate inheritance mode based on your content structure:
- Use `inherit` for properties that should cascade down (e.g., author, copyright)
- Use `add` for cumulative properties (e.g., keywords, tags)
- Use `none` for page-specific properties (e.g., noindex flag)
2. **Language-independent design**: Remember that metadata is not language-dependent. Design your metadata schema accordingly.
3. **Conditional visibility**: Use ELEMENTTYPE and TEMPLATE properties to show relevant metadata fields for specific contexts, improving editor experience.
4. **Fallback values**: Always handle cases where metadata might not be set, providing sensible defaults.
5. **Clear labeling**: Use descriptive labels in LANGINFO sections to help editors understand what each field is for.
6. **Component selection**: Be aware that some components (CMS_INPUT_DOMTABLE, CMS_INPUT_DOM, CMS_INPUT_RADIOBUTTON) cannot be emptied once populated. Choose components carefully.
7. **Visual feedback**: Remember that the metadata icon only appears after saving, so inform editors about this behavior.
## Summary
Metadata templates in FirstSpirit provide a powerful way to attach additional information to content elements. By leveraging:
- The `.meta()` method for accessing metadata values
- Inheritance options for hierarchical content structures
- ELEMENTTYPE and TEMPLATE properties for conditional display
- Form rules for dynamic metadata forms
You can create flexible, context-aware metadata systems that enhance content management and output generation across your FirstSpirit projects.

260
skills/firstspirit-templating/references/page-templates.md Normal file
View File

@@ -0,0 +1,260 @@
# Page Templates Reference
## Overview
Page templates provide the basic framework for pages in FirstSpirit. They serve as the foundational structure that establishes the layout and configuration for web content, containing information on the placement of elements such as logos and navigation tools, general settings, and definitions for locations where editors can insert content.
According to FirstSpirit documentation, "The first step in template development within a new project is to create a page template." Page templates incorporate both unchanging design elements (like navigation and logos) and reusable input components that can be used once per page (such as page titles).
## Page Template Structure
The FirstSpirit workspace organizes page templates through five configurable tabs:
### 1. Properties Tab
Houses all essential settings and configuration options needed for the page template. This tab contains the fundamental configuration that defines how the page template behaves.
### 2. Form Tab
Defines the input components that comprise the page's editing interface. This is where you specify what content editors can input and modify. Input components are defined within `<CMS_MODULE>` tags and enable editors to enter content for different page areas.
### 3. Rules Tab
Enables creation of rules to control elements and their properties. Rules provide dynamic behavior based on conditions and user actions.
### 4. Snippet Tab
Determines how pages appear within overview lists and preview displays. This tab is crucial for providing rich previews in SiteArchitect and ContentCreator.
### 5. Template Set Tab
Specifies the content presentation format within template sets. This controls how the content is ultimately rendered in different output channels.
## Working with Page Templates
### Development Workflow
Page template development follows a structured approach:
1. **Create new page templates** - Establish the foundation for your pages
2. **Define input components** - Set up fields for user data entry
3. **Configure content areas** - Create locations for flexible content placement
4. **Build navigation systems** - Establish website navigation structure
5. **Generate HTML output** - Define how templates render as web pages
### Key Principles
Page templates establish a standardized structure that allows content editors to add materials to predefined content zones while maintaining consistent design and layout across pages. This system balances template designer control with editor flexibility for content insertion.
## Input Components in Page Templates
Input components are the building blocks of the Form tab, enabling editors to enter and manage content.
### CMS_INPUT_TEXT Component
The `CMS_INPUT_TEXT` component provides a single-line or multi-line text field suitable for various text input needs.
#### Basic Structure
```xml
<CMS_INPUT_TEXT name="uniqueName" hFill="yes" singleLine="no" useLanguages="yes">
<LANGINFOS>
<LANGINFO lang="*" label="Default Label" description="Default description"/>
<LANGINFO lang="DE" label="German Label" description="German description"/>
</LANGINFOS>
</CMS_INPUT_TEXT>
```
#### Common Attributes
- **`name`** - Unique identifier used to access stored content throughout the template
- **`hFill="yes"`** - Displays the component at full width within the form
- **`singleLine="no"`** - Renders as multi-line text field with visible border
- **`useLanguages="yes"`** - Stores different values per language, enabling multilingual content
- **`maxInputLength`** - Character limit for input (e.g., `"40"`)
- **`allowEmpty="yes"`** - Makes the field optional; editors can leave it blank
### LANGINFO Elements
LANGINFO elements specify language-specific labels and descriptions for input components:
```xml
<LANGINFOS>
<LANGINFO lang="*" label="Default Label" description="Tooltip text"/>
<LANGINFO lang="DE" label="Deutsche Bezeichnung" description="Deutsche Beschreibung"/>
<LANGINFO lang="EN" label="English Label" description="English description"/>
</LANGINFOS>
```
- **`lang="*"`** - Default fallback for languages not explicitly listed
- **`lang="DE"`** - German language variant
- **`label`** - Display text shown in the form editor
- **`description`** - Tooltip text displayed on mouseover
### CMS_GROUP Component
The `CMS_GROUP` component organizes related inputs into logical sections:
```xml
<CMS_GROUP name="groupName" tabs="top">
<LANGINFOS>
<LANGINFO lang="*" label="Group Label"/>
</LANGINFOS>
<CMS_TAB name="tab1">
<LANGINFOS>
<LANGINFO lang="*" label="Tab 1"/>
</LANGINFOS>
<!-- Input components here -->
</CMS_TAB>
<CMS_TAB name="tab2">
<LANGINFOS>
<LANGINFO lang="*" label="Tab 2"/>
</LANGINFOS>
<!-- Input components here -->
</CMS_TAB>
</CMS_GROUP>
```
The `tabs="top"` attribute positions tab labels above the grouped sections, creating an organized interface for editors.
### Practical Example
Here's a complete example grouping two inputs for page metadata:
```xml
<CMS_GROUP name="pageMetadata" tabs="top">
<LANGINFOS>
<LANGINFO lang="*" label="Page Metadata"/>
</LANGINFOS>
<CMS_TAB name="headline">
<LANGINFOS>
<LANGINFO lang="*" label="Headline"/>
</LANGINFOS>
<CMS_INPUT_TEXT name="st_headline" hFill="yes" singleLine="no" useLanguages="yes" maxInputLength="40">
<LANGINFOS>
<LANGINFO lang="*" label="Page Headline" description="Main headline displayed on the page (max 40 characters)"/>
</LANGINFOS>
</CMS_INPUT_TEXT>
</CMS_TAB>
<CMS_TAB name="browserTitle">
<LANGINFOS>
<LANGINFO lang="*" label="Browser Title"/>
</LANGINFOS>
<CMS_INPUT_TEXT name="st_browser_title" hFill="yes" singleLine="no" useLanguages="yes" allowEmpty="yes">
<LANGINFOS>
<LANGINFO lang="*" label="Browser Title" description="Title displayed in browser tab (optional)"/>
</LANGINFOS>
</CMS_INPUT_TEXT>
</CMS_TAB>
</CMS_GROUP>
```
This example creates:
- A page headline field (required, maximum 40 characters)
- A browser title field (optional, no character limit)
- Both fields organized in separate tabs for logical organization during content editing
## Content Insertion Locations
Page templates define specific locations where editors can insert content. These predefined content zones allow editors to add materials while maintaining consistent design and layout across pages. This approach ensures that:
- Template designers maintain control over the overall structure
- Editors have flexibility to add and manage content within defined areas
- The site maintains visual and structural consistency
- Content can be easily managed and updated without affecting the template structure
## Snippet Tab Configuration
The Snippet tab defines how pages appear in search results and other locations within SiteArchitect and ContentCreator. Rather than displaying only a page name, it enables a richer preview experience.
### Purpose
The Snippet tab provides editors with "a clear presentation of the content of the search hit" to identify relevant results quickly and locate target objects more efficiently than viewing names alone.
### Key Components
The Snippet tab allows configuration of three preview elements:
1. **Thumbnail** - An image representation of the page
2. **Label** - A title for the search result or preview
3. **Extract** - A text excerpt section providing context
### Configuration Approach
Editors can combine multiple input components from the Form tab to customize the display output. The system supports methods compatible with `[$CMS_VALUE(...)$]` functions, allowing conditional display based on editorial content inputs.
#### Example Configuration
```xml
<!-- Snippet configuration example -->
<THUMBNAIL>
[$CMS_VALUE(pt_image.thumbnail)$]
</THUMBNAIL>
<LABEL>
[$CMS_VALUE(st_headline)$]
</LABEL>
<EXTRACT>
[$CMS_VALUE(st_teaser_text)$]
</EXTRACT>
```
### Fallback Behavior
When editors haven't filled in a specified input component, the system provides automatic fallbacks:
- **Default Label**: The page name displays as the title
- **Default Extract**: The path to the search result displays as text
- **Path Display**: The path always displays in ContentCreator regardless of configuration
### Benefits
This configuration approach offers several advantages:
- **Enhanced Discoverability**: Richer previews help editors locate content faster
- **Context at a Glance**: Editors can understand page content without opening it
- **Improved Workflow**: Reduces time spent searching for specific pages
- **Better Content Management**: Visual and textual previews improve content organization
### Access in Interface
In compact view within the FirstSpirit interface, the Snippet tab is represented by a snippet icon. Toolbar functions and additional details are documented in the Composition of templates section.
## Best Practices
When working with page templates, consider these recommendations:
1. **Plan Your Structure**: Design your page template structure before implementation, considering both static elements and dynamic content areas
2. **Use Meaningful Names**: Choose descriptive names for input components that clearly indicate their purpose (e.g., `st_headline`, `pt_image`, `st_teaser_text`)
3. **Implement Language Support**: Enable `useLanguages="yes"` for components that need multilingual content
4. **Group Related Components**: Use `CMS_GROUP` to organize related input components logically, improving the editor experience
5. **Configure Snippet Previews**: Always configure the Snippet tab to provide meaningful previews for editors
6. **Set Appropriate Constraints**: Use `maxInputLength` and `allowEmpty` attributes to guide editors and maintain content consistency
7. **Provide Clear Labels**: Write descriptive labels and descriptions for all input components to guide editors
8. **Balance Flexibility and Control**: Define content insertion locations that give editors flexibility while maintaining design consistency
## Summary
Page templates are the foundational element of FirstSpirit template development. They establish the framework for pages by:
- Defining the overall page structure through five configurable tabs (Properties, Form, Rules, Snippet, Template Set)
- Providing input components for editors to enter and manage content
- Establishing locations where content can be inserted
- Configuring how pages appear in previews and search results
- Balancing template designer control with editor flexibility
By understanding and effectively utilizing page templates, developers can create robust, maintainable, and editor-friendly content management solutions in FirstSpirit.

689
skills/firstspirit-templating/references/rules.md Normal file
View File

@@ -0,0 +1,689 @@
# FirstSpirit Rules and Dynamic Forms
## Overview
FirstSpirit rules enable template developers to create dynamic forms that automatically adjust based on user input and content state. These rules function seamlessly across both SiteArchitect and ContentCreator environments, providing real-time form manipulation capabilities.
### Key Capabilities
Rules allow developers to:
1. **Validate form content** - Check conditions such as whether dates fall within required timeframes, validate field lengths, or ensure required fields contain appropriate data
2. **Control field visibility** - Dynamically hide or show form elements based on specific conditions or user selections
3. **Establish relationships** - Create dependencies where one field's value affects others (e.g., supplier selection filtering available product options)
4. **Manipulate form properties** - Modify editability, focus, selections, and other component properties dynamically
### Execution Timing
Rules analyze form states at three critical stages:
- **During editorial input** - Real-time evaluation as users interact with the form
- **Upon saving** - Validation before committing changes to the database
- **When entering edit mode or creating new elements** - Initial form setup and configuration
### Rule Violations
When rules are violated, the system displays:
- Color-coded messages tied to restriction levels
- Explanatory messages in the user's language
- Immediate feedback without disrupting normal workspace layout
### Important Security Note
**Using rules to display and hide form elements is not a security model.** Rules assist workflow usability rather than protecting sensitive data from unauthorized access. Do not rely on rules for security-sensitive operations.
### Version Compatibility
FirstSpirit 5.2 introduced modified rule syntax, though earlier versions remain compatible during a transition period.
---
## The Rules Tab
### Purpose
The Rules tab within the Template Store enables template developers to define rules that influence form elements and properties dynamically.
### Available Template Types
The Rules tab can be configured in:
- Page templates
- Section templates
- Format templates (style templates only)
- Link templates
- Table templates
- Scripts
- Workflows
### Section Template Limitation
Rules defined in section templates only affect forms directly based on that template. **Section references do not trigger rule violations**, meaning rules have no impact on referenced sections.
### Developer Assistance
The platform provides code completion functionality on the Rules tab, displaying:
- Available tags in the current context
- Valid parameters for each tag
- Possible values for attributes
This assists developers in writing syntactically correct rules.
---
## Rule Structure
FirstSpirit rules consist of five main components, defined within `<RULE>` tags.
### 1. Execution Time
Rules execute by default when forms are edited. The optional `when` attribute restricts execution to specific events:
- **ONSAVE** - Executes during saving operations
- **ONLOCK** - Executes when entering edit mode or creating new items
#### Example
```xml
<RULE>
<!-- Executes during form editing (default) -->
</RULE>
<RULE when="ONSAVE">
<!-- Executes only during save operations -->
</RULE>
<RULE when="ONLOCK">
<!-- Executes when entering edit mode or creating new items -->
</RULE>
```
### 2. Preconditions (Optional)
An `<IF/>` section defines conditions that must be met before the rule executes. These check form properties and are connected using logical tags.
#### Example
```xml
<RULE>
<IF>
<PROPERTY source="checkbox_field" name="VALUE"/>
</IF>
<!-- Rule only executes if checkbox_field is checked -->
</RULE>
```
### 3. Value Determination
The rule evaluates form or element properties using:
- **Synchronous checks** - Using `<WITH/>` tags for immediate evaluation
- **Asynchronous execution** - Using `<SCHEDULE/>` tags for deferred evaluation
Values are compared against constants or other form properties.
#### Example
```xml
<RULE>
<WITH>
<PROPERTY source="text_field" name="EMPTY"/>
</WITH>
<!-- Checks if text_field is empty -->
</RULE>
```
### 4. Handling Instructions (Required)
A **required** `<DO/>` section specifies actions when conditions are met, such as:
- Modifying input component properties
- Displaying correction messages
- Changing form element visibility
- Manipulating selection lists
#### Example
```xml
<RULE>
<WITH>
<PROPERTY source="text_field" name="EMPTY"/>
</WITH>
<DO>
<PROPERTY source="submit_button" name="VISIBLE" value="false"/>
</DO>
<!-- Hides submit button when text_field is empty -->
</RULE>
```
### 5. Validation (Optional)
A `<VALIDATION/>` section executes when value determination returns FALSE, assigning actions to specific input components with three restriction levels:
- **SAVE** - Prevents saving (highest severity)
- **RELEASE** - Prevents releasing
- **INFO** - Default informational level (lowest severity)
#### Example
```xml
<RULE>
<WITH>
<NOT>
<PROPERTY source="email_field" name="EMPTY"/>
</NOT>
</WITH>
<DO>
<VALIDATION>
<PROPERTY source="email_field" name="VALID" value="true"/>
</VALIDATION>
</DO>
</RULE>
```
### Minimum Requirements
Each rule must contain at least:
1. A value determination section (`<WITH/>` or `<SCHEDULE/>`)
2. A handling instruction section (`<DO/>`)
---
## Validation
### Core Concept
Validation is "a certain handling instruction that is executed as long as conditions defined within the `<WITH/>` section are not fulfilled."
### Key Characteristics
- Validations are **optional** within rules
- Must be assigned to a specific form input component
- Uses an internal `<PROPERTY>` tag with the component name and `VALID` attribute
- Multiple validations can exist in a single `<DO>` section for different components
### Message Display
When a `<MESSAGE>` tag follows the `<PROPERTY>` tag, the corresponding message displays below the input component.
#### Example
```xml
<RULE when="ONSAVE">
<WITH>
<NOT>
<PROPERTY source="title_field" name="EMPTY"/>
</NOT>
</WITH>
<DO>
<VALIDATION severity="SAVE">
<PROPERTY source="title_field" name="VALID" value="true"/>
<MESSAGE lang="*" text="Title is required before saving"/>
<MESSAGE lang="DE" text="Titel ist erforderlich vor dem Speichern"/>
</VALIDATION>
</DO>
</RULE>
```
### Negation with NOT
Boolean results can be negated using the `<NOT/>` tag to invert validation logic.
#### Example
```xml
<WITH>
<NOT>
<PROPERTY source="field_name" name="EMPTY"/>
</NOT>
</WITH>
<!-- TRUE when field_name is NOT empty -->
```
### Practical Validation Scenarios
#### Combined Field Checks
Multiple input fields can be validated together, where at least one must contain data before saving.
```xml
<RULE when="ONSAVE">
<WITH>
<OR>
<NOT>
<PROPERTY source="phone_field" name="EMPTY"/>
</NOT>
<NOT>
<PROPERTY source="email_field" name="EMPTY"/>
</NOT>
</OR>
</WITH>
<DO>
<VALIDATION severity="SAVE">
<PROPERTY source="phone_field" name="VALID" value="true"/>
<PROPERTY source="email_field" name="VALID" value="true"/>
<MESSAGE lang="*" text="Either phone or email is required"/>
</VALIDATION>
</DO>
</RULE>
```
#### Multi-Rule Validation
A single component can be validated across separate rules (e.g., character limit in one rule, number restrictions in another). Each rule independently affects validity - if any rule marks it invalid, the component becomes invalid overall.
```xml
<!-- Rule 1: Check minimum length -->
<RULE when="ONSAVE">
<WITH>
<PROPERTY source="username" name="LENGTH"/>
<LESS value="5"/>
</WITH>
<DO>
<VALIDATION severity="SAVE">
<PROPERTY source="username" name="VALID" value="false"/>
<MESSAGE lang="*" text="Username must be at least 5 characters"/>
</VALIDATION>
</DO>
</RULE>
<!-- Rule 2: Check for special characters -->
<RULE when="ONSAVE">
<WITH>
<PROPERTY source="username" name="VALUE"/>
<MATCHES regex="[^a-zA-Z0-9]"/>
</WITH>
<DO>
<VALIDATION severity="SAVE">
<PROPERTY source="username" name="VALID" value="false"/>
<MESSAGE lang="*" text="Username can only contain letters and numbers"/>
</VALIDATION>
</DO>
</RULE>
```
### Default Values Behavior
Rules preventing form saves are suspended when applying default or fallback values through the template store, allowing pre-assigned values to be saved without triggering validation errors.
---
## Form Properties
### Overview
The `<PROPERTY/>` tag defines form element properties across rule definitions. It serves two purposes:
1. Determining values or properties (in preconditions and value determination)
2. Performing actions on form elements (in handling instructions)
### Required Attributes
- **source** - Specifies the form element (component name, design component, or system object)
- **name** - Specifies which property to access
### Source Types
#### 1. Input Component
Access specific component properties like stored values:
```xml
<PROPERTY source="gadget" name="VALUE"/>
```
#### 2. Design Component
Access non-value elements like groups or labels using the `#form.` prefix:
```xml
<PROPERTY source="#form.gadget" name="VISIBLE"/>
```
#### 3. General Form Information
Access form-level data using the `#global` source:
```xml
<PROPERTY source="#global" name="LANG"/>
```
### Available Properties by Context
#### For Input Components
**Preconditions/Value Determination:**
- CONTAINERTYPE
- DEFAULT
- EDITABLE
- EMPTY
- ENTRY
- FOCUS
- LABEL
- LENGTH
- QUERY.*
- SECTION
- SIZE
- VALUE
- VISIBLE
- VALID
**Handling Instructions:**
- ADD
- COPY
- DESELECT
- EDIT
- EDITABLE
- EMPTY
- NEW
- REMOVE
- SELECT
- VALUE
- VISIBLE
**Validation:**
- VALID
#### For Design Components
**Preconditions/Value Determination:**
- FOCUS (returns FALSE)
- LABEL
- VISIBLE
**Handling Instructions:**
- VISIBLE
#### For General Form Information (#global)
**Preconditions/Value Determination:**
- BODY
- ELEMENTTYPE
- GID
- ID
- INCLUDED
- LANG
- MASTER
- PRESET
- STORETYPE
- TEMPLATE
- TRANSLATED
- UID
- WEB
### Key Property Functions
| Property | Function | Example |
|----------|----------|---------|
| VALUE | Returns or sets the value of an input component | `<PROPERTY source="field" name="VALUE"/>` |
| VISIBLE | Controls visibility of components | `<PROPERTY source="field" name="VISIBLE" value="false"/>` |
| EMPTY | Checks or sets blank values | `<PROPERTY source="field" name="EMPTY"/>` |
| EDITABLE | Defines editability | `<PROPERTY source="field" name="EDITABLE" value="false"/>` |
| FOCUS | Returns Boolean focus state | `<PROPERTY source="field" name="FOCUS"/>` |
| SELECT | Manipulates selection in lists | `<PROPERTY source="list" name="SELECT"/>` |
| DESELECT | Removes selection in lists | `<PROPERTY source="list" name="DESELECT"/>` |
| LENGTH | Returns character count | `<PROPERTY source="field" name="LENGTH"/>` |
| VALID | Sets validation state | `<PROPERTY source="field" name="VALID" value="true"/>` |
---
## Practical Examples and Best Practices
### Example 1: Conditional Field Visibility
Show additional fields only when a checkbox is selected:
```xml
<RULE>
<WITH>
<PROPERTY source="show_details" name="VALUE"/>
</WITH>
<DO>
<PROPERTY source="detail_text" name="VISIBLE" value="true"/>
<PROPERTY source="detail_date" name="VISIBLE" value="true"/>
</DO>
</RULE>
<RULE>
<WITH>
<NOT>
<PROPERTY source="show_details" name="VALUE"/>
</NOT>
</WITH>
<DO>
<PROPERTY source="detail_text" name="VISIBLE" value="false"/>
<PROPERTY source="detail_date" name="VISIBLE" value="false"/>
</DO>
</RULE>
```
### Example 2: Dependent Dropdown Lists
Filter product options based on selected category:
```xml
<RULE>
<WITH>
<PROPERTY source="category_select" name="VALUE"/>
<EQUALS value="electronics"/>
</WITH>
<DO>
<PROPERTY source="product_select" name="VISIBLE" value="true"/>
<!-- Additional logic to filter product list would go here -->
</DO>
</RULE>
```
### Example 3: Date Range Validation
Ensure end date is after start date:
```xml
<RULE when="ONSAVE">
<WITH>
<PROPERTY source="end_date" name="VALUE"/>
<LESS>
<PROPERTY source="start_date" name="VALUE"/>
</LESS>
</WITH>
<DO>
<VALIDATION severity="SAVE">
<PROPERTY source="end_date" name="VALID" value="false"/>
<MESSAGE lang="*" text="End date must be after start date"/>
<MESSAGE lang="DE" text="Enddatum muss nach dem Startdatum liegen"/>
</VALIDATION>
</DO>
</RULE>
```
### Example 4: Required Field Groups
Make fields required only when a certain option is selected:
```xml
<RULE when="ONSAVE">
<WITH>
<AND>
<PROPERTY source="contact_type" name="VALUE"/>
<EQUALS value="email"/>
<PROPERTY source="email_address" name="EMPTY"/>
</AND>
</WITH>
<DO>
<VALIDATION severity="SAVE">
<PROPERTY source="email_address" name="VALID" value="false"/>
<MESSAGE lang="*" text="Email address is required when contact type is email"/>
</VALIDATION>
</DO>
</RULE>
```
### Example 5: Character Length Validation
Enforce minimum and maximum character limits:
```xml
<RULE when="ONSAVE">
<WITH>
<OR>
<AND>
<PROPERTY source="description" name="LENGTH"/>
<LESS value="10"/>
</AND>
<AND>
<PROPERTY source="description" name="LENGTH"/>
<GREATER value="500"/>
</AND>
</OR>
</WITH>
<DO>
<VALIDATION severity="SAVE">
<PROPERTY source="description" name="VALID" value="false"/>
<MESSAGE lang="*" text="Description must be between 10 and 500 characters"/>
</VALIDATION>
</DO>
</RULE>
```
### Example 6: Making Fields Read-Only Based on Conditions
Lock fields after a certain workflow stage:
```xml
<RULE>
<WITH>
<PROPERTY source="#global" name="PRESET"/>
<EQUALS value="published"/>
</WITH>
<DO>
<PROPERTY source="title_field" name="EDITABLE" value="false"/>
<PROPERTY source="url_field" name="EDITABLE" value="false"/>
</DO>
</RULE>
```
---
## Best Practices
### 1. Use Descriptive Component Names
Name your form components clearly so rules are easier to understand and maintain:
```xml
<!-- Good -->
<PROPERTY source="user_email" name="EMPTY"/>
<!-- Avoid -->
<PROPERTY source="field1" name="EMPTY"/>
```
### 2. Provide Multi-Language Messages
Always include messages in all supported languages:
```xml
<MESSAGE lang="*" text="Default English message"/>
<MESSAGE lang="DE" text="German message"/>
<MESSAGE lang="FR" text="French message"/>
```
### 3. Use Appropriate Validation Severity
Choose the right severity level for your validation:
- **SAVE** - Use for critical validations that must pass before saving
- **RELEASE** - Use for validations that should pass before releasing to production
- **INFO** - Use for helpful suggestions that don't block saving
### 4. Combine Rules Logically
Break complex logic into multiple rules for better maintainability:
```xml
<!-- Instead of one complex rule, use multiple simpler rules -->
<RULE>
<!-- Rule for visibility -->
</RULE>
<RULE>
<!-- Rule for validation -->
</RULE>
<RULE>
<!-- Rule for editability -->
</RULE>
```
### 5. Test Rules Thoroughly
Test rules in different scenarios:
- Creating new content
- Editing existing content
- Saving content
- Releasing content
- Different language contexts
- Different user permissions
### 6. Consider Performance
- Avoid overly complex rules that might slow down form interactions
- Use `when="ONSAVE"` or `when="ONLOCK"` to limit execution frequency when appropriate
- Be cautious with asynchronous `<SCHEDULE/>` operations
### 7. Document Complex Rules
Add comments to complex rule logic:
```xml
<!-- This rule ensures that when the user selects "custom" option,
the custom text field becomes visible and required -->
<RULE>
...
</RULE>
```
### 8. Remember Security Limitations
Do not rely on rules for security:
- Rules only control UI behavior
- They do not prevent direct API access
- Use proper permissions and backend validation for security
### 9. Handle Edge Cases
Consider what happens when:
- Fields are empty
- Users switch languages
- Content is in different workflow states
- Multiple users edit simultaneously
### 10. Use Logical Operators Effectively
Combine conditions using `<AND>`, `<OR>`, and `<NOT>` for precise control:
```xml
<WITH>
<AND>
<OR>
<PROPERTY source="field1" name="EMPTY"/>
<PROPERTY source="field2" name="EMPTY"/>
</OR>
<NOT>
<PROPERTY source="field3" name="EMPTY"/>
</NOT>
</AND>
</WITH>
```
---
## Summary
FirstSpirit rules provide powerful capabilities for creating dynamic, user-friendly forms that adapt to content and user interactions. By understanding rule structure, validation mechanisms, and form properties, developers can create sophisticated form behaviors that guide editors and ensure content quality. Remember that rules enhance usability but should not be relied upon for security, and always test rules thoroughly across different scenarios and languages.

242
skills/firstspirit-templating/references/script-templates.md Normal file
View File

@@ -0,0 +1,242 @@
# Scripts and Script Templates
## Overview
Scripts in FirstSpirit enable the implementation of custom functions and capabilities not yet available in the system. They are particularly useful for:
- Complex migration scenarios
- Connecting external systems
- Custom business logic implementation
- Temporary solutions before module development
### Important Consideration
While scripts provide flexibility, FirstSpirit recommends that **functionalities required and used in the long term should be implemented as a FirstSpirit module** with executable or plugin components for better stability and maintainability.
## BeanShell Scripting Language
FirstSpirit uses **BeanShell** as its scripting language, which provides a powerful yet accessible scripting environment.
### Language Characteristics
**Syntax Foundation:**
- Heavily based on Java programming language
- Much more straightforward than Java in many aspects
- Familiar to Java developers but easier to learn
**Key Features:**
- **Dynamic Typing**: Global variables and functions support dynamic typing, eliminating the need for explicit type declarations in many cases
- **Limited Reflexive Access**: Programs can examine and modify their own structure at runtime
- **Simplified Syntax**: Reduces boilerplate code compared to traditional Java
### BeanShell vs Java
BeanShell maintains Java's familiar syntax while adding convenience features:
```beanshell
// Dynamic typing - no type declaration needed
myVariable = "Hello, FirstSpirit";
myNumber = 42;
// Traditional Java-style typing also supported
String explicitString = "Typed variable";
int explicitNumber = 100;
```
## Script Template Configuration
Scripts in FirstSpirit are configured through a multi-tab interface in SiteArchitect, each serving a specific purpose.
### 1. Properties Tab
Contains the **required script settings** including:
- Script name and identification
- Basic configuration parameters
- Script metadata
### 2. Form Tab
Defines **input components** that are called during script runtime:
- User input fields
- Configuration parameters
- Runtime arguments
- Interactive elements for script execution
**Purpose:** Enables scripts to receive dynamic input from users or system processes when executed.
### 3. Rules Tab
Enables the definition of **rules** that influence elements or properties:
- Conditional logic
- Element behavior modification
- Property dependencies
- Validation rules
**Purpose:** Controls how the script interacts with and affects FirstSpirit elements and their properties.
### 4. Template Set Tab
Houses the **actual BeanShell source code**:
- Script implementation
- Function definitions
- Business logic
- Integration code
**Purpose:** Contains the executable code that performs the script's intended functionality.
## Implementing Custom Functions
Custom functions in FirstSpirit scripts leverage BeanShell's capabilities to extend system functionality.
### Function Definition
Functions can be defined using BeanShell's flexible syntax:
```beanshell
// Simple function with dynamic typing
myFunction(param1, param2) {
return param1 + param2;
}
// Function with explicit types (Java-style)
String formatName(String firstName, String lastName) {
return firstName + " " + lastName;
}
// Function with mixed typing
processData(dynamicInput) {
String result = "Processed: " + dynamicInput;
return result;
}
```
### Global Variables
Scripts support global variables with dynamic typing:
```beanshell
// Global variable definition
globalCounter = 0;
globalConfig = new HashMap();
// Usage in functions
incrementCounter() {
globalCounter++;
return globalCounter;
}
```
## Script Template Usage
### Use Cases
**Migration Scenarios:**
Scripts excel in complex data migration tasks where:
- Custom transformation logic is needed
- Data structures require manipulation
- Legacy system integration is required
**External System Integration:**
Scripts facilitate connections to:
- Third-party APIs
- External databases
- Custom web services
- Legacy systems
**Custom Business Logic:**
Implement specialized functionality for:
- Unique content processing
- Custom validation rules
- Specialized workflow automation
### Best Practices
1. **Temporary vs Permanent Solutions**
- Use scripts for temporary or experimental features
- Migrate long-term functionality to FirstSpirit modules
2. **Code Organization**
- Keep scripts focused on specific tasks
- Use clear naming conventions
- Document complex logic
3. **Performance Considerations**
- Be mindful of script execution time
- Optimize for frequently-used scripts
- Consider module development for performance-critical operations
4. **Maintainability**
- Write clean, readable code
- Add comments for complex operations
- Follow consistent coding standards
## Integration with Template Development
Scripts work alongside other template components in FirstSpirit's development ecosystem.
### Template Set Relationship
Scripts exist within the Template Set tab, indicating their close relationship with:
- Page templates
- Section templates
- Format templates
- Other template types
### Runtime Execution
Scripts can be:
- Called from templates
- Triggered by workflows
- Executed manually from SiteArchitect
- Invoked through forms and input components
### Development Workflow
1. **Design**: Plan script functionality and input requirements
2. **Configure**: Set up Properties, Form, and Rules tabs
3. **Implement**: Write BeanShell code in Template Set tab
4. **Test**: Execute and validate script behavior
5. **Deploy**: Integrate with templates and workflows
6. **Migrate**: Convert to module if long-term usage is needed
## Advanced Capabilities
### Reflexive Programming
BeanShell's limited reflexive program access allows scripts to:
- Examine object structures at runtime
- Modify behavior dynamically
- Adapt to changing conditions
### Java Integration
Scripts can leverage Java libraries and classes:
```beanshell
// Import Java classes
import java.util.ArrayList;
import java.text.SimpleDateFormat;
// Use Java objects
list = new ArrayList();
formatter = new SimpleDateFormat("yyyy-MM-dd");
```
### FirstSpirit API Access
Scripts have access to FirstSpirit's API for:
- Content manipulation
- Workflow operations
- Template processing
- System integration
## Reference Resources
For deeper technical information about scripting in FirstSpirit, consult:
- **Template Development Resources**: Scripting section
- **FirstSpirit API Documentation**: For available methods and objects
- **BeanShell Documentation**: For language-specific features and syntax
## Summary
Scripts and script templates in FirstSpirit provide a powerful mechanism for extending system capabilities through BeanShell scripting. While they offer flexibility for temporary solutions and complex integrations, long-term functionality should be implemented as FirstSpirit modules for better stability and maintainability. The four-tab configuration system (Properties, Form, Rules, Template Set) provides a structured approach to script development, enabling developers to create sophisticated custom functions that integrate seamlessly with FirstSpirit's template system.

275
skills/firstspirit-templating/references/section-templates.md Normal file
View File

@@ -0,0 +1,275 @@
# Section Templates
## Overview
Section templates are content containers within FirstSpirit pages that add dynamic content to the basic framework defined by page templates. They serve as the primary mechanism for defining input components that will contain dynamic page content such as text, tables, images, datasets, and other content types.
### Key Characteristics
- **Purpose**: Add content to the basic framework of a page defined by the page template
- **Flexibility**: Multiple section templates can be created for different content types on a single page
- **Scalability**: Any number of sections can be added to each section area of a page
- **Configuration Similarity**: Section templates function similarly to page templates in their configuration approach
## Section Template Structure
Section templates are configured through five main tabs in the SiteArchitect editor:
### 1. Properties Tab
Contains all required settings for the template, including:
- Template identification and naming
- Basic configuration parameters
- Template metadata
### 2. Form Tab
Defines the input components for the section's content. This is where you specify what types of dynamic content the section will support:
- Text input components
- Image selectors
- Dataset references
- Table components
- Custom input elements
### 3. Rules Tab
Enables conditional logic to influence elements and properties:
- Define rules that control template behavior
- Set conditions for displaying or hiding elements
- Configure property dependencies
### 4. Snippet Tab
Controls how the section appears in overview lists:
- Define preview representations
- Configure snippet display format
- Control list view appearance
### 5. Template Set Tab
Defines how content appears within the template set framework. See the Template Sets section below for detailed information.
## Creating Section Templates
All input components that contain dynamic page content (text, tables, images, datasets, etc.) are defined within a section template. Follow this step-by-step process to create section templates:
### Step 1: Open the Edit Entry View
Access the HTML file editor and select the relevant HTML area to trigger an overlay window.
### Step 2: Identify the Target Section
Move your cursor within the preview until the correct DIV element is highlighted with a frame border. This visual feedback ensures you're targeting the correct container element.
### Step 3: Access the Add Component Dialog
Click the identified entry in the overlay to open the configuration options dialog.
### Step 4: Configure the Component
When configuring the section template component:
1. **Assign a descriptive name**: Use meaningful names that describe the content purpose (e.g., "teaser", "hero_section", "article_body")
2. **Select component type**: Choose "Section template" as the component type from the available options
3. **Replace entire HTML tag option**: Leave the "Replace entire HTML tag" checkbox unchecked by default
- When checked, this option replaces the entire HTML element with FirstSpirit-specific syntax
- In most use cases, this should remain unchecked to preserve the HTML structure
### Step 5: Save and Transfer
Click Create to finalize the configuration, then save changes to transfer the component to the Overview tab where it can be further edited and managed.
## Variant Detection
The template wizard includes an automatic variant detection feature that recognizes different template variants when the VARIANT component template is enabled in project Settings.
### Benefits of Variant Detection
- **Single Template, Multiple Designs**: A single section template can accommodate optional components and multiple design variations
- **Reduced Duplication**: Eliminates the need to create separate section templates for similar content with minor variations
- **Streamlined Management**: Simplifies template maintenance by consolidating variants into a single template definition
### How It Works
When variant detection is enabled:
1. The template wizard automatically identifies variant patterns in the HTML structure
2. Different design variations are recognized and mapped to the same section template
3. Optional components are detected and can be toggled on/off without requiring separate templates
## Input Components for Dynamic Content
Section templates define input components for various types of dynamic page content. The Form tab is where these components are configured.
### Common Input Component Types
#### Text Components
- Rich text editors for formatted content
- Plain text fields for simple text input
- Multi-line text areas for longer content
#### Image Components
- Image selectors for media library integration
- Image upload interfaces
- Image metadata configuration (alt text, captions, etc.)
#### Table Components
- Data table definitions
- Column and row configuration
- Cell formatting options
#### Dataset Components
- References to database content
- Dataset query configurations
- Related content connections
## Template Sets
Template sets are administrator-configured components within FirstSpirit projects that enable content management and processing.
### What Are Template Sets?
A unique tab is displayed for each template set added by the administrator for a project in the ServerManager. Template sets provide a framework where developers can check, process, and evaluate entries from the Page Store.
### Primary Function
The template set tab serves as a workspace for defining:
- Website functionality
- Content appearance
- Dynamic content processing
The most common implementation is the HTML template set, which allows developers to define website output through source code.
### Structural Organization
Template set content divides into two distinct regions:
#### 1. CMS_HEADER Area
The header area is reserved for function definitions such as:
- Navigation setup
- Dataset output configuration
- Function declarations
- Variable definitions
**Important Note**: `$CMS_(...)` instructions are NOT processed within the CMS_HEADER section. This area is strictly for function definitions.
#### 2. Output Area
The output area supports:
- `$CMS_(...)` instructions for dynamic content
- HTML code for structure and layout
- FirstSpirit syntax for displaying website content
- Template logic and control structures
### Development Features
#### Automatic Code Completion
The template set editor provides automatic code completion for tags starting with `$`, which streamlines template development by:
- Suggesting available FirstSpirit tags
- Reducing syntax errors
- Improving development speed
#### Example Structure
```html
$CMS_HEADER(
// Function definitions
// Navigation setup
// Variable declarations
)$
<!-- Output Area -->
<div class="section-content">
$CMS_VALUE(st_text)$
$CMS_RENDER(template:"image_component")$
</div>
```
### Role in Section Templates
Template set tabs function as integral components of section template architecture. They allow developers to:
1. Translate Page Store content into rendered HTML output
2. Apply dynamic FirstSpirit functionality to content
3. Control the final appearance and behavior of section content
4. Integrate with the broader page framework
## Best Practices
### Naming Conventions
- Use descriptive, meaningful names for section templates (e.g., "article_teaser", "hero_banner", "content_body")
- Follow consistent naming patterns across your project
- Use lowercase with underscores or camelCase for clarity
### Template Organization
- Group related section templates logically
- Create reusable section templates for common content patterns
- Document template purpose and usage in comments or metadata
### Variant Usage
- Enable variant detection when you have similar content with minor variations
- Use variants to reduce template proliferation
- Keep variant logic simple and maintainable
### Content Separation
- Use the CMS_HEADER area for all function definitions
- Keep output logic in the designated output area
- Separate concerns: structure (HTML), style (CSS references), and behavior (FirstSpirit logic)
### Input Component Design
- Define clear, intuitive input components for content editors
- Provide appropriate defaults where possible
- Include help text or documentation for complex components
- Consider the editor's workflow when designing the form layout
## Common Use Cases
### 1. Article Teaser Section
A section template for displaying article previews with:
- Headline text input
- Teaser text area
- Featured image selector
- Link to full article
### 2. Hero Banner Section
A full-width banner section with:
- Background image component
- Headline and subheadline text fields
- Call-to-action button configuration
- Overlay opacity settings
### 3. Content Body Section
The main content area with:
- Rich text editor for article body
- Embedded image support
- Table insertion capability
- Dataset references for related content
### 4. Data-Driven Section
Sections that pull from database content:
- Dataset query configuration
- Display template for dataset items
- Filtering and sorting options
- Pagination controls
## Integration with Page Templates
Section templates work in conjunction with page templates to create complete pages:
1. **Page Template**: Defines the overall page structure, layout framework, and section areas
2. **Section Templates**: Fill the section areas with specific content types and functionality
3. **Content Areas**: Designated regions in page templates where section templates can be added
Multiple sections using different section templates can be added to each section area, providing flexible content composition capabilities.
## Summary
Section templates are essential building blocks in FirstSpirit's templating architecture. They provide:
- Structured content input through configurable form components
- Flexible content rendering through template sets
- Reusable content patterns across multiple pages
- Dynamic content integration with the page framework
By understanding section template structure, creation process, and template set configuration, developers can create powerful, flexible content management solutions that serve both editor and end-user needs effectively.

364
skills/firstspirit-templating/references/snippets.md Normal file
View File

@@ -0,0 +1,364 @@
# FirstSpirit Snippets and Preview Content
## Overview
Snippets are configurable display components in FirstSpirit that define how objects appear in various interfaces throughout the system. They provide a standardized way to present pages, sections, datasets, and media content across search results, reports, and selection dialogs with rich contextual information.
### Purpose
The primary purpose of snippets is to define content that represents FirstSpirit objects as accurately as possible, acting as a form of "teaser" or preview. This enables editors to quickly identify and distinguish between different content items without needing to open each one individually.
### Benefits
- **Improved Editor Experience**: Editors can quickly scan and identify relevant content in search results and selection dialogs
- **Contextual Information**: Provides meaningful previews rather than just technical names or IDs
- **Consistency**: Standardizes how content appears across different FirstSpirit interfaces
- **Efficiency**: Reduces time spent searching for and identifying content items
## Snippet Components
Every snippet consists of three main elements that work together to create a comprehensive preview:
### 1. Thumbnail
A representative image for the object that provides visual identification.
**Characteristics:**
- Displays in the thumbnail area
- Can be pulled from input components (images, media elements)
- Provides quick visual recognition of content
### 2. Label
Representative text serving as the title or main identifier.
**Characteristics:**
- Acts as the primary text identifier
- Typically displays the page or object name
- Should be concise and descriptive
- Falls back to object name if not defined
### 3. Extract
A text summary or teaser content providing additional context.
**Characteristics:**
- Provides a brief description or excerpt of the content
- Often pulled from introductory text or summary fields
- Should give editors enough information to identify content purpose
- Falls back to search result path if not defined
## Where Snippets Appear
Snippets are displayed in multiple locations throughout FirstSpirit:
### SiteArchitect
- Search result lists
- Reports
- Selection dialogs
### ContentCreator
- Search results
- FragmentCreator navigation
- Content selection interfaces
## Defining Snippets in Templates
### The Snippet Tab
Page templates include a dedicated Snippet tab where snippet definitions are configured. This tab is represented by a snippet icon in the compact view.
**Configuration Location:**
- Navigate to the page template
- Select the Snippet tab
- Configure the three areas: Thumbnail, Label, and Extract
### Using Form Variables
Snippets leverage variables from the Form tab's input components. You can reference any input component defined in your template using its identifier.
**Key Principle:**
Multiple input components can be combined to better adjust the output to project-specific requirements.
### Syntax and Access Patterns
Snippet definitions use variable names combined with callable methods:
#### Basic Variable Access
```
#form.IDENTIFIER
```
#### Language-Specific Access
```
#form.IDENTIFIER.LANGABBREVIATION
```
#### Metadata Access
```
#meta.IDENTIFIER
```
#### Method Calls
Variables support methods compatible with `[$CMS_VALUE(...)$]` syntax:
```
#form.IDENTIFIER.method()
```
## Implementation Examples
### Example 1: Simple Page Template Snippet
**Label Configuration:**
```
#form.pt_title
```
**Extract Configuration:**
```
#form.pt_intro
```
This creates a snippet where:
- Label shows the page title from the `pt_title` input component
- Extract shows the introduction text from the `pt_intro` input component
### Example 2: Link Template with Referenced Page
**Label Configuration:**
```
lt_reference.get.displayName(#language)
```
**Extract Configuration:**
```
truncate(lt_reference.pageRef.page.formData.pt_intro, 65)
```
This creates a snippet where:
- Label displays the referenced page's name in the current language
- Extract shows a truncated version (65 characters) of the referenced page's introduction
### Example 3: Media Object Snippet
**Thumbnail Configuration:**
```
#form.pt_image
```
**Label Configuration:**
```
#form.pt_image.meta.description
```
**Extract Configuration:**
```
#form.pt_caption
```
This creates a snippet where:
- Thumbnail displays the actual image
- Label uses the image's metadata description
- Extract shows the caption field
## Advanced Techniques
### Empty Checks
Always implement empty checks to prevent generation errors when fields aren't populated:
```
#if (!form.pt_intro.isEmpty())
#form.pt_intro
#else
Default text or empty string
#end
```
### Type Checks
When snippets need to handle multiple object types (pages, references, files, images):
```
#if (#form.pt_reference.isPage())
#form.pt_reference.page.formData.pt_title
#elseif (#form.pt_reference.isFile())
#form.pt_reference.file.meta.description
#end
```
### Multilingual Support
For multilingual projects, access language-specific content:
```
#form.pt_title.#language
```
Or explicitly specify the language:
```
#form.pt_title.de
```
### Text Truncation
Limit extract length for consistent display:
```
truncate(#form.pt_intro, 100)
```
This ensures extracts don't exceed 100 characters.
### XML-Conforming Escape
Apply XML escaping to logic results for label and extract to ensure valid output:
```
escape(#form.pt_title)
```
This is particularly important when content may contain special characters or HTML.
## Default Behavior
### When Snippets Are Not Defined
If no snippet configuration exists for a template:
- **Label**: Displays the object name
- **Extract**: Shows the search result path
### When Fields Are Empty
If editors leave snippet-referenced fields empty:
- **Label**: Falls back to object name
- **Extract**: Falls back to search result path
### Path Display in ContentCreator
The search result path appears independently in ContentCreator regardless of snippet configuration. This provides consistent navigation context.
## Best Practices
### Content Design
1. **Be Descriptive**: Define content that clearly distinguishes between different object types and content items
2. **User-Focused**: Prioritize user-friendly display over technical hierarchy information
3. **Consistent Structure**: Maintain consistent snippet patterns across similar template types
4. **Meaningful Previews**: Ensure extracts provide enough context for editors to understand content purpose
### Technical Implementation
1. **Implement Validation**: Always include empty checks and type validation
2. **Use Fallbacks**: Provide sensible defaults when referenced fields are empty
3. **Limit Extract Length**: Truncate extracts to maintain consistent display
4. **Apply Escaping**: Use XML-conforming escapes for label and extract content
5. **Test Multiple Scenarios**: Verify snippets work with various content states (empty fields, different types, etc.)
### Performance Considerations
1. **Avoid Complex Logic**: Keep snippet definitions simple to ensure fast rendering
2. **Minimize Method Chaining**: Excessive method calls can impact performance
3. **Use Cached Values**: Leverage metadata and pre-processed values when available
### Content Guidelines
1. **Title/Label**: Should be concise (typically under 100 characters)
2. **Extract**: Recommended length 50-150 characters for optimal display
3. **Thumbnail**: Use appropriate image sizes (thumbnails, not full-resolution images)
### Multilingual Projects
1. **Language Consistency**: Ensure all snippet elements use the same language context
2. **Fallback Languages**: Implement fallback logic for untranslated content
3. **Language-Specific Formatting**: Consider cultural differences in text display
## Common Use Cases
### Teasers and Summaries
Snippets excel at creating teaser content for:
- News articles (headline + intro)
- Product pages (name + description)
- Event listings (title + date/location)
- Blog posts (title + excerpt)
### Selection Dialogs
When editors select pages or content through dialogs:
- Provide clear identification of content type
- Show enough context to make informed selections
- Use thumbnails to aid visual recognition
### Search Results
Optimize search result display:
- Prioritize relevant information in labels
- Include keywords in extracts
- Use thumbnails to differentiate content types
### Reports and Listings
For administrative and editorial reports:
- Display status or workflow information
- Show modification dates or authors
- Include content classification or categories
## Troubleshooting
### Common Issues
**Issue**: Snippet shows empty content
- **Solution**: Verify input component identifiers are correct
- **Solution**: Implement empty checks with fallback values
- **Solution**: Check that referenced form fields exist
**Issue**: Snippet displays technical paths instead of content
- **Solution**: Ensure snippet tab is properly configured
- **Solution**: Verify variable syntax is correct
- **Solution**: Check that form data is accessible
**Issue**: Snippet breaks with certain content types
- **Solution**: Implement type checking for different object types
- **Solution**: Add null/empty validation
- **Solution**: Use conditional logic for different scenarios
**Issue**: Extract content is too long or improperly formatted
- **Solution**: Apply truncation to limit length
- **Solution**: Use XML escaping for special characters
- **Solution**: Strip HTML tags if necessary
## Integration with Template Development
### Relationship to Form Tab
Snippets depend on input components defined in the Form tab:
- Reference form identifiers directly
- Access nested properties through dot notation
- Combine multiple form fields for comprehensive previews
### Relationship to Rules
Snippet visibility can be controlled through template rules:
- Show/hide based on workflow states
- Vary content based on user permissions
- Adjust based on content type or classification
### Relationship to Sections and Content Areas
For section templates and content areas:
- Define snippets that represent the section's purpose
- Include information about contained content types
- Show relevant section-specific metadata
## Summary
Snippets are a powerful feature in FirstSpirit that significantly improve the editor experience by providing rich, contextual previews of content throughout the system. By thoughtfully designing snippet definitions that leverage form data, implement proper validation, and follow best practices, developers can create intuitive interfaces that help editors work more efficiently and effectively.
Key takeaways:
- Snippets consist of thumbnail, label, and extract components
- They're configured in the Snippet tab using form variables and methods
- Proper implementation includes validation, fallbacks, and escaping
- Well-designed snippets improve search, selection, and navigation experiences
- Default behavior ensures content is always identifiable even without configuration

228
skills/firstspirit-templating/references/table-templates.md Normal file
View File

@@ -0,0 +1,228 @@
# Table and Database Schema Templates
## Overview
FirstSpirit provides comprehensive database integration capabilities for managing structured content like product catalogs, address lists, and other frequently changing tabular data. The system includes a graphical schema editor for creating and modifying database tables, along with templates for maintaining and displaying datasets.
## Database Schema Architecture
### Database Abstraction Layer
FirstSpirit implements a database abstraction system that maps the universal FirstSpirit content type system to specific database systems being used. This abstraction enables:
- Platform-independent database connectivity
- Consistent data modeling across different database backends
- Unified content management for structured data
### Core Components
The database schema functionality consists of four primary components:
1. **Schema Creation**: Create new database schemas or generate them from existing database structures
2. **Schema Editor**: Graphical interface for modeling database schemas through visual tools
3. **Table Templates**: Components that connect database tables to data input mechanisms for editors
4. **Queries**: Mechanisms to restrict the number of datasets output for a data source
## Table Templates
### Purpose and Definition
Table templates are essential components in FirstSpirit's database architecture. A table template must be created under the schema for each table entered in the database model.
These templates define the input mechanisms editors use when entering data into corresponding database tables. They function similarly to page and section templates but are specifically tailored for tabular data management.
### Configuration Tabs
Table templates consist of six primary configuration tabs:
#### 1. Properties Tab
Houses essential settings and configuration options for the template.
#### 2. Form Tab
Where input components for data entry are defined. This is the primary location for configuring the editor interface.
#### 3. Mapping Tab
Establishes connections between table columns and their corresponding input components. This mapping ensures data entered through the form is correctly stored in the database.
#### 4. Rules Tab
Enables conditional logic to influence elements or properties. Rules can control visibility, required fields, and other dynamic behaviors.
#### 5. Snippet Tab
Controls how datasets appear in overview lists. This affects how editors see data in list views within ContentCreator.
#### 6. Template Set Tab
Determines content presentation within template sets. This tab configures how the data displays on the website.
### Editing Datasets
Datasets can be edited in ContentCreator through two access points:
- **Data sources view**: Dedicated view for managing data sources
- **Preview**: Directly edit data within the preview interface
### Permissions
An important limitation exists regarding permissions:
- Permissions assigned to data sources are not applied to filters in ContentCreator for technical reasons
- Editorial permissions remain applicable to data source access generally
## Database Integration Tutorial
### Use Case
Database integration is ideal for managing highly structured content that changes frequently. Content is "recorded and managed in the Data Store" for optimal organization and maintenance.
### Implementation Workflow
The complete setup process follows this sequence:
1. **Schema Creation**
- Establish a database schema with table definitions
2. **Table Structure**
- Add multiple related tables with columns
- Define foreign key relationships between tables
3. **Table Templates**
- Create templates for each database table
- Configure template properties
4. **Input Components**
- Define form fields editors use to enter content
- Add components to the Form tab
5. **Data Mapping**
- Assign input components to corresponding table columns
- Configure the Mapping tab to link form fields with database columns
6. **HTML Output**
- Configure how datasets display on the website
- Set up the Template Set tab
7. **Data Population**
- Add data sources to the Data Store with content
- Create initial datasets
8. **Website Integration**
- Output data source content to pages
- Reference data sources in page templates
9. **Query Configuration**
- Use queries to control dataset presentation
- Filter and sort data for specific use cases
### Practical Example
A common implementation pattern uses related tables, such as a product management system where "each product is assigned to a corresponding product category." This demonstrates:
- Primary table (Products) with product details
- Reference table (Categories) for classification
- Foreign key relationship linking products to categories
## Inline Tables
### Core Concept
Inline tables provide a different approach to table management in FirstSpirit. These tables are integrated into continuous text using the `CMS_INPUT_DOM` input component, offering editors "limitless design possibilities right down to the cell level."
### Template Structure
Inline tables require two types of templates working together:
#### 1. Table Format Templates
- Created in the Format templates area
- Determine overall table layout
- Can have one standard style template for the entire table
- Support multiple additional style templates for individual cell formatting
#### 2. Style Templates
Define cell-level presentation including:
- Background color
- Text alignment (horizontal and vertical)
- Text color
- Other cell-specific styling
### Implementation Requirements
To enable inline tables functionality:
1. **Create Style Templates First**
- Style templates must exist before inline tables can function in the DOM input component
2. **Organize Templates**
- Group style and table format templates in a dedicated folder (e.g., "Inline tables") under Format templates
- Improves template management and discoverability
3. **Configure DOM Component**
- Add `table="yes"` parameter to the `CMS_INPUT_DOM` component in section templates
- This parameter enables inline table functionality in the DOM editor
### Setup Process
Before editors can use inline tables in the DOM editor:
1. Navigate to the desired section template
2. Locate or add the `CMS_INPUT_DOM` input component
3. Add the `table="yes"` parameter to the component configuration
4. Ensure appropriate style templates are available
## Best Practices
### Database Schema Design
- Plan table relationships carefully before creating schemas
- Use foreign keys to maintain referential integrity
- Consider query performance when designing table structures
### Table Template Configuration
- Create intuitive form layouts in the Form tab
- Map all relevant columns in the Mapping tab
- Use Rules tab for validation and conditional logic
- Configure meaningful snippets for overview displays
### Inline Tables
- Create a library of reusable style templates
- Organize format templates in dedicated folders
- Provide clear naming conventions for template selection
- Test table rendering across different output channels
## Related Components
### Data Store
The Data Store is FirstSpirit's dedicated area for managing structured content:
- Stores database schemas and data sources
- Provides centralized data management
- Integrates with ContentCreator for editing
### ContentCreator Integration
ContentCreator provides editor interfaces for:
- Data sources view for managing datasets
- Preview-based editing for direct manipulation
- Filter functionality for finding specific datasets
### Queries
Queries enable sophisticated data filtering and presentation:
- Restrict the number of datasets displayed
- Apply conditions based on column values
- Sort datasets for specific output requirements
- Support complex filtering logic
## Documentation Resources
Additional information is available in:
- FirstSpirit SiteArchitect documentation for Data Store functionality
- ContentCreator editor documentation for data management interfaces
- Schema editor documentation for database modeling
- Template documentation for advanced configuration options

304
skills/firstspirit-templating/references/template-development-basics.md Normal file
View File

@@ -0,0 +1,304 @@
# Template Development Basics
## Overview
FirstSpirit is a dynamic, extensible content management platform designed for continuous development rather than as an out-of-the-box solution. The documentation is organized into two levels:
- **Basic principles of template development** - for beginners
- **Template development** - for advanced users
This guide covers the fundamental concepts, tools, and workflows necessary for developing FirstSpirit templates effectively.
## Core Architectural Principles
### Separation of Concerns
The foundational principle of FirstSpirit is the **separation of layout, content, and structure**. This architectural approach ensures:
- **Layout** - Visual presentation and styling
- **Content** - Data and information managed by editors
- **Structure** - Organizational framework and navigation
This separation enables teams to work independently on different aspects of the project while maintaining consistency and scalability.
### Template Organization
Templates serve as the organizational framework within FirstSpirit projects. Each project requires customized templates that function as structural scaffolding, binding together all project content.
**Key aspects:**
- All templates are stored in a centralized **templates repository**
- Templates are categorized into distinct types
- Understanding template composition is essential for effective development
- Templates must be designed to make editor workflows more efficient
## Getting Started with Template Development
### Recommended Learning Path
1. **Start with basics** - Understand core template concepts and architecture
2. **Study composition fundamentals** - Learn how different template types interact
3. **Explore the "First Project" tutorial** - Hands-on implementation through example projects
4. **Advance to specialized techniques** - Move into advanced template development
### Template Development Scope
According to FirstSpirit documentation: "All aspects of development of FirstSpirit projects are explained in the area of template development."
The template development area encompasses:
- Forms and input components
- Rules and dynamic behavior
- Snippets and content presentation
- Template syntax and expressions
- Debugging and testing
- API integration
- Security considerations
## Development Tools and Environments
### Primary Development Interfaces
#### SiteArchitect
The main development environment for template creation and project management. Provides comprehensive access to:
- Template editing
- Project structure management
- Form and rule definition
- Debugging tools
#### ContentCreator
The editor-focused interface with specific requirements and restrictions. Features include:
- Content editing capabilities
- Snippet display in search results
- Content highlighting and EasyEdit functionality
- JavaScript API for user interface interaction
### Developer Tools
#### 1. Code Completion
Available across three key areas:
- **Forms tabs** - for Input components
- **Rules tabs** - for defining Rules
- **Template set tabs** - for inserting FirstSpirit instructions and methods
**Usage:**
Press `Ctrl+Space` to open a window with available tags, parameters, and values.
#### 2. Navigation Features
**Jump-to-References Functionality:**
- Hover over code expressions while holding `Ctrl` to view tooltips
- Tooltips display name, object type, and path
- Use `Ctrl+Click` to navigate directly to referenced elements
- Works across Form, Rules, and Template set tabs
#### 3. Online Help System (F1)
Integrated documentation access:
- Select keywords in templates and press `F1`
- Opens integrated preview with relevant documentation page
- Forms section includes syntax examples with drag-and-drop capability
- Provides immediate context-specific help
#### 4. Template Wizard
Graphical interface for automating template creation:
- Analyzes HTML mockups
- Identifies referenced images and files
- Imports required content into FirstSpirit
- Streamlines the conversion of static HTML to dynamic templates
#### 5. Debugging Tools
**Template Inspector:**
- Quick way to locate existing code in HTML channel
- Accessible via context menu
- Displays tag structure with direct links to relevant template sections
- Enables rapid code navigation
**Template Debugger:**
- Error searching and identification
- Gradual page construction for testing
- View partial results as source text or generated HTML
- Step-through debugging capabilities
#### 6. Chrome Developer Tools
Access to full Chrome Developer Tools suite:
- Available through context menu in integrated preview
- Provides comprehensive web development utilities
- Standard browser debugging features (inspect element, console, network, etc.)
## Template Development Components
### 1. Forms
Forms define input mechanisms and design elements available to editors.
**Purpose:**
- Create input components for content entry
- Define data structure for content types
- Control how editors interact with content
**Key Features:**
- Multiple input component types
- Integration with template composition
- Editor-friendly interfaces
### 2. Rules
Rules enable dynamic form functionality and content validation.
**Capabilities:**
- Implement "Dynamic Forms"
- Real-time content validation
- Allow editors to check data plausibility during entry
- Control element behavior and characteristics
**Benefits:**
- Immediate feedback to editors
- Prevent invalid data entry
- Conditional field display
- Business logic enforcement
### 3. Snippets
Snippets create teaser representations of FirstSpirit objects.
**Usage:**
- Combine imagery with textual content
- Display in search results within SiteArchitect and ContentCreator
- Provide preview functionality
- Object display management
### 4. Template Syntax
The template syntax system includes distinct elements:
- **Instructions** - FirstSpirit-specific directives
- **Expressions** - Value calculations and access
- **Data types** - Type system for template data
- **Functions** - Built-in and custom operations
- **System objects** - Platform-provided objects
**Variables:**
Variables enable content storage and subsequent internal access patterns, allowing templates to:
- Store computed values
- Pass data between template sections
- Evaluate content dynamically
### 5. Content Highlighting and EasyEdit
Features designed to improve editor workflows:
- **Content Highlighting** - Visual indicators in preview mode
- **EasyEdit** - In-context editing capabilities
- Available in both ContentCreator and SiteArchitect
- Reduce friction in content management tasks
## Development Workflow
### Standard Development Process
1. **Project Setup**
- Initialize FirstSpirit project
- Configure project structure
- Set up templates repository
2. **Template Creation**
- Design template architecture
- Define forms for content input
- Implement rules for dynamic behavior
- Create snippets for content preview
3. **Development and Testing**
- Use code completion for efficiency
- Leverage navigation features for exploration
- Employ Template Inspector for code location
- Debug with Template Debugger
4. **Refinement**
- Test with actual content
- Optimize editor workflows
- Validate across different scenarios
- Ensure multi-language support
5. **Deployment**
- Review security considerations
- Test in target environments
- Document customizations
- Train editors on new features
### Best Practices
- **Design for editors** - Always consider the editor experience when creating templates
- **Maintain separation** - Keep layout, content, and structure independent
- **Use built-in tools** - Leverage code completion, F1 help, and debugging tools
- **Test thoroughly** - Use Template Debugger to identify issues early
- **Document decisions** - Maintain clear documentation of template logic
- **Plan for scale** - Design with multi-language and multi-site needs in mind
## API and Scripting
### FirstSpirit API
The public interface for programmatic access:
- Integration with external systems
- Custom functionality implementation
- Automation of repetitive tasks
### JavaScript API
Specific to ContentCreator:
- User interface interaction
- Custom editor behaviors
- Enhanced editing experiences
### Scripting with BeanShell
BeanShell scripting enables:
- Script creation and execution
- Automated processes
- Custom business logic
- Integration with Java ecosystem
## Multi-Language Support
FirstSpirit provides consistent support for managing multiple languages throughout template development:
- Language-aware content storage
- Translation workflows
- Locale-specific rendering
- International project scalability
## Security Considerations
Security is an integral part of template development:
- Project-level security settings
- User and group permissions
- Access control for content and templates
- Secure API usage patterns
## Additional Resources
### Documentation Structure
The FirstSpirit documentation is organized to support progressive learning:
- **Basics section** - Fundamental concepts and getting started
- **Template development** - Comprehensive development reference
- **API documentation** - Technical API references
- **ContentCreator guide** - Editor-focused documentation
### Learning Approach
1. Start with the "First Project" tutorial for practical experience
2. Study the "Composition of templates" section for architectural understanding
3. Explore Forms and Rules for content management patterns
4. Learn Template Syntax for implementation details
5. Master debugging tools for efficient troubleshooting
## Key Takeaways
1. **FirstSpirit is extensible** - It's designed for continuous development and customization, not as a static product
2. **Separation is fundamental** - The separation of layout, content, and structure drives all design decisions
3. **Tools support efficiency** - Built-in tools like code completion, Template Inspector, and debugger accelerate development
4. **Editor experience matters** - Templates should be designed to optimize editor workflows
5. **Progressive complexity** - Start with basics and progressively adopt advanced features as needed
## Summary
Template development in FirstSpirit requires understanding core architectural principles, mastering development tools, and following structured workflows. The platform's separation of concerns enables scalable, maintainable projects, while comprehensive developer tools support efficient implementation. Success comes from balancing technical implementation with editor usability, leveraging built-in features, and following established best practices.

437
skills/firstspirit-templating/references/template-structure.md Normal file
View File

@@ -0,0 +1,437 @@
# Template Structure and Composition
## Overview
Templates form the foundational framework for FirstSpirit websites, serving as the architectural blueprint that connects content from the Page Store and Media Store to the Site Store structure. All templates are centrally maintained in the FirstSpirit **Template Store**, providing a single source of truth for template definitions across projects.
Templates establish consistent, reusable structures that define element placement, content insertion points, and presentation logic. This modular approach enables administrators and developers to create maintainable website architectures while giving content editors the flexibility to manage dynamic content within predefined boundaries.
## Template Types
FirstSpirit provides several template types, each serving specific purposes within the content management system:
### Page Templates
Page templates provide the basic framework for a page, specifying:
- Element placement (logos, navigation, design elements)
- Frame structure and layout
- Designated areas where editors can insert content
- Overall page architecture and hierarchy
Page templates serve as the structural blueprint that contains information about where fixed design elements appear and where dynamic content sections can be placed.
### Section Templates
Section templates insert content into the page framework established by page templates. They feature:
- Individually configured input fields for editorial content
- Support for dynamic content (text, tables, images, datasets)
- Multiple sections per page with various templates for different content types
- Flexible content organization within page structure
Multiple sections can be added to each section area, with several different section templates typically available for different types of potential content found on a page.
### Format Templates
Format templates define text formatting within the system:
- Work with DOM and DOMTABLE input components
- Control text styling and appearance
- Include specialized variants for specific use cases
**Specialized Format Template Variants:**
- **Table Format Templates**: Define formatting for tabular data
- **Style Templates**: Enable integration of inline tables into continuous text
### Link Templates
Link templates define link appearance and behavior within projects:
- Specify input fields editors use to enter link content
- Control HTML output for links
- Standardize link presentation across the project
- Enable consistent link management
### Scripts
Scripts enable automation of operating sequences in FirstSpirit:
- Automate different types of processes
- Enable modifications to data structures
- Extend FirstSpirit functionality programmatically
- Support custom business logic implementation
### Database Schemata
Database schemata provide data structure management:
- Graphical schema editors for creating and modifying database tables
- Associated table templates for data presentation
- Query tools for dataset filtering
- Integration with FirstSpirit content model
### Workflows
Workflows define structured task sequences:
- Fixed, predefined task structures
- Defined due dates and deadlines
- Authorized personnel groups for each task
- Process management and approval chains
## Template Tab Structure
Both page templates and section templates share a common five-tab structure in the SiteArchitect editing interface. Understanding these tabs is essential for effective template development and maintenance.
### Properties Tab
The Properties tab contains all configuration settings required for the template:
**Purpose:**
- General template configuration
- Metadata definition
- Template identification and naming
- Core settings that apply to the entire template
**Key Settings:**
- Template name and identifier
- Description and documentation
- Global template properties
- Template categorization
### Form Tab
The Form tab defines the input components and data fields available to editors:
**Purpose:**
- Define input components for content entry
- Specify data fields and their types
- Configure editorial interface
- Establish content structure
**Content Types Supported:**
- Text fields and text areas
- Rich text editors (DOM components)
- Image selectors
- Dataset references
- Tables and structured data
- Custom input components
**Key Considerations:**
- Input component selection determines editor experience
- Field configuration affects content validation
- Component arrangement impacts usability
- Data binding connects form fields to output
### Rules Tab
The Rules tab enables conditional logic and dynamic behavior:
**Purpose:**
- Define conditional logic
- Influence elements or properties based on criteria
- Create dynamic template behavior
- Implement business rules
**Common Use Cases:**
- Show/hide fields based on other field values
- Conditional validation rules
- Dynamic default values
- Field dependency management
- Workflow automation triggers
**Benefits:**
- Reduces editor complexity by hiding irrelevant fields
- Ensures data consistency
- Enforces business logic
- Creates intelligent, context-aware templates
### Snippet Tab
The Snippet tab controls how pages appear in overview lists and summary views:
**Purpose:**
- Define preview representation
- Configure list view appearance
- Specify summary information
- Control thumbnail generation
**Typical Applications:**
- News article listings
- Product catalogs
- Search results
- Navigation menus
- Content aggregation pages
**Configuration Elements:**
- Preview text extraction
- Thumbnail image selection
- Metadata display
- Custom snippet formatting
### Template Set Tab
The Template Set tab determines content presentation and structure within the template set environment:
**Purpose:**
- Define content appearance in template sets
- Specify output generation rules
- Configure multi-channel delivery
- Control presentation logic
**Key Functions:**
- HTML generation rules
- CSS and JavaScript integration
- Output formatting specifications
- Template set-specific behavior
## Template Organization and Hierarchy
### Template Store Structure
All templates reside in the centrally maintained Template Store, providing:
- Single source of truth for template definitions
- Version control and template management
- Reusability across projects
- Consistent template governance
### Template Composition Patterns
Templates work together in a hierarchical relationship:
```
Page Template (Framework)
├── Header Section Area
│ └── Section Template (Header)
├── Main Content Area
│ ├── Section Template (Text Content)
│ ├── Section Template (Image Gallery)
│ └── Section Template (Data Table)
└── Footer Section Area
└── Section Template (Footer)
```
### Relationship Between Template Types
**Page-to-Section Relationship:**
- Page templates establish the framework
- Section templates populate content areas
- Multiple section templates can coexist on one page
- Section areas are defined within page templates
**Content Flow:**
1. Page template defines overall structure and section areas
2. Editors select appropriate section templates for each area
3. Section templates provide input forms for content entry
4. Content renders according to template set specifications
5. Format templates apply styling to rich text content
6. Link templates standardize link presentation
## Common Template Patterns
### Multi-Section Content Pages
**Pattern:** Page template with multiple distinct content areas
**Structure:**
- Header area (fixed section template)
- Main content area (flexible section templates)
- Sidebar area (optional section templates)
- Footer area (fixed section template)
**Benefits:**
- Maximum editor flexibility
- Consistent page structure
- Content variety within constraints
### Single-Purpose Templates
**Pattern:** Page template designed for specific content type
**Examples:**
- News article templates
- Product detail pages
- Contact forms
- Landing pages
**Benefits:**
- Optimized for specific use case
- Streamlined editor interface
- Purpose-specific validation rules
### Container Templates
**Pattern:** Minimal page template that serves primarily as section container
**Characteristics:**
- Lightweight page structure
- Maximum flexibility for section arrangement
- Focus on content rather than fixed design elements
**Use Cases:**
- Dynamic landing pages
- Marketing campaign pages
- Flexible content assemblies
### Structured Data Templates
**Pattern:** Templates with extensive form definitions for structured content
**Characteristics:**
- Complex form tab configurations
- Multiple input components
- Extensive validation rules
- Database integration
**Use Cases:**
- Product catalogs
- Event calendars
- Directory listings
- Data-driven content
## Common Features Across Templates
Multiple template types include standard editing functionality:
### Editor Features
**Search and Replace:**
- Find text within template code
- Replace across multiple occurrences
- Regular expression support
**Undo/Redo:**
- Revert changes during editing
- Step through edit history
- Recover from mistakes
**Line Numbers:**
- Toggle line number display
- Navigate to specific lines
- Reference code locations
**Code Completion:**
- Auto-suggest functionality
- Syntax assistance
- Faster template development
## Best Practices for Template Structure
### Modularity
**Principle:** Design templates as reusable, self-contained units
**Implementation:**
- Create generic section templates for common content types
- Avoid hard-coding content in templates
- Use parameters for configurable behavior
- Design for reuse across multiple page types
### Separation of Concerns
**Principle:** Keep structure, content, and presentation separate
**Implementation:**
- Page templates focus on structure
- Section templates focus on content
- Template sets focus on presentation
- Rules handle business logic
### Editor Experience
**Principle:** Design templates with content editors in mind
**Implementation:**
- Logical form field organization
- Clear field labels and help text
- Intuitive input component selection
- Progressive disclosure of advanced options
- Validation that guides rather than frustrates
### Maintainability
**Principle:** Create templates that are easy to update and debug
**Implementation:**
- Consistent naming conventions
- Comprehensive template documentation
- Clear code comments
- Logical organization of template code
- Version control integration
### Performance Considerations
**Principle:** Design efficient templates that generate quickly
**Implementation:**
- Minimize complex calculations in templates
- Optimize database queries
- Avoid redundant processing
- Cache where appropriate
## Template Development Workflow
### Planning Phase
1. **Identify Requirements:**
- Content types needed
- Editorial workflows
- Output channels
- Business rules
2. **Design Structure:**
- Sketch page layouts
- Define section areas
- Plan input components
- Map content relationships
### Implementation Phase
1. **Create Page Templates:**
- Configure Properties tab
- Define section areas
- Set up basic structure
2. **Develop Section Templates:**
- Design Form tab layout
- Configure input components
- Define validation rules
3. **Implement Logic:**
- Add Rules tab conditions
- Configure Snippet tab
- Set up Template Set output
### Testing Phase
1. **Functional Testing:**
- Verify input components work correctly
- Test validation rules
- Confirm conditional logic
2. **Editor Testing:**
- Evaluate usability
- Gather editor feedback
- Refine interface
3. **Output Testing:**
- Verify generated HTML
- Test across channels
- Validate accessibility
### Deployment Phase
1. **Documentation:**
- Editor guidelines
- Technical documentation
- Known limitations
2. **Training:**
- Editor training sessions
- Reference materials
- Support resources
3. **Monitoring:**
- Track template usage
- Gather feedback
- Identify improvement opportunities
## Summary
FirstSpirit templates provide a robust, hierarchical framework for content management. Understanding template structure and composition is essential for effective FirstSpirit development. The five-tab structure (Properties, Form, Rules, Snippet, Template Set) provides comprehensive control over template behavior, while the relationship between page templates and section templates enables flexible, maintainable website architectures.
By following established patterns and best practices, developers can create templates that balance editorial flexibility with structural consistency, resulting in efficient content management workflows and high-quality output across multiple channels.

715
skills/firstspirit-templating/references/template-syntax-expressions.md Normal file
View File

@@ -0,0 +1,715 @@
# Template Syntax - Expressions and Data Types
## Overview
In FirstSpirit, a data type is defined as "the summary of a specific object set (e.g. character strings) and the methods allowed on this set." The template syntax supports both general-purpose data types and specialized types for specific FirstSpirit functionality.
## General Data Types
FirstSpirit provides seven fundamental data types that form the basis of template development:
### 1. Boolean
**Available since:** FirstSpirit 4.0
The Boolean data type represents one of two possible values: `true` or `false`. These values are commonly used as return types for input components and in conditional expressions.
#### Definition and Usage
```ftml
$CMS_SET(isValid, true)$
$CMS_SET(isEnabled, false)$
```
#### Conditional Checks
```ftml
$CMS_IF(varName == true)$
Content when true
$CMS_END_IF$
$CMS_IF(isEnabled)$
Enabled content
$CMS_END_IF$
```
#### Input Component
The `CMS_INPUT_TOGGLE` standard input component returns Boolean data types for use in forms.
#### Methods
| Method | Return Type | Description |
|--------|-------------|-------------|
| `booleanValue()` | boolean | Extract primitive boolean value |
| `equals(Object)` | boolean | Compare equality with another object |
| `isNull()` | boolean | Checks whether an expression or object is null |
| `logicalAnd(boolean, boolean)` | boolean | Performs logical AND operation |
| `logicalOr(boolean, boolean)` | boolean | Performs logical OR operation |
| `logicalXor(boolean, boolean)` | boolean | Performs logical XOR operation |
| `parseBoolean(String)` | boolean | Convert string to boolean value |
| `toJSON()` | String | Convert to JSON-compatible representation (v5.2.11+) |
| `toString()` | String | Convert to string representation |
#### Examples
```ftml
$-- Define boolean variables --$
$CMS_SET(isActive, true)$
$CMS_SET(hasPermission, false)$
$-- Using booleanValue() --$
$CMS_VALUE(isActive.booleanValue())$
$-- Logical operations --$
$CMS_SET(result, isActive.logicalAnd(hasPermission))$
$CMS_VALUE(result)$ $-- Returns false --$
$-- String conversion --$
$CMS_VALUE(isActive.toString())$ $-- Returns "true" --$
$-- Parsing from string --$
$CMS_SET(parsed, parseBoolean("true"))$
```
### 2. String
The String data type represents text sequences of variable length. Strings are fundamental for text manipulation in templates.
#### Definition
```ftml
$CMS_SET(text, "Hello World")$
$CMS_SET(name, "FirstSpirit")$
```
### 3. Number
The Number data type handles numeric values for mathematical operations and calculations.
#### Definition
```ftml
$CMS_SET(count, 42)$
$CMS_SET(price, 19.99)$
```
### 4. Date
The Date data type handles date and time values for temporal operations.
#### Definition
```ftml
$CMS_SET(currentDate, now())$
```
### 5. List
**Available since:** FirstSpirit 4.0
The List data type is "an ordered, indexed set of list elements." Unlike Sets, elements can occur more than once within a list.
#### Creation Syntax
```ftml
$-- Empty list --$
$CMS_SET(empty_list, [])$
$-- Filled list --$
$CMS_SET(list, [1, 2, 3])$
$CMS_SET(names, ["Alice", "Bob", "Charlie"])$
$-- Range syntax --$
$CMS_SET(range, [1..10])$
$CMS_SET(letters, ["a".."z"])$
```
#### Element Access
Lists use zero-based indexing:
```ftml
$-- Access by index --$
$CMS_VALUE(list[0])$ $-- First element --$
$CMS_VALUE(list[2])$ $-- Third element --$
$CMS_VALUE(list.get(2))$ $-- Equivalent method syntax --$
$-- Access with variables --$
$CMS_SET(i, 1)$
$CMS_VALUE(list[i])$
$CMS_VALUE(list.get(i))$
$-- Set element values --$
$CMS_SET(list[0], "new value")$
```
#### Sorting and Ordering
```ftml
$-- Sort in ascending order --$
$CMS_VALUE(list.sort)$
$-- Reverse order --$
$CMS_VALUE(list.reverse)$
$-- Sort in descending order --$
$CMS_VALUE(list.sort.reverse)$
```
#### Filtering and Transformation
**Filter with Lambda:**
```ftml
$-- Filter elements matching condition --$
$CMS_SET(filtered, list.filter(item -> item > 5))$
```
**Map (Transform) with Lambda:**
```ftml
$-- Transform each element --$
$CMS_SET(doubled, list.map(item -> item * 2))$
```
**Distinct (Remove Duplicates):**
```ftml
$CMS_SET(duplicates, [1, 2, 2, 3, 3, 3])$
$CMS_SET(unique, duplicates.distinct())$
```
**Fold (Summarize):**
```ftml
$-- Aggregate values --$
$CMS_SET(sum, list.fold((acc, item) -> acc + item, 0))$
```
#### Utility Methods
| Property/Method | Return Type | Description |
|-----------------|-------------|-------------|
| `size` | Number | Returns the number of elements in the list |
| `isEmpty` | Boolean | Checks if the list is empty |
| `isNull` | Boolean | Checks if the list is null |
| `first` | Object | Returns the first element |
| `last` | Object | Returns the last element |
| `min` | Object | Returns the minimum value |
| `max` | Object | Returns the maximum value |
| `toString(String)` | String | Joins elements with the specified delimiter |
#### Collection Methods
Lists support Java Collection interface operations:
- `add(Object)` - Add element to the list
- `remove(Object)` - Remove element from the list
- `contains(Object)` - Check if list contains element
- `toArray()` - Convert to array
- Iterator operations compatible with `java.util.List`
#### Examples
```ftml
$-- Create and manipulate list --$
$CMS_SET(numbers, [5, 2, 8, 1, 9])$
$-- Get size --$
$CMS_VALUE(numbers.size)$ $-- Returns 5 --$
$-- Check if empty --$
$CMS_IF(!numbers.isEmpty)$
List has elements
$CMS_END_IF$
$-- Access first and last --$
$CMS_VALUE(numbers.first)$ $-- Returns 5 --$
$CMS_VALUE(numbers.last)$ $-- Returns 9 --$
$-- Find min and max --$
$CMS_VALUE(numbers.min)$ $-- Returns 1 --$
$CMS_VALUE(numbers.max)$ $-- Returns 9 --$
$-- Sort and display --$
$CMS_VALUE(numbers.sort)$ $-- Returns [1, 2, 5, 8, 9] --$
$-- Join with delimiter --$
$CMS_VALUE(numbers.toString(", "))$ $-- Returns "5, 2, 8, 1, 9" --$
$-- Iterate through list --$
$CMS_FOR(num, numbers)$
$CMS_VALUE(num)$
$CMS_END_FOR$
$-- Filter even numbers --$
$CMS_SET(evens, numbers.filter(n -> n % 2 == 0))$
$CMS_VALUE(evens)$ $-- Returns [2, 8] --$
$-- Double all numbers --$
$CMS_SET(doubled, numbers.map(n -> n * 2))$
$CMS_VALUE(doubled)$ $-- Returns [10, 4, 16, 2, 18] --$
```
### 6. Map
**Available since:** FirstSpirit 4.0
Maps are key-value pair collections that allow efficient data lookup by unique keys.
#### Creation Syntax
```ftml
$-- Empty map --$
$CMS_SET(empty_map, {:})$
$-- Map with key-value pairs --$
$CMS_SET(map, {"name":"Mustermann", "firstname":"Heinz"})$
$-- Multiple pairs, comma-separated --$
$CMS_SET(user, {
"name": "Doe",
"firstname": "John",
"age": 30,
"active": true
})$
```
#### Accessing Values
Values are retrieved through their assigned keys using three equivalent approaches:
```ftml
$-- Method syntax --$
$CMS_VALUE(map.get("name"))$
$-- Property syntax --$
$CMS_VALUE(map.name)$
$-- Bracket syntax --$
$CMS_VALUE(map["name"])$
```
All three approaches return the same value for the given key.
#### Adding and Modifying Entries
```ftml
$-- Using bracket syntax --$
$CMS_SET(map["key"], "value")$
$-- Using put method --$
$CMS_SET(void, map.put("email", "john@example.com"))$
$-- Update existing key --$
$CMS_SET(map["name"], "Smith")$
```
#### Iteration
Loop through all key-value pairs:
```ftml
$CMS_FOR(mapWrapper, map)$
$CMS_VALUE(mapWrapper)$
$CMS_END_FOR$
```
#### Essential Methods
| Property/Method | Return Type | Description |
|-----------------|-------------|-------------|
| `size` | Number | Returns number of key-value pairs |
| `containsKey(Object)` | Boolean | Checks if key exists in map |
| `isEmpty()` | Boolean | Verifies if map is empty |
| `keySet()` | Set | Returns all keys as a Set |
| `values()` | Collection | Returns all values as a Collection |
| `toJSON()` | String | Converts to JSON string (v5.2.11+) |
#### Examples
```ftml
$-- Create map --$
$CMS_SET(person, {
"name": "Mueller",
"firstname": "Anna",
"age": 28,
"department": "Engineering"
})$
$-- Get size --$
$CMS_VALUE(person.size)$ $-- Returns 4 --$
$-- Check if key exists --$
$CMS_IF(person.containsKey("age"))$
Age is defined
$CMS_END_IF$
$-- Check if empty --$
$CMS_IF(!person.isEmpty())$
Person data available
$CMS_END_IF$
$-- Get all keys --$
$CMS_SET(keys, person.keySet())$
$CMS_FOR(key, keys)$
$CMS_VALUE(key)$
$CMS_END_FOR$
$-- Get all values --$
$CMS_SET(vals, person.values())$
$CMS_FOR(val, vals)$
$CMS_VALUE(val)$
$CMS_END_FOR$
$-- Convert to JSON --$
$CMS_VALUE(person.toJSON())$
$-- Iterate through map --$
$CMS_FOR(entry, person)$
Key: $CMS_VALUE(entry.key)$, Value: $CMS_VALUE(entry.value)$
$CMS_END_FOR$
$-- Add new entry --$
$CMS_SET(void, person.put("email", "anna.mueller@example.com"))$
$-- Update existing entry --$
$CMS_SET(person["age"], 29)$
```
### 7. Set
The Set data type is an ordered collection of unique elements. Unlike Lists, Sets do not allow duplicate values.
#### Definition
```ftml
$CMS_SET(uniqueItems, set())$
```
## Special Data Types
FirstSpirit includes 16 specialized types for specific use cases within the CMS:
### DomElement
A document tree which contains structured data. DomElement represents hierarchical XML-like structures within FirstSpirit.
### Link
Suitable for editing and processing values which represent a link within or outside the project. Used for managing internal and external references.
### TargetReference
Returns a reference to any FirstSpirit object. Enables dynamic referencing of content elements, pages, and other project components.
### Other Special Types
Additional specialized types include:
- **Area** - Sections of content areas
- **Card** - Card-based content elements
- **Catalog** - Catalog data structures
- **CatalogAccessor** - Access to catalog data
- **DatasetContainer** - Container for datasets
- **Entity** - Database entities
- **FormData** - Form input data
- **GregorianCalendar** - Calendar operations
- **Index** - Index structures
- **IndexAccessor** - Access to index data
- **MappingMedium** - Media mapping
- **Option** - Option values
- **Record** - Data records
- **Section** - Content sections
- **SectionListEntry** - Section list items
- **Table** - Tabular data
## Expression Syntax
### Variable Assignment
Variables are assigned using the `CMS_SET` instruction:
```ftml
$CMS_SET(variableName, value)$
```
### Value Output
Output variable values using the `CMS_VALUE` instruction:
```ftml
$CMS_VALUE(variableName)$
```
### Type Operations
#### Method Invocation
Methods are invoked using dot notation:
```ftml
$CMS_VALUE(list.size)$
$CMS_VALUE(map.isEmpty())$
$CMS_VALUE(string.toUpperCase())$
```
#### Chaining
Operations can be chained:
```ftml
$CMS_VALUE(list.sort.reverse)$
$CMS_VALUE(string.trim().toLowerCase())$
```
### Type Conversions
#### Boolean Conversions
```ftml
$-- Parse string to boolean --$
$CMS_SET(bool, parseBoolean("true"))$
$-- Convert to string --$
$CMS_VALUE(boolValue.toString())$
$-- Convert to JSON --$
$CMS_VALUE(boolValue.toJSON())$
```
#### List Conversions
```ftml
$-- Convert to array --$
$CMS_SET(array, list.toArray())$
$-- Convert to string with delimiter --$
$CMS_VALUE(list.toString(", "))$
```
#### Map Conversions
```ftml
$-- Convert to JSON --$
$CMS_VALUE(map.toJSON())$
$-- Extract keys as Set --$
$CMS_SET(keys, map.keySet())$
$-- Extract values as Collection --$
$CMS_SET(values, map.values())$
```
## Lambda Expressions
Lambda expressions enable functional programming patterns in FirstSpirit templates.
### Syntax
```ftml
item -> expression
(param1, param2) -> expression
```
### Usage with Lists
**Filter:**
```ftml
$CMS_SET(adults, people.filter(person -> person.age >= 18))$
```
**Map (Transform):**
```ftml
$CMS_SET(names, people.map(person -> person.name))$
```
**Distinct:**
```ftml
$CMS_SET(uniqueAges, people.distinct(person -> person.age))$
```
**Fold (Reduce):**
```ftml
$CMS_SET(totalAge, people.fold((sum, person) -> sum + person.age, 0))$
```
## Null Handling
All data types provide the `isNull()` method for null checking:
```ftml
$CMS_IF(variable.isNull())$
Variable is null
$CMS_ELSE$
Variable has a value
$CMS_END_IF$
```
## Practical Examples
### Example 1: Processing User Data
```ftml
$-- Create list of users --$
$CMS_SET(users, [
{"name": "Alice", "age": 25, "active": true},
{"name": "Bob", "age": 30, "active": false},
{"name": "Charlie", "age": 35, "active": true}
])$
$-- Filter active users --$
$CMS_SET(activeUsers, users.filter(user -> user.active))$
$-- Get user names --$
$CMS_SET(activeNames, activeUsers.map(user -> user.name))$
$-- Display results --$
<h2>Active Users</h2>
<ul>
$CMS_FOR(name, activeNames)$
<li>$CMS_VALUE(name)$</li>
$CMS_END_FOR$
</ul>
$-- Count active users --$
<p>Total active: $CMS_VALUE(activeUsers.size)$</p>
```
### Example 2: Configuration Management
```ftml
$-- Define configuration --$
$CMS_SET(config, {
"siteName": "My Website",
"version": "2.0",
"features": ["search", "comments", "analytics"],
"maintenance": false
})$
$-- Check maintenance mode --$
$CMS_IF(!config.maintenance)$
<div class="site-header">
<h1>$CMS_VALUE(config.siteName)$</h1>
<span class="version">v$CMS_VALUE(config.version)$</span>
</div>
$-- Display enabled features --$
<ul class="features">
$CMS_FOR(feature, config.features)$
<li>$CMS_VALUE(feature)$</li>
$CMS_END_FOR$
</ul>
$CMS_ELSE$
<p>Site is under maintenance</p>
$CMS_END_IF$
```
### Example 3: Data Aggregation
```ftml
$-- Product inventory --$
$CMS_SET(products, [
{"name": "Laptop", "price": 999, "inStock": true},
{"name": "Mouse", "price": 25, "inStock": true},
{"name": "Keyboard", "price": 75, "inStock": false},
{"name": "Monitor", "price": 350, "inStock": true}
])$
$-- Get available products --$
$CMS_SET(available, products.filter(p -> p.inStock))$
$-- Calculate total inventory value --$
$CMS_SET(totalValue, available.fold((sum, p) -> sum + p.price, 0))$
$-- Find price range --$
$CMS_SET(prices, available.map(p -> p.price))$
$CMS_SET(minPrice, prices.min)$
$CMS_SET(maxPrice, prices.max)$
$-- Display summary --$
<div class="inventory-summary">
<p>Available products: $CMS_VALUE(available.size)$</p>
<p>Total value: $$$CMS_VALUE(totalValue)$</p>
<p>Price range: $$$CMS_VALUE(minPrice)$ - $$$CMS_VALUE(maxPrice)$</p>
</div>
```
### Example 4: Date and Number Operations
```ftml
$-- Number operations --$
$CMS_SET(numbers, [10, 20, 30, 40, 50])$
$CMS_SET(sum, numbers.fold((acc, n) -> acc + n, 0))$
$CMS_SET(average, sum / numbers.size)$
<p>Sum: $CMS_VALUE(sum)$</p>
<p>Average: $CMS_VALUE(average)$</p>
$-- Boolean logic --$
$CMS_SET(hasHighValue, numbers.max > 40)$
$CMS_SET(allPositive, true)$
$CMS_FOR(num, numbers)$
$CMS_IF(num <= 0)$
$CMS_SET(allPositive, false)$
$CMS_END_IF$
$CMS_END_FOR$
$CMS_IF(hasHighValue.logicalAnd(allPositive))$
<p>All numbers are positive with high values present</p>
$CMS_END_IF$
```
### Example 5: Map Transformation
```ftml
$-- Create user profile --$
$CMS_SET(profile, {
"username": "jdoe",
"email": "john.doe@example.com",
"role": "editor",
"permissions": ["read", "write", "publish"]
})$
$-- Add computed properties --$
$CMS_SET(void, profile.put("displayName", profile.username.toUpperCase()))$
$CMS_SET(void, profile.put("permissionCount", profile.permissions.size))$
$-- Check permissions --$
$CMS_IF(profile.permissions.contains("publish"))$
<button class="publish-btn">Publish Content</button>
$CMS_END_IF$
$-- Display profile --$
<div class="user-profile">
<h3>$CMS_VALUE(profile.displayName)$</h3>
<p>Email: $CMS_VALUE(profile.email)$</p>
<p>Role: $CMS_VALUE(profile.role)$</p>
<p>Permissions ($CMS_VALUE(profile.permissionCount)$):</p>
<ul>
$CMS_FOR(perm, profile.permissions)$
<li>$CMS_VALUE(perm)$</li>
$CMS_END_FOR$
</ul>
</div>
```
## Best Practices
1. **Use appropriate data types**: Choose the right data type for your use case (List for ordered collections, Set for unique items, Map for key-value pairs)
2. **Leverage lambda expressions**: Use filter, map, and fold for cleaner, more functional code
3. **Check for null values**: Always validate data using `isNull()` before accessing properties or methods
4. **Chain operations**: Combine operations like `sort.reverse` for concise transformations
5. **Use descriptive variable names**: Make templates more maintainable with clear naming conventions
6. **Optimize iterations**: Use methods like `isEmpty()` to avoid unnecessary loops
7. **Type conversion**: Use appropriate conversion methods (`toJSON()`, `toString()`, etc.) for data serialization
## Version Compatibility
- **Boolean, List, Map, Set**: Available since FirstSpirit 4.0
- **toJSON() method**: Available since FirstSpirit 5.2.11
Always check the FirstSpirit version compatibility for specific features when developing templates.

479
skills/firstspirit-templating/references/template-syntax-functions.md Normal file
View File

@@ -0,0 +1,479 @@
# FirstSpirit Template Functions Reference
## Overview
FirstSpirit template functions provide powerful tools for conditional logic, content highlighting, and dynamic template behavior. These functions are essential for creating interactive, editable content experiences in both SiteArchitect and ContentCreator environments.
## Table of Contents
1. [editorId Function](#editorid-function)
2. [if Function](#if-function)
3. [Function Usage Best Practices](#function-usage-best-practices)
---
## editorId Function
### Purpose
The `editorId()` function enables Content Highlighting and EasyEdit functionality in FirstSpirit's SiteArchitect and ContentCreator. It creates unique references to HTML elements within a page, allowing editors to click and edit content directly in the preview interface.
### Basic Syntax
```
$CMS_VALUE(editorId(editorName:"componentName"))$
```
### Parameters
The `editorId()` function supports multiple parameters for controlling editing behavior:
| Parameter | Type | Description | Scope | Required |
|-----------|------|-------------|-------|----------|
| `editorName` | String | UID of the input component to edit | All | Yes (in most cases) |
| `language` | String | Specifies the language for form opening (e.g., "FR", "EN") | ContentCreator | No |
| `entity` | Object | Entity object for database content editing | All | No |
| `template` | Object/String | TableTemplate object or UID for structured content | All | No |
| `view` | Object | Data source (Content2 object) for context | All | No |
| `element` | Object | FirstSpirit objects like GCA or content areas | All | No |
| `target` | Object | Identifies target objects when not directly determinable | All | No |
| `previewRulesEvaluation` | Boolean | Controls rule evaluation (true/false) | ContentCreator | No |
| `resolution` | String | Activates image cropping functionality | ContentCreator | No |
| `reloadPreview` | Boolean | Refreshes entire page after edits | ContentCreator | No |
| `reloadElement` | String | HTML element ID to reload after edits | ContentCreator | No |
| `json` | Boolean | Returns JSON object instead of HTML fragment | ContentCreator | No |
| `meta` | Boolean | Enables metadata editing via InEdit | ContentCreator | No |
| `externalReference` | String | Supports external references with FS_INDEX | ContentCreator | No |
### Usage Examples
#### Block-Level Highlighting
Highlight an entire heading element for editing:
```html
<h3$CMS_VALUE(editorId(editorName:"pt_headline"))$>
$CMS_VALUE(pt_headline)$
</h3>
```
#### Element-Specific Highlighting
Highlight specific attributes like images:
```html
<img src="$CMS_REF(st_picture)$"
alt="$CMS_VALUE(st_picture.description)$"
$CMS_VALUE(editorId(editorName:"st_picture"))$ />
```
#### Language-Specific Editing
Open form in a specific language:
```html
<div$CMS_VALUE(editorId(editorName:"pt_content", language:"FR"))$>
$CMS_VALUE(pt_content)$
</div>
```
#### Database Content Editing
Enable editing for entity-based content:
```html
<div$CMS_VALUE(editorId(entity:entity, template:"product_template"))$>
$CMS_VALUE(entity.tt_name)$
</div>
```
#### Reload Control
Refresh specific elements after editing:
```html
<section id="news-section"$CMS_VALUE(editorId(editorName:"st_news", reloadElement:"news-section"))$>
$CMS_VALUE(st_news)$
</section>
```
#### Image Resolution/Cropping
Enable image cropping interface:
```html
<img src="$CMS_REF(st_banner)$"
$CMS_VALUE(editorId(editorName:"st_banner", resolution:"1920x400"))$ />
```
#### JSON Output
Return editor data as JSON instead of HTML:
```html
<script>
var editorData = $CMS_VALUE(editorId(editorName:"pt_data", json:true))$;
</script>
```
### Default Behavior
When no parameters are passed, the current context is used automatically:
```html
<div$CMS_VALUE(editorId())$>
<!-- Highlights the current section or page -->
</div>
```
### Return Value
Returns an HTML fragment containing editor identifiers (typically as data attributes) that FirstSpirit uses to enable click-to-edit functionality. When `json:true` is specified, returns a JSON object with editor metadata.
### Critical Best Practices
1. **Avoid Empty Tags**: Never create empty HTML tags with only editorId. Tags should contain at least substitute content (e.g., a non-breaking space `&nbsp;`) to ensure highlighting frames display properly.
**Bad:**
```html
<p$CMS_VALUE(editorId(editorName:"pt_text"))$></p>
```
**Good:**
```html
<p$CMS_VALUE(editorId(editorName:"pt_text"))$>
$CMS_IF(!pt_text.isEmpty)$
$CMS_VALUE(pt_text)$
$CMS_ELSE$
&nbsp;
$CMS_END_IF$
</p>
```
2. **Place editorId in Opening Tag**: Always place the editorId function within the opening tag of the HTML element, before the closing `>`.
3. **Combine with Content Output**: Use editorId alongside actual content output to create a seamless editing experience.
### Availability
Available since FirstSpirit Version 4.0
---
## if Function
### Purpose
The `if()` function evaluates conditions in a compact form, enabling conditional output within templates. It's the primary method for implementing conditional logic within `$CMS_VALUE$` instructions, commonly used to verify whether values are set before rendering content.
### Syntax
```
$CMS_VALUE(
if(
CONDITION_1,
CONDITION_TRUE_1,
CONDITION_2,
CONDITION_TRUE_2,
...,
CONDITION_N,
CONDITION_TRUE_N,
CONDITION_FALSE
)
)$
```
### Parameters
The `if()` function uses a variable-length parameter structure:
1. **CONDITION_n** (Required for first pair): Boolean expression or comparison
2. **CONDITION_TRUE_n** (Required for first pair): Output when condition is true
3. **CONDITION_FALSE** (Optional): Output when all conditions are false
### Parameter Requirements
- A condition and corresponding true-branch execution are mandatory
- All other condition/true-branch pairs are optional
- Only one false-branch is permitted, regardless of the number of conditions
- The function must be used within `$CMS_VALUE(...)$` instructions
### Condition Structure
Conditions can be constructed using up to three components:
1. **Variable or constant** - The value to evaluate
2. **Operator** (optional) - Comparison or logical operator
3. **Comparable value** (optional) - The value to compare against
Expressions that return Boolean values (e.g., `#global.preview`) don't require operators or comparison values.
### Evaluation Logic
1. Conditions are evaluated in order from first to last
2. The first condition that evaluates to true triggers its corresponding true-branch
3. If no conditions evaluate to true, the false-branch executes (if provided)
4. No output occurs if no condition is met and no false-branch exists
### Supported Operators
Conditions support standard comparison and logical operators:
- **Comparison**: `==`, `!=`, `<`, `>`, `<=`, `>=`
- **Logical**: `&&` (AND), `||` (OR), `!` (NOT)
- **String/Collection**: `isEmpty`, `isSet`, `contains`
### Usage Examples
#### Simple Condition Check
Check if preview mode is active:
```
$CMS_VALUE(if(#global.preview, "Preview Mode", "Live Mode"))$
```
#### Field Validation
Output default text when field is empty:
```
$CMS_VALUE(if(!lt_text.isEmpty, lt_text, "Link"))$
```
#### Multiple Conditions
Evaluate multiple conditions in sequence:
```
$CMS_VALUE(
if(
st_type == "news",
"News Article",
st_type == "blog",
"Blog Post",
st_type == "product",
"Product Page",
"Standard Page"
)
)$
```
#### Nested Logic with Boolean Expressions
Complex condition with preview and content checks:
```
$CMS_VALUE(
if(
#global.preview && pt_draft.isEmpty,
"Draft content not available in preview",
!pt_draft.isEmpty,
pt_draft,
pt_published
)
)$
```
#### Loop-Based Conditional Output
Use modulo operations within loops:
```
$CMS_FOR(item, items)$
<div class="$CMS_VALUE(if(itemStat.index % 2 == 0, "even", "odd"))$">
$CMS_VALUE(item.name)$
</div>
$CMS_END_FOR$
```
#### Comparison with Variables
Check against dynamic values:
```
$CMS_VALUE(
if(
product.stock > 0,
"In Stock",
product.stock == 0,
"Out of Stock",
"Pre-Order"
)
)$
```
#### Boolean Property Checks
Direct boolean evaluation:
```
$CMS_VALUE(if(page.isVisible, "visible", "hidden"))$
```
#### String Comparison
Compare string values:
```
$CMS_VALUE(
if(
user.role == "admin",
'<a href="/admin">Admin Panel</a>',
user.role == "editor",
'<a href="/editor">Editor Panel</a>',
'<a href="/profile">My Profile</a>'
)
)$
```
#### Null/Empty Checks
Verify content existence before output:
```
$CMS_VALUE(
if(
!st_image.isSet,
"/assets/placeholder.jpg",
st_image.url
)
)$
```
### Advanced Patterns
#### Cascading Conditions with Fallbacks
```
$CMS_VALUE(
if(
!pt_custom_title.isEmpty,
pt_custom_title,
!pt_headline.isEmpty,
pt_headline,
page.displayName
)
)$
```
#### Complex Boolean Logic
```
$CMS_VALUE(
if(
(status == "published" || status == "scheduled") && !content.isEmpty,
content,
(status == "draft" && #global.preview),
"Draft: " + content,
"No content available"
)
)$
```
#### Type-Based Rendering
```
$CMS_VALUE(
if(
element.isType("FS_DATASET"),
element.formData.tt_name,
element.isType("FS_CATALOG"),
element.entity.identifier,
element.name
)
)$
```
### Important Notes
1. **Context Limitation**: The `if()` function works only within `$CMS_VALUE(...)$` instructions. For more complex conditional logic, use `$CMS_IF$...$CMS_END_IF$` blocks.
2. **Operator Precedence**: Standard operator precedence rules apply. Use parentheses to explicitly control evaluation order in complex conditions.
3. **Short-Circuit Evaluation**: Conditions are evaluated left-to-right, and evaluation stops at the first true condition.
4. **Type Sensitivity**: Be aware of type conversions when comparing values. String "0" and numeric 0 may behave differently.
5. **Performance**: For simple true/false checks, `if()` is more efficient than full `$CMS_IF$` blocks.
### Availability
Available since FirstSpirit Version 4.0
---
## Function Usage Best Practices
### General Guidelines
1. **Choose the Right Tool**:
- Use `if()` function for simple inline conditionals within `$CMS_VALUE$`
- Use `$CMS_IF$...$CMS_END_IF$` blocks for complex multi-line logic
- Use `$CMS_SWITCH$` for multiple exclusive conditions
2. **Readability**:
- Format complex `if()` functions with clear indentation
- Use meaningful variable names in conditions
- Add comments for non-obvious conditional logic
3. **Performance**:
- Place most likely conditions first in multi-condition checks
- Cache repeated calculations in variables before use in conditions
- Avoid unnecessary `editorId()` calls on non-editable elements
4. **Maintainability**:
- Extract complex conditions into BeanShell or script variables
- Document expected data types and possible values
- Use consistent naming conventions across templates
### Combining editorId with if
Create editable elements with conditional content:
```html
<h2$CMS_VALUE(editorId(editorName:"pt_headline"))$>
$CMS_VALUE(if(!pt_headline.isEmpty, pt_headline, "Untitled Section"))$
</h2>
```
### Error Prevention
1. **Null Safety**: Always check if objects are set before accessing properties:
```
$CMS_VALUE(if(entity.isSet && !entity.tt_name.isEmpty, entity.tt_name, "N/A"))$
```
2. **Empty Content Handling**: Provide meaningful fallbacks:
```
$CMS_VALUE(if(!content.isEmpty, content, "&nbsp;"))$
```
3. **Type Validation**: Verify types before operations:
```
$CMS_VALUE(if(value.isType("NUMBER") && value > 0, value, 0))$
```
### Testing Functions
1. Test in both preview and live modes
2. Verify behavior with empty/null values
3. Check all conditional branches
4. Validate editorId highlighting in ContentCreator
5. Test with different user roles and permissions
---
## Additional Resources
- FirstSpirit Template Syntax Documentation
- FirstSpirit Function Reference
- ContentCreator InEdit Documentation
- FirstSpirit Best Practices Guide
## Version Compatibility
- `editorId()`: Available since FirstSpirit 4.0
- `if()`: Available since FirstSpirit 4.0
Always check your FirstSpirit version for specific feature availability and behavior.

989
skills/firstspirit-templating/references/template-syntax-instructions.md Normal file
View File

@@ -0,0 +1,989 @@
# FirstSpirit Template Syntax - Instructions Reference
## Overview
FirstSpirit template instructions are special tags that enable dynamic content generation, control flow, variable manipulation, and template composition. All instructions follow the pattern `$CMS_...(...)$` where the content inside the brackets is always an expression.
### Key Characteristics
- **Structure**: Begin with `$CMS_` and end with `)$`
- **Expression-based**: Content within brackets is evaluated as expressions
- **Nesting**: Support unlimited nesting depth for complex logic
- **Block syntax**: Complex instructions use opening/closing tag pairs (e.g., `$CMS_SET(...)$ ... $CMS_END_SET$`)
- **Parameters**: Multiple parameters separated by commas using `IDENTIFIER:"VALUE"` format
### Critical Limitation
Expressions within `<CMS_HEADER>` tags remain unresolved - this is one of the main sources of errors in template development.
---
## Complete Instruction List
FirstSpirit provides the following core instructions:
- **$CMS_VALUE** - Output variable values and expressions
- **$CMS_SET** - Define variables and assign values
- **$CMS_IF** - Conditional output based on criteria
- **$CMS_FOR** - Loop and iteration control
- **$CMS_SWITCH** - Multi-case conditional branching
- **$CMS_RENDER** - Render templates and execute scripts
- **$CMS_INCLUDE** - Include external file content
- **$CMS_REF** - Resolve references to store objects
- **$CMS_TRIM** - Remove unnecessary whitespace
---
## $CMS_VALUE
### Purpose
Outputs variable contents, input component values, and expression results within templates, making them visible in browsers.
### Syntax
```
$CMS_VALUE(VARIABLE)$
$CMS_VALUE(CONSTANT)$
$CMS_VALUE(EXPRESSION)$
$CMS_VALUE(OBJECT1, default:OBJECT2)$
```
### Parameters
- **VARIABLE/CONSTANT/EXPRESSION**: Required. The value to output.
- **default**: Optional. Fallback content when the primary value is undefined.
### Features
**Variable Output with Dot Notation:**
```
$CMS_VALUE(myVariable.attributeName)$
```
**Expression Evaluation:**
```
$CMS_VALUE(myNumber + 2)$
$CMS_VALUE(6 * 7)$ <!-- Outputs: 42 -->
```
**Default Values:**
```
$CMS_VALUE(VARIABLENAME, default:"--VALUE NOT SET--")$
```
**Method Invocation:**
```
$CMS_VALUE(characterstring.contains("text"))$
$CMS_VALUE("1" == "1")$ <!-- Outputs: true -->
$CMS_VALUE(true || false)$ <!-- Outputs: true -->
```
### Best Practices
**Error Prevention:**
Always test for null/empty values before output:
```
$CMS_IF(!VARIABLE.isNull)$
$CMS_VALUE(VARIABLE)$
$CMS_END_IF$
```
**Checking Methods:**
- `.isNull()` - Test for null values
- `.isEmpty()` - Check if empty
- `.isSet()` - Check if defined (use cautiously)
**Caution**: While `isSet()` and default parameters suppress errors, they may complicate debugging and risk unintended output on generated pages.
---
## $CMS_SET
### Purpose
Enables variable definition within templates and assigns values to variables. Supports both immediate object allocation and deferred template fragment execution.
### Syntax
**Variant 1 - Object Allocation (Immediate Execution):**
```
$CMS_SET(IDENTIFIER, OBJECT)$
```
**Variant 2 - Template Fragment (Deferred Execution):**
```
$CMS_SET(IDENTIFIER)$
BODY OF THE TEMPLATE FRAGMENT
$CMS_END_SET$
```
Multiple variables can be defined in a single statement using comma separation.
### Parameters
- **IDENTIFIER**: Required. Variable name containing only A-Z, a-z, 0-9, and underscore characters.
- **OBJECT**: Required for Variant 1. Can be a constant, variable, or expression.
- **BODY**: Required for Variant 2. Template fragment content that executes when the variable is evaluated.
### Supported Instructions in Body
Template fragment bodies support:
- `$CMS_IF(...)$`
- `$CMS_REF(...)$`
- `$CMS_SET(...)$`
- `$CMS_VALUE(...)$`
### Critical Restrictions
- Neither IDENTIFIER nor OBJECT parameters may contain `$CMS_VALUE(...)$` expressions
- Using an identifier within its own template fragment body causes infinite loops
- Variant 1 executes immediately at definition
- Variant 2 defers execution until variable evaluation
### Usage Examples
**Simple Variable Assignment:**
```
$CMS_SET(myVariable, "Hello World")$
$CMS_SET(count, 42)$
```
**Expression Resolution:**
```
$CMS_SET(result, (5 + 3).toString)$
```
**Creating Collections:**
```
$CMS_SET(mySet, { })$ <!-- Empty set -->
$CMS_SET(myList, [])$ <!-- Empty list -->
$CMS_SET(myList, ["item1", "item2", "item3"])$
```
**Language-Dependent Values:**
Use maps to store multilingual content indexed by language abbreviations:
```
$CMS_SET(greetings, {
"en": "Welcome",
"de": "Willkommen",
"fr": "Bienvenue"
})$
```
**Template Fragments:**
Template fragments execute body code when called, allowing dynamic value reassignment:
```
$CMS_SET(dynamicContent)$
<p>Generated at: $CMS_VALUE(#global.now)$</p>
$CMS_END_SET$
```
---
## $CMS_IF
### Purpose
Checks a comparable value for 'true' or 'false' and controls output depending on the determined value. Enables conditional logic in templates.
### Syntax
**Basic Structure:**
```
$CMS_IF(CONDITION)$
EXECUTION PART (FULFILLED CONDITION)
$CMS_END_IF$
```
**With Else Clause:**
```
$CMS_IF(CONDITION)$
EXECUTION PART (FULFILLED)
$CMS_ELSE$
EXECUTION PART (UNFULFILLED)
$CMS_END_IF$
```
**With Multiple Conditions:**
```
$CMS_IF(CONDITION_1)$
EXECUTION PART (FULFILLED CONDITION_1)
$CMS_ELSIF(CONDITION_2)$
EXECUTION PART (FULFILLED CONDITION_2)
$CMS_ELSIF(CONDITION_3)$
EXECUTION PART (FULFILLED CONDITION_3)
$CMS_ELSE$
EXECUTION PART (UNFULFILLED CONDITIONS)
$CMS_END_IF$
```
### Parameters
**CONDITION**: Required. A boolean expression consisting of:
1. Variable or constant
2. Operator (optional)
3. Comparable value (optional)
### Valid Conditions
```
1 == 1
a != b
count > 10
#global.preview
myVariable.isEmpty()
```
### Features
- Supports nested conditions of any depth
- `$CMS_ELSIF(...)$` combines else and if functionality
- Boolean-returning methods require no operator or comparable value
- Multiple `$CMS_ELSE$` and `$CMS_ELSIF$` tags allowed
### Examples
**Simple Condition:**
```
$CMS_IF(!myVariable.isNull)$
$CMS_VALUE(myVariable)$
$CMS_END_IF$
```
**With Else:**
```
$CMS_IF(#global.preview)$
<div class="preview-mode">Preview Mode Active</div>
$CMS_ELSE$
<div class="live-mode">Live Mode</div>
$CMS_END_IF$
```
**Multiple Conditions:**
```
$CMS_IF(userRole == "admin")$
<button>Edit</button>
<button>Delete</button>
$CMS_ELSIF(userRole == "editor")$
<button>Edit</button>
$CMS_ELSE$
<span>Read-only access</span>
$CMS_END_IF$
```
**Nested Conditions:**
```
$CMS_IF(!user.isNull)$
$CMS_IF(user.isActive)$
Welcome, $CMS_VALUE(user.name)$!
$CMS_ELSE$
Your account is inactive.
$CMS_END_IF$
$CMS_END_IF$
```
---
## $CMS_FOR
### Purpose
Enables loop implementation within FirstSpirit templates for iterating over collections, lists, maps, and number ranges. Available since FirstSpirit 4.0, replacing the iterative functionality previously handled by `$CMS_RENDER(...)$`.
### Syntax
```
$CMS_FOR(IDENTIFIER, OBJECT)$
LOOP BODY
$CMS_END_FOR$
```
### Parameters
- **IDENTIFIER**: Required. Variable name representing the current object during each iteration.
- **OBJECT**: Required. A set-valued element to iterate over.
### Object Types
**Number Set (Integers Only):**
```
[STARTVALUE .. ENDVALUE]
```
**List:**
```
[OBJECT_1, OBJECT_2, ..., OBJECT_N]
```
**Map:**
```
{KEY_1: VALUE_1, ..., KEY_N: VALUE_N}
```
### System Object: #for
Within the loop body, the `#for` system object provides metadata:
- **#for.index**: Current iteration count (zero-based)
### Examples
**Iterating Over a List:**
```
$CMS_FOR(item, ["apple", "banana", "cherry"])$
<li>$CMS_VALUE(item)$</li>
$CMS_END_FOR$
```
**Number Range Iteration:**
```
$CMS_FOR(num, [7 .. 14])$
<div>Number: $CMS_VALUE(num)$</div>
$CMS_END_FOR$
```
**Using Loop Index:**
```
$CMS_FOR(product, productList)$
<div class="product-$CMS_VALUE(#for.index)$">
$CMS_VALUE(product.name)$
</div>
$CMS_END_FOR$
```
**Map Iteration:**
```
$CMS_FOR(entry, languageMap)$
<p>
Language: $CMS_VALUE(entry.key)$
Translation: $CMS_VALUE(entry.value)$
</p>
$CMS_END_FOR$
```
**Complex List Iteration:**
```
$CMS_FOR(page, #global.node.children)$
$CMS_IF(!page.isNull && page.isReleased)$
<a href="$CMS_REF(page)$">$CMS_VALUE(page.displayName)$</a>
$CMS_END_IF$
$CMS_END_FOR$
```
### Intended Uses
- Outputting lists and complex elements
- Executing instructions iteratively
- Generating repetitive HTML structures
- Processing collections and datasets
---
## $CMS_SWITCH
### Purpose
Enables conditional output based on multiple possible values of a single variable, functioning as a case-differentiation mechanism within FirstSpirit templates.
### Syntax
```
$CMS_SWITCH(OBJECT)$
STANDARDEXECUTIONPART
$CMS_CASE(CONDITION_1)$
EXECUTIONPART_1
$CMS_CASE(CONDITION_2)$
EXECUTIONPART_2
...
$CMS_CASE(CONDITION_N)$
EXECUTIONPART_N
$CMS_END_SWITCH$
```
### Parameters
- **OBJECT**: Required. The value being evaluated. Can be a constant, variable, expression, or method call.
- **CONDITION**: Required for each case. The value to match against. Can be a constant, variable, expression, or class definition.
### Evaluation Logic
The instruction compares each `$CMS_CASE(...)$` condition sequentially against the provided object. When a match occurs, its corresponding execution block runs. If no conditions match, the default section (content before the first case) executes.
### Default Case Handling
Content preceding the first `$CMS_CASE(...)$` block serves as the default, executing when no case conditions match:
```
$CMS_SWITCH(value)$
Default content here
$CMS_CASE("option1")$
Option 1 content
$CMS_CASE("option2")$
Option 2 content
$CMS_END_SWITCH$
```
### Examples
**Language-Dependent Output:**
```
$CMS_SWITCH(#global.language.abbreviation.toLowerCase)$
Welcome!
$CMS_CASE("de")$
Willkommen!
$CMS_CASE("en")$
Welcome!
$CMS_CASE("fr")$
Bienvenue!
$CMS_END_SWITCH$
```
**Type Checking:**
```
$CMS_SWITCH(_var)$
Unknown type
$CMS_CASE(class("java.lang.String"))$
This is a String
$CMS_CASE(class("java.math.BigInteger"))$
This is an Integer
$CMS_CASE(class("java.lang.Boolean"))$
This is a Boolean
$CMS_END_SWITCH$
```
**User Role Handling:**
```
$CMS_SWITCH(user.role)$
<span>Guest</span>
$CMS_CASE("admin")$
<button>Admin Panel</button>
$CMS_CASE("editor")$
<button>Edit Content</button>
$CMS_CASE("viewer")$
<span>View Only</span>
$CMS_END_SWITCH$
```
**Status-Based Styling:**
```
$CMS_SWITCH(orderStatus)$
$CMS_CASE("pending")$
<span class="status-pending">Pending</span>
$CMS_CASE("shipped")$
<span class="status-shipped">Shipped</span>
$CMS_CASE("delivered")$
<span class="status-delivered">Delivered</span>
$CMS_CASE("cancelled")$
<span class="status-cancelled">Cancelled</span>
$CMS_END_SWITCH$
```
---
## $CMS_RENDER
### Purpose
Used within a template to evaluate another output channel at the calling point, integrate the content of a format template, or call a script. Provides template composition and script execution capabilities.
### Syntax
**Template Rendering:**
```
$CMS_RENDER(template:"IDENTIFIER", PARAM_1:VALUE_1, ...)$
```
**Script Execution:**
```
$CMS_RENDER(script:"IDENTIFIER", PARAM_1:VALUE_1, ...)$
```
**Output Channel Inclusion:**
```
$CMS_RENDER(#this, templateSet:"IDENTIFIER", pinTemplateSet:BOOLEAN)$
```
### Parameters
**Required (Mutually Exclusive):**
- **template**: Format template identifier for integration
- **script**: Template-type script identifier created in the project
- **#this**: Reference to current template for output channel rendering
**Optional:**
- **templateSet**: Identifies which output channel to render
- **pinTemplateSet**: Boolean controlling channel context behavior (default: true)
- `true`: Nested template calls remain in the specified channel
- `false`: Nested calls revert to the original channel
- **User-defined parameters**: Custom values passed as `IDENTIFIER:VALUE` pairs
### Important Constraints
- The identifiers `template`, `script`, or `version` should not be used for user-specified parameters
- Template and script parameters are mandatory when used
- All other parameters remain optional
### Context Behavior
`$CMS_RENDER` creates isolated contexts, preventing external variable overwrites - unlike `$CMS_VALUE` calls, which operate within existing scopes.
### Examples
**Render a Format Template:**
```
$CMS_RENDER(template:"header", pageTitle:"Home Page", showNav:true)$
```
**Execute a Script:**
```
$CMS_RENDER(script:"calculateTotals", items:cartItems, taxRate:0.08)$
```
**Output Another Channel:**
```
$CMS_RENDER(#this, templateSet:"print")$
```
**Render with Custom Parameters:**
```
$CMS_RENDER(
template:"product-card",
product:currentProduct,
showPrice:true,
currency:"USD"
)$
```
**Pinned Template Set:**
```
$CMS_RENDER(#this, templateSet:"mobile", pinTemplateSet:true)$
```
---
## $CMS_INCLUDE
### Purpose
Inserts contents of a file from the Media Store into a template. Useful for including static content, external files, or reusable content fragments.
### Syntax
```
$CMS_INCLUDE(
IDENTIFIER,
parse:BOOLEAN_VALUE,
encoding:ENCODING,
language:LANGUAGEABBREVIATION
)$
```
### Parameters
- **IDENTIFIER**: Required. Object reference using format `type:"name"` or variable name
- `media:"filename"` - Files/pictures from Media Store
- `file:"filename"` - Files from Media Store
- **parse**: Optional. Controls FirstSpirit expression processing
- `true`: Expressions are replaced
- `false`: Expressions remain unchanged
- Default: Uses file's Media Store setting
- **encoding**: Optional. Character encoding for output
- Accepts any Java-supported charset
- Default: Uses file's Media Store setting
- **lang/language**: Optional. Project language version
- Accepts language abbreviation in quotes (e.g., `"DE"`, `"EN"`)
- Alternative: Pass language instance like `#global.project.masterLanguage`
- Useful for language-dependent media
### Key Behavioral Differences
**Parsed (parse:true):**
Variable references within included files get evaluated and replaced with actual values.
**Unparsed (parse:false):**
FirstSpirit expressions remain as literal text in output.
### Examples
**Basic File Inclusion:**
```
$CMS_INCLUDE(media:"header.html")$
```
**With Parsing Enabled:**
```
$CMS_INCLUDE(media:"template-fragment.html", parse:true)$
```
**Specific Encoding:**
```
$CMS_INCLUDE(file:"content.txt", encoding:"UTF-8")$
```
**Language-Specific Media:**
```
$CMS_INCLUDE(
media:"welcome-message.html",
language:"DE",
parse:true
)$
```
**Using Variable Reference:**
```
$CMS_SET(includedFile, mediaReference)$
$CMS_INCLUDE(includedFile, parse:false)$
```
**Master Language Content:**
```
$CMS_INCLUDE(
media:"global-footer.html",
language:#global.project.masterLanguage,
parse:true
)$
```
---
## $CMS_REF
### Purpose
Resolves references to objects stored across FirstSpirit's separate stores (Page Store, Media Store, Site Store, Template Store) into usable paths for browsers and processors.
### Syntax
```
$CMS_REF(
IDENTIFIER,
abs:VALUE,
contentId:VALUE,
index:VALUE,
lang:"LANGUAGE",
postfix:IDENTIFIER,
remote:IDENTIFIER,
res:"RESOLUTION",
template:IDENTIFIER,
templateSet:"CHANNEL",
version:NUMBER
)$
```
Only IDENTIFIER is mandatory; all other parameters are optional.
### Parameters
**IDENTIFIER (Required):**
References objects by type and name:
- `media:"filename"` - Media Store files/pictures
- `pageref:"name"` - Site Store pages/document groups
- `pagefolder:"name"` - Site Store menu levels
- Supports variable names and method invocations
**abs (Path Control):**
- `abs:0` - Relative paths (default)
- `abs:1` - Absolute with prefix
- `abs:2` - Absolute without prefix
- `abs:3` - Internal processor URLs
- `abs:4` - External processor URLs
**lang/language:**
Specifies project language (e.g., `"DE"`, `"EN"`)
**res/resolution:**
Designates image resolution other than original (e.g., `"SCALED"`, `"100_HOCH"`)
**contentId:**
Retrieves URL for specific dataset by ID in content projections
**index:**
Determines URL for specific sub-page in multi-page projections
**postfix:**
Attempts reference with suffix first, then falls back to unsuffixed version
**remote:**
Links to Remote project objects via symbolic name
**template:**
Restricts contentId search to specific table template UID
**templateSet/version:**
Switches between presentation channels (print versions, etc.)
### Important Constraints
- Do not nest `$CMS_REF(...)$` and `$CMS_VALUE(...)$` instructions
- Avoid numerical suffixes for postfix parameters to prevent reference name conflicts
- Remote media access requires valid licensing
- Different remote/target projects may have resolutions with identical names requiring careful specification
### Examples
**Basic Media Reference:**
```
<img src="$CMS_REF(media:"logo.png")$" alt="Logo">
```
**Page Reference:**
```
<a href="$CMS_REF(pageref:"about-us")$">About Us</a>
```
**Absolute Path:**
```
$CMS_REF(media:"stylesheet.css", abs:1)$
```
**Image with Resolution:**
```
<img src="$CMS_REF(media:"hero-image", res:"100_HOCH")$" alt="Hero">
```
**Language-Specific Reference:**
```
$CMS_REF(pageref:"homepage", lang:"DE")$
```
**Print Version:**
```
<a href="$CMS_REF(#global.node, templateSet:"print")$">Print Version</a>
```
**Dataset Reference:**
```
$CMS_REF(pageref:"products", contentId:374)$
```
**Remote Project Reference:**
```
$CMS_REF(media:"shared-asset", remote:"corporate-assets")$
```
**Current Page in Different Channel:**
```
$CMS_REF(#global.node, templateSet:"mobile")$
```
**Page Folder Navigation:**
```
$CMS_FOR(child, #global.node.parent.children)$
<a href="$CMS_REF(child)$">$CMS_VALUE(child.displayName)$</a>
$CMS_END_FOR$
```
---
## Control Flow and Logic Operations
### Conditional Logic Patterns
FirstSpirit provides multiple approaches for conditional logic:
**Simple Conditions:**
Use `$CMS_IF` for basic true/false decisions:
```
$CMS_IF(condition)$
Execute when true
$CMS_END_IF$
```
**Binary Choices:**
Use `$CMS_IF` with `$CMS_ELSE` for either/or scenarios:
```
$CMS_IF(condition)$
Option A
$CMS_ELSE$
Option B
$CMS_END_IF$
```
**Multiple Conditions:**
Use `$CMS_IF` with `$CMS_ELSIF` for sequential condition checking:
```
$CMS_IF(condition1)$
Result 1
$CMS_ELSIF(condition2)$
Result 2
$CMS_ELSIF(condition3)$
Result 3
$CMS_ELSE$
Default result
$CMS_END_IF$
```
**Multi-Case Branching:**
Use `$CMS_SWITCH` when checking a single value against multiple possibilities:
```
$CMS_SWITCH(value)$
Default case
$CMS_CASE(option1)$
Handle option 1
$CMS_CASE(option2)$
Handle option 2
$CMS_END_SWITCH$
```
### Loop Patterns
**Iterating Collections:**
```
$CMS_FOR(item, collection)$
Process $CMS_VALUE(item)$
$CMS_END_FOR$
```
**Number Ranges:**
```
$CMS_FOR(i, [1 .. 10])$
Iteration $CMS_VALUE(i)$
$CMS_END_FOR$
```
**Map Iteration:**
```
$CMS_FOR(entry, mapObject)$
Key: $CMS_VALUE(entry.key)$
Value: $CMS_VALUE(entry.value)$
$CMS_END_FOR$
```
**Conditional Loops:**
Combine loops with conditions:
```
$CMS_FOR(page, pages)$
$CMS_IF(!page.isNull && page.isReleased)$
<a href="$CMS_REF(page)$">$CMS_VALUE(page.displayName)$</a>
$CMS_END_IF$
$CMS_END_FOR$
```
### Variable Scope and Context
**Local Variables:**
Variables defined with `$CMS_SET` have local scope within their template context:
```
$CMS_SET(localVar, "value")$
```
**Template Fragments:**
Deferred execution for dynamic content:
```
$CMS_SET(fragment)$
Content with $CMS_VALUE(#global.now)$
$CMS_END_SET$
```
**Isolated Contexts:**
`$CMS_RENDER` creates isolated variable contexts preventing overwrites:
```
$CMS_RENDER(template:"subtemplate", param1:value1)$
```
### Common Patterns
**Null-Safe Output:**
```
$CMS_IF(!variable.isNull)$
$CMS_VALUE(variable)$
$CMS_ELSE$
Default content
$CMS_END_IF$
```
**List Processing:**
```
$CMS_SET(items, [])$
$CMS_FOR(item, sourceList)$
$CMS_IF(item.isActive)$
$CMS_SET(items, items + [item])$
$CMS_END_IF$
$CMS_END_FOR$
```
**Language-Dependent Content:**
```
$CMS_SWITCH(#global.language.abbreviation)$
English content
$CMS_CASE("de")$
German content
$CMS_CASE("fr")$
French content
$CMS_END_SWITCH$
```
---
## Best Practices Summary
### Error Prevention
1. **Always check for null/empty values** before output
2. **Use conditional wrappers** around `$CMS_VALUE` calls
3. **Test expressions** with `.isNull()` and `.isEmpty()` methods
4. **Avoid `$CMS_VALUE` in `CMS_HEADER`** tags (expressions won't resolve)
### Variable Management
1. **Use descriptive identifiers** following naming conventions
2. **Avoid circular references** in template fragments
3. **Apply `.toString` method** to resolve expressions immediately when needed
4. **Create isolated contexts** with `$CMS_RENDER` to prevent variable conflicts
### Performance
1. **Prefer `$CMS_SWITCH`** over multiple nested `$CMS_IF` statements for multi-case logic
2. **Use template fragments** for deferred execution when appropriate
3. **Minimize nested instructions** where possible
4. **Cache complex expressions** in variables using `$CMS_SET`
### Code Organization
1. **Use meaningful parameter names** in `$CMS_RENDER` calls
2. **Break complex logic** into separate format templates
3. **Document template fragments** with comments
4. **Follow consistent indentation** for readability
### Reference Handling
1. **Don't nest `$CMS_REF` and `$CMS_VALUE`** instructions
2. **Use appropriate path modes** (abs parameter) for context
3. **Specify language explicitly** for multilingual sites
4. **Test remote references** with proper licensing
---
## Troubleshooting Common Issues
### Expressions Not Resolving
**Problem**: Variables show as literal text instead of values.
**Solution**: Ensure expressions are outside `<CMS_HEADER>` tags and use proper syntax.
### Infinite Loops
**Problem**: Template hangs during generation.
**Solution**: Check for self-referencing identifiers in template fragment bodies.
### Null Pointer Errors
**Problem**: Generation fails with null reference errors.
**Solution**: Add null checks before accessing object properties:
```
$CMS_IF(!object.isNull)$
$CMS_VALUE(object.property)$
$CMS_END_IF$
```
### Incorrect Context in Nested Templates
**Problem**: Variables from parent template overwrite child template variables.
**Solution**: Use `$CMS_RENDER` instead of `$CMS_INCLUDE` for proper context isolation.
### Reference Resolution Failures
**Problem**: `$CMS_REF` returns empty or incorrect paths.
**Solution**: Verify object exists, check store type matches reference type, ensure proper language/resolution parameters.

804
skills/firstspirit-templating/references/template-syntax-system-objects.md Normal file
View File

@@ -0,0 +1,804 @@
# FirstSpirit Template Syntax - System Objects
## Overview
System objects in FirstSpirit provide access to information, data, and objects within templates. They are essential for generating dynamic content, accessing contextual information, and controlling template behavior.
### Key Characteristics
- **Context-dependent**: Availability varies depending on the template context
- **Read-access focus**: Primarily provide read-only access, though some methods can modify objects
- **Expression support**: Compatible with template expressions
- **Return types**: Can return objects or standard data types
### Invocation Syntax
All system objects begin with a hash symbol (#) followed by the object name:
```
$CMS_VALUE(#NAME[.METHOD])$
```
## Available System Objects
| Object | Primary Use | Availability |
|--------|------------|--------------|
| **#global** | Preview, project, page, and multi-page information | All templates |
| **#this** | Currently evaluated object (type varies by context) | Context-dependent |
| **#for** | Loop control within `$CMS_FOR(...)$` instructions | For loops |
| **#field** | Access form input components | FS_BUTTON parameters |
| **#content** | Dom Editor sections and table cells | Format templates |
| **#style** | Style information for tables and cells | Format/style templates |
| **#table/#tr/#cell** | Table structure and formatting details | Table contexts |
| **#meta** | Metadata output | Snippets |
| **#nav** | Menu and navigation information | Navigation contexts |
| **#card** | FS_CATALOG component access | Catalog contexts |
---
## #global System Object
The `#global` system object is available across all FirstSpirit template contexts, making it the most versatile system object for accessing contextual information.
### Primary Functions
- Determination of the currently generated node
- Output of content areas
- Output of context information
- Output and evaluation of meta information
- Output and evaluation of page-specific information
- Evaluation of multiple pages
### Key Feature
Methods of `#global` can be invoked both as context-dependent and context-independent methods, providing flexibility in template development.
### Four Main Categories
#### 1. Preview-related Information
Access information about preview states and preview mode.
**Example:**
```
$CMS_IF(#global.preview)$
<!-- Content shown only in preview mode -->
$CMS_END_IF$
```
#### 2. Project-related Information
Access project data and configuration.
**Example:**
```
Project ID: $CMS_VALUE(#global.project.id)$
```
#### 3. Page-related Information
Access node and section details for the current page.
**Example:**
```
Node ID: $CMS_VALUE(#global.node.id)$
Page ID: $CMS_VALUE(#global.page.id)$
```
#### 4. Meta and Multi-page Information
Retrieve metadata and handle multiple pages.
### Basic Syntax
```
$CMS_VALUE(#global.METHOD)$
$CMS_SET(#global.METHOD, VALUE)$
```
### Common Use Cases
**Check Preview Mode:**
```
$CMS_IF(#global.preview)$
<div class="preview-notice">You are in preview mode</div>
$CMS_END_IF$
```
**Access Project Information:**
```
$CMS_SET(project, #global.project)$
Current Project: $CMS_VALUE(project.name)$
```
**Get Current Page Context:**
```
$CMS_SET(currentNode, #global.node)$
$CMS_SET(currentPage, #global.page)$
Page Title: $CMS_VALUE(currentPage.name)$
```
---
## #field System Object
The `#field` object retrieves content and information from input components within forms. Available from FirstSpirit version 5.0.
### Key Characteristics
- **Availability:** Only accessible within the `<PARAMS/>` block of `FS_BUTTON` definitions in XML form structures
- **Core Function:** Provides access to form input components by their variable names
- **Return Type:** `FormField<T>` type object with methods to read properties and content
### Usage Pattern
Accessing a component uses dot notation:
```
#field.st_headline
```
This retrieves the input component named "st_headline" as a `FormField` object.
### Practical Application
Components passed via `#field` can be transmitted to scripts or Java classes as parameters. The parameter name (specified in the `<PARAM>` tag's `name` attribute) becomes available as a variable in scripts or through a `Map<String, String>` object in executable classes.
### Available Methods
The returned object implements the `de.espirit.firstspirit.forms.FormField` interface, providing methods to:
- Retrieve component names
- Access current values
- Check default status
- Examine other component attributes
### Example Usage in FS_BUTTON
```xml
<FS_BUTTON name="validate" hFill="yes">
<LANGINFOS>
<LANGINFO lang="*" label="Validate"/>
</LANGINFOS>
<PARAMS>
<PARAM name="headline">#field.st_headline</PARAM>
<PARAM name="text">#field.st_text</PARAM>
</PARAMS>
<ONCLICK>
<SCRIPT>
// Access the fields in script
var headlineField = context.getParameter("headline");
var textField = context.getParameter("text");
// Validate content
if (headlineField.get().isEmpty()) {
context.showDialog("Headline is required!");
}
</SCRIPT>
</ONCLICK>
</FS_BUTTON>
```
### Use Cases
- Dynamic form validation
- Processing form data in button click handlers
- Passing field values to external scripts or Java classes
- Conditional form behavior based on field states
---
## #for System Object
The `#for` system object is available within `$CMS_FOR(...)$` instructions, enabling developers to track iteration state and control loop execution.
### Properties and Methods
| Feature | Purpose | Return Type | Example |
|---------|---------|------------|---------|
| **#for.index** | Current element's position (zero-indexed) | Integer | `$CMS_VALUE(#for.index)$` |
| **#for.isFirst** | Check if rendering the initial element | Boolean | `$CMS_IF(#for.isFirst)$` |
| **#for.isLast** | Check if rendering the final element | Boolean | `$CMS_IF(#for.isLast)$` |
| **#for.BREAK** | Terminate loop execution prematurely | — | `$CMS_VALUE(#for.BREAK)$` |
| **#for.CONTINUE** | Skip to next iteration | — | `$CMS_VALUE(#for.CONTINUE)$` |
| **#for.CONT** | Skip to next iteration (alias) | — | `$CMS_VALUE(#for.CONT)$` |
| **#for.name** | Returns the object identifier "#for" | String | `$CMS_VALUE(#for.name)$` |
### Practical Examples
#### Example 1: Conditional Wrapper Elements
Output opening and closing table tags only at the beginning and end of iteration:
```
$CMS_FOR(item, items)$
$CMS_IF(#for.isFirst)$
<table>
<thead>
<tr><th>Item</th></tr>
</thead>
<tbody>
$CMS_END_IF$
<tr>
<td>$CMS_VALUE(item.name)$</td>
</tr>
$CMS_IF(#for.isLast)$
</tbody>
</table>
$CMS_END_IF$
$CMS_END_FOR$
```
#### Example 2: Adding Separators Between Items
```
$CMS_FOR(category, categories)$
<span>$CMS_VALUE(category.name)$</span>
$CMS_IF(!#for.isLast)$ | $CMS_END_IF$
$CMS_END_FOR$
```
Output: `Category1 | Category2 | Category3`
#### Example 3: Early Loop Termination
```
$CMS_FOR(product, products)$
$CMS_IF(product.stock == 0)$
$CMS_VALUE(#for.BREAK)$
$CMS_END_IF$
<div>$CMS_VALUE(product.name)$ - In Stock</div>
$CMS_END_FOR$
```
#### Example 4: Skipping Elements
```
$CMS_FOR(user, users)$
$CMS_IF(user.isInactive)$
$CMS_VALUE(#for.CONTINUE)$
$CMS_END_IF$
<div>$CMS_VALUE(user.name)$ - Active</div>
$CMS_END_FOR$
```
#### Example 5: Index-based Operations
```
$CMS_FOR(item, items)$
<div class="item-$CMS_VALUE(#for.index)$">
Position: $CMS_VALUE(#for.index + 1)$ of $CMS_VALUE(items.size())$
<p>$CMS_VALUE(item.text)$</p>
</div>
$CMS_END_FOR$
```
#### Example 6: Alternating Row Colors
```
$CMS_FOR(row, data)$
$CMS_IF(#for.index % 2 == 0)$
<tr class="even">
$CMS_ELSE$
<tr class="odd">
$CMS_END_IF$
<td>$CMS_VALUE(row.content)$</td>
</tr>
$CMS_END_FOR$
```
### Use Cases
- Conditional rendering of wrapper elements
- Loop control and early termination
- Tracking element position within iterations
- Skipping specific elements without breaking iteration flow
- Adding separators between list items
- Implementing alternating styles
---
## #style System Object
The `#style` system object enables access to style information in format templates for table rows/cells and in style templates themselves. Available from FirstSpirit Version 4.1 onward.
### Primary Functions
**Access Points:**
- Style template content
- Values stored in inline table cells (DOM Editor with table="yes")
### Predefined Layout Attributes
These reserved identifiers directly impact table appearance in the DOM Editor:
| Identifier | Function | Usage |
|-----------|----------|-------|
| `bgcolor` | Table cell background color | `#style.attr("bgcolor")` |
| `color` | Text font color | `#style.attr("color")` |
| `align` | Horizontal text alignment | `#style.attr("align")` |
| `valign` | Vertical alignment (ContentCreator only) | `#style.attr("valign")` |
### Key Methods & Usage
#### Output Values in Templates
Use `$CMS_VALUE(...)$` instruction to display input component values:
```
<td$CMS_VALUE(if(!bgcolor.isEmpty, " bgcolor=" + bgcolor, ""))$>
Content
</td>
```
#### Access Cell Properties
Invoke `#style.attr("IDENTIFIER")` to retrieve inline table properties:
```
$CMS_SET(cellBgColor, #style.attr("bgcolor"))$
$CMS_SET(textColor, #style.attr("color"))$
$CMS_SET(alignment, #style.attr("align"))$
```
#### Null Checking
Use `isNull` method (not `isEmpty`) to verify `#style` is set:
```
$CMS_IF(!#style.isNull)$
<td style="background-color: $CMS_VALUE(#style.attr("bgcolor"))$;">
Content
</td>
$CMS_ELSE$
<td>Content</td>
$CMS_END_IF$
```
### Practical Examples
#### Example 1: Applying Cell Background Color
```
<td$CMS_VALUE(if(!#style.isNull && !#style.attr("bgcolor").isEmpty,
' bgcolor="' + #style.attr("bgcolor") + '"',
''))$>
$CMS_VALUE(#content)$
</td>
```
#### Example 2: Complete Cell Styling
```
$CMS_SET(bgcolor, #style.attr("bgcolor"))$
$CMS_SET(color, #style.attr("color"))$
$CMS_SET(align, #style.attr("align"))$
$CMS_SET(valign, #style.attr("valign"))$
<td$CMS_VALUE(if(!bgcolor.isEmpty, ' bgcolor="' + bgcolor + '"', ''))$
$CMS_VALUE(if(!color.isEmpty, ' style="color:' + color + ';"', ''))$
$CMS_VALUE(if(!align.isEmpty, ' align="' + align + '"', ''))$
$CMS_VALUE(if(!valign.isEmpty, ' valign="' + valign + '"', ''))$>
$CMS_VALUE(#content)$
</td>
```
#### Example 3: Style Template with Custom Attributes
```xml
<!-- Style template definition -->
<CMS_INPUT_TEXT name="bgcolor" hFill="yes">
<LANGINFOS>
<LANGINFO lang="*" label="Background Color"/>
</LANGINFOS>
</CMS_INPUT_TEXT>
<CMS_INPUT_TEXT name="color" hFill="yes">
<LANGINFOS>
<LANGINFO lang="*" label="Text Color"/>
</LANGINFOS>
</CMS_INPUT_TEXT>
<CMS_INPUT_COMBOBOX name="align" hFill="yes">
<LANGINFOS>
<LANGINFO lang="*" label="Alignment"/>
</LANGINFOS>
<ENTRIES>
<ENTRY value="left">Left</ENTRY>
<ENTRY value="center">Center</ENTRY>
<ENTRY value="right">Right</ENTRY>
</ENTRIES>
</CMS_INPUT_COMBOBOX>
```
#### Example 4: Format Template Using Styles
```
$CMS_IF(!#style.isNull)$
$CMS_SET(styleAttrs, "")$
$CMS_IF(!#style.attr("bgcolor").isEmpty)$
$CMS_SET(styleAttrs, styleAttrs + "background-color:" + #style.attr("bgcolor") + ";")$
$CMS_END_IF$
$CMS_IF(!#style.attr("color").isEmpty)$
$CMS_SET(styleAttrs, styleAttrs + "color:" + #style.attr("color") + ";")$
$CMS_END_IF$
<td style="$CMS_VALUE(styleAttrs)$" align="$CMS_VALUE(#style.attr("align"))$">
$CMS_VALUE(#content)$
</td>
$CMS_ELSE$
<td>$CMS_VALUE(#content)$</td>
$CMS_END_IF$
```
### Important Considerations
1. **Predefined Identifiers**: The predefined identifiers (bgcolor, color, align, valign) must be used for layout options
2. **Component Naming**: These must always be indicated with `name="identifier"` within the input component
3. **Compatibility**: Ensures compatibility with both inline and DOM tables
4. **ContentCreator**: The `valign` attribute is only available in ContentCreator
### Use Cases
- Applying dynamic styling to table cells
- Creating reusable style templates
- Handling inline table cell formatting
- Conditional styling based on user input
- Maintaining consistent formatting across tables
---
## #content System Object
The `#content` system object provides access to DOM Editor sections and table cell content in format templates.
### Primary Functions
- Access content from DOM Editor sections
- Retrieve table cell content
- Output formatted content in templates
### Usage Context
Available in format templates when working with:
- DOM Editor content areas
- Table cells (when table="yes" is set)
- Section content
### Basic Syntax
```
$CMS_VALUE(#content)$
```
### Practical Examples
#### Example 1: Basic Content Output
```
<div class="content-area">
$CMS_VALUE(#content)$
</div>
```
#### Example 2: Conditional Content
```
$CMS_IF(!#content.isEmpty)$
<section>
$CMS_VALUE(#content)$
</section>
$CMS_ELSE$
<section class="empty">
<p>No content available</p>
</section>
$CMS_END_IF$
```
#### Example 3: Table Cell Content
```
<td$CMS_VALUE(if(!#style.isNull, ' class="styled"', ''))$>
$CMS_VALUE(#content)$
</td>
```
---
## #this System Object
The `#this` system object represents the currently evaluated object within a template context. The type and available methods vary depending on the context.
### Key Characteristics
- **Context-dependent**: Type changes based on the current template context
- **Self-reference**: Refers to the object currently being processed
- **Dynamic typing**: Methods available depend on the actual object type
### Usage Contexts
- Within content area templates: Refers to the current section
- Within format templates: Refers to the current element being formatted
- Within page templates: Refers to the current page or node
### Basic Syntax
```
$CMS_VALUE(#this.METHOD)$
$CMS_VALUE(#this.property)$
```
### Practical Examples
#### Example 1: Accessing Current Object Properties
```
<h1>$CMS_VALUE(#this.name)$</h1>
<p>ID: $CMS_VALUE(#this.id)$</p>
```
#### Example 2: Conditional Logic Based on Object Type
```
$CMS_IF(#this.class.simpleName == "PageRef")$
<!-- Page-specific rendering -->
$CMS_ELSE_IF(#this.class.simpleName == "Section")$
<!-- Section-specific rendering -->
$CMS_END_IF$
```
---
## System Object Best Practices
### 1. Context Awareness
Always be aware of the template context when using system objects:
```
$CMS_IF(!#global.preview)$
<!-- Production-only code -->
$CMS_END_IF$
```
### 2. Null Checking
Always check for null or empty values before accessing properties:
```
$CMS_IF(!#style.isNull && !#style.attr("bgcolor").isEmpty)$
<!-- Use style information -->
$CMS_END_IF$
```
### 3. Efficient Loop Control
Use `#for` properties to avoid unnecessary processing:
```
$CMS_FOR(item, items)$
$CMS_IF(item.isValid)$
<!-- Process valid items -->
$CMS_ELSE$
$CMS_VALUE(#for.CONTINUE)$
$CMS_END_IF$
$CMS_END_FOR$
```
### 4. Combining System Objects
Leverage multiple system objects together for complex scenarios:
```
$CMS_FOR(page, #global.project.pages)$
$CMS_IF(#for.index < 10)$
<div class="page-$CMS_VALUE(#for.index)$">
$CMS_VALUE(page.name)$
</div>
$CMS_ELSE$
$CMS_VALUE(#for.BREAK)$
$CMS_END_IF$
$CMS_END_FOR$
```
### 5. Readable Code Structure
Use `$CMS_SET$` to create intermediate variables for better readability:
```
$CMS_SET(bgcolor, #style.attr("bgcolor"))$
$CMS_SET(hasBackground, !bgcolor.isEmpty)$
$CMS_IF(hasBackground)$
<td bgcolor="$CMS_VALUE(bgcolor)$">
$CMS_ELSE$
<td>
$CMS_END_IF$
$CMS_VALUE(#content)$
</td>
```
### 6. Performance Considerations
Cache frequently accessed values:
```
$CMS_SET(isPreview, #global.preview)$
$CMS_SET(currentProject, #global.project)$
$CMS_IF(isPreview)$
<!-- Use cached value -->
$CMS_END_IF$
```
---
## Common Patterns and Recipes
### Pattern 1: Navigation with Loop Control
```
$CMS_SET(navItems, #global.navigation.items)$
<nav>
<ul>
$CMS_FOR(item, navItems)$
$CMS_IF(!item.isVisible)$
$CMS_VALUE(#for.CONTINUE)$
$CMS_END_IF$
<li$CMS_VALUE(if(#for.isFirst, ' class="first"', ''))$
$CMS_VALUE(if(#for.isLast, ' class="last"', ''))$>
<a href="$CMS_VALUE(item.url)$">$CMS_VALUE(item.name)$</a>
</li>
$CMS_END_FOR$
</ul>
</nav>
```
### Pattern 2: Styled Tables with Content
```
$CMS_FOR(row, tableData)$
$CMS_IF(#for.isFirst)$
<table>
$CMS_END_IF$
<tr>
$CMS_FOR(cell, row.cells)$
$CMS_SET(cellStyle, cell.style)$
<td$CMS_VALUE(if(!cellStyle.isNull && !cellStyle.attr("bgcolor").isEmpty,
' bgcolor="' + cellStyle.attr("bgcolor") + '"',
''))$
$CMS_VALUE(if(!cellStyle.isNull && !cellStyle.attr("align").isEmpty,
' align="' + cellStyle.attr("align") + '"',
''))$>
$CMS_VALUE(cell.content)$
</td>
$CMS_END_FOR$
</tr>
$CMS_IF(#for.isLast)$
</table>
$CMS_END_IF$
$CMS_END_FOR$
```
### Pattern 3: Form Field Validation in Buttons
```xml
<FS_BUTTON name="submit" hFill="yes">
<LANGINFOS>
<LANGINFO lang="*" label="Submit Form"/>
</LANGINFOS>
<PARAMS>
<PARAM name="title">#field.st_title</PARAM>
<PARAM name="content">#field.st_content</PARAM>
<PARAM name="category">#field.st_category</PARAM>
</PARAMS>
<ONCLICK>
<SCRIPT>
var errors = [];
var title = context.getParameter("title").get();
var content = context.getParameter("content").get();
var category = context.getParameter("category").get();
if (title.isEmpty()) {
errors.push("Title is required");
}
if (content.isEmpty()) {
errors.push("Content is required");
}
if (category == null) {
errors.push("Category must be selected");
}
if (errors.length > 0) {
context.showDialog("Validation Errors:\n" + errors.join("\n"));
return false;
}
// Proceed with submission
return true;
</SCRIPT>
</ONCLICK>
</FS_BUTTON>
```
### Pattern 4: Preview-Aware Content Rendering
```
$CMS_SET(isPreview, #global.preview)$
$CMS_SET(currentPage, #global.page)$
$CMS_IF(isPreview)$
<div class="preview-banner">
Preview Mode: $CMS_VALUE(currentPage.name)$
</div>
$CMS_END_IF$
<article>
<h1>$CMS_VALUE(currentPage.headline)$</h1>
<div class="content">
$CMS_VALUE(#content)$
</div>
</article>
$CMS_IF(isPreview)$
<div class="preview-info">
<p>Page ID: $CMS_VALUE(currentPage.id)$</p>
<p>Last Modified: $CMS_VALUE(currentPage.lastModified)$</p>
</div>
$CMS_END_IF$
```
### Pattern 5: Complex Iteration with Multiple Controls
```
$CMS_SET(items, #global.project.items)$
$CMS_SET(maxItems, 20)$
$CMS_SET(itemCount, 0)$
$CMS_FOR(item, items)$
$CMS_IF(itemCount >= maxItems)$
$CMS_VALUE(#for.BREAK)$
$CMS_END_IF$
$CMS_IF(!item.isPublished)$
$CMS_VALUE(#for.CONTINUE)$
$CMS_END_IF$
$CMS_SET(itemCount, itemCount + 1)$
<div class="item item-$CMS_VALUE(#for.index)$">
<h3>$CMS_VALUE(item.title)$</h3>
<p>$CMS_VALUE(item.description)$</p>
</div>
$CMS_IF(#for.index % 5 == 4 && !#for.isLast)$
<div class="separator"></div>
$CMS_END_IF$
$CMS_END_FOR$
```
---
## Summary
FirstSpirit system objects provide powerful tools for template development:
- **#global**: Universal access to project, page, and context information
- **#field**: Form component access in button parameters
- **#for**: Loop control and iteration management
- **#style**: Style information for tables and cells
- **#content**: DOM Editor and table cell content access
- **#this**: Current object reference in context
By understanding and effectively using these system objects, developers can create dynamic, flexible, and maintainable FirstSpirit templates that respond to context, iterate efficiently, and provide rich user experiences.

420
skills/firstspirit-templating/references/template-wizard.md Normal file
View File

@@ -0,0 +1,420 @@
# Template Wizard and HTML Importer
## Overview
The Template Wizard is a FirstSpirit tool that automates the conversion of HTML mockups into FirstSpirit project templates. It streamlines the template development process by importing external HTML designs and automatically generating FirstSpirit components.
### Purpose
The Template Wizard significantly reduces the time and effort required from delivery of HTML mockups to creation of the initial project prototype by:
- Importing HTML/JSP structures from local sources or URLs
- Automatically transferring referenced images and files from HTML mockups
- Extracting design and layout specifications
- Generating FirstSpirit input components (e.g., DOM editors, image references)
- Mapping form elements and content areas to FirstSpirit templates
### Key Benefits
- **Automation**: Automatically imports HTML structures and associated assets
- **Design Transfer**: Extracts and transfers design specifications from HTML
- **Component Generation**: Creates FirstSpirit components matching HTML content
- **Rapid Prototyping**: Accelerates the journey from mockup to working prototype
## Accessing the Template Wizard
### Access Control
As of version 5.2R2, administrators can restrict access to the Template Wizard through the **"FS-AgencySupport-ProjectPermissions"** project component in ServerManager. This allows limiting usage to specific user groups.
### Starting the Wizard
The Template Wizard can be accessed through the toolbar buttons in the import interface:
- **"Select HTML file"** button: Opens a file selection dialog with the import project root directory as default
- **"Select URL"** button: Allows input of external URLs for importing remote HTML structures
## Template Wizard Workflow
The wizard guides developers through a structured process:
1. **Import HTML structures** - Import HTML/JSP files from local sources or URLs
2. **Auto-import assets** - Automatically transfer referenced images, files, and external content
3. **Transfer design specifications** - Extract layout and design elements from HTML
4. **Build forms** - Use Form Builder to create FirstSpirit components matching HTML content
5. **Assign form elements** - Map form components to templates
6. **Configure content areas** - Define editable regions for page templates
## Importing HTML Structures
### Import Process
1. **Select Source**: Choose between local HTML files or external URLs using the toolbar buttons
2. **Automatic Transfer**: Upon confirmation, the HTML structure transfers to the import project
3. **Asset Import**: Referenced images, files, and external content are automatically imported where possible
### Limitations
The Template Wizard cannot automatically handle:
- **Images/files embedded in JavaScript**: Assets loaded dynamically via JavaScript must be imported manually
- **Navigation structures**: HTML navigation elements must be manually mapped to FirstSpirit navigation
- **JavaScript-based content**: Dynamic content loaded through JavaScript requires manual configuration
### Reimport Considerations
**Important Warning**: Reimporting HTML structures will overwrite current project modifications. The wizard cannot merge reimported changes with existing customizations. Always backup your project before reimporting.
## Analyzing and Working with HTML Structure
### HTML Preview Interface
After importing HTML, you can analyze and work with the structure:
1. **Select an entry** in the import project
2. **Click "Edit entry"** to open the preview tab
3. **View HTML preview** showing the page structure
### Interactive Selection
The preview interface provides powerful selection capabilities:
- **Click inside preview**: Displays an overlay window revealing the HTML hierarchy at that location
- **Multiple selection**: Hold Ctrl while clicking to select multiple elements
- **Visual feedback**: Hover over overlay entries to highlight corresponding areas in the preview
- **Selection confirmation**: Selected areas display with green frames once saved
## Creating FirstSpirit Components
The Template Wizard can generate various FirstSpirit components from HTML structures:
### Automatically Generated Components
**PAGE_TEMPLATE**
- Created automatically when HTML structures are added to the import project
- Becomes a full FirstSpirit template after content areas and input components are defined
- Serves as the foundation for page layouts
### Components Created via Preview Selection
**BODY/Content Areas**
- Define editable page sections
- Mark regions where editors can add and modify content
- Created by selecting areas in the HTML preview
**SECTION_TEMPLATE**
- Reusable template structures
- Created from repeating HTML patterns
- Can be nested within page templates
**INPUT_COMPONENT**
- Form elements for editorial input
- Automatically generated from HTML form elements (e.g., image components from `<img>` tags)
- Maps HTML inputs to FirstSpirit form components
**LINK_TEMPLATE**
- Navigation elements
- Created from HTML anchor tags and navigation structures
- Enables dynamic link management
**RENDER_TEMPLATE**
- Format templates for content rendering
- Controls how content is displayed in different contexts
- Separates content from presentation
**MediaMapping**
- Images or files imported as FirstSpirit media
- Automatically maps HTML media references to FirstSpirit Media Store
- Preserves asset organization and references
### Component Creation Workflow
1. **Analyze HTML**: Review the imported HTML structure in the preview
2. **Identify areas**: Select HTML elements that should become FirstSpirit components
3. **Generate components**: Use the wizard to create appropriate component types
4. **Visual confirmation**: Selected areas show green frames indicating successful creation
5. **Configure properties**: Set component properties and configuration options
## Form Builder
### Overview
The Form Builder is an integral part of the Template Wizard that simplifies creation of reusable form components. Forms are essential FirstSpirit template components that "provide the editor with a means of adding editorial content to pages and sections."
### Component Templates
Component templates are "flexible form boilerplates which are created once and can then be reused again and again." They combine GOM definition elements with FirstSpirit template syntax.
**Key Advantages:**
- **One-time creation**: Create once, reuse multiple times
- **Server-wide availability**: Access templates across projects through "Import templates from project" function
- **Reusable boilerplates**: Share form structures across current and other projects
- **Flexibility**: Combine GOM definitions with template syntax for customization
### Form Component Types
Forms utilize two primary component categories:
**Input Components**
- Accommodate editorial content
- Examples: `CMS_INPUT_DATE`, `CMS_INPUT_DOM`, `CMS_INPUT_TEXT`, `CMS_INPUT_TEXTAREA`
- Map to HTML form elements and content areas
- Enable structured content entry
**Design Components**
- Visualize the input components
- Control layout and presentation of form elements
- Provide visual structure for editors
- Enhance user experience in ContentCreator
### Creating Forms
1. **Access Form Builder**: Navigate to the Settings tab in the Template Wizard
2. **Create component templates**: Define new form boilerplates
3. **Configure input components**: Set up components for specific application scenarios
4. **Design layout**: Arrange input and design components
5. **Save and reuse**: Make templates available for current and future projects
### Form Builder Limitations
The Template Wizard has two significant constraints for form creation:
**Cannot Group Input Components**
- The wizard does not support automatic creation of `CMS_GROUP` elements
- Manual adaptation required post-import to group related input components
- Grouping must be done in FirstSpirit SiteArchitect after wizard-based creation
**No Dynamic Forms Support**
- The wizard cannot create dynamic forms that change based on user input
- Complex conditional logic requires manual template modification
- Dynamic form behaviors must be implemented in SiteArchitect
### Post-Wizard Form Customization
For complex form requirements beyond wizard capabilities, manual template modification in FirstSpirit SiteArchitect may be necessary:
- Adding `CMS_GROUP` elements to organize related inputs
- Implementing dynamic form behaviors with conditional logic
- Creating custom validation rules
- Adding advanced input component configurations
- Implementing complex data models
## Best Practices
### HTML Preparation
**Structure for Import**
- Use clean, semantic HTML markup
- Avoid complex JavaScript-based layouts
- Keep navigation structures simple and well-organized
- Use standard HTML form elements where possible
- Externalize CSS and JavaScript files for easier import
**Asset Organization**
- Use relative paths for images and files
- Keep assets in logical directory structures
- Avoid embedding resources in JavaScript
- Use standard image formats (JPG, PNG, GIF, SVG)
### Wizard Usage
**Planning Phase**
- Analyze HTML mockups before importing
- Identify reusable components and patterns
- Map HTML structures to FirstSpirit component types
- Plan content areas and editorial workflows
- Document navigation and link structures
**Import Strategy**
- Start with simple page templates
- Import one section at a time for complex sites
- Backup projects before reimporting
- Test imports in development environment first
- Verify asset imports are complete
**Component Creation**
- Use descriptive names for components
- Create section templates for reusable structures
- Define content areas strategically for editor flexibility
- Map HTML semantic elements to appropriate FirstSpirit components
- Leverage component templates for consistency
### Form Builder Best Practices
**Template Design**
- Create component templates for frequently used form patterns
- Use clear, descriptive names for input components
- Design forms with editor experience in mind
- Balance flexibility with structure
- Document component template purposes
**Component Configuration**
- Configure input components for specific use cases
- Set appropriate validation rules
- Provide helpful labels and descriptions
- Consider default values for common scenarios
- Test forms with actual editorial content
**Post-Import Enhancement**
- Group related input components with `CMS_GROUP` after import
- Add validation rules in SiteArchitect
- Implement conditional logic for complex forms
- Enhance user experience with custom styling
- Add help text and documentation for editors
### Multi-User Considerations
**Important Limitation**: The Template Wizard does not support multi-user operations. Best practices:
- Coordinate wizard usage with team members
- Designate one developer for initial imports
- Use version control for tracking changes
- Document wizard-created templates
- Plan import schedules to avoid conflicts
### Maintenance and Updates
**Version Management**
- Document wizard-generated templates
- Track manual modifications separately
- Create backup before reimporting HTML
- Test updated HTML in isolated environment
- Maintain changelog of template modifications
**Ongoing Development**
- Reserve wizard for initial template creation
- Use SiteArchitect for ongoing modifications
- Avoid reimporting unless necessary
- Keep HTML mockups synchronized with templates
- Document deviations from original HTML
## Common Workflows
### Creating a New Page Template from HTML
1. **Import HTML file** using "Select HTML file" button
2. **Verify asset imports** - Check that images and files imported correctly
3. **Analyze structure** in HTML preview
4. **Define content areas** by selecting editable regions
5. **Create input components** for dynamic content
6. **Configure form elements** using Form Builder
7. **Test in ContentCreator** with sample content
8. **Enhance manually** in SiteArchitect as needed
### Building Reusable Section Templates
1. **Identify repeating patterns** in HTML mockups
2. **Import HTML** containing the section structure
3. **Select section elements** in preview
4. **Create SECTION_TEMPLATE** from selection
5. **Define input components** for variable content
6. **Configure component template** for reusability
7. **Test section** in multiple contexts
8. **Make available** across project
### Converting HTML Forms to FirstSpirit
1. **Import HTML** with form elements
2. **Analyze form structure** and fields
3. **Use Form Builder** to create component templates
4. **Map HTML inputs** to FirstSpirit input components
5. **Configure validation** and constraints
6. **Group related fields** manually with `CMS_GROUP`
7. **Test editorial workflow** in ContentCreator
8. **Document form usage** for editors
### Updating Templates from New HTML Versions
1. **Backup current project** state
2. **Document manual modifications** made since last import
3. **Import updated HTML** (will overwrite existing)
4. **Verify component mappings** remain correct
5. **Reapply manual modifications** from backup
6. **Test thoroughly** before deploying
7. **Update documentation** with changes
## Troubleshooting
### Assets Not Importing
**Problem**: Images or files referenced in HTML don't import automatically
**Solutions**:
- Check that asset paths are relative, not absolute
- Verify assets aren't embedded in JavaScript
- Manually import missing assets through Media Store
- Update references in templates after manual import
### Navigation Not Mapping Correctly
**Problem**: HTML navigation doesn't transfer to FirstSpirit structure
**Solution**: The wizard cannot automatically map navigation. Manually create:
- Navigation structure in SiteArchitect
- Link templates for navigation elements
- Menu templates for dynamic navigation
### Reimport Overwrites Customizations
**Problem**: Reimporting HTML loses manual template modifications
**Prevention**:
- Always backup before reimporting
- Document all manual changes
- Consider if reimport is truly necessary
- Plan to reapply customizations after reimport
### Form Groups Missing
**Problem**: Related form fields aren't grouped
**Solution**: The wizard doesn't create `CMS_GROUP` elements automatically. After import:
- Open template in SiteArchitect
- Add `CMS_GROUP` tags around related input components
- Configure group properties (collapsed, labels, etc.)
### Dynamic Form Features Needed
**Problem**: Need conditional or dynamic form behaviors
**Solution**: Wizard doesn't support dynamic forms. In SiteArchitect:
- Add conditional logic with template syntax
- Implement visibility rules
- Create dependent field behaviors
- Use scripts for complex interactions
## Technical Considerations
### Performance
- Large HTML structures may take time to analyze
- Asset import speed depends on file sizes and quantity
- Preview rendering affected by HTML complexity
- Consider importing complex sites in sections
### Compatibility
- Supports HTML and JSP file formats
- Works with standard HTML form elements
- Compatible with CSS and JavaScript files
- Integrates with FirstSpirit Media Store
### Limitations Summary
The Template Wizard has specific limitations that require manual intervention:
1. **No JavaScript asset handling** - Dynamically loaded assets must be imported manually
2. **No navigation mapping** - Navigation structures require manual configuration
3. **No merge on reimport** - Reimports overwrite existing modifications
4. **No multi-user support** - Single-user tool for template creation
5. **No component grouping** - `CMS_GROUP` must be added manually
6. **No dynamic forms** - Complex form logic requires SiteArchitect
## Summary
The Template Wizard accelerates FirstSpirit template development by automating HTML import and component generation. While powerful for initial template creation, it works best as part of a hybrid approach:
- **Use wizard for**: Initial HTML import, asset transfer, basic component creation, form boilerplates
- **Use SiteArchitect for**: Component grouping, dynamic forms, navigation mapping, complex customizations
By understanding both the capabilities and limitations of the Template Wizard, developers can efficiently create FirstSpirit templates while knowing when to transition to manual development for advanced features.

336
skills/firstspirit-templating/references/variables.md Normal file
View File

@@ -0,0 +1,336 @@
# Variables in FirstSpirit
## Overview
Variables in FirstSpirit store website content separately from structure and layout, implementing the core principle of "separation of structure, content and layout." Content values are managed in designated storage areas called "Stores," with variables serving as named containers that have unique identifiers and changeable values accessed through those identifiers.
## Variable Identifiers
### Valid Identifier Rules
Variable identifiers must follow specific naming conventions:
- Must contain at least one letter (e.g., `a`, `a1`, `a_b`)
- OR start with underscore plus at least one letter/number (e.g., `_0`, `_a`)
- Cannot use hyphens or consist only of underscores
- Should remain unchanged after creation to preserve project references
**Critical Requirement:** Project-wide unique identifiers must be assigned to each variable, as duplicate identifiers can cause variables to overwrite each other.
### Coding Conventions
Recommended prefixes indicate variable origin and location:
| Prefix | Location | Example |
|--------|----------|---------|
| `gv_` | Global project use | `gv_pagetitle` |
| `pt_` | Page templates | `pt_pagetitle` |
| `st_` | Section templates | `st_text_picture` |
| `ft_` | Format templates | |
| `lt_` | Link templates | `lt_linktext` |
| `tt_` | Table templates | `tt_date` |
| `md_` | Metadata templates | `md_keywords` |
| `ps_` | Project settings | `ps_copyright` |
| `ss_` | Site Store structure | `ss_shownavigation` |
## Variable Declaration Locations
### Templates (Forms Tab)
Input components on the Form tab define variables through the `name` attribute. Values entered by editors populate these variables. Each component requires a unique identifier, as non-unique identifiers can cause saved database contents to be overwritten by new content.
### Template Sets
Variables can be set via:
- `$CMS_SET(...,...)$` instruction
- `<CMS_FUNCTION>` tags
- `<CMS_VALUE>` tags
These variables are developer-assigned and not accessible to editors.
### Metadata
Additional information associated with Page, Media, and Site Store nodes.
### Menu Levels
Structure variables for Site Store folders enable layout variations across hierarchical areas.
### Global Store
Reusable content blocks like copyright notices.
### Schedules
Variables configured in generation schedules override other variables during project generation.
## Defining Variables in Templates
Variables can be defined in three distinct areas of templates:
### 1. Form Area
**Purpose:** Editor-assigned values through input components
**Characteristics:**
- Each component requires a unique identifier (variable name)
- Values are entered directly by editors
- Cannot be accessed in header area
**Controlling Editor Input:**
Template developers can influence value assignment through:
- **Reducing functional scope**: Disable specific features (e.g., bold/italic in DOM inputs)
- **Limiting choices**: Restrict selection options using FILTER, ALLOW, or HIDE tags
- **Mandatory fields**: Use `allowEmpty="no"` parameter
- **Default values**: Set fallback values using `preset` parameter or the "Default values" button
- **Case differentiation**: Employ conditional logic with `isNull` or `isEmpty` methods
### 2. Header Area
Variables defined in `<CMS_HEADER>` sections are template developer-defined and cannot be edited by editors.
**Function-Based Definition:**
```xml
<CMS_FUNCTION name="functionName" resultname="variableName">
<!-- Function configuration -->
</CMS_FUNCTION>
```
- Functions execute only once during page generation
- Require `name` and `resultname` attributes
- Available header functions: contentSelect, define, Font, MenuGroup, Navigation, PageGroup, Table
**CMS_VALUE Tag Definition:**
Language-dependent variables:
```xml
<CMS_VALUE name="Labeling">
<LANG id="DE">
<ATTR name="self">Mann</ATTR>
<ATTR name="woman">Frau</ATTR>
</LANG>
<LANG id="EN">
<ATTR name="self">man</ATTR>
<ATTR name="woman">woman</ATTR>
</LANG>
</CMS_VALUE>
```
Access methods:
- `$CMS_VALUE(Labeling)$` - returns default "self" attribute
- `$CMS_VALUE(Labeling.woman)$` - returns specific attribute
**Header Area Constraints:**
- Variables defined in Form area cannot be accessed in header area
- `CMS_VALUE` definitions must precede `CMS_FUNCTION` tags
### 3. Body Area
Variables defined at runtime using the `$CMS_SET(...)$` instruction:
**Simple String Objects:**
```
$CMS_SET(myVar,"This is a text with \"special characters\".")$
$CMS_VALUE(myVar)$
```
Output: `This is a text with "special characters".`
**Complex Document Objects:**
```
$CMS_SET(myVar3)$
$CMS_VALUE(myVar2)$
$CMS_END_SET$
```
This creates a `TemplateDocumentImpl` object containing CMS expressions, unlike simple String objects.
**Special Character Handling:**
Escape special characters in strings using backslash notation (e.g., `\"` for quotes).
## Outputting Variables
### $CMS_VALUE(...) Instruction
Basic syntax outputs variable content:
```
Hello $CMS_VALUE(name.firstname)$ $CMS_VALUE(name.lastname)$!
```
**With Expressions:**
```
Hello $CMS_VALUE(name.firstname + " " + name.lastname)$!
```
**Best Practice for Null Checks:**
Perform `isNull` or `isEmpty` tests rather than using `default` or `isSet()`, which suppress debugging information:
```
$CMS_IF(!name.isNull)$
Hello $CMS_VALUE(name.firstname)$!
$CMS_END_IF$
```
This approach prevents error messages while maintaining visibility of debugging information.
### $CMS_REF(...) Instruction
Resolves references to paths. Requires two-part variable format:
1. Keyword (e.g., `media:`)
2. Reference name from relevant store
```
$CMS_REF(media:imageReference)$
```
## Variable Scope and Lifecycle
### Scope Hierarchy
Variables in FirstSpirit follow a hierarchical scope structure:
1. **Template-level**: Variables defined in specific templates
2. **Template Set-level**: Variables accessible across template set tabs
3. **Global-level**: System objects and global variables accessible project-wide
### Execution Timing
- **Header functions**: Execute only once during page generation
- **Body variables**: Evaluated during runtime
- **Form variables**: Populated by editor input before generation
- **Schedule variables**: Applied during project generation, overriding other definitions
### Variable Manipulation
Variables can be modified through:
- Instructions (e.g., `$CMS_SET(...)$`)
- Operations and Expressions
- Methods (e.g., `.isNull()`, `.isEmpty()`)
- Functions
**Important:** Variable manipulation is only possible in template set tabs, not in form definitions.
## Variables in Metadata
### Definition
Metadata variables require a metadata template (a page template created in the Template Store and designated in ServerManager project properties). Editors input content through the "Metadata" tab in SiteArchitect using defined input components.
### Key Characteristics
**Language Independence:**
Metadata is not language-dependent. For labeling input components (`_LANGINFOS_` / `_LANGINFO_`), only the fallback definition (`lang="*"`) is used.
**Component Limitations:**
Certain input components like `CMS_INPUT_DOMTABLE` cannot be emptied once data is entered. Avoid using fall-back values in metadata templates.
### Accessing Metadata Variables
Metadata variable content is accessed using the `#global` system object with the `.meta()` method:
```
$CMS_VALUE(#global.meta.md_keywords)$
```
Variables must have unique identifiers within the metadata template.
### Inheritance Models
Three inheritance approaches are available:
**none:**
- No inheritance from parent nodes
- Only current node metadata is used
**inherit:**
- If no metadata is stored on the current node, the next highest node of the store is used
- Single-level parent inheritance
**add:**
- All higher level nodes are considered, starting from the root node
- Cumulative inheritance from entire hierarchy
**Inheritance Warning:**
With additive inheritance (`add`), editors see only current-node metadata in the interface, not inherited values. This can cause user errors during editing as the complete effective metadata is not visible.
## System Objects
FirstSpirit provides system-maintained variables prefixed with `#` (e.g., `#global`) that offer built-in functionality. These objects provide access to:
- Global project settings
- Current context information
- Metadata via `.meta()` method
- Navigation structures
- Media references
## Best Practices
### Identifier Management
1. **Use consistent prefixes** following the coding conventions to indicate variable origin
2. **Never change identifiers** after creation to preserve project references
3. **Ensure uniqueness** across the entire project to prevent overwrites
4. **Avoid hyphens** and use underscores for multi-word identifiers
### Value Handling
1. **Implement null checks** using `isNull()` or `isEmpty()` methods
2. **Avoid `default` and `isSet()`** which suppress debugging information
3. **Escape special characters** properly in string assignments
4. **Use mandatory fields** (`allowEmpty="no"`) where appropriate
### Template Organization
1. **Place `CMS_VALUE` definitions before `CMS_FUNCTION` tags** in header areas
2. **Define variables in appropriate areas** based on who needs to modify them:
- Form area for editor-managed content
- Header area for developer-defined constants
- Body area for runtime calculations
3. **Use metadata templates** for cross-cutting node attributes
### Metadata Considerations
1. **Avoid fall-back values** in metadata templates, especially with components that cannot be emptied
2. **Choose appropriate inheritance model** based on content structure needs
3. **Document inheritance behavior** for editors when using `add` model
4. **Use unique identifiers** with `md_` prefix for metadata variables
### Performance
1. **Leverage header functions** that execute only once per generation
2. **Minimize complex expressions** in frequently-accessed variables
3. **Use schedule variables** to override values efficiently during generation
## Common Pitfalls
1. **Duplicate identifiers** causing unexpected overwrites
2. **Accessing form variables in header area** (not allowed)
3. **Incorrect order of CMS_VALUE and CMS_FUNCTION** in headers
4. **Using special characters without proper escaping**
5. **Relying on `default` or `isSet()`** instead of proper null checks
6. **Editing confusion with additive metadata inheritance**
7. **Changing identifiers after initial creation** breaking references
## Related Concepts
- Template Contexts
- System Objects (`#global`, etc.)
- CMS Instructions (`$CMS_VALUE$`, `$CMS_REF$`, `$CMS_SET$`)
- Input Components
- Template Sets
- Metadata Templates
- Generation Schedules

313
skills/firstspirit-templating/references/workflows.md Normal file
View File

@@ -0,0 +1,313 @@
# FirstSpirit Workflows Reference
## Overview
Workflows in FirstSpirit represent "a sequence of tasks that is completed according to a fixed, predefined structure" with configurable due dates and authorized user groups. They enable structured approval and release processes for project elements, ensuring controlled content publication and deletion.
## Workflow Types
FirstSpirit supports two primary workflow categories:
### Context-Oriented Workflows
- Linked to specific objects within the project
- Triggered by actions on particular elements
- Example: Release request workflow for pages or media
### Context-Free Workflows
- Independent of specific objects
- Started manually from the menu bar
- Example: Task workflow for general assignments
## Workflow Structure
### Configuration Tabs
The workflow editor provides five primary configuration interfaces:
#### 1. Properties Tab
Establishes valid settings for the workflow, including:
- Workflow name and description
- Due date configurations
- Authorized user groups
- General behavior settings
#### 2. State Diagram Tab
Enables graphical modeling of workflow states and transitions with specific rules:
- Visual representation of workflow steps
- State connections and flow logic
- Conditional transitions between states
#### 3. Form Tab
Defines input components for workflow entries:
- Custom input fields for workflow initiation
- Data collection forms
- User interaction elements
#### 4. Rules Tab
Controls elements and properties through rule definitions:
- Conditional logic for workflow behavior
- Element visibility and editability rules
- Dynamic workflow adjustments
#### 5. Snippet Tab
Customizes workflow display in overview lists:
- Preview information shown in workflow listings
- Summary data presentation
- Custom display templates
## Permissions and Security
FirstSpirit offers flexible permission management for workflows:
- **Granular Access Control**: "FirstSpirit offers a flexible feature for defining very precisely which user is permitted to perform a particular workflow step"
- **Role-Based Permissions**: Assign workflow steps to specific user groups
- **Step-Level Authorization**: Control who can execute each workflow transition
## Error Handling
### Error States
- Optional error states prevent inconsistent workflow instances
- Provide fallback paths for unexpected situations
- Enable recovery mechanisms for failed operations
### Write Protection
- Restricts editing of protected workflow objects
- Ensures data integrity during workflow execution
- Prevents concurrent modifications
## Script Support
Workflows support scripting for complex functionality:
- Custom logic implementation
- Integration with external systems
- Automated decision-making
- Data validation and transformation
## API Access
Workflows are accessible through dedicated Java packages:
```java
de.espirit.firstspirit.workflow.model
de.espirit.firstspirit.access.store.templatestore
de.espirit.firstspirit.workflow
```
These packages provide programmatic access to:
- Workflow creation and management
- State transitions
- Custom workflow logic
- Integration with FirstSpirit APIs
## BasicWorkflows Module
### Purpose
The BasicWorkflows module is a FirstSpirit standard module providing ready-to-use release and deletion workflows. It combines "common release and delete logics in workflows for releasing or deleting FirstSpirit elements" to prevent re-implementation across projects.
### Technical Requirements
- **FirstSpirit Version**: 2022.3 or later (Isolated or Legacy-Mode)
- **Java Version**: Java 17
- **License**: Valid FirstSpirit license with `license.WORKFLOW` parameter set to `1`
### Core Workflow Types
#### Release Workflow
Manages element publication with dependency tracking across multiple areas:
**SiteArchitect Support:**
- Media elements
- Entities
- Data sources
- Pages
- Page references
- Document groups
- Folders
- Global pages
- Project settings
**ContentCreator Support:**
- Page references
- Entities
- Document groups
**Features:**
- Automatic dependency resolution
- Conflict detection for unreleased dependencies
- Multi-element release coordination
- Approval process integration
#### Delete Workflow
Handles element removal with conflict prevention:
**SiteArchitect Support:**
- Media elements
- Entities
- Data sources
- Pages
- Page references
- Document groups
- Folders
- Global pages
- Project settings
**ContentCreator Support:**
- Page references
- Entities
- Media
- Folders
- Document groups
**Features:**
- Reference validation before deletion
- Conflict detection for elements in use
- Safe removal with dependency checks
- Approval process for deletions
### Installation and Configuration
#### Module Installation
1. Open ServerManager
2. Navigate to Server properties
3. Go to Modules section
4. Install BasicWorkflows module
#### Workflow Activation
1. **Enable in Project Settings**: Activate workflows for ContentCreator in project configuration
2. **Web Component Setup**: Enable web component and web server for ContentCreator workflows
3. **Import Workflows**: Import BasicWorkflows into the project
4. **Define Permissions**: Configure user permissions for workflow steps
5. **Select Delete Workflow**: Designate the appropriate delete workflow for the project
### Conflict Resolution
The BasicWorkflows module includes comprehensive conflict management:
#### Conflict Detection
- Identifies unreleased dependencies
- Detects incorrect object states
- Validates element relationships
- Checks for circular dependencies
#### Cancelation Mechanism
- Triggers workflow abandonment when conflicts cannot be resolved
- Preserves project state integrity
- Provides feedback on cancellation reasons
#### Forced Actions
- Overrides standard workflow rules when necessary
- Requires elevated permissions
- Logs forced action events
- Used for emergency situations
### Extension Capabilities
BasicWorkflows can be extended for custom requirements:
#### Supported Extensions
- **MultiNode Ability**: Support for distributed FirstSpirit environments
- **Section References**: Custom handling of section-based content
- **Custom Business Logic**: Integration of project-specific rules
#### Extension Implementation
The module provides interfaces for:
- Custom workflow steps
- Specialized approval processes
- Integration with external systems
- Enhanced validation logic
### Best Practices
#### Release Workflows
1. Always review dependencies before releasing
2. Use approval steps for critical content
3. Configure appropriate user groups for each step
4. Test workflows in development environment first
5. Monitor workflow execution logs
#### Delete Workflows
1. Verify no active references before deletion
2. Implement multi-level approval for critical elements
3. Use conflict detection to prevent broken references
4. Maintain audit trails of deletion requests
5. Configure rollback mechanisms where possible
#### General Workflow Management
1. Document custom workflow logic
2. Use descriptive names for workflow states
3. Implement error handling for all transitions
4. Configure timeout settings appropriately
5. Regularly review and optimize workflow performance
## Approval and Release Processes
### Typical Release Workflow Structure
1. **Initiation**: Content editor requests release
2. **Validation**: System checks for dependencies and conflicts
3. **Approval**: Designated approver reviews changes
4. **Pre-Release**: Final validation and preparation
5. **Release**: Content published to live environment
6. **Notification**: Stakeholders informed of release
### Approval Stages
Workflows can implement multiple approval stages:
- **First-Level Approval**: Content quality review
- **Second-Level Approval**: Business rule validation
- **Final Approval**: Production release authorization
### Release Coordination
For complex releases involving multiple elements:
- Dependency resolution ensures correct order
- Batch release capabilities for related content
- Rollback mechanisms for failed releases
- Scheduling options for timed publication
## Workflow Validation
### Pre-Execution Validation
- User permissions check
- Element state verification
- Dependency validation
- Configuration correctness
### Runtime Validation
- State transition rules enforcement
- Data integrity checks
- Business rule compliance
- Error condition handling
### Post-Execution Validation
- Completion status verification
- Audit log generation
- Notification delivery confirmation
- State consistency checks
## Target Audience
Workflow development and configuration is designed for:
- Technical project managers
- FirstSpirit developers
- System administrators
- Content architecture specialists
**Prerequisites:**
- Familiarity with FirstSpirit structure
- Understanding of workflow concepts
- Knowledge of project requirements
- Experience with permission management
## Additional Resources
For detailed API documentation and advanced workflow development, refer to:
- FirstSpirit API documentation
- Workflow model package documentation
- Template store access documentation
- Custom script development guides