AppThemes provides an API (Application Programming Interface) which enables developers to extend our themes without modifying the core code. This can be achieved by writing plugins or additional functions that “hook” into different areas of the theme.

Each theme includes it’s own custom API in addition to the “AppThemes General API” which are shared hooks used across all themes.

If you are familiar with the WordPress API (also known as filters, actions, and hooks), then you’ll quickly understand how the AppThemes API can be used.

Note: This information applies to AppThemes released after July 10th, 2011. Any theme version prior to this date did not yet have the API enabled yet.

What are Hooks?

Hooks are defined in specific places throughout each theme so that your plugins or custom functions can ‘hook into’ AppThemes without modifying the core code. There are two different ways to invoke hooks which are called, actions and filters. The AppThemes API currently supports only action hooks although you can still of course use the WordPress API for core actions and filters.

View all the AppThemes action hooks which are included with each of our themes.

Actions

Actions are the hooks that the AppThemes API triggers at specific points during execution such as before the loop, after the footer, init, before comments, etc. Your plugin can respond to the event by executing a PHP function, which might do one or more of the following:

• Modify database data
• Send an email message
• Modify what is displayed in the browser screen

The basic steps to making this happen are:

1. Create the PHP function that should execute when the event occurs, in your plugin or functions.php file.
2. Hook to the action in AppThemes, by calling add_action()
3. Load the page that should trigger the action

Create an Action Callback

The first step in creating an action in your plugin or functions.php file is to create a PHP function with the intended functionality, which is named a ‘callback’.

For example, say you want to send yourself an email message whenever a blog post is viewed (silly example we know). You would create a function similar to the one below and place it in your plugin or functions.php file.

function email_me_on_blog_view() {
    $emailto = 'myemail@mydomain.com';
    wp_mail( $emailto, 'A blog post has been viewed.', 'This is the email body.' );
}
// hook into the correct action
add_action( 'appthemes_after_blog_loop', 'email_me_on_blog_view' );

Now anytime somebody views one of your blog posts, you will receive an email. This means the appthemes_after_blog_loop action was invoked.

Hook into AppThemes

You’ll notice after the function was defined above, the line below it uses add_action() to “hook” into the AppThemes appthemes_after_blog_loop function. Here’s the general syntax you’ll need to use when evoking a hook:

add_action ( 'hook_name', 'your_function_name', [priority], [accepted_args] );

where:

• hook_name – The name of an action hook provided by AppThemes, that tells what event your function should be associated with.
• your_function_name – The name of the function that you want to be executed following the event specified by hook_name. This can be a standard php function, a function present in the AppThemes core, or a function defined by you in the plugin file (such as ’email_friends’ defined above).
• priority – An optional integer argument that can be used to specify the order in which the functions associated with a particular action are executed (default: 10). Lower numbers correspond with earlier execution, and functions with the same priority are executed in the order in which they were added to the action.
• accepted_args – An optional integer argument defining how many arguments your function can accept (default 1), useful because some hooks can pass more than one argument to your function.

Removing Actions

In some cases, you may find that you want your plugin to disable one of the actions or filters built into AppThemes, or added by another plugin. You can do that by calling remove_action( 'action_hook', 'action_function' ).

For example, this code would prevent your JobRoller website from loading the default footer in the theme.

remove_action( 'appthemes_footer', 'jr_do_footer' );

Now you can build your own custom footer without touching the core code.

Note that if a hook was registered using a priority other than the default of 10, then you must also specify the priority in the call to remove_action(). Also note that in general, you shouldn’t remove anything unless you know what it does and why it does it — check the source code or documentation first just to be sure.

Admin Section Hooks

The AppThemes API isn’t limited to just front-end theme hooks. You can also extend your AppThemes into the admin back-end by creating your own admin pages and options. These are done by using admin hooks and are included with all our themes as well.

List of Action Hooks

See AppThemes Actions for a current list of default action hooks available in our themes.