Big Medium 2 Installation Guide

Big Medium and Global Moxie are trademarks of Global Moxie LLC. All rights reserved.


Table of Contents

Quick Start
Server Requirements
Image library strongly recommended
Browser Compatibility
Big Medium control panel
Your public website
Installation Checklist
Upgrading from Big Medium 1.x
Preparing the Big Medium files
Preparation for Unix-based servers
Preparation for Windows servers
About File Permissions
Permissions on Unix
Permissions on Windows
Upload the Files to the Server
Upload the moxiebin directory
Upload the moxiedata directory
Upload the bmadmin directory
Set Permissions on the HTML Directory
Run the Updater Script
Set up the Maintenance Script
Maintenance setup on a Unix-based server
Maintenance setup on a Windows server
Maintenance setup using an external service
The Big Medium Setup Wizard
Step one: About you
Step two: Server information
Step three: Your administrator account
Step four: Your First Site
Step five: Create content sections and categories
Step six: Choose a design theme
Congratulations, you’re done!
Registering Big Medium
Entering your registration code
A. Spam Prevention with Akismet
Your Akismet API key
Configuring Big Medium for Akismet
B. Importing Sites from Big Medium 1.x
Import legacy sites
Select the data location
Importer preferences
“Importing Data...” progress
Where are the imported sites?
Resuming an import
Troubleshooting imported sites
Image-based navigation
Announcements
Images
Related links
Page content doesn’t wrap
CSS hacks for v1.x widgets

Quick Start

Here’s a quick summary of how to install Big Medium; it’s a highly compressed version of what follows in the rest of these installation instructions. If you’ve installed Big Medium 2 before, or if you’re upgrading from a previous version of Big Medium 2, these steps will likely give you everything you need. If you require more detail, or if this is your first time installing Big Medium 2, skip this section and follow the detailed instructions.

  1. Unzip the Big Medium download package.

  2. Upload the moxiebin directory to your server’s cgi bin.

    Upgrading from a previous version of Big Medium 2? Do not delete the file named bm-setup.pl in your server’s moxiebin directory.

  3. For Unix-based servers, set permissions to chmod 755 for the moxiebin directory and the .cgi files inside.

  4. Upload the moxiedata directory to a location above your web root directory.

    Upgrading from a previous version of Big Medium 2? Do not to delete any existing directories in your server’s moxiedata directory when you upload the new files. You can add or update files to existing directories, just be sure not to delete them. Do not make any changes at all to the counters, data, search, templates_custom or user_data directories.

  5. Upload the bmadmin directory to your server’s public HTML directory.

    Upgrading from a previous version of Big Medium 2? Do not delete or replace the bmadmin/themes/_custom directory (if it exists).

  6. Edit bmadmin/index.html to update the two marked URLs for the correct moxiebin location on your server.

  7. If you are upgrading from a previous version of Big Medium 2, browse to bm-update.cgi in your moxiebin directory, and your upgrade is complete:

    http://site.com/cgi-bin/moxiebin/bm-update.cgi
  8. For new installations, set up a cron job to run Big Medium’s maintenance script every 15 minutes. For Unix-based servers, use the following command (updated to reflect the actual location of your moxiebin directory):

    curl -s -o /dev/null http://site.com/cgi-bin/moxiebin/bm-maint.cgi
  9. For new installations, browse to bm-start.cgi in your moxiebin directory to run the setup wizard, and your installation is complete:

    http://site.com/cgi-bin/moxiebin/bm-start.cgi

Server Requirements

To install Big Medium, you must have the following:

Access to a web server

Big Medium is software that runs on your web server. It supports servers running Windows and Unix-based operating systems (including Linux, OSX, Solaris, etc.).

Perl 5.6.1 or higher

Most web servers have Perl installed, but check to make sure before installing Big Medium. Big Medium requires Perl 5.6.1 or higher and will not run with previous versions. (If your server has an older version of Perl, that means your hosting company hasn’t updated the system since at least 2002; you might gently suggest that they upgrade.)

CGI access

You must have the ability to run custom CGI scripts on your web server.

Server-side includes

Your web server should support server-side includes for files with the .shtml extension.

FTP access

Required to load Big Medium’s files to your server.

What is FTP?

FTP stands for “file transfer protocol.” FTP allows you to move files to and from your web server and, on Unix servers, also allows you to set file permissions on those files. Many free or inexpensive FTP programs may be downloaded from the web. Popular FTP programs for Windows include Filezilla, WS_FTP and CuteFTP. FTP programs for Macintosh include Filezilla, Transit, Fetch and Interarchy.

Image library strongly recommended

Although not required to use Big Medium, it is highly recommended that you have one of these four image libraries installed on your server:

With at least one of these libraries installed on your server, Big Medium can size and manage your images for you automatically.

Installing these graphics packages is not for the faint of heart and does require server administration know-how. Check with your hosting company or server admin for help with installation.

Browser Compatibility

Big Medium control panel

The Big Medium control panel requires a modern web browser. The following browsers and minimum version numbers are recommended:

  • Internet Explorer 6+

  • Firefox 1.5+

  • Safari 3.0+

  • Camino 1.0+

  • Netscape 7+

