Simple Add-ons

Part I: Plugins

is.gd/j4EIoz

Isaac Raway (@airways, airways@mm.st)

MetaSushi / The Nerdery

Custom plugins - why?

• Instead of the query plugin
• Safer - escape queries
• More options for parsing output
• Easier to implement business logic
• Sometimes faster

Getting started

• Go to pkg.io and fill out the form (make sure you check the Plugin box)

Getting started

• Download the ZIP file and open your pi.*.php file
• Delete this comment header, this isn't EllisLab's plugin:

/**
 * ExpressionEngine - by EllisLab
 *
 * @package		ExpressionEngine
 * @author		ExpressionEngine Dev Team
 * @copyright	Copyright (c) 2003 - 2011, EllisLab, Inc.
 * @license		http://expressionengine.com/user_guide/license.html
 * @link		http://expressionengine.com
 * @since		Version 2.0
 * @filesource
 */
 
// ------------------------------------------------------------------------

Anatomy of a plugin

• Filename must match the package directory:

system/expressionengine/third_party/member_info/
system/expressionengine/third_party/member_info/pi.member_info.php
    

• Class name must match the package directory, with an initial uppercase letter:

class Member_info {
    

Anatomy of a plugin

• Before the class we have a meta data array:

$plugin_info = array(
    'pi_name'           => 'Member_info',
    'pi_version'        => '1.0',
    'pi_author'         => 'Isaac Raway',
    'pi_author_url'     => '',
    'pi_description'    => 'Gets member information for the supplied ID',
    'pi_usage'          => Member_info::usage(),
);
    

• This info appears in the Add-ons > Plugins list

Anatomy of a plugin

• The plugin class you get looks like this:

class Member_info {
    public function __construct()
    {
        $this->EE =& get_instance();
    }
    public static function usage()
    {
        // pkg.io uses ob_start, HEREDOC does the same thing, but it's shorter:
        return <<<END
How to call this plugin:
{exp:member_info:query member_id="something"}
{/exp:member_info:query}
END;
    }
}

    

Anatomy of a plugin

• The __construct() method is a PHP 5 constructor - this saves a copy of the global EE object so we can reference it later
• The usage() method is referenced by the meta data array:

$plugin_info = array(
    ...
    'pi_usage'          => Member_info::usage(),
);
    

And now the most important bullet point in the presentation:

• All other public methods are the names of our tags

Creating a tag

• Insert this method after the __construct() method:

public function query() {
}
    

• This creates a tag that looks like this:

{exp:member_info:query}
{/exp:member_info:query}
    

• member_info comes from the name of the package / class
• query comes from the name of the method

Creating a tag

• The six steps all plugins must take:

public function query() {
    // 1. Get params from fetch_param() - default value is FALSE
    // 2. Get the contents of the pair tag
    // 3. Setup a default response
    // 4. Run our query
    // 5. Parse results variables into the output
    // 6. Return the results as a string
}
    

Tag processing - step 1

// 1. Get params from fetch_param()
$requested_member_id = $this->EE->TMPL->fetch_param("member_id");
    

• If a param isn't set in the template, we will get FALSE instead
• If you want a different default you can send it as 2nd param:

$test = $this->EE->TMPL->fetch_param("test", -1);
    

Tag processing - step 2

// 2. Get the contents of the pair tag
$result = $this->EE->TMPL->tagdata;
    

• This allows us to get all the text between the opening and closing tags:

{exp:member_info:query}
    This is the part that comes back in tagdata.
{/exp:member_info:query}
    

Tag processing - step 3

// 3. Setup a default response
$vars = array(
    'found' => FALSE
);
    

• If there are no results found, we want to be able to use a conditional to determine that easily:

{exp:member_info:query}
    {if found} ... {if:else}
        No results found for that ID!
    {/if}
{/exp:member_info:query}
    

• More on how the parsing works in step 5

Tag processing - step 4

// 4. Run our query
if($requested_member_id) {
   $query = $this->EE->db->where('member_id', $requested_member_id)
                         ->get('members');
    

• 1. See if we got a member_id   (default fetch_param() is FALSE)
• 2. Create the query object and set a where clause.
  • $requested_member_id will automatically be escaped!
• 3. Run the query against the exp_members table
  • The exp_ prefix is automatically added by get()
  • Admins can change this prefix - hardcoding it is bad

Tag processing - step 4

        // Check that we have at least one row
        if($query->num_rows() > 0) {
            // Replace the default return vars array
            // with the result row
            $vars = $query->row_array();
            $vars['found'] = TRUE;
        }
    

• Check if we have any data in the result - if so, blow away our default values and replace them with the data row
• Add back in the "found" variable and set it to true

Tag processing - step 4

        // Check if request is for their own data,
        // if not we can provide less info:
        $vars['is_current_user'] =
          (
            $requested_member_id 
               == $this->EE->session->member_id
          );
    }
    

• A security check to see if the user is asking for their own data
• The template can use this to show less info

Tag processing - step 5

// 5. Parse results variables into the output
$result = $this->EE->TMPL->parse_variables($result, array($row));
    

• Take the tagdata content that we put into $result and parse out our variables
• parse_variables() handles conditionals as well as variable pairs and single variables for us
• Remember to wrap your variable array in another array
  (unless you have multiple rows)

Tag processing - step 6

// 6. Return the results as a string
return $result;
    

• Return the resulting text
• That's it! We're done!

Using the tag

• Example Template: account/info
• Example URL: http://localhost/account/info/45

{exp:member_info:query member_id="{segment_3}"}
    {if found}
        Screen Name: {screen_name}<br/>
        {if is_current_user}
            Registered Email Address: {email}<br/>
            Username: {username}<br/>
            <a href="{site_url}account/edit/{segment_3}">Edit</a>
        {/if}
    {if:else}
        Invalid request.
    {/if}
{/exp:member_info:query}
    

Questions?

is.gd/j4EIoz

Isaac Raway (@airways, airways@mm.st)