TurboCSV Documentation

Table of Contents


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

Please see the installation instructions: http://wphostreviews.com/install.

Once the plugin is installed you should see a TurboCSV menu under the standard WordPress ‘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 Description Value
!blog_id Blog ID Multisite blog ID.  See the ‘Multisite’ section.
!id Update ID An existing post ID or custom field value.  See the ‘Updates’ section.
!post_type Post type Standard post type (‘post’ or ‘page’) or custom post type.
!post_status Post status WordPress post status: ‘publish’, ‘pending’, ‘draft’, ‘future’, ‘private’,’trash’
!post_author Post author WordPress user ID
!post_title Post title Title text (may include HTML)
!post_content Post body Body text (may include HTML)
!post_excerpt Post excerpt Excerpt (plain text)
!post_name Post slug Slug
!post_parent Parent page Post ID of parent page (applies to pages only)
!post_category Post categories Post categories.  See the ‘Tags, Categories and Taxonomies’ section.
!tags_input Post tags Post tags.  See the ‘Tags, Categories and Taxonomies’ section.
!post_date Post date Preferred format is ‘Y-m-d H:i:s’
!post_format Post format WordPress post format
!post_thumbnail Featured image ID or URL See the ‘Attachments and Images’ section.
     

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

image

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.

image

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.

image

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.

image

Settings

Settings may be entered using column name or a default value. 

If a column name is used, the setting for each post is read from that column in the input file.  If a default value used, that value will be applied to all imported posts.

Post Type

Select a standard post type (‘post’ or ‘page’) or a custom post type

Page Parent, Page Template and Menu Order

These settings apply only when importing pages or a custom post type that supports page properties.  Otherwise they are ignored.

Post Status

WordPress post status.  Valid values:

  • ‘publish’ – A published post or page
  • ‘pending’ – post is pending review
  • ‘draft’ – a post in draft status
  • ‘future’ – a post to publish in the future
  • ‘private’ – not visible to users who are not logged in
  • ‘trash’ – post is in trashbin.

Comment Status

WordPress comment status.  Valid values:

  • ‘closed’- Allow comments
  • ‘open’ – No comments allowed

Post Author

User ID of the post author.  If blank, WordPress will default to the current user.

Post Name / Slug

Post ‘slug’ (the last part of the post’s permalink).  If blank, WordPress will assign a unique default slug automatically.

Post Format

WordPress post format

The ‘standard’ format can be specified in the input file with the value ‘standard’ (without the quotes) or just a blank entry. 

Other allowed formats are: ‘aside’, ‘chat’, ‘gallery’, ‘link’, ‘image’, ‘quote’, ‘status’, ‘video’, and ‘audio’.

Post Date

Publish date for the post.  The date may be in the past, present or future. 

The most compatible date format is “Y-m-d H:i:s” (Y = year, m = month number, d = day number, H = hour, i = minutes, s = seconds).  WordPress will also accept most other date formats.

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 a range of dates for this purpose.  Enter a ‘from’ and ‘to’ date to have TurboCSV randomly generate dates within that range. 

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

image

Tags, Categories and Taxonomies

Use this section to specify the categories, tags and custom taxonomies.  TurboCSV will default the input column for each taxonomy based on the column name, but you may also select a different column or specify a default value in the Import Template screen. 

Tags

To import tags, create a column named !tags_input in the input file.  The column should contain a list of tags separated by commas. 

TurboCSV will create any tags that don’t exist already and assign the post to the specified tags.

Categories

To import categories, create a column named !post_category in the input file.  The column should contain a list of categories separated by commas. 

TurboCSV will create any categories that don’t exist already and assign the post to the specified categories.

Custom Taxonomies

To import custom taxonomies, create a column that begins with “!” followed by the taxonomy name.  For example: !my_taxonomy.

Hierarchical Taxonomies

Taxonomies may be flat (like tags) or hierarchical (like categories).  To specify a hierarchical value separate the terms in the input file with the ‘hierarchy separator character’.  The character may be set on the TurboCSV settings screen.  By default “|” is used.

For example if your input file has a !post_category column with the value “CA|San Mateo|94112”, then TurboCSV will create the category hierarchy CA –> San Mateo –> 94112 if it doesn’t already exist.

TurboCSV will assign the post to the lowest category in the hierarchy – in this example category “94112″.  This is consistent with the way assignment works in the WordPress editor.

Multiple hierarchies can also be specified.  For example if the input column has “CA|San Mateo|94112,Daycare|Toddlers”, TurboCSV will create both of the category hierarchies and assign the post to the categories “Toddlers” and “94112′”

Term Slug and Description

When importing categories, tags or custom taxonomies, TurboCSV creates new terms if the they don’t already exist. 

