2. Documentation
  3. Hooks

Hooks

Each hook trigger to all functions assigned on config.json for themes or plugins installed for current site. Some of this functions receive params to be customized in the function, for example: 

config.json

{
  title: "my plugin", 
  ...
  helpers: ["Plugins::MyPlugin::MainHelper"],
  hooks: {
   taxonomy_the_title: ["front_editor_taxonomy_the_title"]
  }
}

plugins/my_plugin/main_helper.rb

module Plugins::MyPlugin::MainHelper
   def front_editor_taxonomy_the_title(args)
     args[:title] += " - my_custom title" if args[:object].class.name == "PostType"
   end
end


All hooks available for the CMS are:

  Params  Description
THEMES    
on_inactive theme_model  Triggered when theme was uninstalled
on_active theme_model Triggered when theme was installed
on_theme_settings theme_model Triggered when settings are being saved. called after submit on admin->settings->site settings form.
This permit you to save your configurations for the current theme.
theme_options {links: []} Triggered for current installed theme when listing themes on admin panel.
You can add your custom links into links attribute like this:
def my_theme_options(args)
  args[:links] << link_to("My link", root_url)
end
This will add link options for current theme.
     
CONTENTS    
post_the_title {title: current_title, post: object}

Triggered when model_content.the_title was called

title: current content title

post: current content model
post_the_excerpt

{content: (excerpt.present? ? excerpt : object.content.truncate(qty_chars)),

post: object}

Triggered when model_content.the_excerpt was called

content: current excerpt generated

post: current content model
 post_the_content {content: object.content, post: object} 

Triggered when model_content.the_content was called

content: current content

post: current content model
post_the_thumb {image: "", post: object} Triggered when model_content.the_thumb was called

image: current image url

post: current content model
 post_can_visit {flag: true, post: object}  Triggered when model_content.can_visit? was called. This is used for visitor validations.

flag: true/false. false => can't be visited

post: current content model
filter_post {active_record: active_record}  

Triggered to filter collection of contents for current visitor for category page, post_type and post_tag.

active_record: current content records to be shown in the list.

Note: Above is for a single model.
 taxonomy_the_title {title: object.name, object: object}

Triggered when a model.the_title was called. This is only for models inherit from taxonomy, like: post, post_type, post_tag, category.

You can detect the model like this: args[:object].class.name == "PostType"
 taxonomy_the_content {content: object.description object: object}  Triggered when a model.the_content was called.
taxonomy_the_excerpt  {content: object.description.truncate(qty_chars), object: object}  Triggered when a model.the_excerpt was called. 
 on_render  {context: context, options: options, render: true, caller: self}  triggered before to render a template
     
 PLUGINS    
on_active plugin_model Triggered when plugin was activated
on_inactive plugin_model Triggered when plugin was inactivated
on_upgrade plugin_model Triggered when the plugin is being upgraded for a new version.
Sample:
def my_plugin_on_upgrade(plugin)
  case plugin.installed_version
    when "0.1"
      unless ActiveRecord::Base.connection.table_exists? 'my_new_table'
        ActiveRecord::Base.connection.create_table :my_new_table do |t|
          # new table fields
        end
      end
    when "0.2"
      unless column_exists?(:my_new_table, :my_attr2)
        ActiveRecord::Base.connection.add_column :my_new_table, :my_attr2, :string
      end
  end
end
 
plugin_options  {links: []} Triggered for installed plugins when listing on admin.
You can add your custom links into links attribute like this:
def my_plugin_options(args)
  args[:links] << link_to("My link", root_url)
end
This will add link options for this plugin.
     
ADMIN    
admin_before_load  

Triggered for each request when the admin module is being accessed
 admin_after_load  

Triggered for each request when the admin module was accessed
list_post_extra_columns {post_type: @post_type, content: "", from_body: false}

Triggered when the content list is loading. Permit you to add custom columns in the table (header).

from_body: true => for render table body columns

from_body: false => for render table header columns

content: custom variable where you can add your custom html
list_category {categories: @categories, post_type: @post_type}

Triggered when the categories list is loading. Permit you to customize results.

categories: collection of categories

post_type: current post_type model
category_form {html: "", category: category_model}

Permit to add custom html content into category form.
Sample:

def my_hook_for_category_form(args)
  args[:html] = "<div> <label>My label</label><br> <input name='my_custom_input' value='#{params[:category].custom_value}' /> </div>"
end
category_list_header {html: "", post_type: Post_type model}

Permit to add custom columns for the category list table (table header)
category_list_body {html: "",  post_type: post_type model, category: Category model} Permit to add custom columns for the category list table (table body)
 elfinder {dirname: "media/<current_site.id>"} 

 Triggered when the file manager is loading (list or uploads). Permit you to customize location directory.

dirname: simple path located in public/
list_post {posts: @posts, post_type: @post_type, btns: @btns, all_posts: posts_all, render: 'index' }

Triggered when the content list is loading. Permit you to customize records, tabs (buttons).

posts: collection of contents to be shown in the list

post_type: current post_type

btns: array of tabs, sample: published: "Published (#{args[:

posts_all].where(status: "published").size})

all_posts: the same as posts

render: current template to be rendered
new_post {post: @post, post_type: @post_type, extra_settings: @post_form_extra_settings, render: "form"}

Triggered to show the form for a new content.

post: new content model

