Skip to main content

Hooks

Because PMACS Frontend now provides application.html (among other layouts and views) to your application, there is certain information that the gem relies on its host app to provide to it. What follows is a list of hooks which allow app developers to provide data to PMACS Frontend before or during render-time. The gem is designed to function even if no hooks are used but some (such as the application_title) are, of course, recommended.

These hooks can be subdivided into two different types:

Standard (3-Option) Hooks

For each of these layout hooks, you can insert your content in 1 of 3 ways:

  • using content_for in the view layer
  • defining a helper method in the controller or helper layers
  • setting the value in the PmacsFrontend configuration block from the initializer

NOTE: this is true for every option except the page_title and page_subtitle options, which make no sense as global values.

These 3 mechanisms for setting a layout option are hierarchically ordered. If you use content_for to define the application_subtitle, that value will override any value you set using a helper method. So, the order of precedence is:

content_for > helper method > gem configuration.

Examples

Setting a hook in the PmacsFrontend configuration block

application_title, which is unlikely to change from page to page, should probably be set in the PmacsFrontend initializer:

# config/initializers/pmacs-frontend.rb

PmacsFrontend.configure do |config|
  config.application_title = 'My Pmacs App'
end

Setting a hook in the Controller/Helper Layers

If your application_title needed to be overwritten for the views associated with a particular controller, you could override what was set in the PmacsFrontend configuration block using the hierarchy of the PMACS Frontend hooks.

# app/controllers/my_particular_controller.rb

class MyParticularController < ApplicationController
  helper_method :application_title

  def index; end

  def application_title
    'App Title With Priority'
  end
end

Now, when an action from this Controller is called, PMACS Frontend will overwrite your previous application_title with this new one.

Setting a hook in the View Layer with content_for

Hooks can also be inserted directly into views using content_for. This is quite straightforward, as in this example:

// app/views/my_resource/index.html.erb

<% content_for(:application_subtitle, 'Admin Dashboard') %>

Setting a hook with content_for is the highest priority a hook can have. The example above would overwrite an application_subtitle set in either a view helper or a PmacsFrontend configuration block.

Note: content_for should only be used with the Standard (3-Option) Hooks. Hooks with Specialized Setters should use their custom setters.

Hooks With Specialized Setters

  • app_navigation_links
  • force_app_navigation_state
  • header_actions
  • page_navigation_links

These hooks are similar to the Standard (3-Option) Hooks, in that they can be set in the same three ways. But content_for should not but used to set these, though it technically could be. Each of these hooks is providing information of a more complex structure and is therefor best set with its custom setter method.