Hooks

Hooks are functions that listen for specific process where you can customize the normal functionality of Camaleon CMS. This customization can be:

  • Customize results
  • Load custom assets
  • Load custom template/layout
  • Add custom content in the HTML view
  • ....

To use a hook, you need to add your hook key in your config.json, sample:

{
  "title": "My Plugin",
  ...
... "helpers": [ "Plugins::MyPlugin::MainHelper" ], "hooks": { "on_active": [ "my_plugin_on_active" ], "on_inactive": [ "my_plugin_on_inactive" ], "on_upgrade": [ "my_plugin_on_upgrade" ] //here you can add all your hooks (read documentation) } }

on_active: name or key of hook, that accept an array of listeners.
my_plugin_on_active: function that listen this hook, i.e: you need to create the function "my_plugin_on_active" in your helper "Plugins::MyPlugin::MainHelper".
Note: Don't forget to restart your server after any change in your config file.

Sample: Here

These are the hooks supported by Camaleon CMS:

  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
 trashed_post {post: @post, post_type: @post_type} Triggered when a post is moved to the trash.
post: The post being saved
post_type: The post's post_type
restored_post {post: @post, post_type: @post_type} Triggered when a post is restored from trash.
post: The post being saved
     
 PLUGINS    
on_active plugin_model Triggered when the current plugin was activated
on_inactive plugin_model Triggered when the current plugin was inactivated
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 in the section installed plugins list.
front_cache_reading_cache {data: String} Triggered after reading cache content. Permit to customize cache value
front_cache_writing_cache {data: String} Triggered before saving cache content. Permit to customized cache value
plugin_after_uninstall {plugin: PluginModel} Triggered after any plugin was uninstalled
plugin_after_install {plugin: PluginModel} Triggered after any plugin was installed
plugin_after_upgrade {plugin: PluginModel} Triggered after any plugin was upgraded
plugin_after_destroy {plugin: PluginModel} Triggered after any plugin was destroyed (disabled for now)
     
     
     
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)
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

post_get_list_templates {tempates: (Array), post_type: post_type}

Permit to add custom templates in the dropdown of templates for post editor.

post_get_list_layouts {layouts: (Array), post_type: post_type}

Permit to add custom layouts in the dropdown of layouts for post editor.

create_post_draft {post: @post_draft, post_type: @post_type}

Triggered before save a new post draft.

created_post_draft {post: @post_draft, post_type: @post_type}

Triggered after saved a new post draft.

update_post_draft {post: @post_draft, post_type: @post_type}

Triggered before update a post draft.

updated_post_draft {post: @post_draft, post_type: @post_type} Triggered after updated a post draft.
user_after_edited {user, message, params}

Triggered after user was updated

user_edit {user: @user, render: 'form' }

Triggered to show edit user form.

user_new {user: @user, render: 'form' }

Triggered to show new user form.

user_created {user}

Triggered after user was saved.

user_destroyed {user}

Triggered after user was destroyed.

available_user_roles_list {roles_list: (Hash of existent roles)}

Permit to add custom roles to be listed in editing roles form
Sample: args[:roles_list][:manager] << { key: 'my_role_key', label: "my_custom_permission", description: "lorem ipsum"}
authorize! :manage, :my_role_key
Sample permission for post_types:
http://camaleon.tuzitio.com/documentation/category/40756-uncategorized/custom-models.html

list_site {sites, render} Triggered to show sites list.
nav_menu_custom {custom_menus: {}, menu: @nav_menu} Permit to add custom menu items available to be selected in menus editor
on_external_menu {menu_item: (NavMenuItem), parsed_menu: (Hash)} Permit to customize or mark as current menu.
Sample parsed_menu: {link: "url of the link", name: "Text of the menu", type_menu: 'external', current: Boolean (true => is current menu, false => not current menu item)}

on_render_front_menu_item {menu_item: (NavMenuItem), parsed_menu: (Hash)} Permit to customize data of parsed menu item or skip menu item by assigning false into :parsed_menu
user_update_more_actions_form {html: ''} Permit to add custom options within user form
user_update_more_actions {html: ''} Permit to add custom options below of user form
 extra_custom_fields {fields: {}}

Permit to register custom field elements, sample:
http://camaleon.tuzitio.com/documentation/category/139779-examples/create-custom-field.html
Params:
fields: Hash of existent fields.
Each field has this structure:
key: (String, required)
label: (String, required)
options: (Hash) includes:
  - required (boolean if the field support required option)
  - multiple: (boolean if the field support multiple values)
  - default_value: (String) default value for the field
  - translate: (boolean) if the field permit to be translatable
  - multiple_options: (Hash) {label: (String), default: (String "radio | checkbox"), use_no_default: (Boolean)} permit to enter option values for multiple checkboxes or group of radios

  - extra_fields: (Array({item}, {item})) list of fields with following structure:
    type: (String) text_box | checkbox | text_area | select | radio
    key: (String) key of the extra field
    label: (String) label of the extra field
    description: (String) description of the extra field
    values: (Array(value, value, ..)) array of values with the following structure: {value: (value of the option), label: (String label of the option)}. only for extra fields with type select|radio.
Samples: 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
email_late {template_name, layout_name, mail_data, files, ...}

Permit to customize the email values before to delivery the email:
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)

