Plugin: Random File

This plugin has been updated! Comments to this post are now closed. For the latest download, documentation, and link for posting new comments related to this plugin, visit the plugin’s new homepage at:
coffee2code.com/wp-plugins/random-file
Name:
Random File
Author:
Scott Reilly
Version:
1.0
Last updated:
25 March 2005
Description:

Retrieve the name of a randomly chosen file in a given directory. Useful for displaying random images/logos or including text from random files onto your site (writing excerpts, multi-line quotes, etc).

Notes:

– If you want to actually display the name of the random file, be sure to ‘echo’ the results:
<?php echo c2c_random_file('/random'); ?>

– The directory of random files must exist at the directory structure level of your WordPress installation or below. (i.e., if your site is installed on your server at /usr/local/htdocs/yoursite/www/journal/, then the directory of random files you specified will assume that as its base… so $dir=’randomfiles’ would be assumed to actually be:
/usr/local/htdocs/yoursite/www/journal/randomfiles/)

– $extensions can be a space-separated list of extensions (case insensitive), i.e. ‘jpg gif png jpeg’

– Unless you limit the file search to only include a particular $extension, all files in the specified $dir will be under consideration for random selection.

– The reference to the randomly selected file can be returned in one of four ways: ‘absolute’, ‘serverabsolute’, ‘url’, or ‘filename’

– Can be run inside or outside of “the loop.”

Installation:
  1. Download the file random-file.zip and unzip it into your /wp-content/plugins/ directory.
    -OR-
    Copy and paste the the code ( random-file.phps ) into a file called random-file.php, and put that file into your /wp-content/plugins/ directory.
  2. Activate the plugin from your WordPress admin ‘Plugins’ page.
  3. Add a call to the function to your template (see examples below).
Functions:

function c2c_random_file( $dir, $extensions='', $reftype='relative', $exclusions='' )

  • $dir : The directory of random files must exist at the directory structure level of your WordPress installation or below. (i.e., if your site is installed on your server at /usr/local/htdocs/yoursite/www/journal/, then the directory of random files you specified will assume that as its base… so $dir=’randomfiles’ would be assumed to actually be: /usr/local/htdocs/yoursite/www/journal/randomfiles/)

    Leading and trailing ‘/’ are unnecessary… ‘/randomfiles/’ == ‘/randomfiles’ == ‘randomfiles/’ == ‘randomfiles’

  • $extensions : space-separated list of extensions (case insensitive), i.e. ‘jpg gif png jpeg’

    Unless you limit the file search to only include a particular $extension, ALL files in
    the specified $dir will be under consideration for random selection

  • $reftype : The reference to the randomly selected file can be returned in one of three ways:
    [Assume your WordPress installation is at http://www.yoursite.org/journal/ and you’ve
    invoked c2c_random_file(‘random/’, ‘txt’, $reftype)]

    $reftype = ‘absolute’
    => An absolute location relative to the primary domain:
    /journal/random/randomfile.txt
    [This is the default setting as it is the most applicable. Absolute referencing is necessary if
    the random file is to be used as an argument to include() or virtual(). It’s also a valid way
    to reference a file for A HREF= and IMG SRC= linking.]

    $reftype = ‘serverabsolute’
    => An absolute location relative to the root of the server’s file system:
    /usr/local/htdocs/yoursite/www/journal/random/randomfile.txt

    $reftype = ‘url’
    => The URL of the random file:
    http://www.yoursite.org/journal/random/randomfile.txt
    [If you desire the use of full URL, such as for a A HREF= or IMG SRC= link.]

    $reftype = ‘filename’
    => The filename of the random file:
    randomefile.txt

  • $exclusions: optional; if specified it MUST be an array of filenames to exclude from consideration as a random file
Tips & Examples:

// Include random logo or image on your site:

<img alt="logo" class="logo" src="<?php echo c2c_random_file('/wp-content/images/logos/'); ?>" />

// Insert text from a random file (i.e. for random multi-line quotes):

<blockquote class='todayquote'> <?php virtual(c2c_random_file('/quotes/', 'txt')); ?> </blockquote>

// If you wanted to source a random .php file

<?php include(c2c_random_file('/randomphp', 'php')); ?>

// If you wanted to show three random (and different) images

<?php $files = array(); for ($i=1;$i<=3;$i++) { $file = c2c_random_file('/wp-content/images/', 'jpg png gif', 'url', $files); echo '<img src="' . $file . '" alt="Random image #' . $i . '" />'; $files[] = $file; } ?>

Release Log:
  • 25 Mar 2005 : v1.0 —
    • Renamed function from random_file() to c2c_random_file()
    • Added new reftype of ‘filename’
    • Added optional array argument $extensions for files not to be considered in random file selection
    • Updated license and examples
    • Verified that plugin works in WP 1.5 (and still works in WP 1.2)
  • 08 Jul 2004 : v0.9 — Released to the public
Copyright & Disclaimer:

Copyright (c) 2004-2005 by Scott Reilly (aka coffee2code)

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Acknowledgements:
I’d like to thank Matt Mullenweg, whose Random Image Script I came across after I was most of the way into making this plugin and which provoked a couple worthwhile considerations (among which was that I should support multiple extensions).

56 thoughts on “Plugin: Random File

  1. I would like to install this script on my server to rotate php articles. As i a newbie in this game i cant seem to get it to work… i have created a folder called randomphp under wp-content and i have inserted the code on my page but nothing seems to come up. pls help. This is a very useful script.

    PS i installed and activated the script already

Comments are closed.