Older versions of Safari and other Apple WebKit browsers also work with Big Medium, but do not support Big Medium’s WYSIWYG rich-text editing features.

Cookies

Big Medium also requires cookies. If cookies are not enabled in your browser, Big Medium will repeatedly ask you to sign in. If this happens, check your browser’s preferences to make sure cookies are enabled.

Your public website

The HTML markup generated by Big Medium for your public site is compatible with all browser versions. Pages created by Big Medium will work with any browsers for which your page templates are designed. Many of the page templates that ship with Big Medium, however, use design techniques that display correctly only in browsers that understand cascading style sheets. In practice, this means Internet Explorer 5+, Firefox, Netscape 6+, Safari, or Opera version 5+. You may, however, design your own custom templates to be compatible with any and all web browsers.

Installation Checklist

Before installing Big Medium, make sure you have all of the following files and programs:

  • A copy of the Big Medium zip file. The Global Moxie site provides two versions, one for Unix-based servers like Linux, Solaris or OSX, and one for Windows servers.

  • An FTP program such as WS_FTP or CuteFTP (for Windows) or Transmit or Interarchy (for Mac)

Also, make sure that you have the following server and website information in hand (your hosting service can supply this information if you do not know it):

  • The path to Perl for your server. On Unix-based servers, the Perl path is typically /usr/bin/perl. For Windows, the Perl path is typically C:\perl\bin\perl.exe.

  • If your server is on Linux or another Unix-based system, the path to sendmail for your server.

  • If your server is on a Windows system, the name of a SMTP e-mail server that will accept mail from your domain.

  • The directory path for your site’s web directory (where your web pages are stored).

  • The directory path for your site’s CGI directory, often named cgi-bin or cgi.

Upgrading from Big Medium 1.x

To upgrade from Big Medium 1.x, you’ll install Big Medium 2 alongside the previous version and, after the installation is complete, import your v1 sites into Big Medium 2 (for details on the installation process, see Appendix B: Importing Sites from Big Medium 1.x).

When you install Big Medium 2, be sure that you do not overwrite the bmadmin, moxiebin or moxiedata directories from your existing Big Medium 1.x installation. To be safe, change the names of these three directories from your Big Medium download package:

  • Change moxiedata to moxiedata2

  • Change bmadmin to bmadmin2

  • Change moxiebin to moxiebin2

Going forward, when the installation instructions refer to moxiedata, bmadmin or moxiebin, use the new “2” version of each directory instead.

Preparing the Big Medium files

If you have not already unzipped the Big Medium zip file, go ahead and do that now. Depending on your server configuration, you may need to make a minor change to the 25 files ending in “.cgi” in the moxiebin directory. The next two sections describe the necessary changes for Unix and Windows servers, respectively. The relevant files in the moxiebin directory are:

  • bm-account.cgi

  • bm-build.cgi

  • bm-comment.cgi

  • bm-config.cgi

  • bm-css.cgi

  • bm-editor.cgi

  • bm-email.cgi

  • bm-help.cgi

  • bm-import.cgi

  • bm-library.cgi

  • bm-login.cgi

  • bm-maint.cgi

  • bm-mod.cgi

  • bm-plugins.cgi

  • bm-prefs.cgi

  • bm-reset.cgi

  • bm-review.cgi

  • bm-search.cgi

  • bm-sections.cgi

  • bm-siteconfig.cgi

  • bm-start.cgi

  • bm-templates.cgi

  • bm-themes.cgi

  • bm-update.cgi

  • ping.cgi

Preparation for Unix-based servers

The files in the download package for Unix-based servers are configured by default to run on servers whose Perl path is /usr/bin/perl, which is by far the most common configuration. If this is the Perl path for your server, you can skip ahead to the next step, “About File Permissions”.

If your Perl path is not /usr/bin/perl then you have to update 25 of Big Medium’s files with the correct path for your server. Among the unzipped files in your Big Medium download is a directory named moxiebin. This directory holds the Perl scripts for Big Medium. Using Notepad, BBEdit or another text editor, open each of the files ending with “.cgi” and make sure that the top line of each of these .cgi files matches your server’s Perl path.

For example, if your server’s Perl path is /usr/local/bin/perl, the top line of each .cgi file should be:

#!/usr/local/bin/perl

Preparation for Windows servers

The files in the download package for Windows servers are configured to run on servers whose Perl path is C:\perl\bin\perl.exe, a very common configuration. If this is the Perl path for your server, you can skip ahead to the next step, “About File Permissions”.

If your Perl path is not C:\perl\bin\perl.exe then you have to update 25 of Big Medium’s files with the correct path for your server. Among the unzipped files in your Big Medium download is a directory named moxiebin. This directory holds the Perl scripts for Big Medium. Using Notepad, BBEdit or another text editor, open each of the files ending with “.cgi” and make sure that the top line of each of these .cgi files matches your server’s Perl path.

For example, if your server’s Perl path is D:\perl\bin\perl.exe, the top line of each .cgi file should be:

#!D:\perl\bin\perl.exe

