Random File

Author:Scott Reilly
Version:1.5
Last update:05 April 2008
Compatibility:WP 1.5+, 2.0+, 2.1+, 2.2+, 2.3+, and 2.5+
Comments:go here
Download:[ zip ]
Description:

Retrieve the name, path, or link to a randomly chosen file in a specified directory.

Extended Description

Useful for displaying random images/logos or including text from random files onto your site (writing excerpts, multi-line quotes, etc).

  • If you want to actually display the name of the random file, be sure to ‘echo’ the results:
    <?php echo c2c_random_file('/random'); ?>
  • Unless you limit the file search to only include a particular extension (via $extensions argument), 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 five ways:
    [Assume your WordPress installation is at www.yoursite.org/journal/ and you've invoked c2c_random_file('random/', 'txt', $reftype)]

    • $reftype = ‘relative’
      => A location relative to the primary domain:
      /journal/random/randomfile.txt
      [This is the default setting as it is the most applicable. Relative 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 = ‘absolute’
      => 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
    • $reftype = ‘hyperlink’
      => The filename of the random file hyperlinked to that random file:
      <a href='http://yoursite.org/journal/random/randomfile.txt' title='randomfile.txt'>randomfile.txt</a>
  • 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.
  2. Activate the plugin through the ‘Plugins’ admin menu in WordPress.
  3. Make use of the c2c_random_file() template function in your template (see examples below).

Template Tag

The plugin provides one optional template tag for use in your theme templates.

Function

<?php function c2c_random_file( $dir, $extensions='', $reftype='relative', $_exclusions='' ) ?>
This retrieves the name of a random file from a specified directory and returns information based on the file according to the $reftype value.

Arguments

  • $dir

    The directory to search for a random file. The directory 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 a value of ‘randomfiles’ would be assumed to actually be: `/usr/local/htdocs/yoursite/www/journal/randomfiles/`)

  • $extensions

    Optional argument. A space-separated list of extensions (case insensitive), i.e. ‘jpg gif png jpeg’.

  • $reftype

    Optional argument. Can be one of the following: ‘relative’ (which is the default), ‘absolute’, ‘url’, ‘filename’, ‘hyperlink’. See Examples section for more details and examples.

  • $_exclusions

    Optional argument. If specified, MUST be an array of filenames to exclude from consideration as a random file.

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) (Apache web-server only, probably): 

    <blockquote class='todayquote'>
   <?php virtual(c2c_random_file('/quotes/', 'txt')); ?>
</blockquote>
  • If you wanted to source a random .php file

Frequently Asked Questions

  • Q: Does this plugin do dynamic random rotation within a loaded page (i.e. randomly rotating images within a loaded page)?

    A: No. This plugin only selects a random file when the page is loaded. Once loaded, it does not currently add any dynamic functionality to automatically retrieve another random file on its own.


Release Log

  • 05 Apr 2008 : v1.5 - Release notes
  • NOTE: documentation and discussion about versions of this plugin prior to v1.5 can be found here
  • 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 © 2004-2008 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

Thanks to all those who have contributed feedback and support!