post_type: current post_type

extra_settings: array of custom html to be shown on sidebar

render: current template to be rendered 
 create_post {post: @post, post_type: @post_type} 

Triggered when a new content is being registered. Permit to add extra validations.

post: current content to be saved

post_type: current post_type
 created_post  {post: @post, post_type: @post_type} 

 Triggered after a new content was registered.

post: current content saved

post_type: current post_type
edit_post {post: @post, post_type: @post_type, extra_settings: @post_form_extra_settings, render: "form"}

Triggered to show the form for edit a content.

post: new content model

post_type: current post_type

extra_settings: array of custom html to be shown on sidebar

render: current template to be rendered 
 update_post {post: @post, post_type: @post_type}  

Triggered when a content is being updated. Permit to add extra validations.

post: current content to be updated

post_type: current post_type
 updated_post  {post: @post, post_type: @post_type}  Triggered after a content was updated.

post: current content updated

post_type: current post_type
destroy_post {post: @post, post_type: @post_type, flag: true}

Triggered when a content is being destroyed. Permit to add extra validations.

post: current content to be destroyed

post_type: current post_type

flag: true/false, indicate if content can be destroyed or not
destroyed_post {post: @post, post_type: @post_type}

Triggered when a content was destroyed. 

post: current content to be updated

post_type: current post_type
sitemap {site: site, eval: ""}

Triggered when a sitemap is being generated.

site: current site

eval: extra routes to add into sitemap, see docs here
     
 APP (GLOBAL)    
app_before_load   Triggered for each request when the app is being accessed
app_after_load   Triggered for each request when the app was accessed
cron {site: Site object, eval: ""}

Triggered on server starting (need restart server).

Permit you to add cron jobs in your project.
site: Current site object
eval: Callback function to eval as cronjob
Sample: 

def my_hook_for_cron(args)
  args[:eval] = lambda{|args|
     job_id = $scheduler.cron '00 04 * * *' do
       puts "it is 4 am"
     end
   }
end

More info here.
email {template_name, layout_name, mail_data, files}

Permit to customize the default values of email params:
template_name: (String) Name of the template to be rendered (default: "html_mailer/mailer.html.erb")
layout_name: (String) Name of the layout to be rendered (default: "mailer.html.erb")
mail_data: (Hash) This is a Hash that contain current email params, such us: to, from, subject, ...
files: (Array) This is an array of files to be attached in the email
format: (String) This is the format of the email, if this is empty, this will send a simple inline text (default html)
     
FRONTEND    
front_before_load  

Triggered for each request when the frontend module is being accessed
front_after_load  

Triggered for each request when the frontend module was accessed
on_render_index {layout: default_layout, render: "nil", custom: false}

Triggered for access into home page (index)

you can change the layout and set your custom template file on render attr.

If you change any data of the params, you must to change the custom into true to apply changes.
on_render_category {category: @category, layout: default_layout, render: "category"}

Triggered when a category is being accessed.

category: current category

layout: current layout to be rendered

render: current template to be rendered
on_render_post_type {post_type: @post_type, layout: default_layout, render: "post_type"}

Triggered when a post type is being accessed.

post_type: current post_type

layout: current layout to be rendered

render: current template to be rendered
on_render_post_tag {post_tag: @post_tag, layout: default_layout, render: "post_tag"}

Triggered when a post tag is being accessed.

post_tag: current post_tag

layout: current layout to be rendered

render: current template to be rendered
on_render_search {layout: current_layout, render: "search"}

Triggered to execute search request.

layout: current layout to be rendered

render: current template to be rendered
on_ajax {render_file: nil, render_text: "", layout: current_layout }

Triggered to execute ajax requests.

layout: nil

render_file: current template to be rendered

render_text: answer for ajax request
on_render_post {post: @post, post_type: @post_type, layout: current_layout, render: r_file}

Triggered when a post (content) is being accessed.

post_type: Post_type of the current content

layout: current layout to be rendered

render: current template to be rendered

post: current content model
seo {seo_data, object}

Triggered when SEO attributes are created.
You can customize or add extra attributes for SEO by this hook.
Receive a Hash with:
- seo_data: Hash with current seo attributes
- object: current model for current page.
     - home page: current_site
     - category page: Category
     - posttype page: Posttype
     - posttag page: Posttag
     - post page: Post

To see all attributes supported, visit here.
Sample:

def my_custom_seo(args)
  args[:seo_data][:title] = "#{current_site.the_title} | #{args[:object].the_title}" unless is_home?
  args[:seo_data][:twitter][:site] = current_site.the_field("twitter_username")# Note: you need to add field
end

 

 

    
SESSIONS    
session_before_load   Triggered when the request is for access to session module (before load the action): login, verify_login, logout, logout, forgot....
sessions_after_load   Triggered when the request is for access to session module (after load the action): login, verify_login, logout, logout, forgot....
user_before_register  {user, params} Triggered before user was registered.
user: User model saved
params: (Hash) params received from request
user_after_register {user, message, redirect_url } Triggered after user was registered.
user: User model saved
message: String (Message after created) 
redirect_url: (String) url to redirect after creation
user_register_form {html} print custom html content in register form
user_login_form {html} print custom html content in login form
user_before_login {user, params, password, captcha_validate} Triggered after login form was submitted.
user: User model with username=params[username]
params: request params
password: password received
captcha_validate: boolean