Documentation - Advanced Plugin Helper¶

Encapsulate presentation logic and Redmine patch management in PORO

Table of contents
Documentation - Advanced Plugin Helper

The Advanced Plugin Helper plugin is a Redmine plugin for developers. It is helping to keep Rails helper and views light in favour of encapsulating presentation login in plain old ruby classes (PORO). It also provides a patch api to easily register Redmine patches for Redmine 4 or 5 as well as an exception notifier.

Plugin Features¶

The Advanced Plugin Helper addresses Redmine plugin developer seeking to write reusable and easy maintainable code.

Presenter API¶

Inherit presenter classes from AdvancedPluginHelper::BasePresenter.
Register the newly created presenter to be loaded with your plugin.

Patch API¶

Register your patch files to be loaded with your plugin under Redmine 4 or 5.
Apply custom modifications to be loaded with your plugin under Redmine 4 or 5.

Subclass associations¶

Allows to add superclass associations to subclasses when they are missing, see Rails Issue 20678

Exception notifier¶

Get notified via email when something went wrong in your Redmine instance.

Getting Started¶

This quick introduction shows you the most convenient way for trying out the plugin with your Redmine instance.

You need a running Redmine instance in order to install the plugin. If you need help with the installation, please refer to Redmine.org.

Downloading the plugin¶

Attention

Don't clone the default branch: For production you need to clone the master branch explicitly!

Navigate into the /plugins directory of your Redmine instance.

Download the latest version of this plugin and add it as advanced_plugin_helper folder into your plugin directory.

cd (REDMINE_ROOT_DIR)/plugins
git clone -b master https://github.com/xmera-circle/advanced_plugin_helper

Restart Redmine¶

Navigate into the root directoy of Redmine.

Run the restart Rake task. This will touch restart.txt in order to force Redmine's application server to restart and load
everything from scratch. This will register the new plugin.

cd (REDMINE_ROOT_DIR)
rake restart

Plugin Usage¶

Create a custom presenter class¶

First , you need a app/presenters directory in your plugin. When created it will be automatically added to Rails autoload_path when restarting Redmine.

Second , create a presenter class as subclass of AdvancedPluginHelper::BasePresenter like so:

module MyRedminePlugin
  class MyModelPresenter < AdvancedPluginHelper::BasePresenter
    presents :my_model  # you can use 'my_model' as any instance variable of your model
    
    def helper_method_for_my_model
      # method body here
    end
  end
end

The AdvancedPluginHelper::BasePresenter class supports:

Redmine::I18n for internationalization,
ActionView::Helpers.

Save the file as app/presenters/my_model_presenter.rb.

Third , register your presenter. This could be done in lib/my_redmine_plugin.rb

module MyRedminePlugin
  class << self
    def setup
      AdvancedPluginHelper::Presenter.register('MyRedminePlugin::MyModelPresenter', 'MyModel')
    end
  end
end

Fourth , make sure that MyRedminePlugin.setup is loaded when booting Redmine. For doing so, add this to your init.rb:

require File.expand_path('lib/my_redmine_plugin', __dir__)

Redmine::Plugin.register :my_redmine_plugin do
  name 'My Redmine Plugin'
  author '(your_name)'
  description '(plugin_description)'
  version '(current_version)'
  url '(plugin_url)'
  author_url '(your_github_profile)'

  requires_redmine version_or_higher: '4.2.0'
  requires_redmine_plugin :advanced_plugin_helper, version_or_higher: '0.2.0'
end

MyRedminePlugin.setup

Finally , in your view you can use your presenter like so:

<%= show(@my_model).helper_method_for_my_model %>

Of course, replace my_redmine_plugin and similar placeholder with your plugin name, class name, etc.

The AdvancedPluginHelper::PresentersHelper is added as helper to these classes by default:

ActionMailer::Base,
ApplicationController,
SettingsController,
ProjectsController,
QueriesController,
NewsController.

You can extend the list by adding your class to the array:

AdvancedPluginHelper.klasses << YourKlass

