.. _extending_create_a_module:

######################
Create a module
######################

This chapter will show you how to create a custom module for Post Status Notifier.

************
Requirements
************

A module must consist of at least a **directory** containing a **bootstrap.php** file. The directory is mandatory, a single bootstrap.php file will not be accepted. The module directory must only contain alphanumerical characters, no whitespace or special characters.

This is the structure of a minimalistic module setup, a directory called "Example" containing a file named "bootstrap.php".

.. code:: jinja

    Example
    └ bootstrap.php

Module package
~~~~~~~~~~~~~~

The final module must be **packaged in a zip file** to be able to upload it through the Module Manager. It must contain the folder, in this case "Example", on the root level.

.. image:: _static/extend_archive_example.jpg
    :height: 176px
    :width: 323px
    :scale: 100%
    :alt: Module archive


.. _module_bootstrap:

********************
The module bootstrap
********************

Naming conventions
~~~~~~~~~~~~~~~~~~

The module's bootstrap.php file must contain a PHP class. This class must adhere to naming conventions. For example, if your module directory is called **"Example"**, your bootstrap class must be called **"Example_Bootstrap"**. If your module directory is called **"MyAwesomeModule"**, your bootstrap class must be called **"MyAwesomeModule_Bootstrap"** and so on.

Additionally the bootstrap class must **extend "IfwPsn_Wp_Module_Bootstrap_Abstract"**.

