install EasyPluginInstallGuide
If you are having difficulty or getting frustrated the first and most important thing to realize is that it is not your fault. Not in the slightest. The problem lies in having poor documentation which exists because plugin authors often take plugin installation for granted. As a result, the instructions, while well intentioned, are sometimes not sufficient for all users. So here's a basic guide to installing plugins in Melody.
First off, these instructions assume that you are installing a plugin that adheres to the documented best practices for plugin packaging. To determine if the plugin you are installing adheres to this standard you will need to unzip the plugin on your local computer, which should create a new folder containing all of the files needed to run the plugin. Look inside this folder, if it contains another folder called plugins then you are in luck. If not, then this guide will be of little use to you. We encourage you to contact the plugin author and ask them to please repackage their plugin according to the documented standard, or point them to the Melody community so we can help them.
You are clearly on the right track. Now, another thing you need to know is that these instructions make frequent reference to your "$M_HOME" (aka melody) and "$M_STATIC" (aka mt-static) directories. The location of these directories will be different for virtually everyone; what is important is knowing where these directories are for you.
The $M_HOME directory is a cgi-bin directory where you have the Melody application installed. Let's look at this common example: suppose you have installed Melody into the following directory:
/var/www/cgi-bin/m
We know that this is the right directory because if you view its contents you will find within it a file called index.cgi like so:
/var/www/cgi-bin/m/index.cgi
This is your $M_HOME directory.
Now, your $M_STATIC directory is where you will find Melody's static files. Like with Melody itself, you may1 need to place the plugin's static files outside of your $M_HOME directory into a "web accessible" directory. You will know this is the case for you if you access Melody from a URL like:
http://foo.com/cgi-bin/m/index.cgi
And your images are served from a URL like:
http://foo.com/mt-static/melody/melody-logo.png
Alternatively, your system may be configured such that static files can be served directly from your cgi-bin directory like so:
http://foo.com/cgi-bin/m/mt-static/melody/melody-logo.png
Knowing how your system is configured to serve static files is essential to a successful plugin installation. To find your $M_STATIC directory, find on your system a file called mt.js. Let's suppose that your system tells you that mt.js can be found in:
/var/www/htdocs/mt-static/mt.js
Then your $M_STATIC directory is:
/var/www/htdocs/mt-static/
If your system finds more than one copy of mt.js you will need to do some sleuthing to figure out which one of these directories is in use by Melody. Hint: consult your config.cgi file; in it might be a configuration parameter that will indicate the proper path to the directory in question.
Now, let's proceed with your installation.
If you are at all familiar with using the command line, then this is without a doubt, the quickest and most straightforward solution to plugin installation:
prompt> unzip SomePlugin-1.3.zip
prompt> cp -a SomePlugin-1.3/* $M_HOME/
This will copy all of your files into the appropriate directories, including the plugin's cgi scripts, and Perl library files and sometimes even its PHP files needed to support dynamic publishing2.
And optionally, if the plugin has an mt-static folder and your system requires you to install static files into a different directory than your $M_HOME:
prompt> cp -a SomePlugin-1.3/mt-static/* $M_STATIC/
Installing a plugin on a Mac is almost identical to installing on in Unix. The only difference really is the cp command used since cp -a is not supported. So the command sequence becomes:
prompt> unzip SomePlugin-1.3.zip
prompt> cp -pR SomePlugin-1.3/* $M_HOME/
This will copy all of your files into the appropriate directories, including the plugin's cgi scripts, and Perl library files and sometimes even its PHP files needed to support dynamic publishing2.
And optionally, if the plugin has an mt-static folder and your system requires you to install static files into a different directory than your $M_HOME:
prompt> cp -pR SomePlugin-1.3/mt-static/* $M_STATIC/
If you are installing the plugin via FTP, then the instructions are similar as to the above, but you will be installing the plugin by dragging and dropping files around. Whee! Of course, your exact instructions may vary depending upon the FTP software you use, but the general gist is the same no matter what. Let's take a look:
- Unzip the plugin's zip file to your desktop.
- Start your FTP client and connect to your web server.
- In your FTP client navigate to your
$M_HOMEdirectory. - Select all of the files found in the folder created when you unzipped the plugin's archive and drag and drop them directly into your
$M_HOMEdirectory in your FTP client. Wait for all of the files to be copies. - In your FTP client navigate to your
$M_STATICdirectory. - Select all of the files found in the
mt-staticfolder found in the folder created when you unzipped the plugin's archive and drag and drop them directly into your$M_STATICdirectory in your FTP client. Wait for all of the files to be copies.
And you are finished. Granted, textual instructions like that can sometimes not be very intuitive, so check out the Melody Plugin Installation Demo screencast by Byrne Reese on Vimeo which demonstrates the instructions above more precisely:
And that's it. Hopefully this will answer the questions most people have about installing Melody plugins. If you have trouble installing one, let us know at the Melody community center so we can help.
1 - You may or may not need to perform this extra step, which depends exclusively upon how your web server has been setup. Some prefer to configure their web servers such that they can serve images and javascript file (static files) from the cgi-bin directory.
2 - Some plugins come with a set of PHP files that are used by Melody's dynamic publishing system. These files should get installed into your M_HOME/php directory, and not into your mt-static directory. But if you follow the instructions in this document, you shouldn't have to worry about this.
Questions, comments, can't find something? Let us know at our community outpost on Get Satisfaction.
- Author: Byrne Reese
- Edited by: Violet Bliss Dietz