Smugmug extension for MediaWiki

<digg />

Overview

This extension allows embedding images from Smugmug into a MediaWiki wiki.

<smugmug>206695594|right|thumb|s|example image embedded from smugmug</smugmug>

Syntax

Based on the basic syntax for images in a wiki, the full syntax for displaying an image from smugmug is:

<smugmug>{id}|{type}|{location}|{size}|{caption}</smugmug>

OR

<smugmug id="{id}" type="{type}" location="{location}" size="{size}" caption="{caption}"></smugmug>

• {id} is required.
• {type} can be thumb, thumbnail, or frame. This controls how the image is formatted. Default is none. For between-tag parameters, do not explicitly set "none" as it would be interpreted as location.
• {location} can be left, right, center, or none: Controls the alignment of the image(s) on the page. Default is none
• {size} can be Tiny, Thumbnail, Square, Medium, Large, Original, or their short name counterparts: Ti, Th, S, M, L, O. Default is Medium
• {caption text} is the caption text

The options are not case-sensitive and can be given in any order. If a given option does not match any of the other possibilities, it is assumed to be the caption text. Caption text can probably contain wiki links or other formatting, (not tested yet).

Caption text will default to the caption on Smugmug, or the keywords on Smugmug if the caption does not exist.

Options given as attributes will override options between the tags.

Examples

<source lang="xml"> <smugmug>206695566</smugmug> </source>

Display a medium-sized photo with no formatting

<source lang="xml"> <smugmug>206695594|right|thumb|s</smugmug> </source>

Display a small-sized photo on the right in a thumbnail frame

<source lang="xml"> <smugmug id="206695594" location="right" type="thumb" size="s"></smugmug> </source>

Same as above, but with parameters given as attributes instead of between tags

Finding the Photo ID

This screenshot shows where to find the Photo ID for an image on Smug Mug. View the image you want, and then check the URL. Between the # and _ is the Photo ID.

<smugmug>470987257|Thumb|small</smugmug>

Requirements

Smugmug extension for MediaWiki requires

1. an installation of MediaWiki
2. Colin Seymour's PHP wrapper, phpSmug

Installation

