Exchange Code Snippets

From IThemes Codex
(Difference between revisions)
Jump to: navigation, search
m (Step One: Extend the target class)
 
(One intermediate revision by one user not shown)
Line 1: Line 1:
 
Here you'll find various snippets of code from iThemes Exchange.
 
Here you'll find various snippets of code from iThemes Exchange.
  
 +
== Extending the Theme API to include a custom tag ==
 +
<br />
 +
This process takes 2 steps:
 +
* Creating a new Class to Extend the one you are targeting
 +
* Adding a filter to let the original class know about new tags
 +
<br />
 +
In this example we will be adding a new argument to the product class. The product class comes with many default tags like title, description, and base_price for example:
 +
* it_exchange( 'product', 'title' );
 +
* it_exchange( 'product, 'description' );
 +
* it_exchange( 'product', 'base_price' );
 +
<br />
 +
We will be adding a new tag called custom. You will use it like this: it_exchange( 'product', 'custom' );
 +
 +
==== Step One: Extend the target class ====
 +
Use the following code to create a new class that includes the code needed for your custom tag:
 +
 +
<pre class="brush: php gutter:false">
 +
<?php
 +
/**
 +
* This class extends the Product THEME API
 +
*
 +
* @since 1.0.0
 +
*/
 +
class IT_Theme_API_Product_Extension_For_Custom_Add_On extends IT_Theme_API_Product {
 +
 +
    /**
 +
    * Create a Constructor that calls the parent custructor
 +
    *
 +
    * @since 1.0.0
 +
    */
 +
    function IT_Theme_API_Product_Extension_For_Custom_Addon() {
 +
        parent::__construct();
 +
    } 
 +
 +
    /**
 +
    * Create your tag function that returns your custom value.
 +
    *
 +
    * It always needs to return. You can also add some code to support the has and supports prefixes:
 +
    * it_exchange( 'product', 'custom' ); // This will echo your returned result. Our API takes care of this.
 +
    * it_exchange( 'product', 'get-custom' ); // This will return your result
 +
    * it_exchange( 'product', 'supports-custom' ); // Needs a boolean returned from your function
 +
    * it_exchange( 'product', 'has-custom' ); // Needs a boolean returned from your function
 +
    *
 +
    * @since 1.0.0
 +
    */
 +
    function custom( $options=array() ) {
 +
 +
        // Return boolean if supports flag was set.
 +
        if ( $options['supports'] )
 +
            return true;
 +
 +
        // Return boolean if has flag was set
 +
        if ( $options['has'] )
 +
            return true;
 +
 +
        // This is where your code goes to return your output.
 +
        return 'The result of your logic returns the tag';
 +
    } 
 +
}
 +
</pre>
 +
 +
That should do it. You can now use it_exchange( 'product', 'custom' ); in your template files
 +
<br />
 +
 +
==== Step Two: Tell our API that your new tag exists for the Product class ====
 +
<pre class="brush: php gutter:false">
 +
/**
 +
* Extend the product theme api to include new tags
 +
*
 +
* @since 1.0.0
 +
*/
 +
function it_exchange_addon_custom_extend_product_theme_api( $result, $class, $tag ){
 +
    // We don't want this happening in the admin
 +
    if ( is_admin() )
 +
        return;
 +
 +
    // We only want to do this if the current class is the product class and the tag is custom
 +
    // This means our code will only happen when it_exchange( 'product', 'custom' ) is called.
 +
    // If you have multiple tags, you can do all that logic in here as well
 +
    if ( 'IT_Theme_API_Product'== $class && 'custom' == $tag ) {
 +
        // Include the file with the class
 +
        include_once( '/path/to/our/file/with/class/from/step/one.php' );
 +
        // Init an object from the class
 +
        $IT_Theme_API_Product_Extension_For_Custom = new IT_Theme_API_Product_Extension_For_Custom();
 +
        // Return a callback to your function for the tag
 +
        $result = array( $IT_Theme_API_Product_Extension_For_Custom, 'custom' );
 +
    }   
 +
    return $result;
 +
}
 +
add_filter( 'it_exchange_theme_api_get_extended_tag_functions', 'it_exchange_addon_custom_extend_product_theme_api', 10, 3 );
 +
</pre>
 +
<br />
 
== Adding a field to the registration form from an add-on ==
 
== Adding a field to the registration form from an add-on ==
  

Latest revision as of 07:54, June 12, 2014

Here you'll find various snippets of code from iThemes Exchange.

Contents

Extending the Theme API to include a custom tag


This process takes 2 steps:

  • Creating a new Class to Extend the one you are targeting
  • Adding a filter to let the original class know about new tags


In this example we will be adding a new argument to the product class. The product class comes with many default tags like title, description, and base_price for example:

  • it_exchange( 'product', 'title' );
  • it_exchange( 'product, 'description' );
  • it_exchange( 'product', 'base_price' );


We will be adding a new tag called custom. You will use it like this: it_exchange( 'product', 'custom' );

Step One: Extend the target class

Use the following code to create a new class that includes the code needed for your custom tag:

<?php
/**
 * This class extends the Product THEME API
 *
 * @since 1.0.0
*/
class IT_Theme_API_Product_Extension_For_Custom_Add_On extends IT_Theme_API_Product {

    /** 
     * Create a Constructor that calls the parent custructor
     *
     * @since 1.0.0
    */
    function IT_Theme_API_Product_Extension_For_Custom_Addon() {
        parent::__construct();
    }   

    /** 
     * Create your tag function that returns your custom value.
     *
     * It always needs to return. You can also add some code to support the has and supports prefixes:
     * it_exchange( 'product', 'custom' ); // This will echo your returned result. Our API takes care of this.
     * it_exchange( 'product', 'get-custom' ); // This will return your result
     * it_exchange( 'product', 'supports-custom' ); // Needs a boolean returned from your function
     * it_exchange( 'product', 'has-custom' ); // Needs a boolean returned from your function
     *
     * @since 1.0.0
    */
    function custom( $options=array() ) { 

        // Return boolean if supports flag was set.
        if ( $options['supports'] )
            return true;

        // Return boolean if has flag was set
        if ( $options['has'] )
            return true;

        // This is where your code goes to return your output.
        return 'The result of your logic returns the tag';
    }   
}

That should do it. You can now use it_exchange( 'product', 'custom' ); in your template files

Step Two: Tell our API that your new tag exists for the Product class

/**
 * Extend the product theme api to include new tags
 *
 * @since 1.0.0
*/
function it_exchange_addon_custom_extend_product_theme_api( $result, $class, $tag ){
    // We don't want this happening in the admin
    if ( is_admin() )
        return;

    // We only want to do this if the current class is the product class and the tag is custom
    // This means our code will only happen when it_exchange( 'product', 'custom' ) is called.
    // If you have multiple tags, you can do all that logic in here as well
    if ( 'IT_Theme_API_Product'== $class && 'custom' == $tag ) {
        // Include the file with the class
        include_once( '/path/to/our/file/with/class/from/step/one.php' );
        // Init an object from the class
        $IT_Theme_API_Product_Extension_For_Custom = new IT_Theme_API_Product_Extension_For_Custom();
        // Return a callback to your function for the tag
        $result = array( $IT_Theme_API_Product_Extension_For_Custom, 'custom' );
    }    
    return $result;
}
add_filter( 'it_exchange_theme_api_get_extended_tag_functions', 'it_exchange_addon_custom_extend_product_theme_api', 10, 3 ); 


Adding a field to the registration form from an add-on

Requires Exchange 1.1.0


This process takes 3 steps:

  • Adding the template part to the registration form
  • Creating a template file in your add-on
  • Registering that template directory with Exchange


Step One: Add the field to the Registration Form’s field array

The registration form is generated by looping through an array of fields and pulling in a template part for each field. Add a filter to your add-on that pulls in the existing fields and adds your custom field to the array:

/**
 * This function adds our registration field to the list of fields included in the content-registration template part
 *
 * @since x.x.x
 *
 * @param array $fields existing fields
 * @return array
*/
function my_addon_add_field_to_content_registration_template_part( $fields ) { 

    /** 
     * We want to add our field right before the save button
     * 1) Find the save button
     * 2) Splice our value in right before the save button
     * 3) In the event that the save button wasn't found, just tack onto the end
    */

    $save_key = array_search( 'save', $fields );
    if ( false === $save_key )
        $fields[] = 'my-addon-field';
    else
        array_splice( $fields, $save_key, 0, array( 'my-addon-field' ) );

    return $fields;
}
add_filter( 'it_exchange_get_content_registration_field_details', 'my_addon_add_field_to_content_registration_template_part' );


Step Two: Create the template file in you’re add-on.

You’ll want to duplicate the directory structure found within core Exchange for the content-registration template-part: /your-addon/templates/content-registration/details/my-addon-field.php


Step Three: Register your template folder with the Exchange template part API

/**
 * This function tells Exchange to look in a directory in your add_on for template parts
 *
 * @since x.x.x
 *
 * @param array $template_paths existing template paths. Exchange core paths will be added after this filter.
 * @param array $template_names the template part names we're looking for right now.
 * @return array
*/
function my_addon_add_template_directory( $template_paths, $template_names ) { 

    /** 
     * Use the template_names array to target a specific template part you want to add
     * In this example, we're adding the following template part: content-registration/details/my-addon-field.php
     * So we're going to only add our templates directory if Exchange is looking for that part.
    */
    if ( ! in_array( 'content-registration/details/my-addon-field.php', $template_names ) ) 
        return $template_paths;

    /** 
     * If we are looking for the my-addon-field template part, go ahead and add our add_ons directory to the list
     * No trailing slash
    */
    $template_paths[] = dirname( __FILE__ ) . '/templates';

    return $template_paths;
}
add_filter( 'it_exchange_possible_template_paths', 'my_addon_add_template_directory', 10, 2 );



← Back to Exchange Codex Home

Personal tools
Namespaces
Variants
Actions
iThemes Codex
Codex Navigation
Toolbox