In this part of the User Submitted Image Galleries series we will look at setting up our custom image sizes and also the image submission form. In the previous part we registered out custom post types and taxonomies, and setup the basic structure of the plugin.

The Image Sizes

Once the plugin is complete, we will have a complete gallery system that users (both registered and not) will be able to submit images to. Due to users having a notorious ability to not follow guide lines, we are going to setup some pre-defined image sizes that all gallery images will be resized to. This helps us make sure that our gallery images are all the exact same size, at least in thumbnail view, and prevents layouts from breaking.

The image sizes we are going to setup will be connected to the WordPress media library system. So any image uploaded to the media library will be automatically resized / cropped to match our specifications. We will create two separate image sizes: one for the gallery thumbnails and one for the single gallery image page. The thumbnails will link to the single gallery image page, where the larger version will be displayed, and then the single gallery image will link to its full size version in a light box.

So to setup our image sizes, we are going to use the add_image_size() function.

The first thing we need to do is create a new file called “image-sizes.php” and place it inside of our “includes/” folder. Once you have done that, open the file and place this in it:

<?php
 
function uig_add_thumbnail_support() {
	if(!current_theme_supports('post-thumbnails')) {
		add_theme_support('post-thumbnails');
	}
}
add_action('init', 'uig_add_thumbnail_support', 999);

Because we are using the add_image_size() function, which requires that the current theme supports post thumbnails, we have to make sure that we have support for post thumbnails. I wrote a quick tutorial on this last week.

Now that we have ensured that we have support for post thumbnails, let’s add our function that will register the image sizes:

// set up image sizes
function uig_image_size_setup() {
	$gallery_width = apply_filters('uig_gallery_image_width', 200); 
	$gallery_height = apply_filters('uig_gallery_image_height', 120);
 
	$single_width = apply_filters('uig_single_image_width', 560);
	$single_height = apply_filters('uig_single_image_height', 999);
 
	add_image_size('uig-gallery-image', $gallery_width, $gallery_height, true);
	add_image_size('uig-single-image', $single_width, $single_height, false);
}
add_action('init', 'uig_image_size_setup', 999);

So what is happening here? The four variables at the top are defining our image size. I have connected them to a filter to allow the sizes to be easily changed. Don’t worry, I will explain this more in a bit. By default, the gallery thumbnails will be 200×120 px, and the single gallery images will have a maximum width of 560px and a maximum height of 999px.

The uig-gallery-image image size has the fourth parameter set to TRUE because we want the images to be hard cropped, or always exactly 40×40. The uig-single-image has the fourth parameter set to FALSE because we want to use the soft crop mode, meaning that the images are given a max width of 590, but the height can vary, but won’t go larger than 999px.

Any image that we upload to the media library will now have these two sizes generated for it. Note, if you want to create these sizes for any image already added to the library, then use the Regenerate Thumbnails plugin. You will also want to use this plugin if you change the image sizes after activating our gallery plugin.

Now we need to include our “image-sizes.php” file into our main plugin file. To do that, open “user-image-gallery.php”, find the includes section at the bottom, and add this:

1

include(UIG_PLUGIN_DIR . '/includes/image-sizes.php');

Remember a moment ago I mentioned that each of our image sizes was passed through a filter that would allow us to alter the image sizes without modifying the plugin? The idea behind this is to provide users of the plugin a simple way adjust the size of the images without touching the code of the plugin. This could easily be done with a settings page as well, but since filter hooks are so powerful and allow you to drastically enhance your plugins, I want to show you this method.

Create a new file called “filters.php” and save it into the “includes/” folder. We are going to add a filter function for each of the image sizes, so four in total. Each function will take a size, in pixels, as a parameter and will then return the size back. The functions each look like this:

// set the width of gallery images
function uig_set_gallery_image_width($width) {
	return 200;
}
add_filter('uig_gallery_image_width', 'uig_set_gallery_image_width');

Now this may seem a little redundant because we first set our default size to 200 pixels and now we are setting it to 200 pixels again. Well, this function isn’t actually designed to do anything besides return the default value, but we use it in order to make it available for others to modify. I will show you an example in a moment.

All four filters together look like this:

// set the width of gallery images
function uig_set_gallery_image_width($width) {
	return 200;
}
add_filter('uig_gallery_image_width', 'uig_set_gallery_image_width');
 
