Compatibility

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

In order to import map data you must have the MapPress Pro plugin.

Installation

1. 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.
2. Go to your WordPress administration panel and log in.
3. Click on the ‘plugins’ menu on the left side of the admin page.  The TurboCSV plugin will be listed under Inactive plugins.
4. Click on the ‘activate’ link to activate the plugin (see the ‘Multi-site’ section if you’re running a multi-site installation)
5. 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	ID field (for updating posts or pages)
!post_author	Post author
!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
!blog_id	Blog ID (see the Multisite section below)

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 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 template 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.

Multisite

TurboCSV supports WordPress multisite installations.  A single import file may be used to import into multiple sites.  The import history (and even the “undo” function) will work across sites.

When the plugin is installed you can activate it or network activate it.  Normally you will activate it only in the main site, but if you choose to give child sites the ability to import then you can network activate instead.  If you choose network activation, child sites will be able to import data but only into that site – only the main site can import into a different site.

If you are running multisite and in the main site, the multisite fields below are available in the import template.  Choose ‘column’ to use a column in the import spreadsheet to specify a blog ID (also called “site ID”) to import into, or select a site from the list.

If you use the column “!blog_id” in your input spreadsheet it will be defaulted here.

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 Type

Indicate if you want to import posts or pages.  The value here will apply to the entire import.

Page Settings

Page parent, template and menu order are ignored for posts.  For pages, the values specified will apply to the entire import.

Post Status

Choose a post status.  The value specified here applies to the entire import.

Comment Status

Choose a comment status.  The value specified here applies to the entire import.

Author

Choose an author (if the same author should apply to the entire import) or an import column that contains the author ID if the author may be different for each post/page.

Slug

Choose a column that contains the post slug (or leave this blank to let WordPress assign a default slug).

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.

Updates

Unique ID Column

TurboCSV can be used to update existing posts or pages.

To perform an update, specify the input file column that contains a unique ID to be updated, and a “Match to” field in WordPress with that same ID.  During the import, TurboCSV will try to find the existing post or page and update it.

The default is to match to the WordPress “Post ID” field but you can also use a custom field value if you have unique IDs stored in another field.

To find the Post ID for an existing post or page you can:

1. Edit the post/page in WordPress.  During editing part of the URL will be the post ID.
2. If you imported the post/page 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.

TurboCSV uses the following rules when doing an update:

• If the unique ID column is empty, or no unique ID column was specified, a new post/page will be created
• If a single matching post is found, the post/page is updated
• If multiple matching posts are found, the first post/page is updated
• If no match is found, an error is issued

Tags, Categories and 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.

Tags

If you are using an input column to specify post tags, the column must contain a list of tags separated by commas.  TurboCSV will create any tags that don’t exist already.

Categories

If you are using an input column to specify categories, the column must contain a list of categories separated by commas (just like tags).  TurboCSV will create any categories that don’t exist already.

Hierarchical Categories

Categories can also be hierarchical.  To specify a category hierarchy in an input column, separate the categories with a “|”.  For example if your input column has “CA|San Mateo|94112” then TurboCSV will create a category hierarchy CA –> San Mateo –> 94112 and assign those categories to the current post.

You can also specify multiple hierarchies: for example if your input column has “CA|San Mateo|94112,Daycare|Toddlers”, TurboCSV will create two both category hierarchies and assign them to the current post.

Taxonomies

Custom taxonomies can be mapped on the template screen just like tags or categories.  You may also specify the values in the input spreadsheet by using a column name that begins with “!” followed by the taxonomy name.

For example, column “!turbocsv_demo1” will import values to custom taxonomy “turbocsv_demo1”.

Like tags and categories, custom taxonomies also be hierarchical or flat.  Values for flat taxonomies are separated using commas (like tags) and values for hierarchical taxonomies are separated using the hierarchy separator “|” (just like hierarchical categories).

Custom Fields

The custom fields section lets you create new custom fields or import data into existing custom fields.

For each existing custom field you can specify a column in the import file to import from.  If the names match, the plugin will automatically propose the column for import into the custom field with the same name.

If the custom field doesn’t exist already then select the checkbox next to the name of an import column.  A new custom field will be created and populated from that column.

Tip: See the below for more information about entering multiple values into custom field import 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 any import link to display the details and log.

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.

Settings

The settings screen lets you specify various parameters for imports.

Setting	Description
Input file encoding	Normally you can let TurboCSV automatically detect your encoding, but if the import isn’t working you may want to select one from the list.  For example, Windows-1251 is required for some Cyrillic (Russian or Greek) input files.
Input file delimiter	Select the field separator for your file.  Normally for CSV files this is the comma, but you may also select the semicolon (for European CSV files), tab, or pipe delimiter.Note: be sure to adjust the other settings if you change this.  For example, if you choose the pipe (“|”) symbol, then select something other than the pipe symbol for the hierarchy / address separator.
Skip lines with errors	Indicate the maximum number of errors to ignore before the plugin stops processing the input file (by default, this is 0, so the plugin stops at the first error)
Commit rows	Indicate how many rows to process before each database commit.  A smaller value will use less memory, but a larger value will process faster.  Normally you should leave this at the default setting.
Values separator for custom fields	For custom fields, tags and categories, fields containing commas are normally treated as a list of separate values. If you have custom fields that contain commas you may find it convenient to change this separator.  See the “Advanced Topics” section for details.
Hierarchy separator	When importing category hierarchies this separator indicates a parent – child relationship.  See the “Tags, Categories and Taxonomies” section for details

