<h1>smd_thumbnail</h1>

<h2>Features</h2>

	<ul>
		<li>Assign any number of thumbnails to Txp&#8217;s images</li>
		<li>Batch assign thumbnails to existing images</li>
		<li>Set one thumbnail size as default</li>
		<li>Display any of the thumbnail sizes on your site</li>
		<li>Keep thumbs in sync with Txp&#8217;s thumbs if you wish</li>
		<li>Conditional thumbnail check available</li>
	</ul>

<h2>Installation / upgrading / uninstallation</h2>

<p class="warning">Requires Txp 4.5.0+</p>

<p>Download the plugin from either <a href="http://textpattern.org/plugins/1186/smd_thumbnail">textpattern.org</a>, or the <a href="http://stefdawson.com/sw">software page</a>, paste the code into the Txp Admin -&gt; Plugins pane, install and enable the plugin. Visit the <a href="http://forum.textpattern.com/viewtopic.php?id=34367">forum thread</a> for more info or to report on the success or otherwise of the plugin.</p>

<p class="warning">When upgrading froim v0.1x to v0.20, your preferences for <em>Keep Txp thumbnails in sync with default profile</em> will be removed. Please visit the <em>Tools/Prefs</em> area to reinstate the behaviour you desire.</p>

<p>To uninstall, delete from the Admin -&gt; Plugins page.</p>

<h2>Usage &#8212; admin side</h2>

<p>Visit the Content-&gt;Images tab. Above the list of images is an area labelled <em>Thumbnail Profiles</em>. Click it to reveal the control panel. You can toggle this panel on and off by clicking the heading.</p>

<p>You must define at least one profile to begin with, so click the <em>New profile</em> button. This will reveal edit boxes where you can enter:</p>

	<ul>
		<li><strong>Name</strong>: some descriptive name for this thumbnail dimension. You are limited to usual non-weird characters in the name</li>
		<li><strong>Width</strong>: thumbnail width, in pixels. If left blank (or set to 0) and height is specified, the width will be computed in proportion to the height</li>
		<li><strong>Height</strong>: thumbnail height, in pixels. If left blank (or set to 0) and width is specified, the height will be computed in proportion to the width</li>
		<li><strong>Quality (%)</strong>: The quality of the resulting thumbnail. Generally only of use for jpg or png(24) images. The higher the value the better the quality and the bigger the file size. Default: 75</li>
		<li><strong>Crop</strong>: whether to crop the image when the thumbnail is created, or scale it to fit</li>
		<li><strong>Sharpen</strong>: whether to apply a sharpening filter to the thumbnail when it is created. Useful for very small images</li>
		<li><strong>Active</strong>: Enable/disable this thumbnail size so it will/won&#8217;t be automatically generated when the next image is uploaded. Click the checkbox to instantly switch the profile on/off. Click the &#8216;Active&#8217; word in the heading row to toggle the status of all profiles. Note that this setting governs how the <a href="#smd_thumb_create">All sizes</a> dropdown entry interacts with the <em>Create</em> and <em>Delete</em> buttons</li>
		<li><strong>Default</strong>: set this thumbnail profile as the default. The default image will be displayed in the Images list and will also be used as the default size to be displayed using <code>&lt;txp:smd_thumbnail/&gt;</code>. If the option to <a href="#smd_thumb_prefs">sync with Txp&#8217;s thumbs</a> is on, it will also become Txp&#8217;s standard (built-in) thumbnail size from this point forward</li>
	</ul>

<p>Once you&#8217;ve configured your profile, click Save to store it. You can always edit it again by clicking its name. Go ahead and create some more profiles for thumbnails of different sizes/parameters. If you wish to delete a profile, hit the <em>[Delete]</em> button and confirm. <strong>All thumbnails associated with that profile will be deleted</strong>.</p>

<p>At this point, no thumbnails have been created. Let&#8217;s rectify that.</p>

<h3 id="smd_thumb_create">Creating thumbnails</h3>

<p>Pick one of your images and click to edit it.</p>

