Omeka S

Essential Patterns

# Sync files to server (excludes 'files' folder with media)
rsync -avz --exclude 'files' ./local-path/ $OMEKA_HOST:$OMEKA_PATH/path/

# Sync theme to server
rsync -avz --exclude 'files' ./my-theme/ $OMEKA_HOST:$OMEKA_PATH/themes/my-theme/

# Sync from server to local (for initial setup or backup)
rsync -avz --exclude 'files' $OMEKA_HOST:$OMEKA_PATH/path/ ./local-path/

# SSH to run commands on server (limited access)
ssh $OMEKA_HOST "ls -la $OMEKA_PATH/themes/"

# Clear cache on server
ssh $OMEKA_HOST "rm -rf $OMEKA_PATH/application/data/cache/*"

# View logs on server
ssh $OMEKA_HOST "tail -50 $OMEKA_PATH/logs/application.log"

Database Access (MariaDB via SSH)

Database credentials are stored in config/database.ini on the server:

# View database credentials
ssh $OMEKA_HOST "cat $OMEKA_PATH/config/database.ini"

# Example database.ini format:
# user     = "omeka_user"
# password = "password"
# dbname   = "omeka_s"
# host     = "localhost"

Run SQL queries via mariadb command over SSH:

# Run a query (replace credentials from database.ini)
ssh $OMEKA_HOST "mariadb -u DB_USER -pDB_PASS DB_NAME -e 'SELECT * FROM resource LIMIT 5;'"

# Interactive session
ssh $OMEKA_HOST "mariadb -u DB_USER -pDB_PASS DB_NAME"

When to Use This Skill

• Theme Development: Custom layouts, SCSS/CSS styling, template overrides
• Module Development: PHP modules, event listeners, forms, database entities
• Configuration: Site setup, content visibility, database relationships
• Troubleshooting: Media issues, permission problems, build failures

Development Workflow Decision Tree

User Request → What type of work?