1. Download phpSmug and install it on your server. Don't worry about "Usage" on the phpSmug page, but of course you'll need to remember where you installed it.
   • (This is probably overkill on details, but here's my Log of installation of phpSmug.)
2. Get a smugmug API key
   • Name: Smugmug extension for MediaWiki
   • Type: Plug-in
   • Platform: All
   • Use: Non-Commercial
   • Description:
     • if you will only make changes as described on this page, just use http://robnugen.com/wiki/index.php?title=Smugmug_extension_for_MediaWiki
     • otherwise, write whatever is appropriate for you. I'd love to get a note on how you are using it!
3. Copy the source code below into a file in your extensions directory: (e.g. wiki/extensions/Smugmug.php)
4. overwrite PATH TO YOUR LOCAL phpSmug in Smugmug.php with the location you chose in step 1
5. overwrite COPY YOUR SMUGMUG API KEY HERE in Smugmug.php with your new API key from step 2
6. Add the following line to the bottom of your MediaWiki's LocalSettings.php file:
   • <source lang="php">require_once("$IP/extensions/Smugmug.php");</source>

Source Code

The source at Smugmug.php.txt is guaranteed to have been written by me, and will be the latest "stable release." The source code below is all beautifully marked up, but may have been altered by a bunch of monkeys with wiki web browsers, so be warned. Of course, they may have fixed some bugs! -Thunder Rabbit 22:17, 7 November 2007 (PST)

See beta versions for how to get my latest and buggiest beta versions. Yum!

<source lang="php"> <?php

1. Smugmug MediaWiki extension
3. This code is licensed under the Creative Commons Attribution-ShareAlike 3.0 License
4. http://creativecommons.org/licenses/by-sa/
6. For attribution or more information please use
7. http://robnugen.com/wiki/index.php?title=Smugmug_extension_for_MediaWiki

$_smugmug_version = "v0.10 first public release";

$phpSmug_include = "PATH TO YOUR LOCAL phpSmug"; // (e.g. "phpSmug-1.0.2/phpSmug.php") (download at http://www.lildude.co.uk/projects/phpsmug/) $smugmug_api_key = "COPY YOUR SMUGMUG API KEY HERE";

// below is optional (though recommended) to improve performance through caching. // See http://www.lildude.co.uk/projects/phpsmug/docs/ for details. $phpSmug_cache_enabled = false; // set this to true and set the next variables appropriately. $phpSmug_cache_type = ""; // "db" for database, "fs" for filesystem $phpSmug_cache_connection = ""; // mysql://user:password@server/database or /absolute/path/of/existing/directory/ //$phpSmug_cache_expire = ""; // optional. This is the maximum age of each cache entry in seconds. Default is 600 //$phpSmug_cache_table = ""; // optional. Name of the table in db (if type is "db"). Default is "smugmug_cache"

// *** For the casual user, you shouldn't have to edit anything below this line ***

require_once($phpSmug_include);

$wgExtensionFunctions[] = 'wfSmugmug'; $wgExtensionCredits['parserhook'][] = array(

       'name' => 'Smugmug extension for MediaWiki',
       'description' => 'Display Smugmug images in installations of MediaWiki',
       'author' => 'Rob Nugen',
       'url' => 'http://robnugen.com/wiki/index.php?title=Smugmug_extension_for_MediaWiki'

);

function wfSmugmug() {

       global $wgParser;
       $wgParser->setHook('smugmug', 'renderHTML');

}

1. The callback function for converting the input text to HTML output

function renderHTML($input, $params) { # $input is what's between the tags, and $params are the modifiers inside the first tag: # <smugmug param1="value1" param2="value2">input</smugmug>

// use the global values (defined above) for these variables global $smugmug_api_key, $phpSmug_cache_enabled, $phpSmug_cache_type, $phpSmug_cache_connection, $phpSmug_cache_expire, $phpSmug_cache_table;

// these parameters have defaults if nothing is specified $smugmug_default_type = "none"; // override with <smugmug type="thumb|frame"> $smugmug_default_idtype = "image"; // override with <smugmug idtype="album"> $smugmug_default_location = ""; // override with <smugmug location="left|center|none|right"> $smugmug_default_size = "medium"; // override with <smugmug size="ti|th|s|l|o">

// these are allowable values for the various parameters. There should be *no repetition* of allowable values here, otherwise the parameter reading won't work correctly. // If there must be repetition here, then specify the parameter values via attributes in the tag, and you should have no problem $valid_smugmug_idtypes = array("album"); $valid_smugmug_types = array("thumbnail", "thumb", "frame"); $valid_smugmug_locations = array("right", "left", "center", "none"); $valid_smugmug_sizes = array("tiny", "thumb", "small", "medium", "large", "original");

// keys in these arrays should point to values that exist in the corresponding arrays above. $other_spellings_of_types = array ("thumbnail" => "thumb", "thumnail" => "thumb"); $other_spellings_of_sizes = array ("ti" => "tiny", "th" => "thumb", "s" => "small", "m" => "medium", "med" => "medium", "l" => "large", "o" => "original", "orig" => "original");

// allow the other spellings of the arrays to be found in the parameters. There should be a line here for each of the "other_spellings" arrays above $valid_smugmug_sizes = array_merge($valid_smugmug_sizes, array_keys($other_spellings_of_sizes)); $valid_smugmug_types = array_merge($valid_smugmug_types, array_keys($other_spellings_of_types));

/***************************************************************************************************************************************************************

The arrays above define the parameters that we'll be using below. You should be able to tweak a lot without changing anything below this line.

Now we start looking for parameters sent by the wiki

****************************************************************************************************************************************************************/

// if they exist, the parameters sent as attributes override the parameters sent <smugmug>between the tags</smugmug>, so grab them first. // Then we must be sure not to overwrite existing values for these variables. $_smugmug_id = $params['id']; $_smugmug_type = $params['type']; $_smugmug_idtype = $params['idtype']; $_smugmug_location = $params['location']; $_smugmug_size = $params['size']; $_smugmug_caption = $params['caption'];

       # split the text sent <smugmug>between the tags</smugmug> on |
       $inputs = explode("|", $input);

# process the inputs, basically comparing them to the arrays set above to determine for which parameter their value should be used. foreach($inputs as $value) { if ($_smugmug_id == "" && ctype_digit($value)) { $_smugmug_id = $value; /* if the value is all digits, it must be the id */ } elseif ($_smugmug_type == "" && in_array(strtolower($value), $valid_smugmug_types)) { $_smugmug_type = strtolower($value); } elseif ($_smugmug_idtype == "" && in_array(strtolower($value), $valid_smugmug_idtypes)) {$_smugmug_idtype = strtolower($value); } elseif ($_smugmug_location == "" && in_array(strtolower($value), $valid_smugmug_locations)) { $_smugmug_location = strtolower($value); } elseif ($_smugmug_size == "" && in_array(strtolower($value), $valid_smugmug_sizes)) { $_smugmug_size = strtolower($value); } elseif ($_smugmug_caption == "") { $_smugmug_caption = $value; } // everything else is caption else { $_smugmug_caption .= "|".$value; } // this allows caption to have | chars in it }

// finally, if none of the above worked, fill in the defaults if($_smugmug_type == "") { $_smugmug_type = $smugmug_default_type; } if($_smugmug_idtype == "") { $_smugmug_idtype = $smugmug_default_idtype; } if($_smugmug_location == "") { $_smugmug_location = $smugmug_default_location; } if($_smugmug_size == "") { $_smugmug_size = $smugmug_default_size; }

// We have all the parameters as sent by the user (actually they have been lowercased). // Now convert them to allowable values according to the other_spellings arrays if(is_array($other_spellings_of_types) && isset($other_spellings_of_types[$_smugmug_type])) { $_smugmug_type = $other_spellings_of_types[$_smugmug_type]; } if(is_array($other_spellings_of_idtypes) && isset($other_spellings_of_idtypes[$_smugmug_idtype])) { $_smugmug_idtype = $other_spellings_of_idtypes[$_smugmug_idtype]; } if(is_array($other_spellings_of_locations) && isset($other_spellings_of_locations[$_smugmug_location])) { $_smugmug_location = $other_spellings_of_locations[$_smugmug_location]; } if(is_array($other_spellings_of_sizes) && isset($other_spellings_of_sizes[$_smugmug_size])) { $_smugmug_size = $other_spellings_of_sizes[$_smugmug_size]; }

       # Now make sure we have the one required parameter: id
       if (!isset($_smugmug_id)) {
               $output = "";
               return $output;
       }

$f = new phpSmug($smugmug_api_key, "http://robnugen.com/wiki/index.php?title=Smugmug_extension " . $_smugmug_version); if($phpSmug_cache_enabled) { if($phpSmug_cache_expire == "") { $phpSmug_cache_expire = 600; } // set this value if it's not set above if($phpSmug_cache_table == "" && $phpSmug_cache_type == "db") { $phpSmug_cache_table = "smugmug_cache"; } // set this value if it's not set above $f->enableCache($phpSmug_cache_type, $phpSmug_cache_connection, $phpSmug_cache_expire, $phpSmug_cache_table); } $f->login_anonymously();

$image_info = $f->images_getInfo($_smugmug_id);

// It makes no sense to have a default caption for all pictures, so the default will be whatever is set on smugmug servers if ($_smugmug_caption == "") { $_smugmug_caption = $image_info['Caption']; } if ($_smugmug_caption == "") { $_smugmug_caption = $image_info['Keywords']; } // use the keywords if there was no caption

/*********************************************************************************************************************************************

From here, we are just basically mimicking the code in ../includes/Linker.php

However, I have skipped the Right To Left languages, and skipped vertical alignment options

*********************************************************************************************************************************************/ // Clean up our output strings $prefix = $postfix = $s = ;

if ($_smugmug_location == 'center') {

$prefix = '

'; $postfix = '

';

$_smugmug_location = 'none'; // This 'none' value will be used in subsequent div class (same as Linker.php) }

if ($_smugmug_idtype == "image") {

// best I can tell, this matches Linker.php except for valign parameters if ($_smugmug_type == "none") { $size_url_key = ucfirst($_smugmug_size) . "URL"; // for example "LargeURL" $s = "<a href=\"{$image_info['AlbumURL']}\" class=\"image\" title=\"{$_smugmug_caption}\"><img src=\"{$image_info[$size_url_key]}\" alt=\"{$_smugmug_caption}\"></a>"; if ($_smugmug_location != ) {

$s = "

{$s}

";

} return str_replace("\n", ' ',$prefix.$s.$postfix); } else { // basically we are in $_smugmug_type = "frame" or "thumb" if($_smugmug_location == "") { $_smugmug_location = 'right';} // This 'right' value will be used in subsequent div classes (same as Linker.php)

switch($_smugmug_size) { case "tiny": $outerWidth = min($image_info['Width'] + 2, 102); break; case "thumb": $outerWidth = min($image_info['Width'] + 2, 152); break; case "small": $outerWidth = min($image_info['Width'] + 2, 402); break; case "medium": $outerWidth = min($image_info['Width'] + 2, 602); break; case "large": $outerWidth = min($image_info['Width'] + 2, 802); break; case "xlarge": $outerWidth = min($image_info['Width'] + 2, 1026); break; case "x2large": $outerWidth = min($image_info['Width'] + 2, 1282); break; case "x3large": $outerWidth = min($image_info['Width'] + 2, 1602); break; case "original": $outerWidth = $image_info['Width'] + 2; break; }

$s = "

";

// this basically matches Linker.php. Check that code for documentation. Oh wait! There is none! $size_url_key = ucfirst($_smugmug_size) . "URL"; $s .= "<a href=\"{$image_info['AlbumURL']}\" class=\"image\" title=\"{$_smugmug_caption}\">" . "<img src=\"{$image_info[$size_url_key]}\" alt=\"{$_smugmug_caption}\" class=\"thumbimage\"></a>";

if ($_smugmug_type == 'frame') { // type="frame" just gets a frame $zoomicon=""; } else { // type="thumb" gets a cute little zoom icon global $wgStylePath;

$zoomicon = '

' .

'<a href="' . $image_info[$size_url_key] . '" class="internal" title="Enlarge">'.

'<img src="'.$wgStylePath.'/common/images/magnify-clip.png" width="15" height="11" alt="" /></a>

';

}

$s .= '

'.$zoomicon.$_smugmug_caption."

"; // closes the divs for class="thumbcaption", class="thumb t..", and class="thumbinner"

return $s; } // close $_smugmug_type != "" } // Matches if ($_smugmug_idtype == "image") elseif ($_smugmug_idtype == "album") { return "Smugmug.php doesn't yet support display of albums." . "
Visit the <a href=\"http://robnugen.com/wiki/index.php?title=Smugmug_extension\">Smugmug_extension</a> site to make sure you have the latest version." . "
If so, contact smugmug.php (AT) robnugen (DOT) com to encourage him to make it!"; }

} ?> </source>

Versions

stable releases

2007 Nov 07: v0.10 first public release (images only; no album support)

beta versions

Presumably, I'll be continually tweaking this code as I have time and interest. I'll put beta versions on Smugmug extension for MediaWiki: beta versions