Normally WordPress assigns each term a default description and ‘slug’ based on the term name. 

The slug and description can also be set explicitly using the “term / description separator”.  The separator character(s) can be defined on the TurboCSV settings screen.  The default is two colons (‘::’).

The format is: term name::description::slug.

Description and slug are optional.  For example, when importing the category “mycat”, the following are all valid:

mycat
mycat::my description
mycat::my description::myslug
mycat::::myslug

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.

image

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.

image

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.

image

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

image

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

Google Maps

If you have the MapPress Pro plugin installed, you can import map data for your posts using TurboCSV.

Warning: Geocoding dramatically slows down your imports (by up to 1 second per record).  Also, Google limits the number of geocoding requests per day.  See the MapPress documentation for details.

Setting Up MapPress

You will need at least two custom fields:

  1. A field for addresses
  2. A field for geocoding errors

Tip: The errors field is not required, although it is recommended you use it.  Do not use the same field name for both settings.

Tip: You may need to create a “dummy” post with the necessary fields in order to get them to appear in the dropdown list.

Once the fields are created, go to the MapPress settings screen and enter the address and error field names.  See the MapPress Pro documentation for detailed information about the possible settings. 

MapPress will now create a map for posts that contain the address custom field, even if the post is entered manually.  The map will contain a single “POI” (Point of Interest) for that address. 

You can test your setup by editing a post in WordPress: enter an address in the address custom field, then publish or update the post.  You should see the geocoding result displayed on a map in the MapPress map editor.  If there was an error it should be visible in the errors custom field.

Importing Map Data with TurboCSV

Once MapPress is set up you can use TurboCSV to import map data with your posts.  As the data is imported, MapPress will create a map for each post.

The import file will need to have a column for the addresses custom field you specified.  For example, if the field name was “address” the import file should have a column “address”.  If you are using other fields (such as icon, title or body), then you will need columns for those fields as well.

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.

Tip: If you need to create multiple POIs on a single map, import each POI into its own post, then use a MapPress “mashup” to combine the POIs into a single map. 

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.

Attachments and Images

If you need to link your posts to attachments (such as images or files), you will first need to import the files into the WordPress Media Library.  Then you can use TurboCSV to link your posts to them.

TurboCSV will accept an attachment ID or a full or partial URL for the attachment.  The URL must be prefixed with “u:” (you can change the prefix in the TurboCSV settings).

For example, suppose you have imported several images using the WordPress Media Library.  One image is called “myimage.jpg” with ID “1234″ and URL “http://myblog.com/wp-content/uploads/2010/08/myimage.jpg".

To store a reference to that image when importing a custom field, you can provide any of the following in the input file:

  • 1234
  • u:http://myblog.com/wp-content/uploads/2010/08/myimage.jpg
  • u:2010/08/myimage.jpg
  • u:myimage.jpg

Featured Images

TurboCSV can help you set a featured image for each imported post. 

WordPress creates a featured image for a post by storing a link to the image’s ID in a hidden custom field called “_thumbnail_id”. 

To import a featured image just select the field in the ‘Featured Images’ field dropdown on the TurboCSV import template screen.  The formats described in the ‘Attachments and Images’ section can be used in the input file – with or without the “u:” prefix.  For example:

Before you import featured images, you should also check that your theme supports them and try creating at least one featured image manually.

Tip: some plugins may store ‘featured images’ in their own custom fields, rather than the default WordPress ‘_thumbnail_id’ field.  In that case see the section “Attachments” for information about importing attachment IDs into other fields.

Frequently Asked Questions (FAQ)

My import times out and I get blank page or a 500 (error) page

TurboCSV doesn’t log this kind of error because it is a fatal error on the server that halts PHP execution.  You can check your PHP error log or Apache error log to determine the cause.  These are the most common issues:

  • PHP timeout: your import may exceed the maximum run time for PHP scripts.  This usually happens only with large files, or when importing map data.  This PHP script time can increased by editing the php.ini file and increasing the parameter max_execution_time.  Note: some hosts ignore this setting and impose their own, stricter, limits (usually 30 seconds or less). 
  • Out of memory: there are several ways to increase memory.  From easiest to hardest, they are: set WP_MEMORY_LIMIT in  your wp_config.php file, set memory_limit in your php.ini file and set php_value_memory_limit in your .htaccess file.

  • Slow server: if your server seems slow (for example, if you get a timeout after only a few hundred records) then the most likely cause is a plugin or a theme function (SEO plugins, for example, can dramatically slow imports).  To see if this is the problem, try deactivating all of your other plugins and switching to a standard theme, then repeating the import.  

If you are unable to resolve the problem, try contacting your hosting service for help, or you can split large files into smaller ones before importing.