<p>Beneath the main picture you will see an area labelled <em>Thumbnails</em>. You can toggle this panel on and off by clicking the heading.</p>

<p>Inside the panel is a simple select list containing one entry for each thumbnail profile you have configured, plus the special entry <em>All sizes</em>. You can select one of these entries and click <em>Create</em> to create thumbnail(s) in the selected size or hit <em>Delete</em> to remove the selected thumbnail(s).</p>

<p>Once created, the thumbnails appear in the panel; remember they can be tucked away if you don&#8217;t want to look at them.</p>

<p>If you select <em>All sizes</em> and hit <em>Create</em>, you will get one thumbnail for each active profile. Similarly, if you hit <em>Delete</em> any thumbnails stored against an active profile for the current image will be removed. By toggling certain thumbnail profiles on/off you can control which ones are created or deleted.</p>

<p>By default:</p>

	<ul>
		<li>when you upload a new image, thumbnails will be automatically created for any active profiles</li>
		<li>when you replace an existing image, thumbnails will only be automatically created for active profiles if thumbs <em>do not</em> already exist. This option can be altered with the <a href="#smd_thumb_prefs">prefs</a></li>
	</ul>

<p>Note that if you use Txp&#8217;s multi-edit tool to delete images, <strong>all</strong> corresponding thumbnails for the selected images (including inactive ones) will be removed.</p>

<h3 id="smd_thumb_custom">Custom thumbnails</h3>

