Using an external configuration file
An external configuration file ( wimpyConfigs file) allows you to customize Wimpy using an external file rather than including the configuration options directly within the HTML code that displays the player.
Using a wimpyConfigs file is intended for advanced users who are familiar with editing HTML and XML by hand.and provides a means for to quickly set up a new player instance without having to use the Customizer Tool.
There are three ways that a wimpyConfigs file can be used.
1. To configure the default server-side behavior.
If a file named "wimpyConfigs.xml" (case sensitive) exists within your Wimpy installation folder all of the server-side specific settings will be applied to ALL player instances that rely on wimpy.php to provide a playlist.
The following "server-side" options will be applied to all player instances:
- Startup folder
- Hide files
- Hide folders
- Directory cover art file name
Setting up a default wimpyConfigs file does not mean that all players will take on player-specific settings, such as skin, "start playing immediately", "random track at start up", etc -- only server-side settings will be applied to all players that are running in "automatic" mode where the Wimpy Script (wimpy.php/asp/cfm) is used to provide players with a playlist.
When using a wimpyConfigs file to control server-side settings, only one wimpyConfigs file can be used.
To configure the default server-side behavior / default player, follow the instructions below for creating a wimpyConfigs file below, then upload the resulting file to your Wimpy installation folder.
NOTE: The wimpyConfigs.xml file must be located in the same folder as wimpy.php/asp/cfm and the name "wimpyConfigs.xml" should not be changed. (Case sensitive)
2. To establish a default player.
If a wimpyConfigs file is present in your Wimpy installation folder, you can simply navigate directory to wimpy.php/asp/cfm with a web browser. The resulting player will automatically take on the settings as defined within the wimpyConfigs file.
HINT: If a wimpyConfigs file is present in your Wimpy installation folder, and you go directly to wimpy.php/asp/cfm, then you review the source code you will see something similar to:
You can use this code throughout your site to quickly render Wimpy within a page.
3. To configure separate instances of a player.
You can generate any number of wimpyConfig files to configure player instances. These independent wimypConfig files can be used to control only player-specific options, such as: skin, "start playing immediately", "random track at startup", and other player-specific options.
For example, wimpyConfigs_A.xml can be applied to a player that uses a small skin and doesn't start to play when loaded, and wimpyConfigs_B.xml can be applied to another player that uses a bigger skin and starts to play immediately.
The process of running Wimpy off of an external configuration file is a two-step process.
1. Create a configs file
2. Generate HTML code (to "apply" the WimpyConfigs file to the player)
The Customizer tool is used to accomplish both steps. This means that we'll be using the Customizer tool two times, once to generate the config file and the second time to generate the HTML code.
Create a configs file
These instructions assume:
- You have already installed (uploaded) Wimpy.
- Are using the "PHP" version. If you are using the ASP or ColdFusion version, replace "wimpy.php" with "wimpy.asp" or "wimpy.cfm" respectively throughout these instructions.
1. Use the Customizer tool and set options as desired.
In the "Wimpy Script Configuration" section click the checkbox for "Download a wimpyConfigs.xml file" then scroll to the bottom of the page and click "Download" and save the wimpyConfigs.xml file to your PC.
NOTE: When using the Customizer tool, be sure that you click the "test" link next to each URL that you enter to ensure that you are using the proper address.
NOTE: If you are using a skin that uses a background image, be sure that you have uploaded the background image to the same folder as the skin_name.xml file.
Generate HTML code
These instructions will explain how to create HTML code to run separate instances of Wimpy off of separate wimpyConfig files.
1. Upload the resulting wimpyConfigs file to your website
NOTE: The file can be uploaded to any location on your site. It does not have to be within your Wimpy Installation folder. You are are also free to use any file name you wish for the wimpyConfigs file.
2. Use the Customizer tool again but this time:
- In the Wimpy Script Configuration Section, uncheck the option to "Download a wimpyConfigs.xml file."
- In the Advanced Section, check the option to Apply my "wimpyConfigs.xml" file: "
- Download the resulting "myWimpy.html" file to your local PC, then upload it to your server and test.
The resulting myWimpy.html file apply's the wimpyConfigs.xml file in the HTML as:
<object classid="clsid:D27CDB6E-AE6D-11cf-96B8-444553540000" codebase="http://download.macromedia.com/pub/shockwave/cabs/
flash/swflash.cab#version=6,0,47,0" width="480" height="140" id="wimpy">
<param name="movie" value="http://www/path/to/wimpy.swf" />
<param name="loop" value="false" />
<param name="menu" value="false" />
<param name="quality" value="high" />
<param name="scale" value="noscale" />
<param name="salign" value="lt" />
<param name="bgcolor" value="#660033" />
<param name="flashvars" value="wimpyConfigs=http://www/path/to/wimpyConfigs_A.xml" />
width="480" height="140" bgcolor="#660033" loop="false"
menu="false" quality="high" scale="noscale" salign="lt"
id="wimpy" align="middle" allowScriptAccess="sameDomain"
... which is a little different from the standard way that options are configured. Traditionally, options are set using the Customizer tool as:
<param name="flashvars" value="wimpyApp=http://www.yoursite.com/mp3s/wimpy.php
As you can see, in the traditional method, options are established within the HTML code. When using an external wimpyConfigs file, a reference to a wimpyConfigs.xml file is used instead.
The added benefits are that you can edit the options for each player using an external file rather than editing your HTML code. And you can apply different setting to different players depending on your needs.
It should be noted that using an external configuration file will not automatically adjust the width and height of the player. Width and height can only be controlled through HTML. However, if you use the Customizer tool to apply a wimpy Configs file, the Customizer tool will attempt to automatically read the skin dimensions from the skinFile defined in your wimpyConfigs file.
It should be also noted that if you plan on editing the HTML code manually, Flash HTMl code uses both an <object> and <embed> tag to define ONE instance of a player, the <object> tag is used for Internet Explorer based browsers and the <embed> tag is used for Mozilla-based browsers, so you must edit both the <object> and <embed> tag for each instance of a player in your HTML code.
A wimpyConfigs file is an XML file that contains all of the available configuration options for the player. Information about each configuration option is explained in the API section of the documentation.
The format for a wimpyConfigs file is set up as follows:
Where config_option_name is set to a pre-defined configuration option name, and "option value" is set to either a pre-defined value (such as "yes" or "no") or to an acceptable value such as a URL, or other custom setting.
Here is an exampe of a wimpyConfigs.xml file:
<?xml version="1.0" encoding="UTF-8"?>
<!-- File Paths -->
<!-- Client Side -->
<!-- Server Side -->
<!-- Cover Art -->
<!-- HTML display -->
<!-- Dual Purpose -->