Initial commit

2025-11-30 08:50:01 +08:00
commit 0a3981a4f1
12 changed files with 1496 additions and 0 deletions
--- a/skills/firstspirit-fs-cli/reference/fs-cli-sync-structure.md
+++ b/skills/firstspirit-fs-cli/reference/fs-cli-sync-structure.md
@@ -0,0 +1,410 @@
+# FirstSpirit FS-CLI Export/Sync Directory Structure
+
+## Overview
+
+This document describes the structure and file formats used when exporting FirstSpirit templates using FS-CLI (FSDevTools). The export creates a hierarchical file system structure that mirrors the FirstSpirit project structure, preserving all template configurations, forms, rules, and output channels.
+
+## General Structure
+
+The FS-CLI export follows a consistent pattern:
+
+```
+sync_dir/
+├── .FirstSpirit/           # Export metadata (do not version control)
+│   ├── Files_*.txt        # List of all exported files with checksums
+│   └── Import_*.txt       # Import metadata
+│
+└── TemplateStore/         # Template Store root
+    ├── FormatTemplates/   # Text formatting templates
+    ├── LinkTemplates/     # Link templates
+    ├── PageTemplates/     # Page templates
+    ├── SectionTemplates/  # Section templates (content modules)
+    ├── Schemes/           # Database schema templates
+    ├── Scripts/           # Script templates
+    └── Workflows/         # Workflow definitions
+```
+
+### Key Principles
+
+1. **Folder hierarchy mirrors FirstSpirit structure**: The file system replicates the exact folder structure from the FirstSpirit project
+2. **One folder per element**: Each FirstSpirit template/element gets its own directory
+3. **Consistent file naming**: Files use standardized names based on their purpose
+4. **Multiple files per template**: Templates are decomposed into separate files for different aspects (form, output, rules, etc.)
+
+## Template Store Structure
+
+### Template Types and Locations
+
+| Template Type | Directory | Purpose |
+|--------------|-----------|---------|
+| **Page Templates** | `TemplateStore/PageTemplates/` | Define page framework and structure |
+| **Section Templates** | `TemplateStore/SectionTemplates/` | Content modules inserted into pages |
+| **Format Templates** | `TemplateStore/FormatTemplates/` | Text formatting options for editors |
+| **Link Templates** | `TemplateStore/LinkTemplates/` | Link type configurations |
+| **Table Templates** | `TemplateStore/Schemes/` | Database schema templates |
+| **Script Templates** | `TemplateStore/Scripts/` | BeanShell scripts and functions |
+| **Workflows** | `TemplateStore/Workflows/` | Approval and release workflows |
+
+## File Types Reference
+
+Each template directory contains a combination of the following files, depending on the template type:
+
+### Core Files (All Templates)
+
+#### StoreElement.xml
+**Purpose**: Core template metadata and configuration
+
+**Contains**:
+- Template ID (`id` attribute) - unique identifier
+- Template reference name (`filename` or `name` attribute)
+- Template type (`type` attribute: `page`, `section`, `format`, etc.)
+- Display names (multilingual via `<LANG>` elements)
+- Channel/extension mappings (`<EXTENSION>` elements)
+- Template body definitions (`<TEMPLATEBODY>`)
+- Format template style definitions (`<style>` for format templates)
+
+#### FS_Files.txt
+**Purpose**: File registry with metadata for all files in the template directory
+
+**Contains**: Tab-delimited list with checksum, file size, timestamp, MIME type, and filename for each file
+
+#### FS_Info.txt
+**Purpose**: Additional metadata about the template element
+
+**Contains**: Template information, creation/modification dates, author information
+
+#### FS_References.txt
+**Purpose**: Dependency tracking
+
+**Contains**: References to other FirstSpirit elements that this template depends on or uses
+
+### Form Definition Files
+
+#### GomSource.xml
+**Purpose**: Form definition (GOM = GUI Object Model)
+
+**Contains**:
+- Input component definitions (CMS_INPUT_*, FS_CATALOG, FS_INDEX, etc.)
+- Form field configurations
+- Labels and descriptions (multilingual via `<LANGINFO>`)
+- Layout and organization
+- Default values
+
+#### GomDefaults.xml
+**Purpose**: Default values for GOM form fields (optional)
+
+**Found in**: Style/Format templates primarily
+
+**Contains**: Default values for form fields
+
+### Output Channel Files
+
+#### ChannelSource_[CHANNEL]_[EXTENSION].[EXTENSION]
+**Purpose**: Template output for specific delivery channels
+
+**Naming pattern**: `ChannelSource_<ChannelName>_<extension>.<extension>`
+
+**Common examples**:
+- `ChannelSource_HTML_html.html` - HTML output channel
+- `ChannelSource_XML_xml.xml` - XML output channel
+- `ChannelSource_JSON_json.json` - JSON output channel
+
+**Contains**: FirstSpirit template syntax with output logic (HTML, XML, or other formats)
+
+### Rule Definition Files
+
+#### Ruleset.xml
+**Purpose**: Dynamic form behavior and validation rules
+
+**Contains**:
+- Conditional visibility rules
+- Field dependency rules
+- Validation rules (SAVE, RELEASE, INFO severity)
+- Dynamic value calculations
+- Multi-language support rules
+
+### Preview/Snippet Files
+
+These files define how templates appear in preview mode and in template selection dialogs.
+
+#### SnippetThumb.txt
+**Purpose**: Thumbnail/icon preview
+
+**Contains**: Template syntax to generate small preview image or icon
+
+#### SnippetHeader.txt
+**Purpose**: Header/title preview
+
+**Contains**: Template syntax to generate preview title (often just the headline field)
+
+#### SnippetExtract.txt
+**Purpose**: Content extract preview
+
+**Contains**: Template syntax to generate preview text/excerpt
+
+**Example**:
+```
+$CMS_IF(!pt_headline.isEmpty)$
+  $CMS_VALUE(pt_headline.toText(false))$
+$CMS_END_IF$
+```
+
+### Workflow-Specific Files
+
+#### Workflow.xml
+**Purpose**: Complete workflow definition
+
+**Contains**:
+- States (start, end, intermediate states)
+- Activities (tasks, actions)
+- Transitions (connections between states)
+- Email configurations
+- Permissions and rights
+- User/group assignments
+- Scripting logic
+
+**Structure**: Java object serialization format describing the workflow graph
+
+**Key Components**:
+- **States**: Workflow stages with permissions and duration
+- **Activities**: Tasks users perform
+- **Transitions**: Connections with email notifications and rights
+- **Coordinates**: Visual layout positions (x, y coordinates)
+
+#### ViewScript.txt
+**Purpose**: Custom workflow display/view logic (optional)
+
+**Contains**: BeanShell script for custom workflow UI
+
+## Directory Organization by Template Type
+
+### Page Templates
+```
+PageTemplates/
+└── pt_standard_page/
+    ├── StoreElement.xml                    # Template metadata
+    ├── GomSource.xml                       # Form definition
+    ├── Ruleset.xml                         # Form rules
+    ├── ChannelSource_HTML_html.html        # HTML output
+    ├── SnippetThumb.txt                    # Thumbnail preview
+    ├── SnippetHeader.txt                   # Header preview
+    ├── SnippetExtract.txt                  # Extract preview
+    ├── FS_Files.txt                        # File registry
+    ├── FS_Info.txt                         # Metadata
+    └── FS_References.txt                   # Dependencies
+```
+
+### Section Templates
+```
+SectionTemplates/
+└── st_text_image_module/
+    ├── StoreElement.xml                    # Template metadata
+    ├── GomSource.xml                       # Form definition
+    ├── Ruleset.xml                         # Form rules
+    ├── ChannelSource_HTML_html.html        # HTML output
+    ├── SnippetThumb.txt                    # Thumbnail preview
+    ├── SnippetHeader.txt                   # Header preview
+    ├── SnippetExtract.txt                  # Extract preview
+    ├── FS_Files.txt                        # File registry
+    ├── FS_Info.txt                         # Metadata
+    └── FS_References.txt                   # Dependencies
+```
+
+### Format Templates
+```
+FormatTemplates/
+├── h1/
+│   ├── StoreElement.xml                    # Format definition with style
+│   ├── ChannelSource_HTML_html.html        # HTML rendering
+│   ├── FS_Files.txt
+│   ├── FS_Info.txt
+│   └── FS_References.txt
+│
+└── common_format_templates/                # Folder grouping
+    ├── StoreElement.xml                    # Folder metadata
+    ├── FS_Files.txt
+    ├── FS_Info.txt
+    ├── FS_References.txt
+    │
+    ├── default_style_template/
+    │   ├── StoreElement.xml                # Style template definition
+    │   ├── GomSource.xml                   # Style configuration form
+    │   ├── GomDefaults.xml                 # Default style values
+    │   ├── Ruleset.xml
+    │   ├── ChannelSource_HTML_html.html
+    │   ├── FS_Files.txt
+    │   ├── FS_Info.txt
+    │   └── FS_References.txt
+    │
+    └── p/                                  # Paragraph format
+        ├── StoreElement.xml
+        ├── ChannelSource_HTML_html.html
+        └── ...
+```
+
+### Workflows
+```
+Workflows/
+└── assign_task/
+    ├── StoreElement.xml                    # Workflow metadata
+    ├── Workflow.xml                        # Workflow definition (states, transitions)
+    ├── GomSource.xml                       # Form for workflow parameters
+    ├── Ruleset.xml                         # Form rules
+    ├── ViewScript.txt                      # Custom view script (optional)
+    ├── SnippetThumb.txt                    # Preview files
+    ├── SnippetHeader.txt
+    ├── SnippetExtract.txt
+    ├── FS_Files.txt
+    ├── FS_Info.txt
+    └── FS_References.txt
+```
+
+## Metadata Directory: .FirstSpirit
+
+**Location**: `.FirstSpirit/` at the root of the sync directory
+
+**Purpose**: Contains internal metadata required for successful synchronization between file system and FirstSpirit server
+
+**Important**: Do NOT version control this directory. It contains session-specific information.
+
+### Files
+
+#### Files_[sessionid]_[revision].txt
+**Purpose**: Complete file registry for the export
+
+**Contains**: Tab-delimited entries with reference IDs and file information (checksum, size, timestamp, MIME type, filename)
+
+#### Import_[sessionid]_[revision].txt
+**Purpose**: Import instructions and metadata for re-importing into FirstSpirit
+
+## Template Identification
+
+### Finding Templates
+
+Templates are located by type in their respective directories:
+
+| What to find | Where to look | Identifier |
+|-------------|---------------|------------|
+| Page template by name | `PageTemplates/[name]/` | Directory name matches template reference name |
+| Section template by name | `SectionTemplates/[name]/` | Directory name matches template reference name |
+| Format template by name | `FormatTemplates/[name]/` | Directory name matches format name |
+| Template by ID | Search `StoreElement.xml` files for `id` attribute | Unique numeric ID |
+| Template display name | Look in `StoreElement.xml` → `<LANG>` elements | Multilingual display names |
+
+### Template Reference Names
+
+The directory name matches the template's **reference name** (UID name) in FirstSpirit:
+- `pt_standard_page` → Page Template with reference name "pt_standard_page"
+- `st_text_image_module` → Section Template with reference name "st_text_image_module"
+
+### Template IDs
+
+Each template has two IDs in `StoreElement.xml`:
+- `id` - Element instance ID
+- `templateid` - Template definition ID (for page/section templates)
+
+## Information Access Guide
+
+### How to Find Specific Information
+
+| Information Needed | File to Check | Location in File |
+|-------------------|---------------|------------------|
+| **Template display name** | `StoreElement.xml` | `<LANG displayname="..." language="EN"/>` |
+| **Template reference name** | `StoreElement.xml` | `filename` or `name` attribute |
+| **Template ID** | `StoreElement.xml` | `id` attribute |
+| **Form fields** | `GomSource.xml` | `<CMS_INPUT_*>` elements |
+| **Field labels** | `GomSource.xml` | `<LANGINFO lang="*" label="..."/>` |
+| **Available format templates** | `GomSource.xml` in DOM fields | `<FORMATS><TEMPLATE name="..."/></FORMATS>` |
+| **HTML output** | `ChannelSource_HTML_html.html` | Entire file |
+| **Template variables** | `ChannelSource_HTML_html.html` | `<CMS_HEADER>` section |
+| **Form rules** | `Ruleset.xml` | `<RULE>` elements |
+| **Dependencies** | `FS_References.txt` | List of referenced elements |
+| **Workflow states** | `Workflow.xml` | `<FIELD name="states">` section |
+| **Workflow transitions** | `Workflow.xml` | `<FIELD name="transitions">` section |
+
+## Template Set Configuration
+
+**Location**: `StoreElement.xml` → `<EXTENSION>` element
+
+**Attributes**:
+- `file` - File extension for generated files
+- `link` - Link extension
+- `templateSet` - Template set ID
+- `replaceable` - Whether extension can be changed
+
+## Common Use Cases
+
+### 1. Finding All Section Templates
+```bash
+find sync_dir/TemplateStore/SectionTemplates -name "StoreElement.xml" -type f
+```
+
+### 2. Extracting Template Display Names
+```bash
+grep -r "displayname=" sync_dir/TemplateStore/*/*/StoreElement.xml
+```
+
+### 3. Finding Templates Using a Specific Format
+```bash
+grep -r '<TEMPLATE name="h1"/>' sync_dir/TemplateStore/*/*/GomSource.xml
+```
+
+### 4. Listing All Form Fields in a Template
+```bash
+grep -o 'name="[^"]*"' sync_dir/TemplateStore/PageTemplates/pt_standard_page/GomSource.xml
+```
+
+### 5. Finding All HTML Output Templates
+```bash
+find sync_dir/TemplateStore -name "ChannelSource_HTML_html.html" -type f
+```
+
+## Best Practices
+
+### Version Control
+1. **DO** version control all template files in `TemplateStore/`
+2. **DO NOT** version control `.FirstSpirit/` directory
+3. **DO** commit `StoreElement.xml`, `GomSource.xml`, `ChannelSource_*`, and `Ruleset.xml` files
+4. **CONSIDER** whether to version `FS_Files.txt` (contains checksums that change frequently)
+
+### Template Development
+1. **Naming**: Use consistent prefixes (e.g., `pt_` for page templates, `st_` for section templates)
+2. **Organization**: Group related format templates in folders (like `common_format_templates/`)
+3. **Documentation**: Use meaningful `displayname` attributes in multilingual `<LANG>` elements
+4. **Dependencies**: Check `FS_References.txt` to understand template dependencies
+
+### Editing Exported Files
+1. **StoreElement.xml**: Edit carefully, preserve IDs unless creating new templates
+2. **GomSource.xml**: Standard XML, can be edited directly
+3. **ChannelSource files**: Edit freely, contains your template output logic
+4. **Ruleset.xml**: Edit rules following FirstSpirit rule syntax
+5. **Workflow.xml**: Complex Java serialization format, prefer editing in SiteArchitect
+
+### Re-importing
+1. Maintain the exact directory structure
+2. Keep `StoreElement.xml` IDs consistent for updates
+3. Ensure all referenced templates exist
+4. Validate XML syntax before import
+
+## File Type Summary Table
+
+| File | Required | Template Types | Editable | Purpose |
+|------|----------|----------------|----------|---------|
+| `StoreElement.xml` | Yes | All | Yes (carefully) | Template metadata and configuration |
+| `GomSource.xml` | For templates with forms | Page, Section, Workflow, Style | Yes | Form definition (input components) |
+| `GomDefaults.xml` | No | Style/Format | Yes | Default form values |
+| `Ruleset.xml` | No | Page, Section, Workflow | Yes | Dynamic form rules |
+| `ChannelSource_*.html` | For output templates | Page, Section, Format | Yes | Output channel templates |
+| `Workflow.xml` | Yes | Workflow | No (use SiteArchitect) | Workflow definition |
+| `ViewScript.txt` | No | Workflow | Yes | Custom workflow view |
+| `Snippet*.txt` | No | Page, Section | Yes | Preview content |
+| `FS_Files.txt` | Yes | All | No (auto-generated) | File registry |
+| `FS_Info.txt` | Yes | All | No (auto-generated) | Element metadata |
+| `FS_References.txt` | Yes | All | No (auto-generated) | Dependency tracking |
+
+## References
+
+- **Official Documentation**: https://docs.e-spirit.com/odfs/edocs/sync/
+- **FS-CLI Tool**: https://github.com/e-Spirit/FSDevTools
+- **Template Development**: https://docs.e-spirit.com/odfs/template-develo/
+- **External Synchronization**: https://docs.e-spirit.com/odfs/edocs/sync/how/4-export/