Register your Redmine patches¶

When you need to patch Redmine code you can register your patch in lib/my_redmine_plugin.rb:

module MyRedminePlugin
  class << self
    def setup
      AdvancedPluginHelper::Patch.register(data)
    end
    
    private

    def data
      { klass: Issue, patch: MyRedminePlugin::Extensions::IssuePatch, strategy: :include }
    end
  end
end

The strategy could be one of :include, :prepend, :helper.

Strategy	Recommendation
:include	when adding new methods
:prepend	when overriding existing methods
:helper	when adding a helper module

Apply other modifications¶

When you need to apply custom modifications, which does not require a patch file, you can do that with this command:

module MyRedminePlugin
  class << self
    def setup
      AdvancedPluginHelper::Patch.apply do
        # your code here
      end
    end
  end
end

IMPORTANT

Make sure that your code is idempotent since Rails/Redmine loads it several times during the apps boot process!

Subclass associations¶

When you have created a subclass and will try to add associations to the corresponding superclass, you will notice that the subclass won't have that associations. It will have the methods to access the association but you cannot call them. This is a bug in Rails since 2015 (see above).

In order to patch that behavior, you can register your subclass like below. This will create missing associations.

module MyRedminePlugin
  class << self
    def setup
      AdvancedPluginHelper::Associations.register(MySubclass)
    end
  end
end

Configure the exception notifier¶

# In config/additional_environment.rb:

require File.expand_path('plugins/advanced_plugin_helper/lib/advanced_plugin_helper/notifier', __dir__)
require File.expand_path('plugins/advanced_plugin_helper/lib/exception_notifier/custom_mail_notifier', __dir__)
require 'exception_notification/rails'

ExceptionNotification.configure do |config|
  if AdvancedPluginHelper::Notifier.email_delivery_enabled?
    config.add_notifier :custom_mail, AdvancedPluginHelper::Notifier.custom_mail
    config.error_grouping = AdvancedPluginHelper::Notifier.error_grouping
    config.ignore_if do |_exception, _options|
      AdvancedPluginHelper::Notifier.disabled?
    end
  end
end

Configuration with environment variables¶

In order to configure sender and recipients set the corresponding env vars:
DEFAULT_EXCEPTION_NOTIFIER_RECIPIENTS (default: nil)
EXCEPTION_NOTIFIER_SENDER (default: Setting.mail_from as set in Administration » Setting » Email notifications)
EXCEPTION_NOTIFIER_RECIPIENTS (default: nil)

You can also disable the notifier via EXCEPTION_NOTIFIER_DISABLED (default: false).

DEFAULT_EXCEPTION_NOTIFIER_RECIPIENTS and EXCEPTION_NOTIFIER_RECIPIENTS will be merged into a single list of recipients.

Configuration with class variables¶

DEFAULT_EXCEPTION_NOTIFIER_RECIPIENTS can be overridden with AdvancedPluginHelper::Notifier.default_exception_recipients=(your-comma-separated-list-of-recipients).

EXCEPTION_NOTIFIER_RECIPIENTS can be overridden with AdvancedPluginHelper::Notifier.custom_exception_recipients=(your-comma-separated-list-of-recipients).

EXCEPTION_NOTIFIER_DISABLED can be overridden with AdvancedPluginHelper::Notifier.disabled=(true-or-false)

Changelog¶

All notable changes to this plugin will be reported in the changelog.

License¶

This plugin program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.

Files (0)

Project

General

Profile

Advanced Plugin Helper

Wiki

Documentation - Advanced Plugin Helper¶

Plugin Features¶

Presenter API¶

Patch API¶

Subclass associations¶

Exception notifier¶

Getting Started¶

Downloading the plugin¶

Restart Redmine¶

Plugin Usage¶

Create a custom presenter class¶

Register your Redmine patches¶

Apply other modifications¶

Subclass associations¶

Configure the exception notifier¶

Configuration with environment variables¶

Configuration with class variables¶

Changelog¶

License¶