We're now going to take a look at WacsUI module's most important function, iconlink. It's job is simply to display and icon with an appropriate link around it. Sounds simple enough, doesn't it? Unfortunately it isn't - there's a lot of work that needs to be done relating to permissions, access methods, checking caches and resizing which actually makes it fairly complex. The good news is that the iconlink function will do it all for you!

The iconlink function takes quite a few arguments which control how it works, but they are reasonably straightforward. In most cases parameters are optional and sensible defaults will be used instead if they are not given - obviously things like set number and the location fields (sarea, scategory and sdirectory) are necessary.

print $wacsui->iconlink(
	array( 'type'=>$setdetails[1],
	       'setno'=>$setdetails[0],
	       'sarea'=>$setdetails[2],
	       'scategory'=>$setdetails[3],
	       'sdirectory'=>$setdetails[4],
	       'model'=>$moddetails[1],
	       'resize'=> 0,
	       'silent'=> 'y' ))."\n";

	Note
	Note the silent attribute being set to 'y' - this tells the function not to print the result to stdout. If you set silent to 'n' you don't need to use print iconlink() you can just call iconlink() within your code. Generally it is considered better practice to print the return value from the function call, but with these three functions that choice is yours.

The perl dialect is again very much the same:

print iconlink( type=>$setdetails[1],
                setno=>$setdetails[0],
                sarea=>$setdetails[2],
                scategory=>$setdetails[3],
                sdirectory=>$setdetails[4],
                model=>moddetails[1],
                resize=> 0,
                silent=> 'y' ))."\n";

The thumblink function works very much the same as iconlink does and provides a way to produce thumbnail images from a photoset or any of a number of additional icon images (typically thumbnails from a movie) for a video clip. It is slightly different from iconlink in that since the cache of set thumbnails is organised by set number and not area, category, etc, it needs on the set number, image number and type to function.

print $wacsui->thumblink(
        array( 'setno'=>$setdetails[0],
               'stype'=>$setdetails[1],
               'imgno'=>$imgnumber,
               'resize'=>1,
               'silent'=>'y' ))."\n";    

And of course using it in Perl is much the same:

print thumblink( setno=>$setdetails[0],
                 stype=>$setdetails[1],
                 imgno=>$imgnumber,
                 resize=>1,
                 silent=>'y' )."\n";

The final one of the three link functions, again joining the WACS API reportoire in release 0.9.1, is contentlink. Once again this is similar to thumblink in not needing the full path within the collection as the cache mechanism it refers to is organised by set number. As with the other two members of the link family, it falls back gracefully to the old methods of content delivery if it cannot find a cached version of the desired content, so you can and should use it at all times for content link delivery.

As usual we specify both the set number and the set type, plus you also have the option by using the silent parameter as to whether it should print out the link text it creates or merely return the necessary text as the return variable from the function call. It's also good practice to specify the desired name for the download file using the archive parameter. Normally this name can simply be taken from the sdownload field in the sets database. If this variable is empty, it will default to set1234.zip or set1235.wmv as appropriate.

We do usually specify the srank parameter too, although it will function without it, to clarify the relationship of this set to other things. The ext (for extension) is the file name extension of this file - ie .zip, .wmv, .mov and .mpg . As shown in the example below, passing the scodec field from the database via the getvideoext function should work right for videos.

The one rather odd parameter here is serve - this specifies which type of file you would like on those occasions where there is a choice. For some sets, the cache system holds both an original version and a compilation or edited version comprising either the combination of a number of seperate parts of a video clip, or a video clip with the leading declarations trimmed so as not to disturb the viewing experience. In these cases, if you want the compilation or edited version where are available, you set serve to cooked and where you want the vanilla unaltered file you set serve to raw.

print $wacsui->contentlink(
        array( 'setno'=>$setdetails[0],
               'stype'=>$setdetails[1],
               'srank'=>$setdetails[2],
               'ext'=> $wacsui->getvideoext( $setdetails[3] ),
               'serve'=>'cooked',
               'archive'=>$setdetails[4],
               'silent'=>'y' ))."\n";    

As usual, the perl dialect version of this command is almost identical in how you call it:

print contentlink( setno=>$setdetails[0],
                   stype=>$setdetails[1],
                   srank=>$setdetails[2],
                   ext=> getvideoext( $setdetails[3] ),
                   serve=>'cooked',
                   archive=>$setdetails[4],
                   silent=>'y' )."\n";

	Note
	The content cache, unlike the icons or thumbnail caches, is NOT self-maintaining. You need to take actions to create the cached versions in the first place - please see the administration manual for more information about how to use wacscachectl to do this