smd_remote_file

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.

Contents

• Features
• Author
• Installation / Uninstallation
• Pre-requisites
• The Files tab
• Multiple personalities
• Tag usage
  • smd_file_download_link
  • smd_file_download_name
  • smd_file_download_image
• How it works
• Examples
• Changelog
• Credits

Features

• Manage links to third party files directly from the TXP Files tab, as if they were natively inside TextPattern. Category / description / status / download count all supported
• Use standard <txp:file_download_list /> tags to build lists of local and remote files
• Three new tags: <txp:smd_file_download_link> for choosing specific remote files, <txp:smd_file_download_name> for showing remote file names and <txp:smd_file_download_image> for showing images based on the filename of the download
• Upload identical files to more than one place on the web and tell TXP the various alternatives. file_download_link and smd_file_download_link will choose a random location to help load-balance your available bandwidth
• No modifications to the TXP database: just a beautiful cheat suggested by ruud (thanks!)

Author

Stef Dawson. For other software by me, or to make a donation, see the software page.

Installation and Uninstallation

Requires TextPattern v4.0.6 or greater installed.

Download the plugin from either textpattern.org, or the software page, paste the code into the TXP Admin -> Plugins pane, install and enable the plugin. Visit the forum thread for more info or to report on the success or otherwise of the plugin.

To remove the plugin, simply delete it from the Admin->Plugins tab.

Pre-requisites

Choose any 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 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.

When you select a .link file for editing from the Files tab, you will see a dialog box at the bottom for adding more URLs to your file. Paste the url-encoded direct link file name into the box and hit Upload to append it to the existing one. If you check the Overwrite box then the URL you supply will overwrite all URLs currently defined in the file. It does this without warning, so consider this a warning!

Tag 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.

Attributes

• id : 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 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.
• show_link : set to 0 by default, 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_name

An exact drop-in replacement for the standard <txp:file_download_name> tag, but with one attribute. This tag’s default behaviour will remove any .link on the end of file names.

Attributes

• show_link : set to 0 by default, which hides the .link on the end of file names. Set it to 1 to make the tag behave like the built-in file_download_name

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 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.

Attributes

• id : the ID of an image to display
• filename : 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, as it does that for you by default if you use JPGs and you can specify thumbnails instead using thumb
• extension : saves 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 : set to 0 by default, 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.

Known issue: If editing a “normal” file (not a .link) and you hit the Upload button without specifying a file, the URL upload box does not appear on the File List page. Hitting the Files tab again or performing some other action re-instates it. *shrug*

Examples

Example 1

In your files form:

<txp:file_download_link>
 <txp:smd_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.

Changelog

• 12 Nov 07 | 0.1 | Initial release
• 04 Dec 07 | 0.2 | Added download counter and some better status messages
• 04 Dec 07 | 0.3 | Removed .link when using smd_file_download_link ; added show_link attribute ; improved error handling code ; download count only increases if file sizes match
• 05 Dec 07 | 0.31 | File is checked for error condition prior to download in line with core changeset r2720 (thanks Mary) – can be removed when 4.0.6 is released
• 12 Dec 07 | 0.32 | Enhanced ifmissing to include image support; changed the ?file attribute to ?ref (it’s a better name)
• 03 Feb 08 | 0.4 | Requires TXP 4.0.6 ; removed error check from v0.31 ; added/improved replace remote file ; reduced timeout for accessing remote URL to try and prevent ugly warnings
• 02 Apr 08 | 0.41 | Added smd_file_download_name (thanks aswihart)
• 09 Apr 08 | 0.42 | Fixed minor edge case bug in smd_file_download_link
• 10 Jun 08 | 0.43 | Fixed spurious characters in the single tag version of smd_file_download_link (thanks iblastoff)

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.