Creating AMM Templates

Editing Templates

You can either edit all the required files in a text editor and upload them, OR, you can make the wp-content/amm/ folder writeable and use the file editor built in to wordpress in the Manage->Files section. For instructions on how to do this please refer to the Wordpress Support Forums and the Wordpress Codex

Right...

Now the fun part. For those who like to just dive in, open up the file amm_extras.php and take a look inside. You'll see three functions:

amm_default_output
amm_debug_output
amm_first_template

All you must remember is:

functions MUST start with 'amm_'
Make sure your function name is UNIQUE (So don't call it amm_Output or amm_getMedia... :))
functions MUST receive '($amm)' as their only parameter

So if you're feeling brave, dive in and write something.

For those who prefer to do a little more reading...

Template layout

Every template function you write must have a unique name, and if you want to print more than one item out, a loop. (For non-techies, a loop in programming just does the same thing several times, Wordpress uses one when it prints out 10 blog posts on the frontpage of your site, etc...)

The best way to illustrate how templates work is to write one, so here's a walkthrough!

Template Name

At the bottom of the amm_extras.php file there is a set of tags that look like this:

    <?php
    }
    ?>

This signals that the PHP stops here. (It is the end of the previous template function)

You will want to put your template code below this (in other words, your template is the last thing in the file). So, after the ?> tag add two or three new lines, and enter the following:

<?php
    function amm_my_first_go($amm){

    return $content;
    }
?>

For all your template functions you must do two things

functions MUST start with 'amm_'
functions MUST have ($amm)

You have to put amm_ on the front to make sure you don't accidentally conflict with a wordpress function's name, and you must have ($amm) else your desired results won't be available to print!

$amm is no ordinary variable, it's an object. Objects have data and functions in them, and you get to the functions like so:

    $amm->function();

We'll go into that in detail soon... If you're impatient, Skip to the final code.

The Loop

The easiest way to make sure you output all your results is with a loop. The $amm object contains a variable that is set to the number of items stored in the $amm object. So, we use this and a 'For Loop' to repeat our template the right number of times.

Here's what the loop looks like:

<?php for ($x = 0; $x < $amm->totalItems(); $x++ ) :?>

<?php $amm->nextItem(); endfor; ?>

If you've never seen a FOR loop done like this before, don't worry, it's just the PHP 'Shorthand'. You can copy and paste the code from the supplied functions to make your life easier !

You may notice two odd looking statements, $amm->totalItems(); and $amm->nextItem(); These are the functions inside the $amm object, which is why you need to point to them. totalItems() is pretty obvious, it's the total number of items in the results you asked for with the getMedia function.

nextItem(); happens at the end of the loop to move the $amm object on to the next item in the results. If you forget this, you will end up printing the same book 10 times!

All the functions available to you will be explained later.

The Fun Stuff

Ok, so we have the function, it has a name and a loop but right now it's not doing anything. We display the information about our books and other stuff by using functions that live inside the $amm object.

In your function, between the openening and closing loop tags, enter the following:

    <strong>Title: </strong>    <?=$amm->title();?> <br />

    <strong>Author: </strong> <?=$amm->author();?><br />

In case you haven't seen it before:

 <?=        is the same as       <?php echo

 The shorthand may not work on your server. 

 If it does not, use the normal <?php  and ?> tags.

If you don't like using the shorthand, type this instead:

    <strong>Title: </strong>    <?php echo $amm->title();?> <br />
    <strong>Author: </strong> <?php echo $amm->author();?><br />

We can keep adding HTML and $amm functions to this to provide all manner of options, displaying the rating, date, a small or large image from Amazon etc... But for now, we'll stick with just these two.

The Final Code

NOTE:You can download a sample amm_extras.php file with the completed example in it here: tutorial.txt

The final code should look like this:

    <?php
    function amm_my_first_go($amm){
    ?>
    <?php for ($x = 0; $x < $amm->totalItems(); $x++ ) :?>

        <strong>Title: </strong>    <?php echo $amm->title();?> <br />
        <strong>Author: </strong> <?php echo $amm->author();?><br />

    <?php $amm->nextItem(); endfor; ?>

    <?php return $content;
    }
    ?>

Don't be put off if it looks scary, trail and error and some experimentation will pay off and soon you'll be able to display whatever you want, however you want it.

IMPORTANT!: It is very important that there is NO WHITESPACE anywhere in the amm_extras.php file outside a PHP function. This relates to how Wordpress includes plugin files. If you get a 'Headers already sent out' error when you activate the AMM, you have extra whitespace in the amm_extras.php file.

You can download a sample amm_extras.php file with the completed example in it here: tutorial.txt

Save the amm_extras.php file and upload it to /wp-content/plugins/amm making sure that you overwrite the old one if it's there.

Showing your first template to the world!

You can do this in two ways, one is to edit the getmedia call in to your template file, the other is to call it with a "quicktag" from inside a wordpress post or page. How to do this is explained in the page on Editing Templates

For reference, the getmedia calls you'd need are:

For templates:
    <?php amm_getMedia('amm_my_first_go',10); ?>

For posts and pages:
    <!--amm_getMedia('amm_my_first_go',10)-->

(Note how you don't need a semicolon (;) if you're adding it to a post)

Also remember that if you're inserting the quicktag into a post, you need to add the custom field "amm" with the value "enabled" to trigger the plugin. Again how to do this is explained in the page on the amm_getmedia() Function

All the Functions...

For a complete list of the functions you can use and what they do, please see the Function Reference.

Sozu Web Studio - Stylish Accessibility