on_uploader (args)

args =

{
server: (String) local | aws,
thumb: {w: (Integer), h: (Integer)},
aws_settings: { # only for AWS
region: (String),
access_key: (String),
secret_key: (String),
bucket: (String),
cloud_front: (String),
aws_file_upload_settings: lambda{|settings| settings },
aws_file_read_settings: lambda{|data, s3_file| data }
}
}

Permit to customize the uploder.
aws_file_upload_settings : permit to add your custom attributes for file_upload http://docs.aws.amazon.com/sdkforruby/api/Aws/S3/Object.html#upload_file-instance_method
aws_file_read_settings: permit to read custom attributes from aws file and add to file parsed object

before_upload (args)

Permit to customize the settings of the file before to upload.

on_uploader_resize {file: (String file path), w: (Integer), h: (Integer), w_offset: 0, h_offset: 0, resize: (Boolean), replace: (Boolean), gravity: :north_east}

Permit to customize the thumbnail generation.

     
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

front_default_layout {layout: (params[:cama_ajax_request].present? ? "cama_ajax" : 'index'), controller: controller}

Triggered to customize the layout for frontend. Default layout "index".

on_render_index {layout: default_layout, render: "index"}

Triggered for access into home page (index)

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_render_profile {user: @user, layout: layout_, render: "profile"}

Triggered on render user profile on frontend

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

on_render_sitemap

{layout: def_layout, render: "sitemap", custom: {}, format: , skip_post_ids: [], skip_posttype_ids: [], skip_cat_ids: [], skip_tag_ids: []}

triggered visiting http://localhost:3000/sitemap.xml
With hook "on_render_sitemap" you can
- skip post_types, categories, tags or posts
- you can change render file and layout
- you can add custom sitemap elements in the attr "custom", like: https://github.com/owen2345/camaleon-cms/issues/106#issuecomment-146232211
- you can customize your content for html or xml format 

on_render_robots

{layout, render}

Triggered to show http://localhost:3000/robots.txt

on_render_rss

{layout, render}

Triggered on http://localhost:3000/rss.rss

 draw_custom_assets {stylesheets: (Array), javascripts: (Array), js_html: (String), css_html: (String)} Permit to customize the render of assets changing the value of js_html or css_html using  stylesheets or javascripts values
     
SESSIONS    
session_before_load   Triggered when the request is for access to session module (before load the action): login, verify_login, logout, logout, forgot....
session_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, f: form} print custom html content in register form
user_login_form {html, f: form} print custom html content in login form
user_before_login {user: @user, params: params, password: data_user[:password], captcha_validate: captcha_validate, stop_process: false} Triggered after login form was submitted.
user: User model with username=params[username]
params: request params
password: password received
captcha_validate: boolean
after_login {user: @user, redirect_to: nil}

Triggered after login user. Also you can customize the redirect url after login

user_registered {user, redirect_url}

Triggered  after user was registered. Also permit to customize the redirect url after registered