Skip to content

Create your own Newsletter plugin

Jump to bottom Edit New page
Christian Flach edited this page Mar 1, 2014 · 4 revisions

Basic plugin

  1. Create the folder modules/Foo/lib/Foo/NewsletterPlugin.
  2. Choose a nice plugin name and put the file into the new folder (i.e.: ItemList.php).
  3. Put the following minimal content in the file: 
    <?php
class Foo_NewsletterPlugin_ItemList extends Newsletter_AbstractPlugin
{
    // $filtAfterDate is null if is not set, or in format yyyy-mm-dd hh:mm:ss
    public function getPluginData($filtAfterDate=null)
    {
        if (!$this->pluginAvailable()) {
            return array();
        }

        if (!SecurityUtil::checkPermission('Foo::', '::', ACCESS_READ, $this->userNewsletter)) {
            return array();
        }
        $DBItems = ... //Get items from DB
        
        $items = array(); //This array will be returned
        foreach ($DBItems as $k => $item) {

            //Set title of this item.
            $items[$k]['nl_title'] = $item['title'];

            //Set link of title. Be sure to call ModUtil::url() with true as seventh parameter
            // (full qualified url)!
            $items[$k]['nl_url_title'] = ModUtil::url('Foo', 'user', 'display', array('lang' => $this->lang), null, null, true);

            //Set main content of the item.
            $items[$k]['nl_content'] = $item['longtext'];

            //Url for further reading. In this case it is the same as used for the title.
            $items[$k]['nl_url_readmore'] = $items[$k]['nl_url_title'];
            
            //A picture to display in Newsletter next to the item
            $items[$k]['nl_picture'] = $item[$k]['path_to_picture']
        }
        return $items;
    }
}

Enhanced plugin

  • Title in newsletter. Choose a short one.

    public function getTitle()
{
    return $this->__("Latest items");
}

  • Display name in admin interface

    public function getDisplayName()
{
    return $this->__("Item list of foo items");
}

  • Description in admin interface

    public function getDescription()
{
    return $this->__("This plugin shows a list of items of the Foo module");
}

  • Plugin availability: This has to return true, else the plugin is not shown in newsletter.

    public function pluginAvailable()
{
    return ModUtil::available($this->modname) && $foo;
}

  • Modname of the module the plugin is providing content for. This is usefull if module A want's to provide a plugin for module B. This is used by the native Newsletter plugins, providing content for other modules.

    public function getModname()
{
    return $this->modname;
}

Handling plugin variables

You can easily add a configuration screen for your plugin. Add the following (example: Clip) functions to your plugin class:

    public function getParameters()
    {
        $pubtypes = array();
        if (ModUtil::available('Clip') && ModUtil::loadApi('Clip')) {
            $pubtypes = Clip_Util::getPubtype(-1)->toArray();
        }

        $active = $this->getPluginVar('TIDs', array());
        foreach ($pubtypes as $k => $v) {
            $pubtypes[$k]['nwactive'] = in_array($k, $active);
        }

        $args = $this->getPluginVar('Args', array());

        return array('number' => 1,
                     'param'  => array(
                                       'PubTypes'=> $pubtypes,
                                       'Args' => $args
                                      )
                    );
    }

    public function setParameters()
    {
        // Clip TIDs
        $tids = FormUtil::getPassedValue('ClipTIDs', array(), 'POST');

        $this->setPluginVar('TIDs', array_keys($tids));

        // Additional arguments
        $args = FormUtil::getPassedValue('ClipArgs', array(), 'POST');

        $this->setPluginVar('Args', $args);
    }

Add a template called as your plugin file is called to templates/plugin_config. In this case, it looks like this:

{assign var='pubtypes' value=$plugin_parameters.Newsletter_NewsletterPlugin_Clip.param.PubTypes}
{assign var='pageargs' value=$plugin_parameters.Newsletter_NewsletterPlugin_Clip.param.Args}

{assign var='j' value=1}
{foreach from=$pubtypes key='tid' item='pubtype'}
<hr />
<div class="z-formrow">
    <label for="plugin_{$i}_enable_{$j}">{$pubtype.title|safehtml}</label>
    <input id="plugin_{$i}_enable_{$j}" type="checkbox" name="ClipTIDs[{$tid}]" value="1" {if $pubtype.nwactive}checked="checked"{/if} />
</div>
<div id="plugin_{$i}_suboption_{$j}">
    <div class="z-formrow">
        <label for="ClipArgs_{$tid}_template">{gt text='Template'}</label>
        <input type="text" value="{$pageargs.$tid.template|default:''}" name="ClipArgs[{$tid}][template]" id="ClipArgs_{$tid}_template" maxlength="100" size="30">
        <span class="z-formnote z-sub">{gt text='Only for HTML Newsletter'}</span>
    </div>
    <div class="z-formrow">
        <label for="ClipArgs_{$tid}_itemsperpage">{gt text='Number of publications'}</label>
        <input type="text" value="{$pageargs.$tid.itemsperpage|default:''}" name="ClipArgs[{$tid}][itemsperpage]" id="ClipArgs_{$tid}_itemsperpage" maxlength="5" size="5">
    </div>
    <div class="z-formrow">
        <label for="ClipArgs_{$tid}_orderby">{gt text='Order by'}</label>
        <input type="text" value="{$pageargs.$tid.orderby|default:''}" name="ClipArgs[{$tid}][orderby]" id="ClipArgs_{$tid}_orderby" maxlength="255" size="30">
    </div>
    <div class="z-formrow">
        <label for="ClipArgs_{$tid}_filter">{gt text='Filter string'}</label>
        <input type="text" value="{$pageargs.$tid.filter|default:''}" name="ClipArgs[{$tid}][filter]" id="ClipArgs_{$tid}_filter" maxlength="512" size="30">
    </div>
</div>
{assign var='j' value=$j+1}
{foreachelse}
    <div class="z-warningmsg">{gt text='No publication types found.'}</div>
{/foreach}

The following functions help you to save your configuration:

    /**
     * The setPluginVar method sets a Newsletter plugin variable.
     *
     * @param string $name    The name of the variable.
     * @param string $value   The value of the variable.
     *
     * @return boolean True if successful, false otherwise.
     *
     * @note You can choose any name you want, your variable will be automatically prefixed.
     * @warning Protected variable names:\n
     * - Settings
     * - nItems
     * - Settings0
     * - Settings1
     */
    final protected function setPluginVar($name, $value)

    /**
     * The setPluginVars method sets multiple Newsletter plugin variables.
     *
     * @param array $array    The variables array
     *
     * @note You can choose any name you want, your variable will be automatically prefixed.
     * @warning Protected variable names:\n
     * - Settings
     * - nItems
     * - Settings0
     * - Settings1
     */
    final protected function setPluginVars($array)
    
    /**
     * The getPluginVar method gets a Newsletter plugin variable.
     *
     * @param string  $name    The name of the variable.
     * @param boolean $default The value to return if the requested modvar is not set.
     *
     * @return string Newsletter plugin variable value
     */
    final protected function getPluginVar($name, $default=null)

    /**
     * The getPluginVars method gets multiple Newsletter plugin variables.
     */
    final protected function getPluginVars()

    /**
     * The delPluginVar method deletes a Newsletter plugin variable.
     *
     * Delete a Newsletter plugin module variable.
     *
     * @param string $name    The name of the variable.
     *
     * @return boolean True if successful, false otherwise.
     */
    final protected function delPluginVar($name)

    /**
     * The delPluginVars method deletes ALL Newsletter plugin variables.
     */
    final protected function delPluginVars()
Add a custom footer
Add a custom sidebar
Clone this wiki locally