About File Permissions

Big Medium requires that certain files and directories have specific permissions in order to work properly. The specific method for establishing these permissions depends on whether your web server is Unix-based (Linux, Mac OSX, Sun Solaris, etc) or Windows-based.

Permissions on Unix

The chmod command is used to set file permissions in Unix systems. Throughout the installation instructions, you will see instructions for setting chmod on various files and directories, followed by the notation “(Unix only).”

Most servers allow you to send chmod commands using your FTP program. For specific instructions, please consult your FTP program’s instructions.

Permissions on Windows

In most hosted Windows server environments, file and directory permissions will already be set correctly, and you can ignore the instructions about setting chmod in the installation instructions that follow (those sections are all marked “Unix only”).

However, if Big Medium encounters a problem with permissions, you will see a message asking you to correct those file settings. Only an authorized system administrator can update permissions for the necessary directories.

Specifically, the Internet Guest User requires permission to read, write, execute and modify (all permissions except “full control”) for the moxiebin directory. The Internet Guest User also requires read, write, and modify privileges for the site’s public html directory, the bmadmin directory and the moxiedata directory. (You’re about to upload the moxiebin, bmadmin and moxiedata directories as part of this installation.)

Upload the Files to the Server

Upload the moxiebin directory

Caution

If you’re updating from a previous version of Big Medium 2, be careful not to delete the file named bm-setup.pl in your server’s moxiebin directory when you upload the new moxiebin directory.

Open your FTP program, and connect to your server.

Set the program to upload files in “ASCII” mode or “Plain Text” mode (see your FTP program’s help files or instructions for help if you’re not sure how to do this).

Find your server’s CGI directory, usually named cgi or cgi-bin. If you cannot find this directory, check with your hosting company to find out where you should install CGI scripts on your server.

Upload the moxiebin directory and all of its contents to your CGI directory. You should now have a directory named moxiebin inside your server’s CGI directory, and the moxiebin directory should in turn contain 25 .cgi files, plus two directories: Modules and plugins. (If you are upgrading from a previous version of Big Medium 2, you will also have a file named bm-setup.pl).

Set permissions on these files and directories to chmod 755 (Unix only). If you are upgrading from a previous version of Big Medium 2, do not change permissions on the bm-setup.pl file. (If you accidentally change the permissions on bm-setup.pl, you can change them back by setting them to chmod 600).

The permissions on the moxiebin directory itself should also be set to chmod 755 (Unix only).

Upload the moxiedata directory

Caution

If you’re updating from a previous version of Big Medium 2, be careful not to delete any existing directories in your server’s moxiedata directory when you upload the new files. You can add or update files to existing directories, just be sure not to delete them. Do not make any changes at all to the counters, data, search, templates_custom or user_data directories.

Switch your FTP program to “Automatic” mode if it has one, otherwise to “Binary” or “Raw Data” mode. The remaining file uploads for your Big Medium installation will be done in this mode.

If possible, you should upload the moxiedata directory to a location outside of your CGI directory and above the web root of your server.

What is the web root?

The web root is the directory where your webpages are stored. Placing the moxiedata directory “above” the web root means that Big Medium’s data files will not be accessible via web browser. For example, if your web root is:

/home/mywebsite/public_html

...you should upload moxiedata to the directory “above” public_html in the /home/mywebsite directory:

/home/mywebsite/moxiedata

If you do not have access to the directory above your web root, you have two additional options:

  1. Locate the moxiedata directory in your CGI directory.

  2. Locate the moxiedata directory in a browser-accessible location, but be sure that it is password-protected. Your hosting company may provide a control panel that lets you password-protect directories, or if your server supports .htaccess files, you can password-protect the moxiedata directory manually.

After you have selected the location of your moxiedata directory, upload it to the server.

Unix permissions for the moxiedata directory

If you have an account with a web hosting service, then the web-server account is probably the same as the account that you use to upload files to the server; in that case, set permissions on the moxiedata directory to chmod 700.

If Big Medium later complains that it does not have permission to access the moxiedata directory, try setting permissions on the account to chmod 770 or, if Big Medium continues to have trouble with the moxiedata directory, try chmod 777.

Windows permissions for the moxiedata directory

The Internet Guest User requires permission to read, write, execute and modify (all permissions except “full control”) for the moxiedata directory.

Upload the bmadmin directory

Caution

If you’re updating from a previous version of Big Medium 2, be careful not to delete or replace the bmadmin/themes/_custom directory (if it exists). If you have saved any custom themes to your theme library, those themes are stored in that directory. Deleting that directory would also delete your saved themes.

Upload the bmadmin directory and all of its contents to the directory where you store your webpages. This directory should be located somewhere outside of the CGI directory and below the web-root directory so that it is accessible via web browser, at a location like:

http://site.com/bmadmin/

Unix permissions for the bmadmin directory

Set permissions on the bmadmin directory (and all files and directories inside) to chmod 755.

If Big Medium later complains that it does not have permission to access the bmadmin directory, try setting permissions on the account to chmod 775 or, if Big Medium continues to have permission problems with the bmadmin directory, try chmod 777.