// set the height of gallery images
function uig_set_gallery_image_height($height) {
	return 120;
}
add_filter('uig_gallery_image_height', 'uig_set_gallery_image_height');
 
// set the width of single images
function uig_set_single_image_width($width) {
	return 584;
}
add_filter('uig_single_image_width', 'uig_set_single_image_width');
 
// set the height of single images
function uig_set_single_image_height($height) {
	return 999;
}
add_filter('uig_single_image_height', 'uig_set_single_image_height');

Now make sure that you include this new “filters.php” file in the same way that we included the “image-sizes.php”.

include(UIG_PLUGIN_DIR . '/includes/filters.php');

Remember, this goes in the “user-image-gallery.php” file.

Okay, so how about an example of what these filters are good for, and how they can be used. Let’s say that you want to change the size of the single gallery images, and, since we don’t want to modify the plugin code, we’re going to put this in our functions.php or a custom functions plugin:

function uig_custom_single_image_width($width) {
	return 700;
}
remove_filter('uig_single_image_width', 'uig_set_single_image_width');
add_filter('uig_single_image_width', 'uig_custom_single_image_width');

This will remove the default size and set a new one. If we wanted to, we could also set the size based on what the default is, which will be accessible with the $width variable.

Again, this may seem kind of silly, but when you begin building large plugins that have a LOT of possible parameters / options to modify, these kind of techniques can be very, very useful. JigoShop is a great example of a plugin that has made excellent use of filters to allow users to customize the plugin without touching the code. This is really important when it comes to maintaining the ability to update the plugin.

If you’re looking for a basic introduction to how filter hooks work in WordPress, check out my tutorial.

So that’s it for the image sizes. The next thing to build is our submission form.

The Image Upload Form

The image upload form is going to be displayed using a short code, so let’s first create the “shortcodes.php” file. This file will be saved inside of the “includes/” folder.

We will first create a function and then attach it to the add_shortcode() function, which will make our submission form short code available for use.

function uig_submission_form()
{
    // form html will be here
}
add_shortcode('upload_image_form', 'uig_submission_form');

Inside of the function, the first thing we need to do is setup some global variables. One will hold the information for the currently logged-in user (if any), and one will be a variable we will use to determine whether CSS / JS should be loaded for the form.

Update 01-31-2012: The first part of this function has actually been changed to load our CSS and JS directly. WordPress 3.3+ allows us to load scripts and styles inline (in our short code), so this is a good way to demonstrate it.

function uig_submission_form()
{
	global $current_user;
 
	// load the necessary JS and CSS -- these are loaded inline and only work with WP 3.3+
	wp_enqueue_script('uig-forms', UIG_PLUGIN_URL . 'includes/js/forms.js', array('jquery'));
	wp_enqueue_style('uig-gallery', UIG_PLUGIN_URL . 'includes/css/gallery.css');        
 
        // form html will be here
}
add_shortcode('upload_image_form', 'uig_submission_form');

HTML displayed with short codes must be returned and not echoed, so in order to do that easily we’re going to setup an output buffer. This is very easy. Our function, with the output buffer now looks like this:

function uig_submission_form()
{
	global $current_user;
 
	// load the necessary JS and CSS -- these are loaded inline and only work with WP 3.3+
	wp_enqueue_script('uig-forms', UIG_PLUGIN_URL . 'includes/js/forms.js', array('jquery'));
	wp_enqueue_style('uig-gallery', UIG_PLUGIN_URL . 'includes/css/gallery.css');        
 
        ob_start();
 
	get_currentuserinfo();
 
        // form html goes here
 
        return ob_get_clean();
}
add_shortcode('upload_image_form', 'uig_submission_form');

The get_currentuserinfo() function just ensures that we have loaded all of the information for the currently logged-in user.

Our form is going to consist of several elements:

• A function to show all error messages (if they exists)
• An input that will contain the ID of the current user, or the email of a non-logged-in user
• An input for the image name
• A textarea for the image description
• A select menu for choosing the image category
• An input for entering image tags
• An upload field for choosing the image file
• Several hidden fields to assist with the upload process / validation

Okay, so now, instead of going line by line with the HTML, here’s the complete function with our submission form:

function uig_submission_form()
{
	global $current_user;
 
	// load the necessary JS and CSS -- these are loaded inline and only work with WP 3.3+
	wp_enqueue_script('uig-forms', UIG_PLUGIN_URL . 'includes/js/forms.js', array('jquery'));
	wp_enqueue_style('uig-gallery', UIG_PLUGIN_URL . 'includes/css/gallery.css');        
 
	ob_start();
 
	get_currentuserinfo();
 
		if($_GET['image-submitted'] == 1) { ?>
			<p class="image_submitted"><?php _e('Thanks! Your image as been submitted for review', 'uig'); ?></p> 
		<?php } ?>
 
		<?php uig_show_error_messages(); ?>
 
		<form id="uig_submission" action="" method="POST" enctype="multipart/form-data">		
			<?php if(is_user_logged_in()) { ?>
				<input type="hidden" name="uig_user_id" value="<?php echo $current_user->ID; ?>"/>
			<?php } else { ?>
				<fieldset>
					<div>
						<label for="uig_user_email"><?php _e('Your Email', 'uig'); ?></label>
						<input type="email" name="uig_user_email" id="uig_user_email"/>
					</div>
				</fieldset>
			<?php } ?>
			<fieldset>
				<div>
					<label for="uig_image_name"><?php _e('Image Name', 'uig'); ?></label>
					<input type="text" name="uig_image_name" id="uig_image_name"/>
				</div>
				<div>
					<label for="uig_image_desc"><?php _e('Image Description', 'uig'); ?></label>
					<div><textarea name="uig_image_desc" id="uig_image_desc"><?php _e('Describe your image', 'uig'); ?></textarea></div>
				</div>
 
				<div>
					<label for="uig_image_cat"><?php _e('Select the category that best fits your image', 'uig'); ?></label>
					<div><select name="uig_image_cat" class="ignore" id="uig_image_cat">
						<?php
						$terms = get_terms('uig_image_category', array('hide_empty' => false));
						if($terms) {
							foreach($terms as $term) {
								echo '<option value="' . $term->term_id . '">' . $term->name . '</option>';
							} 
						} else {
							echo '<option>' . __('No image categories created yet', 'uig') . '</option>';
						}	
						?>
					</select><br/></div>
 
				</div>
 
				<div>
					<label for="uig_image_file"><?php _e('Choose Image', 'uig'); ?> - <strong><?php _e('Max file size: 1mb', 'uig'); ?></strong></label>
					<div><input type="file" name="uig_image_file"/></div>
				</div>
 
				<div>
					<input type="hidden" name="uig_referrer" value="<?php echo get_permalink(get_the_ID()); ?>"/>
					<input type="hidden" name="uig_action" value="upload"/>
					<input type="hidden" name="uig_upload_nonce" value="<?php echo wp_create_nonce('uig-upload-nonce'); ?>"/>
					<input type="submit" id="uig_submit" value="<?php _e('Upload Image', 'uig'); ?>"/>
				</div>
			</fieldset>
		</form>
	<?php
 
	return ob_get_clean();
}
add_shortcode('upload_image_form', 'uig_submission_form');

There are only three “special” parts to this form that are not (for the most part) plain HTML. The first is the uig_show_error_messages() function (which we will write in the next part). It is used to display any error messages present after trying to (unsuccessfully) upload an image.

The second is at the top where we have a conditional to check whether the user is logged-in. If they are, then we insert their user ID into a hidden input. This will be used to set the user as the author (owner) of the image being uploaded. If they are not logged-in, then the user is asked for their email address, which will then be stored in a custom meta field of the image.

The Third “special” part of the form is the image category selection field. This is just a regular select field whose options are automatically populated with the available terms in the “uig_image_category” taxonomy.

Also at the top of the form is a conditional that checks whether the “image-submitted” $_GET variable is set. If it is, then a message is displayed letting the user know that the image has been successfully submitted.

And that’s it for our submission form.

You can display the submission form on a page by adding the [upload_image_form] short code to a page. In the default Twenty Eleven theme, the form looks like this:

In the Next Section

In part three of this tutorial series, I will show you how to process the image uploads, and then shortly after that, in the following parts of the series, we will cover jQuery validation of the submission form, modifying the post type columns in the dashboard, registering dashboard widgets for pending images, sending admin notifications when new images are ready for moderation, and more.