<p>If you prefer to make your own thumbs in an external program, you can still set up the profiles as normal but instead of clicking <em>Create</em> in the Image Edit screen, you can pick a profile size from the dropdown and use the file picker facility (Browse&#8230; / Choose&#8230;) to select a thumbnail from your hard drive. When you click <em>Upload</em> the image will be inserted against the selected profile.</p>

<p>At any time you can click one of the thumbnails (or select a size from the dropdown) and choose for another image to replace the existing thumbnail &#8212; even ones that have been auto-created. Some things to note about this feature:</p>

	<ul>
		<li>the thumbnail must be of the same file type as the original image or the upload will be ignored</li>
		<li>you can click a highlighted image to deselect it</li>
		<li>you cannot Browse for an image (the file upload box is greyed out) unless you have chosen one profile</li>
	</ul>

<h3 id="smd_thumb_batch">Batch thumbnail creation</h3>

<p>You can also create thumbnails en-masse. Click the <em>Tools</em> button (labelled &#8216;<em>Tools / Prefs</em>&#8217; if you have sufficient rights) in the top-right hand corner of the smd_thumbnail control panel. From there you will see an area that allows you to create thumbnails for:</p>

	<ul>
		<li>Only the selected images (the checkboxes next to each image)</li>
		<li>All images of a particular category</li>
		<li>All images uploaded by a particular user</li>
		<li>All images</li>
	</ul>

<p>After selecting the desired option (and if you choose category or author, select one of the entries from the secondary list that apears), hit <em>Create</em>. Once you confirm your action, the plugin will go away and create thumbnails for every active profile for all images that match your criteria. This is a quick way to generate thumbs for your existing images. Note that if you choose the first (empty) category entry, then all images that have not been assigned a category are manipulated.</p>

<p>Because of the nature of this tool &#8212; especially with large image pools &#8212; the process is done as a background task via <span class="caps">AJAX</span>. After clicking the <em>Create</em> button (and confirming you are sure) a counter will appear in the top-right of the prefs panel showing how many images it has processed out of the total number of images in the set. When it&#8217;s done, if you then refresh your Images tab (e.g. click to the <em>Profiles</em> pane) you will see your chosen default thumbnails in the list &#8212; assuming you&#8217;ve set one as default.</p>

<h3 id="smd_thumb_prefs">Preferences</h3>

<p>If you have sufficient privileges, in the lower portion of the <em>Tools</em> panel are some options that govern how thumbnails are created for all users. There is no &#8216;Save&#8217; action here: the checkmarks are stored in real-time and always reflect the current state.</p>

<h4>Create smd_thumbnails from</h4>

<p>Governs whether the smd_thumbnails are created from the full size image or its (Txp) thumbnail. If you have elected not to have Txp thumbnails created then it&#8217;ll probably not work very well :-)</p>

<p>This preference applies:</p>

	<ul>
		<li>when you use any of the batch tools to mass-produce smd_thumbnails</li>
		<li>if you upload a new image</li>
		<li>if you reupload a main image and <em>Recreate thumbnails on re-upload of main image</em> is checked</li>
	</ul>

<h4>Keep Txp thumbnails in sync with default profile</h4>

<p>(This option only appears if you have set a profile as default)</p>

<p>Ordinarily, smd_thumbnail works independently of Txp&#8217;s thumbs. If you disable the plugin you&#8217;ll see that everything goes back to how it was before you installed it. This is great because your hard-graft isn&#8217;t lost if you have uploaded your own thumbs.</p>

<p>But if you start creating thumbs with the plugin you will notice that Txp&#8217;s built in tags such as <code>&lt;txp:article_image thumbnail=&quot;1&quot; /&gt;</code> and <code>&lt;txp:thumbnail /&gt;</code> won&#8217;t work for newer thumbnails. This might be confusing so you can opt to have smd_thumbnail update your Txp thumbnails at the same time.</p>

<p>By ticking either of the checkboxes, the plugin will track any changes <strong>to the default profile</strong> and mimic them with Txp&#8217;s thumbnails. This has a few effects worth highlighting.</p>

<p>When the <em>Creation</em> checkbox is ticked:</p>

	<ol>
		<li>if you batch create thumbs, upload a new image, or replace an existing image, a new Txp thumbnail will be created at the default size. Any existing thumbs will be overwritten</li>
		<li>if you change default profile, any Txp thumbnails that have been created will remain at the previous size. Only when you start creating, uploading or replacing images will the new thumbnail sizes be created</li>
	</ol>

<p>When the <em>Deletion</em> checkbox is ticked:</p>

	<ol>
		<li>if you delete a single thumb that corresponds to the default profile, both the profile thumb and Txp&#8217;s thumb will be deleted</li>
		<li>if you delete an entire profile, all its thumbnails <strong>and all Txp&#8217;s thumbs</strong> will be removed</li>
	</ol>

<p>Further:</p>

	<ol>
		<li>if you have no default profile, the checkboxes disappear and the settings have no effect. Choose a default profile to reinstate the behaviour</li>
		<li>if you deactivate the default profile the checkboxes have no effect <strong>unless</strong> you delete the profile (since you&#8217;re deleting it, its status is &#8216;lost&#8217; and therefore the checkboxes function as normal). If there&#8217;s any doubt, uncheck the <em>Deletion</em> checkbox first!</li>
	</ol>

<h4>Recreate thumbnails on re-upload of main image</h4>

<p>When this checkbox is cleared and you <strong>replace</strong> a main image (from the Image Edit screen) any thumbnails that have already been assigned to the image are left as they are &#8212; only missing thumbnails will be created from the main image. Conversely, if you set this checkbox, when you upload the replacement image <strong><span class="caps">ALL</span> smd_thumbnails for active profiles will be (re)created from the main image</strong>.</p>

<p>Note one important exception: Txp thumbnails are <strong><span class="caps">NOT</span></strong> covered by this option &#8212; they are governed by the <em>Keep Txp thumbs in sync</em>&#8217;s &#8216;Creation&#8217; checkbox. Thus, if you upload a replacement image and the &#8216;Creation&#8217; checkbox is on, you will replace Txp&#8217;s thumb regardless of the setting of the <em>Recreate thumbnails&#8230;</em> option.</p>

<h2 id="smd_thumbnail">Tag: <code>&lt;txp:smd_thumbnail /&gt;</code></h2>

<p>A direct replacement for the built in <a href="http://textpattern.net/wiki/index.php?title=thumbnail">txp:thumbnail</a> tag with exactly the same functionality and attributes apart from these exceptions:</p>

	<ul>
		<li><span class="atnm">type</span> : use this attribute to display thumbnails of the given profile name. e.g. <code>type=&quot;large&quot;</code>. If you do not specify this attribute, the default profile will be used. If there is no default profile you&#8217;ll see warning messages</li>
		<li><span class="atnm">class</span> : if omitted, the name of the profile will be used as a class name for the img tag. If you specify a wraptag and omit the class, the profile name will be used as a class on both the container and the img tag</li>
		<li><span class="atnm">align</span> : this attribute has been removed</li>
		<li><span class="atnm">add_stamp</span> : adds the image file modification time to the end of the thumbnail&#8217;s <span class="caps">URL</span>. Use <code>add_stamp=&quot;1&quot;</code> to switch this feature on. This helps prevent stale images, but may prevent browsers from cacheing the thumbs properly thus increasing bandwidth usage. Default: 0</li>
		<li><span class="atnm">force_size</span> : usually when you set one or other width/height to 0 in a profile, the browser scales the missing dimension automatically. It does this by omitting the <code>width=</code> or <code>height=</code> attribute in the <code>&lt;img&gt;</code> tag. This may cause visual artefacts as the page is rendered and the browser calculates the sizes. If you wish the plugin to add the actual dimension to the <code>&lt;img&gt;</code> tag (the size at the time the thumbnail was created), tell the plugin with this attribute. Choose one or both of <code>width</code> or <code>height</code>. Comma-separate as required. Default: unset</li>
		<li><span class="atnm">display</span> : by default, this tag outputs a full <code>&lt;img&gt;</code> tag. If you just require the image <span class="caps">URL</span> so you can make your own image tags, set <code>display=&quot;url&quot;</code>. Default: <code>thumbnail</code></li>
		<li><span class="atnm">form</span> : you can construct your own <code>&lt;img&gt;</code> tags using the given form. If not specified, you may use the tag as a container.</li>
	</ul>

<p>The tag works inside <code>&lt;txp:images&gt;</code> or can be used standalone by specifying the <code>id</code> or <code>name</code> attribute. If using it as a container or with the <code>form</code> attribute you display the various pieces of thumbnail information using the <code>&lt;txp:smd_thumbnail_info&gt;</code> tag.</p>

<h2 id="smd_thumbnail_info">Tag: <code>&lt;txp:smd_thumbnail_info /&gt;</code></h2>

<p>Display various information from the current <code>&lt;txp:smd_thumbnail&gt;</code> tag (in either its form or container). Attributes:</p>

	<ul>
		<li><span class="atnm">item</span> : list of things you wish to display. Choose from:
		<ul>
			<li><code>url</code> : full image <span class="caps">URL</span> of the thumbnail</li>
			<li><code>type</code> : thumbnail profile name</li>
			<li><code>name</code> : image name</li>
			<li><code>id</code> : thumbnail ID</li>
			<li><code>ext</code> : thumbnail file extension</li>
			<li><code>category</code> : image category name</li>
			<li><code>category_title</code> : image category title</li>
			<li><code>alt</code> : image alt text</li>
			<li><code>title</code> : image title / caption</li>
			<li><code>author</code> : image author</li>
			<li><code>class</code> : class applied to thumbnail (if not supplied, is same as type)</li>
			<li><code>date</code> : raw datestamp of when the image was uploaded</li>
			<li><code>w</code> : thumbnail width (pixels)</li>
			<li><code>h</code> : thumbnail height (pixels)</li>
			<li><code>html_w</code> : <span class="caps">HTML</span>-formatted width attribute</li>
			<li><code>html_h</code> : <span class="caps">HTML</span>-formatted height attribute</li>
		</ul></li>
		<li><span class="atnm">wraptag</span> : <span class="caps">HTML</span> tag, without angle brackets, to wrap all the items with. e.g. <code>wraptag=&quot;ul&quot;</code></li>
		<li><span class="atnm">class</span> : <span class="caps">CSS</span> class name to apply to the wraptag</li>
		<li><span class="atnm">break</span> : <span class="caps">HTML</span> tag, without angle brackets, to wrap each item with. e.g. <code>break=&quot;li&quot;</code></li>
	</ul>

<h2 id="smd_if_thumbnail">Tag: <code>&lt;txp:smd_if_thumbnail&gt;</code></h2>

<p>A direct replacement for the built in <code>&lt;txp:if_thumbnail /&gt;</code> tag with exactly the same functionality. It has one attribute:</p>

	<ul>
		<li><span class="atnm">type</span> : use this attribute to check for thumbnails of the given profile name. e.g. <code>type=&quot;Medium&quot;</code>. If you do not specify this attribute, the default profile will be tested. If there is no default profile the tag will always render the <code>&lt;txp:else /&gt;</code> portion</li>
	</ul>

<h2 id="smd_thumb_how_it_works">How it works</h2>

<p>For reference, when you create a profile a directory is created with that name inside your Txp <code>images</code> folder. Inside this folder you will find images of the format <code>id.ext</code>: where <code>id</code> and <code>ext</code> match the corresponding image IDs in the Txp database. That&#8217;s pretty much it.</p>

<p>You can delete thumbnail files manually from any of these directories and the plugin will figure everything out. But it&#8217;s probably not advisable to delete the directories themselves &#8212; use the <em>[Delete]</em> buttons in the control panel for that.</p>

<h2>Author / credits</h2>

<p>Written by <a href="http://stefdawson.com/contact">Stef Dawson</a>. Many thanks to the beta test crew who offered feature and workflow advice, especially thebombsite, jakob, jstubbs and maniqui.</p>

<h2 id="smd_thumb_changelog">Changelog</h2>

	<ul>
		<li>26 Sep 2014 | 0.31 | Selected thumbnail creation for 4.6.x (thanks jpdupont)</li>
		<li>14 Jan 2013 | 0.30 | For Txp 4.5.0 ; added mem_moderation_image support ; smd_thumbnail tag has form/container support ; added smd_thumbnail_info tag ; fixed image &lt;-&gt; select list interaction (damn you attr/prop!) ; added better tooltip on thumb hover ; fixed invalid markup ; added width &amp; height attributes (thanks jstubbs)</li>
		<li>12 Oct 2011 | 0.22 | Added <code>display</code> attribute ; added &#8216;create from&#8217; preference (thanks the blue dragon/maniqui) ; fixed plugin for dashboard use ; fixed jQuery attr/prop in prefs ; fixed Txp menu interference (thanks maniqui)</li>
		<li>12 May 2011 | 0.21 | Added <code>smd_thumb_get_profiles()</code> for other plugins to find which profiles are available</li>
		<li>26 Jan 2011 | 0.20 | Tools / prefs separated from profile list ; permitted batch creation via 1) selected images 2) category 3) author (thanks jpdupont) ; added smd_thumb_auto_replace option and altered default behaviour (thanks maniqui) ; fixed Txp thumbnail creation on thumbnail replace and made prefs global &#8212; and only available to site admins (all thanks jstubbs) ; fixed New Profile button wrapping (thanks jpdupont)</li>
		<li>21 Nov 2010 | 0.14 | Permitted thumbs to be larger than the original images (thanks maniqui) ; fixed callbacks for image uploading and deleting</li>
		<li>10 Nov 2010 | 0.13 | Added confirmation on <em>Create all</em> ; relabelled upload box (thank uli) ; tamed styles ; silenced chmod warnings (thanks zero)</li>
		<li>10 Nov 2010 | 0.12 | Added ability to sync default profile thumbs with the corresponding Txp thumbnails (thanks zero)</li>
		<li>09 Nov 2010 | 0.11 | Added <code>force_size</code> and <code>add_stamp</code> (both thanks zero) ; removed unnecessary DB call</li>
		<li>04 Oct 2010 | 0.10 | Official public release</li>
		<li>06 Aug 2010 | 0.10beta | Initial beta release</li>
	</ul>