Windows permissions for the bmadmin directory

The Internet Guest User requires permission to read, write, execute and modify (all permissions except “full control”) for the bmadmin directory.

Update index.html

Inside the bmadmin directory, locate the file named index.html. In a text editor like Notepad or BBEdit, open the index.html file in the bmadmin directory on your local hard drive. You must update two URLs in this file to reflect locations on your web server. The first is marked with this comment in the file:

    *********************************************************************
    UPDATE THE “ACTION” URL TO POINT TO THE DOMAIN WHERE BIG MEDIUM IS
    INSTALLED. FOR EXAMPLE:
    http://www.example.com/cgi-bin/moxiebin/bm-login.cgi/login-verify
    *********************************************************************

…and again:

    *********************************************************************
    UPDATE THE “HREF” URL TO POINT TO THE DOMAIN WHERE BIG MEDIUM IS
    INSTALLED. FOR EXAMPLE:
    http://www.example.com/cgi-bin/moxiebin/bm-login.cgi/login-reminder
    *********************************************************************

Set Permissions on the HTML Directory

Big Medium needs permission to read and write files in your site’s public HTML directory, which is where your site’s homepage file is located, for example. To enable this, please be sure that the web-server user account has full access to this directory.

On Unix-based servers

If you have an account with a web hosting service, then it’s likely that no change is required. However, if Big Medium later complains that it does not have permission to read or write files in the public HTML directory, try setting permissions on the directory to chmod 755. If you continue to receive an error, try setting permissions to chmod 775. And finally, if you continue to receive error messages, try chmod 777.

For Windows servers

The Internet Guest User requires permission to read, write, execute and modify (all permissions except “full control”) for the site’s public html directory.

Run the Updater Script

This step is necessary only if you are upgrading from a previous version of Big Medium 2; if you are installing a fresh copy of Big Medium 2, please jump ahead to the “Set up the Maintenance Script” section.

The updater script makes all of the necessary behind-the-scenes changes to bring your upgraded installation up to speed. When necessary, it also updates the public site(s) managed by Big Medium so that your visitors can immediately enjoy any new features. Until you run the updater, Big Medium will present a “Temporarily Unavailable” message whenever you try to access the Big Medium control panel.

To run the updater, browse to bm-update.cgi in your server’s moxiebin directory. To do this, go to the following location (updating the URL to reflect the location of the moxiebin directory on your server):

http://site.com/cgi-bin/moxiebin/bm-update.cgi

Your upgrade is complete. Congrats, you’re done! You can stop here and go enjoy the smell of freshly upgraded software.

Set up the Maintenance Script

Big Medium has a script that runs regular maintenance tasks, including search indexing and the scheduled publication/removal of site content. This maintenance script should be run every few minutes (15 minutes is a good period for most sites) to ensure that all background tasks are being handled in a timely fashion.

If the maintenance script is not run regularly, a message will be displayed to Big Medium administrators when they sign into the control panel to alert them to the problem.

Your web server can be configured to run this maintenance script at regular intervals, and most web hosting plans offer access to the necessary tools to schedule this task. This is the preferred method to use, but if you’re not provided access to these tools, you can use an external service (such as that provided by webcron.org) to run the script for you.

However you do it, the goal is to trigger this URL every 15 minutes (updating it, of course, to point to the moxiebin directory on your server):

http://site.com/cgi-bin/moxiebin/bm-maint.cgi

Maintenance setup on a Unix-based server

Unix servers have a service named “cron” to schedule tasks, which are commonly called “cron jobs.” Most web hosting plans offer a control panel for managing the server, and this frequently includes an option for scheduling cron jobs. If your hosting company does not provide a control-panel interface for this, then you will need command-line access (telnet or SSH) to your server to add the scheduled task, or your web hosting company may be able to set it up on your behalf.

Unix option one: Add the task from the control panel

The interface for the cron job control panel will vary according to the software used by your hosting company. If you need help, check with your host’s tech support team.

All cron job panels, however, will allow you to schedule a Unix command to run at various intervals. You should schedule the job to run every 15 minutes. The specific command to use depends on the tools installed on your server. If you’re not sure, your hosting company can tell you which command your server supports.

Whichever of the following commands you choose, update the http://site.com/cgi-bin/moxiebin portion of the URL with the correct URL to the moxiebin directory on your server.

If your server supports the curl command (the “-o” below is the lowercase letter “oh”):

curl -s -o /dev/null http://site.com/cgi-bin/moxiebin/bm-maint.cgi

If your server supports the fetch command (the “-o” below is the lowercase letter “oh”):

fetch -o /dev/null http://site.com/cgi-bin/moxiebin/bm-maint.cgi

If your server supports lynx:

lynx > /dev/null -dump http://site.com/cgi-bin/moxiebin/bm-maint.cgi

If your server supports wget (the “-O” below is the uppercase letter “oh”):

wget -q -O /dev/null http://site.com/cgi-bin/moxiebin/bm-maint.cgi

Unix option two: Add the task from the command line

If you have shell access to your server, you can add the task using the Unix crontab command.

