====== Tutorials / How to make a new project displayer ======

===== Introduction =====

This tutorial will show you how to add a new project displayer (in addition to the default One By One, Slideshow and Pop) to the system, so that it shows up in project groups in the backend and will also show you how to get your displayer working on the frontend (with text blocks, images, audio and video files).

This displayer will be a modified version of One By One, using the file caption as a link, so that image thumbnails can be linked to an external source, along with a little bit of jQuery to make a fade effect on hover. An example of this can be seen in the Showcase section on the Secretary homepage.

===== Step 1 =====

We start by making a folder for our plugin. Our plugin is called "Linked One by One", so the folder will be called "linked-onebyone", following Secretary naming conventions, where spaces are turned into dashes and all letters are lowercase.

It is important that dashes, and not underscores for example, are used. Folders with underscores or other characters will not work.

===== Step 2 =====

In this folder, make a new file called "linked_onebyone.plugin.php". This will be the main plugin file.

===== Step 3: In the backend =====

Now the fun begins: registering your displayer with the displayer dropdown in the backend. It's quite simple:

<code php>
hook( "displayersList", "register_linked_onebyone" );
</code>

This code hooks into the ''displayersList'' anchor and attaches a function called ''register_linked_onebyone'' which will handle adding our custom displayer to the list:

<code php>
function register_linked_onebyone( $displayers )
{
	// Key is displayer title, value is slug, same as folder name
	$displayers['Linked One by One']= "linked-onebyone";
	return $displayers;
}
</code>

If you save this and upload the plugin to your plugins folder, login to your Secretary installation and select a project to edit, you will now see your displayer in the dropdown!

===== Step 4: On the frontend =====

An essential part of the plugin is missing at this point: the function that will handle outputting images on the frontend.

This function receives three values from the system: the project array, an array of all files in the project, and an array describing the current group. Essentially, this function loops through all the files and matches them with the current group, so that files and groups set up in the backend are recreated on the frontend:

<code php>
function linked_onebyone( $project, $files, $group )
{
	global $clerk;
		
	// Loop through the files
	foreach ( $files as $file => $data )
	{
		// Match the file's group with the group number
		// Does this file belong to this group?
		if ( $data['filegroup'] == $group['num'] )
		{
			// Yes. Do some cool shit now.
		}
	}
}
</code>

**Note that the function name must match the folder name, the only difference being that dashes are underscores.**

Now we move on to file handling. Displayers need to be able to handle all file types: images, video and audio.

<code php>
function linked_onebyone( $project, $files, $group )
{
	global $clerk;
		
	// Loop through the files
	foreach ( $files as $file => $data )
	{
		// Match the file's group with the group number
		// Does this file belong to this group?
		if ( $data['filegroup'] == $group['num'] )
		{
			// Define file width and height for proper CSS
			$width= ( $data['width'] == 0 ) ? "auto" : $data['width'];
			$height= ( $data['height'] == 0 ) ? "auto" : $data['height'];
			
			// Handle the different file types
			switch ( $data['type'] )
			{
				case "image":
					$html.= '<div class="file"><img src="' . PROJECTS_URL . $project['slug'] . '/' . $data['file'] . '" width="' . $width . '" height="' . $height . '" alt="" />';
					break;
				case "video":
					$html.= '<div class="file">' . mediaplayer( $data, $project );
					break;
				case "audio":
					$html.= '<div class="file">' . audioplayer( $data, $project );
					break;
			}
		}
	}
}
</code>

To handle the different file types we use a ''switch'' statement. The video and audio cases will always make use of the built in media and audio players (unless you want to provide your own). So that leaves most customization to the image case, which by default will always just spit out an ''img'' tag.

The ''src'' attribute for images is in this format: ''[path_to_projects_folder]/[project_slug]/[file_name]''