.. code::

    <?php
    // Example
    // └ bootstrap.php

    class Example_Bootstrap extends IfwPsn_Wp_Module_Bootstrap_Abstract
    {
        ...


.. code::

    <?php
    // MyAwesomeModule
    // └ bootstrap.php

    class MyAwesomeModule_Bootstrap extends IfwPsn_Wp_Module_Bootstrap_Abstract
    {
        ...

Mandatory properties
~~~~~~~~~~~~~~~~~~~~

.. highlight:: ruby

The bootstrap class must have a **set of protected properties** which provide information about the module:

* _id
* _name
* _description
* _textDomain
* _version
* _author
* _authorHomepage
* _homepage
* _dependencies

_id
===

The module's internal ID. Choose something unique as this ID may only be used by one module. If there are two modules with the same ID, only the first one in the loading procedure will win. For the Example module the ID could be "psn_mod_exm". For MyAwesomeModule it could be "psn_mod_maw" or more verbose "psn_mod_myawesome". The string for the ID is not limited but keep it short.

.. code::

    protected $_id = 'psn_mod_exm';

_name
=====

The module's name. It will be displayed in the Module Manager (see screenshot).

.. code::

    protected $_name = 'MyModule';

.. image:: _static/module_name.jpg
    :height: 98px
    :width: 595px
    :scale: 100%
    :alt: Module name

_description
============

The module's description. It will be displayed in the Module Manager (see screenshot).

.. code::

    protected $_description = 'This is an example module';

.. image:: _static/module_description.jpg
    :height: 88px
    :width: 591px
    :scale: 100%
    :alt: Module description

_textDomain
===========

The module's text domain if it uses translation.

.. code::

    protected $_textDomain = 'psn_exm';

_version
========

The module's version. It will be displayed in the Module Manager (see screenshot).

.. image:: _static/module_version.jpg
    :height: 88px
    :width: 591px
    :scale: 100%
    :alt: Module version

.. code::

    protected $_version = '1.0';

_author
=======

The module's author name. It will be displayed in the Module Manager (see screenshot).

.. image:: _static/module_author.jpg
    :height: 88px
    :width: 591px
    :scale: 100%
    :alt: Module version

.. code::

    protected $_author = 'Timo';

_authorHomepage
===============

The module's author homepage. It will be displayed in the Module Manager (see screenshot).

.. image:: _static/module_author.jpg
    :height: 88px
    :width: 591px
    :scale: 100%
    :alt: Module version

.. code::

    protected $_authorHomepage = 'http://www.ifeelweb.de/';

_homepage
=========

The module's homepage. It will be displayed in the Module Manager (see screenshot).

.. image:: _static/module_homepage.jpg
    :height: 88px
    :width: 591px
    :scale: 100%
    :alt: Module version

.. code::

    protected $_homepage = 'http://www.ifeelweb.de/wp-plugins/post-status-notifier/';

_dependencies
=============

The module dependencies. An array of other module's ID's which should be loaded before this one loads. Modules should always load after the built-in premium module (**psn_mod_prm**) which activates PSN's in premium mode.

.. code::

    protected $_dependencies = array('psn_mod_prm');


bootstrap method
~~~~~~~~~~~~~~~~

The bootstrap class is required to have a method called "bootstrap". It will be executed in the module loading process. This method is the starting point of each module.

.. code::

    <?php
    class Example_Bootstrap extends IfwPsn_Wp_Module_Bootstrap_Abstract
    {
        ...

        public function bootstrap()
        {
            // This is the starting point of a module. This method gets called when the module gets loaded.

            // Your magic code starts from here :)
        }

This a complete example of a module bootstrap class:

.. code::

    <?php
    class Example_Bootstrap extends IfwPsn_Wp_Module_Bootstrap_Abstract
    {
        /**
         * @var string
         */
        protected $_id = 'psn_mod_exm';

        /**
         * @var string
         */
        protected $_name = 'Example';

        /**
         * @var string
         */
        protected $_description = 'This is an example module';

        /**
         * @var string
         */
        protected $_textDomain = 'psn_exm';

        /**
         * @var string
         */
        protected $_version = '1.0';

        /**
         * @var string
         */
        protected $_author = 'Timo';

        /**
         * @var string
         */
        protected $_authorHomepage = 'http://www.ifeelweb.de/';

        /**
         * @var string
         */
        protected $_homepage = 'http://www.ifeelweb.de/wp-plugins/post-status-notifier/';

        /**
         * @var array
         */
        protected $_dependencies = array('psn_mod_prm');



        /**
         * The module's bootstrap method
         */
        public function bootstrap()
        {
            // This is the starting point of a module. This method gets called when the module gets loaded.
        }
    }

On module activation
~~~~~~~~~~~~~~~~~~~~

After a module got uploaded through the Module Manager and it was accepted, it will be listed under "Installed modules".

.. image:: _static/module_activation.jpg
    :height: 92px
    :width: 599px
    :scale: 100%
    :alt: Module activation

The bootstrap class features three methods which will get called on activation, deactivation and deletion of the module.

onActivate
==========

The **onActivate** method will be called when a module gets activated by clicking the "Activate" link in the Module Manager.
Here you can initialize the creation of a custom database table for example.

.. code::

    /**
     * Fires when module gets activated by the Module Manager
     */
    public function onActivate()
    {
    }

onDeactivate
============

The **onDeactivate** method will be called when a module gets activated by clicking the "Deactivate" link in the Module Manager.

.. code::

    /**
     * Fires when custom modules get deactivated by the Module Manager
     */
    public function onDeactivate()
    {
    }

onDelete
========

The **onDelete** method will be called when a module gets activated by clicking the "Delete" link in the Module Manager.
Here you can initialize the deletion of all custom data the module stored while it was active.

.. code::

    /**
     * Fires when custom modules get deleted by the Module Manager
     */
    public function onDelete()
    {
    }

On plugin activation
~~~~~~~~~~~~~~~~~~~~

If the complete plugin gets deactivated and deleted, the module's ``onDeactivate`` respectively ``onDelete`` methods will not get called. For this case you should also hook into the plugin's deactivation and deletion routines. This is done by using the **Installer**. The Installer object is accessible from the bootstrap class through the Plugin Manager like this:

.. code::

    $this->_pm->getInstaller();

It features three methods to add your own logic:

addActivation
=============

The ``addActivation`` method gets called when PSN gets activated in the WordPress plugin backend. It expects an object implementing the interface ``IfwPsn_Wp_Plugin_Installer_ActivationInterface``.

.. code::

    // e.g. in your bootstrap file
    $this->_pm->getInstaller()->addActivation( new Psn_Module_Example_Installer_Activation() );

Objects implementing the interface ``IfwPsn_Wp_Plugin_Installer_ActivationInterface`` must implement the **public method** ``execute``. There you can place your custom activation code like in this example:

.. code::

    class Psn_Module_Example_Installer_Activation implements IfwPsn_Wp_Plugin_Installer_ActivationInterface
    {
        /**
         * @param IfwPsn_Wp_Plugin_Manager $pm
         * @param bool $networkwide - true if WordPress multisite is activated
         * @return mixed|void
         */
        public function execute( IfwPsn_Wp_Plugin_Manager $pm, $networkwide = false )
        {
            // here you could for example create a new database table
        }
    }

addDeactivation
===============

The ``addDeactivation`` method gets called when PSN gets deactivated in the WordPress plugin backend. It expects an object implementing the interface ``Ifw_Wp_Plugin_Installer_DeactivationInterface``.

.. code::

    // e.g. in your bootstrap file
    $this->_pm->getInstaller()->addDeactivation( new Psn_Module_Example_Installer_Deactivation() );

Objects implementing the interface ``IfwPsn_Wp_Plugin_Installer_DeactivationInterface`` must implement the **public method** ``execute``. There you can place your custom deactivation code like in this example:

.. code::

    class Psn_Module_Example_Installer_Deactivation implements IfwPsn_Wp_Plugin_Installer_DeactivationInterface
    {
        /**
         * @param IfwPsn_Wp_Plugin_Manager $pm
         * @param bool $networkwide - true if WordPress multisite is activated
         * @return mixed|void
         */
        public function execute( IfwPsn_Wp_Plugin_Manager $pm, $networkwide = false )
        {
            // if you want to execute code when the plugin gets deactivated, place it here
        }
    }

addUninstall
============

The ``addUninstall`` method gets called when PSN gets deleted in the WordPress plugin backend. It expects an object implementing the interface ``Ifw_Wp_Plugin_Installer_UninstallInterface``.

.. code::

    // e.g. in your bootstrap file
    $this->_pm->getInstaller()->addUninstall( new Psn_Module_Example_Installer_Uninstall() );

Objects implementing the interface ``IfwPsn_Wp_Plugin_Installer_UninstallInterface`` must implement the **public static method** ``execute``. There you can place your custom uninstall code like in this example:

.. code::

    class Psn_Module_Example_Installer_Uninstall implements IfwPsn_Wp_Plugin_Installer_UninstallInterface
    {
        /**
         * @param IfwPsn_Wp_Plugin_Manager|null $pm
         * @return mixed|void
         */
        public static function execute($pm)
        {
            // for example remove database tables if the plugin gets deleted

            if (IfwPsn_Wp_Proxy_Blog::isMultisite()) {

                // on multisite installation

            } else {

                // on single blog installation
            }
        }
    }