Sign into your server using telnet or ssh and use the following command to export your existing scheduled tasks to a text file:

crontab -l > cron.txt 

Open the cron.txt file in a text editor. You will add the new cron job command to this file.

Which command to use?

The exact command depends on the software tools installed on your server. Type the name of each of the following tools on the command line one at a time until you do not get a command not found message: curl, fetch, lynx and wget. If you do not get a command not found message, that tool is supported on your server.

After choosing your tool, add one of the following lines to the bottom of the cron.txt file, replacing the http://site.com/cgi-bin/moxiebin portion of the URL with the correct URL to the moxiebin directory on your server:

If your server supports the curl command (the “-o” below is the lowercase letter “oh”):

*/15 * * * * curl -s -o /dev/null http://site.com/cgi-bin/moxiebin/bm-maint.cgi

If your server supports the fetch command (the “-o” below is the lowercase letter “oh”):

*/15 * * * * fetch -o /dev/null http://site.com/cgi-bin/moxiebin/bm-maint.cgi

If your server supports lynx:

*/15 * * * * lynx > /dev/null -dump http://site.com/cgi-bin/moxiebin/bm-maint.cgi

If your server supports wget (the “-O” below is the uppercase letter “oh”):

*/15 * * * * wget -q -O /dev/null http://site.com/cgi-bin/moxiebin/bm-maint.cgi

After updating and saving the cron.txt file, type the following command on the command line:

crontab cron.txt

Maintenance setup on a Windows server

Download and install wget

Wget is a tool that allows your server to retrieve web files, and we will use it to run the Big Medium maintenance script for you. You can grab a copy of wget for Windows from the wget website:

http://www.gnu.org/software/wget/ After you have downloaded and unzipped the zip file, copy the wget.exe file along with any .dll files directly inside the directory where Windows is installed on your server. For example, typical locations include:

c:\windows\wget.exe
c:\winnt\wget.exe

Create a batch file

In a text editor like Notepad, create a new file with the following line, replacing the http://site.com/cgi-bin/moxiebin portion of the URL with the correct URL to the moxiebin directory on your server (that’s the capital letter “oh” in `wget -q -O` below):

wget -q -O NUL http://site.com/cgi-bin/moxiebin/bm-maint.cgi

Save the file as bigmedium.bat. You may save the file anywhere you like on the server, but it’s strongly recommended that you keep it in a location that won’t change and is not accessible to the web server (in other words, don’t save the file in the same directory as your HTML files on the server).

Create the scheduled task

Your server’s tasks are stored in the “Scheduled Tasks” directory in the server’s “Control Panel” directory. Go the “Scheduled Tasks” directory and click on “Add Scheduled Task.” The task wizard will launch.

After clicking Next, it will ask for the program to run. Click “Browse...” and select the bigmedium.bat batch file that you created.

Give the Scheduled Task a name (e.g., “Big Medium Maintenance”) and select to perform this task daily. Click Next.

Set the Start time to 0:00 and choose to perform this task every day. Click Next.

Supply your user name and password, and click Next.

Check the “Open advanced properties for this task when I click Finish” option, and click “Finish.”

Click the “Schedule” tab and then the “Advanced...” button. Check the “Repeat task” option and set the task to run every 15 minutes. Beside “Until,” check the Time option and enter the value 23:59. Click OK.

Click Apply to save all settings.

Maintenance setup using an external service

If you do not have access to the necessary tools to schedule the maintenance script using the methods described above, you can use an external service to run the script on a regular basis.

This is not as reliable as the other methods, however, and relies on the uptime of the external service. Use this method only as a fallback if you’re unable to schedule your server to run the job.

There are a variety of free and paid services that will visit web pages for you on a fixed schedule. One such service is webcron.org (this is not an endorsement of the service, only a pointer to one of many). After selecting your external service, follow the service’s directions for setting up your scheduled task. The service should request the following URL every 15 minutes (with the URL updated, of course, to point to the bm-maint.cgi script in your server’s moxiebin directory):

http://site.com/cgi-bin/moxiebin/bm-maint.cgi

The Big Medium Setup Wizard

Whew, congratulations, the hardest part is over! The rest of your Big Medium installation takes place in a friendlier environment: your web browser.

To start the Big Medium setup wizard, go to this location in your browser, adjusting the URL as necessary to point to the moxiebin/bm-start.cgi file on your server:

http://site.com/cgi-bin/moxiebin/bm-start.cgi

Step one: About you

Provide your organization name and administrator e-mail address in the requested field and click “Onward.”

Step two: Server information

This page asks for several directory paths and URLs to help Big Medium get its bearings on the server. Use the help links for detailed info and suggestions about the locations of these directories and URLs.

Figure 1. Step two: Server Information

Step two: Server Information

Important

If you are installing on the same server where another Big Medium 1.x installation is already installed, you should have changed the names of the bmadmin, moxiedata and moxiebin directories. Don’t forget to use those changed names (e.g. bmadmin2, moxiedata2 and moxiebin2) when entering them into the form.

Firewall settings

