Snippets

Snippets are reusable HTML components that can be included in your pages. They help avoid code duplication for common elements like headers, footers, navigation bars, etc.

Snippets are small, independent and reusable HTML code portions that can be added to any page through the render_snippet directive:

        
            <div>
                {{ render_snippet('my-snippet', page) }}
            </div>

Snippet Naming Rules #

  • Must be lowercase (e.g., header, nav-bar)
  • Must start with a letter
  • Can only contain letters, numbers, and hyphens
  • Examples of valid names: nav-bar, footer-2, main-menu
  • Examples of invalid names: Header (uppercase), 1nav (starts with number), nav_bar (underscore)

Creating Snippets #

To create a snippet, use the create command:

        
            elemental-cms snippets create -s nav-bar

This creates two files in your SNIPPETS_FOLDER:

  • nav-bar.json: Contains snippet metadata and dependencies
  • nav-bar.html: Contains the HTML content

Managing Snippets #

Listing Snippets

        
            elemental-cms snippets list

Shows all snippets with repository difference indicators (*) for:

  • Snippets that have differences between local and database versions
  • Snippets missing their local files
  • Snippets that exist locally but not in the database

Comparing Snippets

        
            # Compare local and database versions
            elemental-cms snippets diff -s nav-bar
            
            # Using full path
            elemental-cms snippets diff -s workspace/snippets/nav-bar

Shows differences in both spec and content files in a git-like format.

Pushing Snippets

        
            # Direct format
            elemental-cms snippets push -s nav-bar
            
            # With path
            elemental-cms snippets push -s workspace/snippets/nav-bar
            
            # Push all snippets
            elemental-cms snippets push --all

Pulling Snippets

        
            # Direct format
            elemental-cms snippets pull -s nav-bar
            
            # With path
            elemental-cms snippets pull -s workspace/snippets/nav-bar
            
            # Pull all snippets
            elemental-cms snippets pull --all

Removing Snippets

        
            # Direct format
            elemental-cms snippets remove -s nav-bar
            
            # With path
            elemental-cms snippets remove -s workspace/snippets/nav-bar

Important Notes #

Path Support

All snippet commands support both formats:

  • Direct: -s name (e.g., -s nav-bar)
  • With path: -s path (e.g., -s workspace/snippets/nav-bar)

Batch Operations

Some commands support the --all flag:

  • push --all: Push all snippets
  • pull --all: Pull all snippets

Snippet Structure #

Spec File

The spec file (nav-bar.json) contains the snippet metadata:

        
            {
                "_id": {
                    "$oid": "62602530f62a2bb120f9ce14"
                },
                "name": "nav-bar",
                "cssDeps": [],
                "jsDeps": [],
                "createdAt": {
                    "$date": 1650468144926
                },
                "lastModifiedAt": {
                    "$date": 1650468144926
                }
            }

Content File

The content file (nav-bar.html) contains the HTML for the snippet:

        
            <div class="nav-bar">
                Your navigation content here
            </div>

Backup Files #

If the snippet already exists, backup files will be created and stored at:

  • [your-snippets-folder]/.bak/nav-bar-[epoch-creation-time].json
  • [your-snippets-folder]/.bak/nav-bar-[epoch-creation-time].html
Content