TurboCSV Documentation

Compatibility

TurboCSV is compatible with WordPress 3.0 and higher. It also requires PHP version 5.2 or higher.

Installation

Download turbocsv.zip and extract it to your plugins directory (this is normally “/wp-content/plugins/”). You will now have a directory called “/wp-content/plugins/turbocsv” that contains the TurboCSV files.
Go to your WordPress administration panel and log in.
Click on the ‘plugins’ menu on the left side of the admin page. The TurboCSV plugin will be listed under Inactive plugins.
Click on the ‘activate’ link to activate the plugin.
You should now see a TurboCSV’ menu under the standard ‘Tools’ menu on the left side of the admin page.

Prepare the Input File

TurboCSV can import data saved in comma-separated-values format (with a .CSV extension). Any Excel spreadsheet can be saved in this format (just select the “CSV (MS-Dos)” format in the Excel ‘save as’ dialog). .

The data fields from the input file are used to create WordPress posts or pages. The file must contain one line for each post/page. An example of the format is included in the files “sample.xls” and “sample.csv”.

The input file should ideally be in UTF-8 format but TurboCSV can also read Windows (ANSI) files, such as those exported by Excel.

Column Names

You may use any column headings in your input file. If you use your own headings, they must be mapped to the various post attributes. For example, your column ‘description’ could be mapped to the post title or post excerpt fields.

Alternatively, if your input file contains these ‘magic’ column headings then TurboCSV will detect them automatically and map them to the correct WordPress fields:

Column Name	Use
!id	Post ID field (for updating posts or pages)
!post_title	Post title
!post_content	Post body
!post_excerpt	Post excerpt
!post_name	Post slug
!post_category	Post categories
!tags_input	Post tags
!post_date	Post date

Any other column prefixed with “!” will be assumed to be a custom taxonomy. For example, TurboCSV will treat column “!turbocsv_demo1” as values for updating custom taxonomy “turbocsv_demo1”.

Columns that don’t have a “!” prefix have no special significance; they can be mapped or ignored as needed by your import.

Specify the Input File

A new import begins by selecting TurboCSV from the tools menu or clicking the ‘new import’ link in the TurboCSV menu. The input file can be:

A local file on your PC (in which case TurboCSV will upload it to your WordPress ‘uploads’ directory)
A URL to a file located somewhere on the internet
A file located on your web server

Enter the input file and then click the ‘load file’ button to continue.

Set the Import Options

TurboCSV offers settings for every post/page option. A group of settings can be saved as a ‘template’ so you don’t have to re-enter them over and over.

The settings screen is divided into several sections.

Import Status

This section shows the file name being imported and the file’s path on your web sever. The status of the import is also displayed.

Layout

The Layout section has a form for loading, saving or deleting templates. You can templates to save all of your import settings for future use.

The Post Title, Post Body and Post Excerpt fields are used to specify those parts of your imported posts or pages. You can enter plain text here or click on the input file column names to insert a placeholder (a column name with “#” on each side). During the import the placeholders are replaced with the data from the input file.

You can use the ‘HTML’ and ‘Visual’ buttons on the post body editor to switch between plain HTML and the visual tinyMCE editor.

Post / Page Settings

Post ID: New Import or Update

Normally TurboCSV will create new posts and pages. To update existing posts/pages specify a column for “Post ID”. Any rows in the input file where the post ID is populated will then perform an update.

During update the post contents are completely replaced along with the other post settings (categories, tags, etc.) and the post metadata.

There are two ways to find the Post ID for an existing post or page:

Edit the post/page in WordPress. During editing part of the URL will be the post ID.
If you’re updating posts/pages you created with TurboCSV, it’s even easier: just go to the import ‘results’ screen (described below) and you’ll see every imported post/page along with its post ID.

Post Date

Sometimes you’ll want to make it look like your blog was populated over a period of weeks or months rather than all at once. TurboCSV lets you specify various dates for this purpose: you can use the current date, read the post date from a column in the input file or generate random dates.

Other Settings

The other post/page settings let you specify the other standard WordPress options:

Tags, Categories and Custom Taxonomies

Use this section to specify the categories and tags. The categories and tags can be read from a column in the input file or you can pick existing values to be assigned to all posts.

Custom Taxonomies

Custom taxonomies can’t be mapped visually. They must be specified in the input spreadsheet using a ‘magic column’ – a column name that begins with “!”. For example, column “!turbocsv_demo1” will be assumed to have the post values for custom taxonomy “turbocsv_demo1”. See the “sample.csv” spreadsheet in your TurboCSV directory for an example.

Custom taxonomies can either be hierarchical or flat. If they’ are hierarchical, the entries are separated with “,” and “|” like hierarchical categories. For flat taxonomies the entries are separated with “,” like tags.

Custom Fields

The custom fields section lets you assign input file columns to populate existing custom fields.

You can also select input columns to have TurboCSV create new custom fields for those columns.

Processing the Import

When you’ve made all of the import settings and optionally saved them as a template, click the ‘process’ button to begin the import.

You’ll get a warning to back up your database before beginning. This is always a good practice when you’re importing large amounts of data.

Be patient – it can take several minutes to load large imports. When the import is complete TurboCSV will display a log with any error messages.

You can come back to this screen from the ‘history’ menu at any time. The original settings used for the import are displayed but cannot be modified.

The History Screen

All completed imports are stored in the WordPress database. You can see the import history on the ‘history’ screen. Click an import link to display the details and log.

There are two other actions you can perform on this screen:

Delete

Click the delete link to delete the import history for the selected import. This saves space and reduces clutter but you will never be able to undo an import once you delete it. Be sure that the import was successful before selecting this option.

Undo

Click the undo link to undo an import. TurboCSV will attempt to undo the import and it will log any messages resulting from the undo.

Undo for Posts/Pages Created During Import

Any posts/pages created as part of the import will be deleted, even if they were subsequently modified – so be careful!

Undo for Posts/Pages Updated During Import

Any posts/pages updated as part of the import will be rolled back to the last version prior to import. If you modified the post after the import it won’t be rolled back and a warning message will be logged. This allows you to decide manually whether to remove your updates or not (you can revert to an earlier version in the WordPress).

Undo for Categories, Tags, and Taxonomies

Any categories or tags created during the import will be deleted if no longer in use (i.e. if you used a category in a post that wasn’t part of the import, the category won’t be deleted)
Any custom taxonomy entries created during the import will be deleted if no longer in use

Undo for Metadata

For posts that are deleted during the undo the metadata will also be deleted.
For posts that are restored to a prior version: WordPress doesn’t save metadata with revisions, so the metadata is not changed.

Chris Richardson's Plugins