Fresh Tilled Soil

Flutter, the popular Wordpress plugin, is a very simple way to add a lot of flexible extra functionality to posts and pages. It’s a gold mine of usefulness that allows Wordpress to compete with more robust CMS applications, and with some tweaking can provide some really powerful features.

As awesome as Flutter is, the documentation blows. Any new user will experience firsthand the displeasure of sorting through vague syntactic examples and soundless uninformative screencasts. There are plenty of good resources for learning how to use the plug-in, but Flutter has notable feature that no one seems to know about: image manipulation.

See that little “Custom Options List” link? This is the only indication that image manipulation is even possible. Clicking this link brings down a long list of confusing commands.

By skimming quickly through this list you will see a boatload of useful-sounding photo manipulations, such as rounded corners, or sizing and cropping images.

These commands can be used to write strings that will apply edits to images on the fly, allowing users to upload photos without breaking a template’s visual style. I’ll demonstrate how to use Flutter to associate an image with each post, and print out a heavily styled image.

Setting up the content type

I assume you already know the basics of flutter, so I’ll go through this quickly. If you know all about this, skip down to the code.

1. Create a new Write Panel in Flutter

2. Set up basic options

Notice that I unchecked “Custom Fields.” This prevents the user from messing up the Flutter data, but you might want those turned on for development. Create a new field. Make it an image field and pay special attention to the “Name” textbox because you’ll need it later. I set this field to “Required” as every blog post will need an image.

3. Remember this screen?

We’ll get back to it later, but expand the “Custom Options List” and copy + paste everything into a blank .txt file for reference. You can’t get back to this list unless you make a new field. Leave everything blank and hit finish.

Okay, we’ll need a test post or two, so make a dummy post using your new content type. Don’t forget to upload an image! When you’re done, we’ll move on to code.

4. Building the WordPress Template

If you look at the test blog post, you’ll see that the image you added isn’t there. We need to add it to the template file. Take a look at your loop:

<?php if ( have_posts() ) : while ( have_posts() ) : the_post(); ?>

<div>

<h2><a href="<?php the_permalink() ?>" rel="bookmark" title="Permanent Link to <?php the_title_attribute(); ?>"><?php the_title(); ?></a></h2>

<div class="entry">

<?php the_content(); ?>

</div>

<p class="postmetadata">Posted in <?php the_category(', '); ?></p>

</div>

<?php endwhile; else: ?>

<p>Sorry, no posts matched your criteria.</p>

<?php endif; ?>

We need to add the Flutter image code. Use Flutter’s “get_image” command with the name of the image field.

I’ll put it right before the content:

<div class="entry">

<?php echo get_image('post-image') ?>

 <?php the_content(); ?>

</div>

Voila! There’s the image. But it’s pretty blocky in the layout. If every post must have an image, all the images will need a standard look and feel. For this blog, I’ll make every photo a 600×400 grayscale image with rounded corners. That’s where Flutter’s image tools come into play.

There it is: the unaltered uploaded image.

5. Manipulate your images on the fly with Flutter and PHPThumb

Look through the “Custom Options List” and determine which operations to use. I’ll be using these:

w    = max width of output thumbnail in pixels
h    = max height of output thumbnail in pixels
f    = output image format ("jpeg", "png", or "gif")
zc   = zoom-crop. Will auto-crop off the larger dimension
so that the image will fill the smaller dimension

fltr = filter system. Call as an array as follows:
- "gray" (Grayscale) [ex: &fltr[]=gray]
remove all color from image, make it grayscale

Here’s the full code we’ll end up with:

<div class="entry">

<img src="<?php echo pt(); ?>?src=<?php echo get('post-image'); ?>&f=png>&w=600>&h=400>&zc=C>&fltr[]=ric|12|12>&fltr[]=gray" />
 <br />
 <?php the_content(); ?>

</div>

The final result of Flutter's image manipulation

6. Cool, huh? Let’s break this down.

To generate its image manipulations, Flutter uses something called PHPthumb. Step one is to rewrite the query to pass through PHPthumb. Instead of using  get_image() we’ll need to create the tags ourselves and use the pt() function for the path to PHPthumb:

<div class="entry">

<img src="<?php echo pt(); ?>" />
 <br />
 <?php the_content(); ?>

</div>

…PHPthumb takes a query string with several parameters, the first of which is always the image source. We need to print out the name of the image using a Flutter get() command. Make sure to use the correct field name (mine is ‘post-image’) for the get().

<div class="entry">

<img src="<?php echo pt(); ?>?src=<?php echo get('post-image'); ?>" />
 <br />
 <?php the_content(); ?>

</div>

Finally, you can add the image filters. Each command is added onto the query with an “&” We’ll start by converting the image to a PNG using the “f“ command:

<div class="entry">
<img src="<?php echo pt(); ?>?src=<?php echo get('post-image'); ?>&f=png" />
 <br />
 <?php the_content(); ?>

</div>

Image manipulation commands must be separated by a “>” symbol. We’ll add on the commands to set the target width and height, separating them with a “>”:

<div class="entry">

<img src="<?php echo pt(); ?>&src=<?php echo get('post-image'); ?>&f=png>&w=600>&h=400" />
 <br />
 <?php the_content(); ?>

</div>

Next up is telling the system to crop the image so that it doesn’t have to stretch out to fit the dimensions. We’ll use the zc command with “C” as the attribute to crop evenly towards the photo center:

<div class="entry">

<img src="<?php echo pt(); ?>?src=<?php echo get('post-image'); ?>&f=png>&w=600>&h=400>&zc=C />
 <br />
 <?php the_content(); ?>

</div>

Finally, it’s time to apply the fancy filters. I’m using the ric filter for rounded corners and the gray  filter for desaturation. ric  takes values for the corner radius, and I used 12 for each:

<div class="entry">

<img src="<?php echo pt(); ?>?src=<?php echo get('post-image'); ?>&f=png>&w=600>&h=400>&zc=C>&fltr[]=ric|12|12>&fltr[]=gray" />
 <br />
 <?php the_content(); ?>

</div>

Finish by closing the image tag. Phew!

Additional Notes

This system is really easy and powerful once you get used to it. Play around a little and read through the list of all possible image manipulations; There’s a lot of good stuff there.

When creating an image field, the “Custom” textbox allows you to enter an image filter string. You should avoid using this because there’s NO WAY TO EDIT it and the original unaltered image will no longer be available for display.

An assigned image for each post would make a great image gallery; You could even superimpose the post’s title onto the thumbnail as a teaser.

List of all available filter options

Has anyone else used this Flutter feature?? Let us know how it went and what you used it for.