The “Firewall” panel on this screen allows you to enter proxy server information. If you rent a web server from a standard hosting service, you almost certainly do not have a proxy server, and you can leave these fields as-is; move along, nothing to see here.

However, if your web server is part of a private network, it may use a proxy server to connect out to the Internet. Check with your server administrator if you’re not sure. (You can also leave this field as-is for now and fill it in later via the “Settings>Big Medium Server Info” screen in the control panel after running the setup wizard.)

Akismet anti-spam service

Big Medium offers the option to use the Akismet online service to check visitor comments for spam and, if they’re spammy, prevent them from being posted to your pages. If you plan to enable visitor comments on your site(s), this feature is highly recommended.

In order to enable Akismet, you need to enter your 12-digit Akismet key in this field. For information about Akismet and obtaining a key, see Appendix A: Spam Prevention with Akismet .

If you don’t want to use Akismet, or if you’re not sure, you can leave this field blank. (You can always supply the key later via the “Settings>Big Medium Server Info” screen in the control panel after running the setup wizard.)

Step three: Your administrator account

Enter the user name, e-mail address and password information for your Big Medium administrator account, then click “Onward.”

Figure 2. Step three: Your administrator account

Step three: Your administrator account

Step four: Your First Site

This page asks for the name, URLs and directories for your first site. The help links offer detailed help and suggestions for choosing these directories, but briefly...

The homepage directory

The path and URL of the directory where you would like Big Medium to build and store the homepage for this site. In most cases, this is the web root directory of your site. For example: http://site.com

However, if you already have an existing site, you may want to set this to a temporary directory so that your new site does not interfere with your current site until it’s ready to go. For example: http://site.com/bm

Figure 3. Step four: Your first site

Step four: Your first site

The page directory

The path and URL of the directory where you would like Big Medium to build and store all of the non-homepage files and pages for your site.

After choosing the name, URLs, directories and time zone for your new site, click “Onward.”

You’ll be asked to confirm that you can see two images. If you can, this indicates that you have filled in the correct values for your site directories and URLs. If not, you need to try again. Click the “Yes” link if you see the image, or click “No” if not.

Step five: Create content sections and categories

Your site will consist of the homepage and one or more content categories, or “sections.” Sections are the organizational tools that you use to categorize content on your website, and the primary navigational method that your visitors will use to move about the site.

Sections can be one-pagers (like a “Contact Us” page), but more commonly they’re containers for lots of web pages (like “News,” “Business” or “Sports” sections in a newspaper website). This page lets you define the sections of your site.

Figure 4. Step five: Create content sections and categories

Step five: Create content sections and categories

To add a new section, click the “Add main section” link and give the section a title and a “slug name.”

What’s a slug name?

The slug name is a kind of internal nickname for the section and also determines the name of the directory where the section’s pages will be found. For example, a section with the slug name “news” might have its pages in the directory: http://site.com/bm/news ...and if you have a “Local News” subsection of this news section, with a slug name of “local,” that subsection’s pages would be located here: http://site.com/bm/news/local

To add subsections to your new section, click the section name and then “Add subsection” and fill out the form with the title and slug name of the new subsection. When you have created your sections -- or at least enough to get started -- click “Onward.”

Step six: Choose a design theme

“Themes” determine the look and feel of your site. Select a design theme by clicking “Apply” next to the theme that you want (or “details” to see a preview). Never fear, you won’t be locked in. You can choose another theme later, customize this theme, or create your own design from scratch. For now, choose a theme to get started.

Figure 5. Step six: Choose a design theme

Step six: Choose a design theme

Congratulations, you’re done!

Your site is now ready for editing. You can get started right away by clicking the “Welcome to [site name]” link in the edit menu and editing the text on the home page. Or click “New Article Page” to create a new page in one of your site sections.

Or, if you are upgrading from Big Medium v1, you’re now ready to import your sites into Big Medium 2. See Appendix B: Importing Sites from Big Medium 1.x for details.

Registering Big Medium

Big Medium is free to use for the first 30 days. During this time, you can enjoy the software’s full functionality without spending a dime. After the 30-day trial period, Big Medium’s administrative interface will stop working until you purchase a license and register the installation with your license code.

To purchase a license, visit: http://globalmoxie.com/buy/

Entering your registration code

Sign into Big Medium with an administrator account. If the 30-demo period has expired, follow the instructions to register your account. Otherwise, go to “Settings>Register Big Medium,” and follow the instructions there.

A. Spam Prevention with Akismet

What’s more disheartening than having spammers vandalize your site with scrawled comments about Viagra, ringtones and dark visions of Paris Hilton? To help prevent such comments from seeing the light of day, Big Medium offers the option to use the Akismet anti-spam service to screen comments for spam.

The brainchild of Wordpress phenom Matt Mullenweg, Akismet is an online service that torture-tests comments with hundreds of tests and then tells Big Medium whether or not it’s spam. If a comment has the scent of processed ham, Big Medium chucks it into the spam bin instead of posting it to the site. Spam comments are deleted automatically every 15 days.

If a good comment is incorrectly identified as spam (a “false positive”), never fear. Accounts with publisher privileges or better can review spam comments, approving the good comments. This also triggers Big Medium to notify Akismet about the mistake, helping to improve Akismet’s filtering in the future.

