Convert Omeka plugin into Omeka S module

Convert Omeka plugin into Omeka S module

Here are a few tips on how to convert a Omeka 2.x plugin into a Omeka S module

• Directory structure
• plugin.ini -> config/module.ini
• Module.php
• Recipes

Directory structure

1. Create the directory structure

   mkdir asset
   mkdir config
   mkdir language
   mkdir -p src/Controller
   mkdir -p src/View/Helper
   mkdir view
   

2. Copy files from existing plugin

   cp $PLUGIN_PATH/controllers/* src/Controller
   cp $PLUGIN_PATH/languages/* language
   cp -r $PLUGIN_PATH/libraries/$PluginName/* src
   cp $PLUGIN_PATH/plugin.ini config/module.ini
   cp $PLUGIN_PATH/${PluginName}Plugin.php Module.php
   cp $PLUGIN_PATH/views/helpers/* src/View/Helper
   cp -r $PLUGIN_PATH/views/* view    # exclude helpers here
   

3. You're done moving files around. It's time to edit them!

plugin.ini -> config/module.ini

They are very similar but some keys differ

1. Remove [info] line
2. Change link to module_link
3. Add configurable = true if your plugin is configurable (implements hooks config_form and config)
4. Valid keys at the moment are: name, version, author, configurable, description, module_link, author_link. You can remove the others (you can keep them if you prefer, it's harmless)

config/module.config.php

You will need this file to declare your controllers, routes, view helpers, ...

Here's a simple example to start with

<?php
return [
    'controllers' => [
        'invokables' => [
            'MyModule\Controller\Index' => 'MyModule\Controller\IndexController',
        ],
    ],
    'controller_plugins' => [
        'invokables' => [
            'myControllerPlugin' => 'MyModule\Mvc\Controller\Plugin\MyControllerPlugin',
        ]
    ],
    'router' => [
        'routes' => [
            'my_route' => [
                'type' => 'segment',
                'options' => [
                    'route' => '/mymodule/:id',
                    'constraints' => [
                        'id' => '\d+',
                    ],
                    'defaults' => [
                        '__NAMESPACE__' => 'MyModule\Controller',
                        'controller' => 'Index',
                        'action' => 'show',
                    ],
                ],
            ],
        ],
    ],
    'view_manager' => [
        'template_path_stack' => [
            OMEKA_PATH . '/modules/MyModule/view',
        ],
    ],
    'view_helpers' => [
        'invokables' => [
            'myViewHelper' => 'MyModule\View\Helper\MyViewHelper',
        ],
    ],
    'translator' => [
        'translation_file_patterns' => [
            [
                'type' => 'gettext',
                'base_dir' => __DIR__ . '/../language',
                'pattern' => '%s.mo',
                'text_domain' => null,
            ],
        ],
    ],
];

You can find real examples at https://github.com/omeka-s-modules

Module.php

Basically everything will change in this file, and this page won't cover all but here are a few things you will have to do first

1. Add namespace MyModule; at beginning of file
2. Add use Omeka\Module\AbstractModule; just below
3. Rename your plugin class into Module and make it extends AbstractModule
4. Remove protected variables $_hooks and $_filters
5. Rename a few hooks (you will have to change their signature and their content as well, it's not magic!)

• hookInstall -> install
• hookUninstall -> uninstall
• hookInitialize -> onBoostrap
• hookUpgrade -> upgrade
• hookConfigForm -> getConfigForm
• hookConfig -> handleConfigForm

6. Replace other hooks by listeners

   public function attachListeners(SharedEventManagerInterface $sharedEventManager) {
   
   }

7. Add this method

   public function getConfig() {
       return include __DIR__ . '/config/module.config.php';
   }

Recipes

$serviceLocator

You will need this object almost everywhere, and there are different ways to retrieve it depending on the where you are (controller, view helper, ...)

• In the main Module class: $this->getServiceLocator()
• In a controller: $this->getServiceLocator()
• In a view helper: $this->getView()->getHelperPluginManager()->getServiceLocator()

__() / Translate strings

• In a controller: $this->translate('string')
• In a view helper: $translate = $this->getView()->translate('string');
• Everywhere else: $serviceLocator->get('MvcTranslator')->translate('string')

get_option($key) / set_option($key, $value)

• $serviceLocator->get('Omeka\Settings')->get($key)
• $serviceLocator->get('Omeka\Settings')->set($key, $value)

absolute_url($args, $route)

• In a controller: $this->getView()->url($route, $args)

get_view()

• In a controller: $this->getView()

get_record_by_id($recordType, $id)

• In a controller: $this->api()->read($recordType, $id)
• Everywhere else: $serviceLocator->get('Omeka\ApiManager')->read($recordType, $id)

add_translation_source()

• Not useful anymore, set translation path in config/module.config.php

_log($msg, $priority)

• $serviceLocator->get('Omeka\Logger')->log($priority, $msg)