Skip to content

Plugin Hooks

Marvin Frederickson edited this page Dec 11, 2015 · 11 revisions

Hooks are a Concerto feature that allows plugins to integrate with the frontend user interface. The integration may be as simple as adding a link to the plugin from a relevant view in Concerto, or involve more complicated data display and interaction.

There are two types of hooks: controller hooks and view hooks. Typically, these will be paired so that the controller hook will fetch any needed data, and the view hook can display that data. The code in the hooks always executes in the context of the main Concerto Application.

There are not many hooks in Concerto yet, but we will be adding them in places where it seems like they will be needed for plugins.

Existing Hooks

Contents Controller

  • :content_form view hook - takes place in the form partial to allow plugins to add fields to the form.
  • :content_details view hook - takes place in the contents#show view and provides plugins the opportunity to add details to the side of the content.
  • :tile_labels view hook - takes place in the content_tile partial to allow plugins to add to the icons displayed on the content tiles.
  • :update_params controller hook - takes place in the content_update_params method to allow plugins to modify the strong parameters to include any additional fields they are using. @content_sym (the symbol of the content being updated, and @attributes (the permitted attributes) are available.

Screens Controller

  • :show controller hook - takes place in the screens#show before rendering and auth. @screen is available.
  • :screen_details view hook - takes place in the screen#show view and inserts code into the right-hand sidebar.
  • :destroy controller hook - takes place in the screen#destroy method after auth, and is useful for deleteing related records from your plugin.

Templates Controller

  • :show controller hook - takes place in the templates#show before rendering and auth. @template is available.
  • :sidebar view hook - takes place in the templates#show view and inserts code into the right-hand sidebar.
  • :template_details view hook - takes place in the template#show view and inserts code into the bottom area under the author details.

Dynamic Content Model

  • :alter_content hook - takes place in the refresh_content method and is used when a plugin needs to alter the dynamically generated content. For example, the concerto_content_scheduling plugin needed to make sure that the schedule that was specified for the parent RSS item applied to all of the children RSS items, so it sets the extra data config item "schedule_info" on each child item. The newly built content that is being iterated through is available in @content and the attributes to be assigned to the new child content item are in @new_attributes.

Subscription Model

  • :filter_contents hook - takes place in the contents method and is used when a plugin has a need to influence the contents that are returned for a subscription (perhaps to alter what type of contents are returned to the frontend for a specific subscription).

Template Model

  • :is_deletable for influencing whether or not your plugin has a dependency that should prevent the deletion of a template. If the @deletable value is true, your :after callback should set it false, if needed.
  • :screen_dependencies for your plugin to indicate which screens this template is using so those screens can be reported as blocking the delete. Add your screen model instances to @dependencies in your :after callback. The screens are listed in the disabled delete button's tip.

Frontend::ContentsController

  • :index controller hook - takes place in the Frontend::ContentsController#index and is for influencing the content that will be displayed on the frontend screens. In the :after callback, the @content variable is available and can be reset to the contents you want rendered. The auth! call is made after your callback returns. @screen, @field, and @subscriptions are available.

If you need a hook for a particular application, submit an Issue to this project.

Defining Hooks in Concerto

Defining controller hooks

Controller hooks sometimes correspond to actions, but they don't have to. Names are arbitrary, and there can be more than one per action/method. Further, the same hook could be called in multiple actions (for example if they share a partial).

At the top of the controller, inside the class declaration, where before_filter and the like would normally go, add the following two lines, where :show is the name of your new callback. If you have more than one callback in the controller, you can just put a comma-separated list after define_callbacks.

  define_callbacks :show # controller callback for 'show' action
  ConcertoPlugin.install_callbacks(self) # Get the callbacks from plugins

Next, trigger the callback in the action where you would like it. Typically, this will be after fetching instance variables, so that the plugin can read them. Make sure it is before rendering, though!

    run_callbacks :show # Run plugin hooks

Defining View Hooks

These are even easier. In your view or partial, just add the following:

    <%= ConcertoPlugin.render_view_hook self, :screen_details %>

Replace :screen_details with your new hook name. Hook names need to be unique within each controller (unless you want the same code to run in both places), but not globally.

Hooking in from a Plugin

For details on the plugin side of things, see the Plugin Development page.

It is important to note again that the Plugin hooks execute in the context of the main application, so it will be necessary to explicitly specify the routing helper or namespace when referring to things provided by the plugin. See the above link for more details.

Something went wrong with that request. Please try again.