zhongwei/gh-rawe-claude-dev-skills-firstspirit-fs-cli
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
gh-rawe-claude-dev-skills-f…/skills/firstspirit-fs-cli/reference/fs-cli-sync-structure.md
Zhongwei Li 0a3981a4f1 Initial commit
2025-11-30 08:50:01 +08:00

16 KiB
Raw Permalink Blame History

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

find sync_dir/TemplateStore/SectionTemplates -name "StoreElement.xml" -type f

2. Extracting Template Display Names

grep -r "displayname=" sync_dir/TemplateStore/*/*/StoreElement.xml

3. Finding Templates Using a Specific Format

grep -r '<TEMPLATE name="h1"/>' sync_dir/TemplateStore/*/*/GomSource.xml

4. Listing All Form Fields in a Template

grep -o 'name="[^"]*"' sync_dir/TemplateStore/PageTemplates/pt_standard_page/GomSource.xml

5. Finding All HTML Output Templates

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

Reference in New Issue View Git Blame Copy Permalink