Clone this wiki locally
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.
:content_formview hook - takes place in the
formpartial to allow plugins to add fields to the form.
:content_detailsview hook - takes place in the
contents#showview and provides plugins the opportunity to add details to the side of the content.
:tile_labelsview hook - takes place in the
content_tilepartial to allow plugins to add to the icons displayed on the content tiles.
:update_paramscontroller hook - takes place in the
content_update_paramsmethod 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.
:showcontroller hook - takes place in the
screens#showbefore rendering and auth. @screen is available.
:screen_detailsview hook - takes place in the
screen#showview and inserts code into the right-hand sidebar.
:destroycontroller hook - takes place in the
screen#destroymethod after auth, and is useful for deleteing related records from your plugin.
:showcontroller hook - takes place in the
templates#showbefore rendering and auth. @template is available.
:sidebarview hook - takes place in the
templates#showview and inserts code into the right-hand sidebar.
:template_detailsview hook - takes place in the
template#showview and inserts code into the bottom area under the author details.
Dynamic Content Model
:alter_contenthook - 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.
:filter_contentshook - 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).
:is_deletablefor influencing whether or not your plugin has a dependency that should prevent the deletion of a template. If the @deletable value is true, your
:aftercallback should set it false, if needed.
:screen_dependenciesfor 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
:aftercallback. The screens are listed in the disabled delete button's tip.
:indexcontroller hook - takes place in the Frontend::ContentsController#index and is for influencing the content that will be displayed on the frontend screens. In the
:aftercallback, 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 :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 %>
: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.