smd_remote_file

For more information on usage, bugs, features etc, please visit the forum thread. For other software by me, or to make a donation, see the software page.

Contents

Overview

Uploading large files through TextPattern's Files tab is hit and miss depending on the size / type of file, the server limits and so on. Sometimes you just don't have the bandwidth available to host media content.

Third party sites such as fileden.com offer the ability to upload fairly sizeable files and then freely hotlink to them (within quite generous bandwidth limits) so they can be shared. Take advantage of this service by integrating the remote files into TXP with this plugin.

Features:

Before you begin

Choose a third party file hoster that offers free downloads of your stuff. Create an account, upload files to it, and make sure you know how to get Direct Link URLs from their interface (it's usually fairly obvious). You'll need these to paste into TextPattern.

Then simply install and activate the plugin, and hop over to the Files tab to get started.

The Files tab

The plugin adds one input form field to the Files tab. From your third party site(s) of choice, simply copy a web-friendly (i.e. url-encoded) hotlink and paste it into the URL box. You can usually tell if the link is url-encoded because it'll probably have %20 in place of any spaces in the filename. The directory part is, however, not usually encoded (i.e. any forward slashes and colons etc remain).

A typical file might look like this:

http://www.fileden.com/files/2007/11/1/
     1234567/Here%20is%20some%20music.mp3

The link must be an absolute URL, beginning http://. Once you have pasted it in, hit Upload next to the box and a new special 'link' file will be created in TXP. It takes on the filename exactly as it appears in your URL (with .link added). So in the example above, a new file called Here is some music.mp3.link will be made in your standard TXP files directory.

The new "file" will appear in the list just like any real file in TextPattern. You can edit it to add a description, category, set its status: everything you can do with a conventional file. Just don't rename it!

Multiple personalities

Third party sites don't give you something for nothing; they normally have a bandwidth cap, just like your web hoster probably does. If you want to distribute your music or latest video, a few thousand hits per month and your bandwidth is gone.

So spread the load around the Internet. Get accounts at various third party sites and upload exactly the same file (make sure the filenames are identical - including caSe SensITivItY). Then just paste the URLs into the upload box: smd_remote_file will only maintain one physical file within TXP but will hold details of your other copies for you. Using either the standard file_download_link or the new smd_file_download_link tag will randomly pick one of your download locations associated with each file every time the page loads, spreading your bandwidth usage.

smd_file_download_link

An exact drop-in replacement for the standard <txp:file_download_link> tag, with two extra options. Use the tag in exactly the same way as you would normally. The only subtle difference in this tag's default behaviour is that it will remove any .link on the end of the file names in the public interface (the .link suffixes always remain visible in the Files tab to remind you). The .link can be reinstated with the show_link attribute.

id

The id attribute specifies the ID of the file you want to link to. If left blank, it can be supplied from whatever is between the opening and closing tag.

filename

The filename attribute specifies the filename of the file you want to link to. If left blank, it can be supplied from whatever is between the opening and closing tag. If both filename and ID are specified, ID takes precedence.

choose

Governs how to choose which remote URL to serve. If using the standard file_download_link tag (or by default in this tag), it is set to 0 which means 'randomly pick a URL from those I've uploaded for this file' (where would an smd_ plugin be without a random option, eh?!)

You can also specify a higher number to pick the URL from that particular slot. So choose="1" will always select the 1st file you uploaded and deliver that; choose="2" the second; and so on. If you specify a number bigger than the number of URLs stored against a file, it picks the first one you uploaded.

By default this is set to 0 which hides the .link on the end of URLs. Set it to 1 to make the tag behave like the built-in file_download_link.

smd_file_download_image

When linking to external content (especially media files) it is often useful to make a mini image to go with it, such as a still from a movie or some artwork for an mp3 track. You can of course embed a <txp:image> tag in your download form, but that will give a static image for each file. This extra tag can be used to display images that vary with the filename of the remote (or local of course) file.

To use it, just upload an image (by default a jpg) via TXP's Images tab and give it the exact same filename as the remote file it represents, plus its normal image file extension. i.e. if your remote file was Man and boy.mpg you would upload an image and name it Man and boy.mpg.jpg. Do this for each file and then use this tag to display them.

By default, if any image doesn't exist, the tag outputs the image filename instead (if using the filename) or the id (if using the id). This behaviour can be overridden with the ifmissing option.

The tag accepts the following options:

id

The id attribute specifies the ID of an image to display.

filename

The filename attribute specifies the filename of an image to display. If both filename and ID are specified, ID takes precedence. Note that in this and id modes, the tag is essentially the same as <txp:image>. The exception is that you do not have to specify the image file extension (extension does that for you by default if you use JPGs) and you can specify thumbnails instead using thumb.

extension

To save you having to specify the file extension in the filename parameter, enter it here without the dot. By default it is set to extension="jpg".

thumb

By default this is set to 0 which means use the full size image. If you have created thumbnails you may use thumb="1" to use those instead.

ifmissing

When an image file is missing, this option's default setting of ifmissing="?ref" will display either the image filename or its ID if it was used. Alternatively, you can specify a dedicated 'no pic' image by uploading one and using the special code ifmissing="?image:ID_or_name" (e.g. ifmissing="?image:32" or ifmissing="?image:NoPic.jpg").

If not using the special codes, put any text you like here, for example ifmissing="No image yet". Use ifmissing="" to output nothing in the event of a missing image.

wraptag

The tag to wrap around the outside of the image. Specify it with no angle markers, e.g. wraptag="p". Defaults to empty (i.e. no wraptag).

class

The class name to apply to the image. If using wraptag the class is applied to the surrounding tag. If it is omitted the class is applied directly to the image. Default: empty (i.e. no class).

How it works

For the curious, the plugin just creates a dummy text file with the name of your file plus the special suffix .link to distinguish it from a standard file. Every time you add a URL of the same name it is added as a new line within this file.

This means you can shuffle the order of URLs, delete remote files or edit the URLs directly if you so wish by simply downloading the relevant .link file from your FTP server, editing it and re-uploading it. As long as you make sure you have one URL per line everything will work.

Incidentally, the real file size is re-read (from the 1st file listed in the .link file) every time the local file is edited because otherwise TXP overwrites it with the size of the dummy text file. This has potential ramifications when downloading because the plugin checks that the remote file size matches the one in the TXP interface before serving the file. If one of your uploaded files is a different size it will refuse to download.

The reason for this is to try to maintain download count integrity. Instead of dishing out a standard 404 message, some servers will redirect to an image or HTML file to tell you that a file is missing. This returns a status code of '200 OK' to indicate that the download of the replacement content went ok, but in this case we do not want to increment the counter; the file's still missing after all! Under rare circumstances you might find that the provider returns content exactly the same length as the file itself and the count would then be wrongly incremented. Practically, your file is going to be larger than their replacement so it won't matter.

Note that the 'download' link next to each file on the Files tab of the admin interface always chooses a random file from those uploaded with that name.

Examples

Example 1

In your files form:

<txp:file_download_link>
 <txp:file_download_name /> [<txp:file_download_size
     format="auto" decimals="2" />]
</txp:file_download_link>

Example 2

<txp:smd_file_download_link choose="2"
     show_link="1" />

Will always select the 2nd URL from those uploaded for each file. Shows the .link on the end of each remote file.

Example 3

<txp:smd_file_download_link>
 <txp:smd_file_download_image ifmissing="Sorry, no image found"
     wraptag="span" class="dload" />
</txp:smd_file_download_link>

Displays an image with the same name (plus .jpg) as the remote file. The image is clickable to allow the file to be downloaded but if the image is not found, the text "Sorry, no image found" will be displayed instead (the text is also clickable). Wraps the img or text in <span> tags with a class of dload.

Credits

I cannot possibly claim all the credit for this hunk of code. The plugin would not have existed if it weren't for the amazing mind of Ruud van Melick. He suggested a very clever solution to my remote file predicament. I built on that, extended it, refined it, pluginised it and gave it to you. Many thanks to Ruud for the awesome support he offers the community, and also to Wet for his assistance with helping me understand the core.