Likewise, if a spam comment manages to escape detection, you can mark the comment as spam, and Big Medium will remove it from the site and inform Akismet about the spam message.

Your Akismet API key

In order to enable Big Medium to communicate with the Akismet service, you have to sign up for an Akismet “key.” This key is a special identifier, like an account name.

Akismet keys are free for personal sites and have a modest licensing fee for commercial sites. The key is used for all sites managed by your installation of Big Medium; if you use Big Medium to host one or more commercial sites, you should purchase a commercial license. For information about obtaining your Akismet key and licensing options, please visit the Akismet site:

http://akismet.com/commercial/

Configuring Big Medium for Akismet

To make Big Medium Akismet-ready, you simply need to give it your 12-digit Akismet key. You have the option to do this when you’re first setting up Big Medium, in the second screen of the setup wizard, or administrators can add the comment in the “Settings>Big Medium Server Info” screen after Big Medium has already been configured.

After supplying your key, Big Medium will, by default, submit new comments from all sites to Akismet. You can disable Akismet service for an individual site in the “Visitor Comments” screen of the site’s HTML preferences.

B. Importing Sites from Big Medium 1.x

Import legacy sites

Administrators can import accounts and sites from previous versions of Big Medium by selecting “Settings>Import Legacy Sites” in the control panel. The importer can import data only from v1.x installations on the same server. The accounts and sites are copied into Big Medium 2, leaving the original data from the v1.x installation untouched. This allows you to keep your original v1.x site running while you transition to your new v2 site.

Select the data location

Figure B.1. Provide the location of the old moxiedata directory

Provide the location of the old moxiedata directory

The first screen of the import process prompts you to supply the location of the original v1.x moxiedata directory. Enter the directory path and click Continue.

Importer preferences

Figure B.2. Step 2 asks you how/what to import

Step 2 asks you how/what to import

The next screen asks you how and what you would like to import. Select your preferences and click continue.

Sites

Click the “All sites” tab to import all sites from the v1.x installation, or click the “Selected sites” tab to import only certain sites. (You can choose to import selected sites now and then import the rest later). Use CTRL-click (or Command-click on Mac) to select more than one site in the “Selected sites” tab.

Directories

The default (and recommended) setting is to create the imported sites in new HTML directories so that the public v1.x site remains untouched. Later, when you’re ready to take your new Big Medium v2 site live, you can move the HTML directory to replace the old v1 site.

If you prefer to have Big Medium import the v2 site into the same directory and immediately replace the v1 site files, uncheck the “Build all imported sites in new directories” option.

Duplicate user names

You’ve already created at least one administrator account in your v2 installation, and perhaps others, too. The importer needs to know what to do if it runs into accounts with the same user names from the v1 installation.

The default handling of duplicate user names is to assume that both v1 and v2 accounts refer to the same person. The privileges for v1 accounts and sites are extended to v2 accounts of the same name, “merging” the privileges of the two installations.

Unchecking the “Apply v1 privileges to v2 accounts of the same name” option instead tells Big Medium to create new accounts under a new name when it encounters a user name that already exists. For example, when Big Medium imports an account named “mary,” and an account already exists for “mary,” it will import the v1 account as “mary-2.”

“Importing Data...” progress

The next screen does the actual data import. If you’re running Big Medium on a Unix-based server, a progress bar will show you where you are in the process. Sites with hundreds or thousands of pages may take a couple of minutes to import.

Figure B.3. “Importing Data...” progress bar

“Importing Data...” progress bar

The progress bar will show “DONE” when the import is complete.

Where are the imported sites?

To edit your imported sites, sign into Big Medium as usual. Click the “Switch sites” link in the left column to select the site to edit. From there, you can visit the public site by clicking the site’s name under “Now editing” in the left column.

The location of the public site depends on the “Directories” preference that you chose before importing.

If you chose the default “Build all imported sites in new directories” option...

You can find the site in a page directory relative to the original site’s page directory. For example, if the original v1 site’s page directory was located here:

http://www.example.com/moxie

...then the imported site will be located here:

http://www.example.com/moxie-bm2

For sites whose page directories are the same as the domain root:

http://www.example.com

...the imported site will be located here:

http://www.example.com/site-bm2

If you did not choose the “Build all imported sites in new directories” option...

You can find the site in the same location as the original v1 site.

Resuming an import

If Big Medium encounters a problem (if it does not have permission to create a directory, for example), the import process will stop, and Big Medium will display a message explaining the problem.

After resolving the issue, you can restart the import process by going back to the beginning: Select “Import Legacy Sites” from the Settings menu of the Big Medium control panel.

The importer is clever enough to figure out where it left off so that it does not import the same data twice with one exception: When resuming a stalled import, be sure that you leave the “Apply v1 privileges to v2 accounts of the same name” checked. Otherwise, Big Medium will import all of the v1 accounts a second time under a new name.

Troubleshooting imported sites

The importer handles most site designs smoothly, but there are some changes and incompatibilities that may require minor changes to imported sites. These design variations can be addressed by editing the site’s templates and/or theme style sheet.