├─ Theme Customization
│  ├─ Simple CSS change?
│  │  └─ Edit theme/asset/css/style.css locally, sync via rsync
│  │     (see references/theme-development.md → Quick CSS Editing)
│  │
│  ├─ Need SCSS/variables?
│  │  └─ Use SCSS build process locally
│  │     1. Edit theme/asset/sass/*.scss locally
│  │     2. Run locally: cd themes/THEME && npm run build
│  │     3. Sync compiled CSS via rsync
│  │     (see references/theme-development.md → SCSS Build Process)
│  │
│  └─ Template override?
│      └─ Download from application/view/, edit locally, sync to theme/view/
│         (see references/theme-development.md → Template Structure)
│
├─ Module Development
│  ├─ Creating new module?
│  │  └─ Create locally, upload entire module directory
│  │     (see references/module-development.md → Module Structure)
│  │
│  ├─ Adding event listener?
│  │  └─ Edit Module.php locally, upload, clear cache
│  │     (see references/module-development.md → Event System)
│  │
│  └─ Database entities?
│      └─ Create Entity locally, update module.ini, upload, reinstall module
│         (see references/module-development.md → Database Entities)
│
├─ Content Visibility Issues
│  └─ Items not showing?
│      1. Run queries via mariadb over SSH
│      2. Verify is_public flags
│      3. Confirm site assignments
│      (see references/database.md → Content Visibility)
│
└─ Configuration/Setup
    └─ See references/troubleshooting.md

Directory Structure

$OMEKA_PATH/                    # Server path (configurable)
├── application/                # Core (DON'T MODIFY)
│   ├── view/                   # Default templates (COPY to theme to override)
│   └── src/                    # PHP source
├── config/
│   ├── database.ini
│   └── local.config.php
├── modules/                    # Custom modules here
│   └── MyModule/
│       ├── Module.php
│       ├── module.ini
│       ├── src/
│       └── view/
├── themes/                     # Custom themes here
│   └── MyTheme/
│       ├── theme.ini
│       ├── asset/
│       │   ├── css/
│       │   └── sass/
│       └── view/
└── files/                      # Uploaded media
    ├── original/
    ├── large/
    ├── medium/
    └── square/

Quick Reference

Common File Operations

# Set your project variables first
OMEKA_HOST="[email protected]"
OMEKA_PATH="/var/www/html/omeka-s"

# Read theme file from server
ssh $OMEKA_HOST "cat $OMEKA_PATH/themes/THEME/theme.ini"

# Download theme for local editing (excludes files folder)
rsync -avz --exclude 'files' $OMEKA_HOST:$OMEKA_PATH/themes/THEME/ ./themes/THEME/

# Upload modified theme (excludes files folder)
rsync -avz --exclude 'files' ./themes/THEME/ $OMEKA_HOST:$OMEKA_PATH/themes/THEME/

# View logs
ssh $OMEKA_HOST "tail -50 $OMEKA_PATH/logs/application.log"

# Clear cache
ssh $OMEKA_HOST "rm -rf $OMEKA_PATH/application/data/cache/*"

Common Database Queries (via MariaDB over SSH)

First, get credentials from database.ini:

ssh $OMEKA_HOST "cat $OMEKA_PATH/config/database.ini"

Then run queries:

# Make all items public
ssh $OMEKA_HOST "mariadb -u USER -pPASS DBNAME -e \"UPDATE resource SET is_public = 1 WHERE resource_type = 'Omeka\\\\Entity\\\\Item';\""

# Assign all items to site 1
ssh $OMEKA_HOST "mariadb -u USER -pPASS DBNAME -e 'INSERT INTO item_site (item_id, site_id) SELECT id, 1 FROM item ON DUPLICATE KEY UPDATE site_id = VALUES(site_id);'"

# Check item visibility
ssh $OMEKA_HOST "mariadb -u USER -pPASS DBNAME -e \"SELECT r.id, r.title, r.is_public, COUNT(is_i.item_id) as in_site FROM resource r LEFT JOIN item_site is_i ON r.id = is_i.item_id WHERE r.resource_type = 'Omeka\\\\Entity\\\\Item' GROUP BY r.id;\""

For complete database operations, see references/database.md

Theme Development Quick Start

1. Create theme directory locally:

mkdir -p my-theme/{asset/{css,js,sass},view/common}

2. Required theme.ini:

[info]
name = "My Theme"
version = "1.0"
author = "Your Name"
theme_link = ""
author_link = ""
description = "Custom theme"

3. Sync to server:

rsync -avz --exclude 'files' ./my-theme/ $OMEKA_HOST:$OMEKA_PATH/themes/my-theme/

4. Override templates: Download from application/view/, edit locally, sync to theme/view/

For complete theme guide, see references/theme-development.md

Module Development Quick Start

1. Basic Module.php:

<?php
namespace MyModule;

use Omeka\Module\AbstractModule;
use Laminas\EventManager\SharedEventManagerInterface;

class Module extends AbstractModule
{
    public function attachListeners(SharedEventManagerInterface $sharedEventManager)
    {
        // Add event listeners here
    }
}

2. Required module.ini:

[info]
name = "My Module"
version = "1.0.0"
author = "Your Name"
description = "Module description"

3. Sync to server:

rsync -avz --exclude 'files' ./MyModule/ $OMEKA_HOST:$OMEKA_PATH/modules/MyModule/

For complete module guide, see references/module-development.md

Common Workflows

Workflow 1: Change Theme Colors

1. Download SCSS files: rsync -avz --exclude 'files' $OMEKA_HOST:$OMEKA_PATH/themes/THEME/asset/sass/ ./sass/
2. Edit sass/_base.scss variables locally
3. Build locally: cd themes/THEME && npm install && npx gulp css
4. Upload compiled CSS: rsync -avz ./asset/css/style.css $OMEKA_HOST:$OMEKA_PATH/themes/THEME/asset/css/
5. Clear cache: ssh $OMEKA_HOST "rm -rf $OMEKA_PATH/application/data/cache/*"

Workflow 2: Override Item Display Template

1. Download template: rsync -avz $OMEKA_HOST:$OMEKA_PATH/application/view/omeka/site/item/show.phtml ./
2. Edit locally
3. Create theme directory and sync:

   ssh $OMEKA_HOST "mkdir -p $OMEKA_PATH/themes/THEME/view/omeka/site/item"
   rsync -avz ./show.phtml $OMEKA_HOST:$OMEKA_PATH/themes/THEME/view/omeka/site/item/
   

4. Clear cache

Workflow 3: Fix Items Not Showing

1. Run visibility queries via mariadb over SSH (see references/database.md)
2. Verify site assignments
3. Check item set linkage
4. Clear cache via SSH

Workflow 4: Add Custom Module

1. Create module structure locally
2. Write Module.php and module.ini
3. Sync: rsync -avz --exclude 'files' ./MyModule/ $OMEKA_HOST:$OMEKA_PATH/modules/MyModule/
4. Install via admin interface
5. Test functionality

Best Practices

DO

• Edit files locally then upload - never edit directly on server
• Keep local copies of all your customizations
• Use SCSS build process locally for maintainable styling
• Copy templates to theme - never modify application/ directly
• Test database queries via mariadb before bulk operations
• Version control your custom themes and modules locally (git)
• Document custom code - future you will thank you
• Clear cache after uploads - changes won't appear otherwise

DON'T

• Don't modify core files in application/
• Don't edit files directly on server - use local development
• Don't edit compiled CSS - changes will be overwritten by SCSS build
• Don't forget site assignments - items won't show without them
• Don't skip backups before database changes
• Don't forget to clear cache after uploading changes

Troubleshooting

Items Not Visible

→ See references/database.md (Content Visibility section) → Run queries via mariadb over SSH

CSS Changes Not Appearing

• Clear browser cache (hard refresh)
• Clear server cache: ssh $OMEKA_HOST "rm -rf $OMEKA_PATH/application/data/cache/*"
• Verify file was uploaded correctly
• Check theme is active

→ See references/theme-development.md (Troubleshooting Build Issues)

Module Not Loading

• Check module.ini format
• Verify Module.php namespace
• Check PHP syntax locally: php -l Module.php
• View logs: ssh $OMEKA_HOST "tail -50 $OMEKA_PATH/logs/application.log"

→ See references/troubleshooting.md

Media/Thumbnail Issues

• Check file permissions on server
• Verify Imagemagick is installed on server
• Check thumbnail generation settings

→ See references/database.md (Media & Thumbnails)

Reference Files

Detailed documentation for each area:

• references/database.md - Site configuration, content visibility, database relationships, media system, SQL queries
• references/theme-development.md - Complete theme structure, SCSS build process, template overrides, view helpers
• references/module-development.md - Module structure, event system, forms, database entities, API integration
• references/troubleshooting.md - Common issues, error messages, debugging techniques
• examples/workflows.md - Step-by-step examples for common tasks

Key Concepts

Content Visibility (Critical!)

Items need 4 conditions to be visible:

1. Item is public (is_public = 1)
2. Item is assigned to site (item_site table)
3. Item set is open (is_open = 1)
4. Item set is linked to site (site_item_set table)

See references/database.md for complete details

Theme Inheritance

Themes inherit from default theme:

• Your theme only contains overrides
• Missing templates fall back to application/view/
• CSS builds from SCSS in asset/sass/

See references/theme-development.md for template patterns

Module Event System

Modules extend Omeka via events:

• api.search.query - Modify search
• view.show.after - Add to page display
• form.add_elements - Add form fields

See references/module-development.md for event list

Getting Started Checklist

For new Omeka S projects:

1. ☐ Configure connection variables (OMEKA_HOST, OMEKA_PATH)
2. ☐ Verify SSH access works
3. ☐ Check Omeka version on server
4. ☐ Get database credentials from config/database.ini
5. ☐ Download existing theme/module files to local workspace (via rsync)
6. ☐ Set up local build tools (npm, gulp) if using SCSS
7. ☐ Test rsync and cache clearing workflow
8. ☐ Test mariadb access via SSH

Resources

• Official Docs: https://omeka.org/s/docs/
• Developer Docs: https://omeka.org/s/docs/developer/
• Forums: https://forum.omeka.org/

For detailed guidance on any topic, see the appropriate reference file above.

Critical Lessons Learned

Two Deployment Patterns

Pattern A: Single File Changes

# Edit locally, sync single file
rsync -avz ./path/to/file.php $OMEKA_HOST:$OMEKA_PATH/path/to/file.php
ssh $OMEKA_HOST "rm -rf $OMEKA_PATH/application/data/cache/*"

Pattern B: Directory Sync

# Sync entire directory (excludes files folder with media)
rsync -avz --exclude 'files' ./my-module/ $OMEKA_HOST:$OMEKA_PATH/modules/my-module/
ssh $OMEKA_HOST "rm -rf $OMEKA_PATH/application/data/cache/*"

Block Layouts: Two Types

Omeka S has two distinct types of block layouts that are registered differently:

1. Site Page Blocks (block_layouts)

Used for site pages (like Time Periods, About, etc.)

// In module.config.php
'block_layouts' => [
    'invokables' => [
        'timePeriodsGrid' => MyModule\Site\BlockLayout\TimePeriodsGrid::class,
    ],
],

2. Resource Page Blocks (resource_page_block_layouts)

Used for item/media/item-set display pages

// In module.config.php
'resource_page_block_layouts' => [
    'invokables' => [
        'relatedItems' => MyModule\Site\ResourcePageBlockLayout\RelatedItems::class,
    ],
],

Key Difference: Site page blocks go in regular pages; resource page blocks appear when viewing an item.

Using the API in Block Layouts

NEVER use direct database connections in blocks. Use the API instead:

// WRONG - Will fail
$connection = $view->getHelperPluginManager()->get('api')->getManager()->getConnection();

// CORRECT - Use the API
$view->api()->search('items', [
    'site_id' => $site->id(),
    'property' => [[
        'joiner' => 'and',
        'property' => 'dcterms:coverage',
        'type' => 'eq',
        'text' => 'some value',
    ]],
]);

Getting unique property values dynamically:

// Get property first
$coverageProperty = $view->api()->searchOne('properties', [
    'term' => 'dcterms:coverage',
])->getContent();

// Get all items with that property
$allItems = $view->api()->search('items', [
    'site_id' => $site->id(),
    'has_property' => [$coverageProperty->id()],
])->getContent();

// Extract unique values
$uniqueValues = [];
foreach ($allItems as $item) {
    $values = $item->value('dcterms:coverage', ['all' => true]);
    foreach ($values as $val) {
        $textValue = (string)$val;
        if (!in_array($textValue, $uniqueValues)) {
            $uniqueValues[] = $textValue;
        }
    }
}

Module Version Mismatches

Symptoms:

• Blocks render empty
• "Unknown block layout" errors
• Features not working despite module being active

Diagnosis (via mariadb over SSH):

# Check database version
ssh $OMEKA_HOST "mariadb -u USER -pPASS DBNAME -e \"SELECT id, version FROM module WHERE id = 'ModuleName';\""

Compare with file version in module.ini.

Solution: Download the correct version from GitHub releases to match database expectations.

Custom Block Layout Template

Full working example of a site page block:

<?php
namespace MyModule\Site\BlockLayout;

use Omeka\Api\Representation\SiteRepresentation;
use Omeka\Api\Representation\SitePageRepresentation;
use Omeka\Api\Representation\SitePageBlockRepresentation;
use Omeka\Site\BlockLayout\AbstractBlockLayout;
use Laminas\View\Renderer\PhpRenderer;

class MyCustomBlock extends AbstractBlockLayout
{
    public function getLabel()
    {
        return 'My Custom Block'; // @translate
    }

    public function form(
        PhpRenderer $view,
        SiteRepresentation $site,
        SitePageRepresentation $page = null,
        SitePageBlockRepresentation $block = null
    ) {
        // Get saved data
        $data = $block ? $block->data() : [];
        $myValue = $data['myValue'] ?? '';

        // Return HTML form for admin
        return sprintf(
            '<div class="field"><label>My Setting</label><input type="text" name="o:block[__blockIndex__][o:data][myValue]" value="%s"></div>',
            htmlspecialchars($myValue, ENT_QUOTES)
        );
    }

    public function render(PhpRenderer $view, SitePageBlockRepresentation $block)
    {
        $site = $view->currentSite();
        $data = $block->data();

        // Query items dynamically
        $items = $view->api()->search('items', [
            'site_id' => $site->id(),
            'limit' => 10,
        ])->getContent();

        // Render template
        return $view->partial('common/block-layout/my-custom-block', [
            'items' => $items,
            'data' => $data,
        ]);
    }
}

Block Data Storage

Block configuration is stored as JSON in site_page_block.data (query via mariadb over SSH):

# View block data
ssh $OMEKA_HOST "mariadb -u USER -pPASS DBNAME -e 'SELECT id, layout, data FROM site_page_block WHERE page_id = 10;'"

# Update block data (be careful with escaping!)
ssh $OMEKA_HOST "mariadb -u USER -pPASS DBNAME -e 'UPDATE site_page_block SET data = \"{\\\"key\\\": \\\"value\\\"}\" WHERE id = 54;'"

Important: Data must be valid JSON. Use proper escaping when updating via SQL.

Querying with Property Filters

// Search items by property value
$response = $view->api()->search('items', [
    'site_id' => $site->id(),
    'property' => [[
        'joiner' => 'and',           // 'and' or 'or'
        'property' => 'dcterms:title', // property term
        'type' => 'eq',               // 'eq', 'neq', 'in', 'nin', 'ex', 'nex'
        'text' => 'search term',
    ]],
]);

$count = $response->getTotalResults();
$items = $response->getContent();

CSS Loading System (CSSEditor Module)

Omeka S uses the CSSEditor module for custom CSS. It provides two methods:

1. Inline CSS (css_editor_css) - Written directly in admin interface
2. External CSS (css_editor_external_css) - URLs to external CSS files

Database Storage (check via mariadb over SSH):

# Check current CSS configuration
ssh $OMEKA_HOST "mariadb -u USER -pPASS DBNAME -e \"SELECT id, value FROM site_setting WHERE id LIKE '%css%';\""

# Example output:
# css_editor_css                 (empty or contains CSS code)
# css_editor_external_css        ["/themes/foundation/asset/css/cdha-custom.css"]

CSS Loading Order (Cascade):

1. Core CSS (iconfonts.css, resource-page-blocks.css)
2. Module CSS (from installed modules)
3. Theme base CSS (default.css, inkwell.css, etc.)
4. Inline CSS from css_editor_css (via /s/SITE/css-editor endpoint)
5. External CSS from css_editor_external_css
6. Additional module CSS

Key Points:

• Inline CSS loads BEFORE external CSS - External files can override inline styles
• Both are added by CSSEditor module, accessible via Admin → Sites → [Site] → Theme
• External CSS URLs can be theme-relative paths or full CDN URLs
• Inline CSS is stored directly in database; external CSS is just a reference

Common Issue: CSS Conflicts (fix via mariadb over SSH)

# Clear conflicting inline CSS
ssh $OMEKA_HOST "mariadb -u USER -pPASS DBNAME -e \"UPDATE site_setting SET value = '' WHERE id = 'css_editor_css';\""

# Check what external files are referenced
ssh $OMEKA_HOST "mariadb -u USER -pPASS DBNAME -e \"SELECT value FROM site_setting WHERE id = 'css_editor_external_css';\""

Best Practice:

• Use external CSS files for maintainable, version-controlled styles
• Use inline CSS only for quick tweaks or site-specific overrides
• Reference external files via CSSEditor rather than hardcoding in templates

Template Precedence Order (CRITICAL!)

Omeka S loads templates in this order (highest to lowest priority):

1. Theme templates (themes/THEME/view/) - HIGHEST PRIORITY
2. Module templates (modules/MODULE/view/)
3. Core templates (application/view/) - LOWEST PRIORITY

This means theme templates override EVERYTHING, including module templates.

Real-World Example:

# You edit this module template locally:
modules/CdhaBlocks/view/common/resource-page-block-layout/filtered-values-main.phtml

# But Omeka actually uses this theme template (if it exists on server):
themes/foundation/view/common/resource-page-block-layout/filtered-values-main.phtml

# Result: Your module changes don't appear, causing confusion!

Debugging Template Issues:

When template changes don't appear:

# 1. Check if theme has override on server
ssh $OMEKA_HOST "find $OMEKA_PATH/themes/ACTIVE_THEME -name 'template-name.phtml'"

# 2. If found, edit the THEME template, not the module template

# 3. Use error logging to confirm which file loads:
# Add to top of both templates:
<?php error_log('TEMPLATE: ' . __FILE__); ?>

Best Practice:

• Always check theme directory first before editing module templates
• Use SSH with grep to find ALL instances of a template name
• Remember: even resource page block templates can be overridden by themes

Common Symptoms:

• "I changed the module template but nothing happens"
• "My debug logs in the module template don't appear"
• "The module is being called but using old code"

Common Pitfalls

1. Don't hardcode values - Query database dynamically
2. Don't use direct SQL in PHP - Use API methods
3. Don't forget to clear cache - ssh $OMEKA_HOST "rm -rf $OMEKA_PATH/application/data/cache/*"
4. Don't skip version checks - Module version mismatches cause silent failures
5. Don't edit module templates without checking for theme overrides - Theme templates take precedence
6. Don't edit files on server directly - Always edit locally and upload