Advanced Topics

Escaping Commas

If your input files contains tags, categories, taxonomies or custom fields you can separate multiple values using commas.  For example, to assign categories “a”, “b”, and “c” to a post your input file would contain a single field “a,b,c”.

In some cases the values may themselves may contain commas.  In this case you can escape the commas using a backslash (“\”) character.

For example, to import categories might be: “a”, “a,b” and “a,b,c”, you would use a single field containing the value “a,a\,b,b\,c”.

To import “Chicago, IL” and “New York, NY” you would use a single field containing the value “Chicago\,IL,New York\,NY”.

If you don’t want to use the escape character you can also change the values separator character on the TurboCSV ‘settings’ screen.  For example if you change it to “*” instead of “,” then you can enter the above example as: “Chicago, IL*New York,NY” without escaping the commas.  Note that this setting affects values for ALL tags, categories, taxonomies and custom fields.

Escaping Double Quotes

In CSV files, double quotes are used to contain values that have commas in them.  For example the value a,b,c should appear in your input file as “a,b,c”.

If you need to have double quotes inside a value – for example if you’re putting a quote in the post body – then you can enter them as two double quotes.  For example this to import:

He said “hello”

Use:

“He said “”Hello”" “

Tip: if you create your file in Excel and then save it in .CSV format, Excel will automatically add the double quotes for you.

Maps

If you have the MapPress Pro plugin installed, you can import maps using TurboCSV.

Importing Maps

To import addresses you need to create two custom fields:

1. A field for addresses
2. A field for geocoding errors (errors that occur when MapPress tries to turn an address into a latitude/longitude)

Once the fields exist, go to the MapPress settings screen and enter the field names.  See the MapPress Pro documentation for detailed information about how to set up these fields.

MapPress will now create a map whenever a post containing the address custom field is saved.  If there are any errors, they’ll be written to the errors custom field.

Once MapPress is set up, you can use TurboCSV to import your posts.  Your import file will need to have a column for the addresses custom field you specified above.  For example, if the field name was “address” the import file should have a column “address”.

During the import, TurboCSV will create posts and populate the “address” custom field.  MapPress will then generate a map from the contents of that field.  If there are any errors TurboCSV will write them to the import log and MapPress will write them to the custom field you specified for geocoding errors.

Map Address Formats

The import file can contain a single address, such as:

Chicago, IL

You can enter multiple addresses separated by commas, just escape the commas inside the addresses.  For example:

Chicago\, IL|Paris\,France

You can also precisely specify information about each map marker using a “POI” specification.  For example, this will display a map marker with a specific latitude, longitude, title and marker body:

point_lat="43.44" point_lng="54.55" title="My Coffee Shop" body="Check out my favorite java"

The POI is entered much like you would enter a WordPress shortcode: the value for each argument must be enclosed in double quotes.  You can enter multiple markers using the “|” separator:

point_lat="43.44" point_lng="54.55" title="My Coffee Shop" body="Check out my favorite java" | point_lat="11.22" point_lng="33.55" title="Cheesecake" body="Here's the cheesecake factory"

You can even enter multiple POIs in a single column.  Here’s an example with two POIs:

point_lat="43.44" point_lng="54.55" title="My Coffee Shop" body="Check out my favorite java",point_lat="11.22" point_lng="33.55" title="Cheesecake" body="Here's the cheesecake factory"

Tip: See the MapPress Pro documentation for details about the POI format.

Displaying Maps in Posts/Pages

The easiest way to display the imported maps is to turn on the “automatic display” option in the MapPress settings.  This will automatically display the first map in every page or post, but it doesn’t work in every theme.

You can also use TurboCSV to import a post body that includes the MapPress shortcode, .  This allows you to specify additional information, such as the map type and size.  See the MapPress documentation for details about the shortcode.

There is one limitation: since you do not know the map ID number during import you cannot use the mapid parameter to explicitly display the imported map.  This means that your posts and pages must have only one map, or the imported map must be the first map in the post.

Featured Images and Attachments

TurboCSV does not currently support importing attachments or images directly, but you can load images to the WordPress media library separately and then refer to them in your imported posts or pages by URL.

For example, to use featured images for your posts do the following:

1. Check that your theme supports featured images, and enable them for the theme.
2. Upload the images to the WordPress media library.  Internally, WordPress actually saves each image as post of type “attachment”.
3. Get the post ID of each image.  The post ID is displayed as the “attachment_id” part of the URL when you mouse over a link to an image or edit it.  For example, this is the URL for post ID 2941:
   http://localhost/wordpress/wp-admin/media.php?attachment_id=2941&action=edit
4. To use the image as a post’s featured image, you must set a hidden custom field called “_thumbnail_id” to the image’s post ID.  You can test this manually in the WordPress post editor.
5. To import featured images using TurboCSV, create a column named “_thumbnail_id” in the import file.  For each post you’re importing, enter the post ID of the featured image in that column (“2941″ in this example).