How do I edit templates and style sheets?

To edit templates, go to “Layout>Edit Templates” in the Big Medium control panel, and click on the template to edit.

To edit the theme style sheet, which contains your site’s custom CSS styles, go to “Layout>Edit Theme Style Sheet.”

This section describes common design inconsistencies for imported sites and solutions for common problems.

Image-based navigation

The HNAVIMAGE, VNAVIMAGE, HSUBNAVIMAGE and VSUBNAVIMAGE widgets from Big Medium 1.x are not supported in Big Medium 2. The importer handles this by generating the final HTML output for these widgets and embedding it directly into the templates of the imported site.

This creates navigation bars that are identical to those in the original v1.x site, but they are no longer updated automatically by Big Medium. This means that section changes (e.g., new, reordered or deleted sections) are not automatically reflected in the site’s navigation without separately updating the templates.

Figure B.4. Image navigation in a site imported from v1

Image navigation in a site imported from v1

If you don’t plan to add or change sections in the imported site, then no problem; move along, nothing to see here.

But if you want Big Medium to be able to update the section navigation automatically, you should replace this generated image-navigation HTML with one of Big Medium’s other navigation widgets, <%navigation%> or <%subnavigation%>.

These navigation widgets are text-based. If you prefer to keep your image-based navigation, the Global Moxie site offers a tutorial on creating graphical navigation bars from Big Medium’s text-based widgets.

Announcements

In Big Medium 2, announcements behave more like page content than they did in previous versions.

Announcements from subsections

The ANNOUNCE widget in Big Medium 1.x displayed only announcements that were assigned specifically to the current section. In Big Medium 2, the <%announcements%> widget displays announcements that are displayed in the current section, plus all subsections.

As a result, pages that displayed just one announcement in Big Medium 1.x may now display several announcements. The homepage, for example, will display all announcements from the entire site.

If you used the v1.x ANNOUNCE widget as a way to display editable text on section pages, you may find it more convenient to replace the <%announcements%> widget on section templates with the <%content%> widget.

Announcement titles

Announcements now have headline titles. The importer uses the placeholder word “Announcement” as the title for all imported announcements. You can edit these titles in the content editor (“Edit>Edit Announcements” in the Big Medium control panel).

Images

If you relied on previous versions of Big Medium to resize your images to precise dimensions, and if your server does not have one of the recommended image libraries installed (ImageMagick, GD, NetPBM or Imager), images will be displayed in their original size instead of the resized version that you had in previous versions. This could result in very large images being shown in places where you want much smaller images.

This same issue applies to images entered as URLs in Big Medium v1 (as opposed to uploaded image files). Even if you have the image libraries described above, Big Medium does not resize images entered as URLs, and they will instead be displayed in their original size.

You can resolve these issues by adding specific heights and widths for each type of image in your theme style sheets.

Example B.1. Enforce image dimensions via CSS

div.bmw_link img {   /* link images, a.k.a "thumbnail images" in v1 */
    width:  175px;
    height: 100px;
}

div.bmw_spotlightLinks div.bmw_link img {   /* spotlight images */
    width: 200px;
    height: 200px;
}

div.bmw_pageContent img {   /* "body images" embedded in article text */
    width: 300px;
    height: 200px;
}

Related links

Big Medium 2 introduces two changes to the way that related links are displayed below links to a page. (There are no changes to how related links are displayed on the page itself, only with promotional links to the page.)

Related links are displayed in a bulleted list

Previous versions of Big Medium simply separated related links with <br> line breaks. Big Medium 2 puts them into a <ul> bullet list. To make the display look more similar to the v1.x format, add these styles to the theme style sheet:

div.bmw_link ul, div.bmw_link li {
    margin:0;
    padding:0;
    list-style:none;
}
All related links are shown

Previous versions of Big Medium displayed only the first two related links alongside links to a page. Big Medium 2 now shows all links. You cannot choose individual related links to be displayed with links to the page; it’s all or nothing. You can turn off the display of related links as part of link content in the site’s HTML preferences: “Settings>HTML Preferences>Links.”

Page content doesn’t wrap

In previous versions, page content and link widgets would wrap around floated or left/right-aligned elements (including the v1.x TOOLPANEL widget) that came immediately before. In Big Medium 2, those layouts now create a “gutter,” and the text that used to wrap no longer completes the wrap.

Figure B.5. The content widget wraps around floated elements in v1 (left) but not v2 (right)

The content widget wraps around floated elements in v1 (left) but not v2 (right)

If you don’t want this effect, you can fix it by adding a custom style in the theme style sheet:

div.bmw_pageContent {
    overflow:visible;
}

CSS hacks for v1.x widgets

Big Medium 2 has changed much of the underlying markup and CSS of sites generated by Big Medium. If your site relies on custom CSS changes to the CSS styles of Big Medium widgets, those changes will probably not work in Big Medium 2.

Feel free to lean on the Big Medium support forum to revise these CSS hacks. Post your questions, along with before-and-after links to the v1 and v2 pages that display the problems, to the Big Medium 2 support forum.