Best Practices

1. Make the add-on run only when necessary.

Your add-on should only run when the user is importing to the theme or post types supported by your add-on.

Otherwise, your add-on’s import function would save data in the database when the user is doing an import that isn’t making use of your add-on.

Specify when your add-on runs using the run function.

Example A – only when importing to “listing” Custom Post Type

$my_addon->run(
	array(
		"post_types" => array( "listing" ),
	)
);

Example B – only when “Twenty Fourteen” OR “Twenty Fifteen” themes are activated

$my_addon->run(
	array(
		"themes" => array( "Twenty Fourteen", "Twenty Fifteen" )
	)
);

Example C – only when importing to “post” OR “page” Custom Post Type AND when “Max Estate” theme is activated

$my_addon->run(
	array(
		"themes" => array( "Max Estate" ),
		"post_types" => array( "post", "page" )
	)
);

Example D – run the add-on always

$my_addon->run();

2. Make the add-on respect the user’s “Choose which data to update…” Import Settings.

On future runs of the same import, users can choose to not update Custom Fields, Images, and more.



The rapid add-on API supports checking if Custom Fields or images should be updated.

To do that, use the following functions.

Use can_update_meta to see if a Custom Field should be updated:

function my_addon_import( $post_id, $data, $import_options ) {

	global $my_addon;

	if ( $my_addon->can_update_meta( '_price', $import_options ) ) {
		update_post_meta( $post_id, '_price', $data[''] );
	}

}

Use can_update_image to check of the “Images” box is checked:

function my_addon_import( $post_id, $data, $import_options ) {

	global $my_addon;

	if ( $my_addon->can_update_image( $import_options ) ) {
                set_post_thumbnail( $post_id, $data['image']['attachment_id'] );
	}

}

There are more options in the Choose which data to update section, but they are rarely used by add-ons. These options are stored in the $import_options variable, which is passed to the registered import function. If your add-on does advanced things like changing parent posts, menu orders, etc. and you want to support these options, the settings you need to check are stored inside $import_options.

Please note can_update_image only tells you if the Images box is checked, it doesn’t tell you the settings. If you care, read it from $import_options.

3. Warn the user to install WP All Import.

You can display a dismissible notice warning the user to install WP All Import to use your add-on.

$my_addon->admin_notice();

Customize the notice text by passing a string to admin_notice(), i.e.

$my_addon->admin_notice( "XYZ theme import add-on requires <a href='http://wordpress.org/plugins/wp-all-import'>WP All Import</a>" );

Add conditions for displaying the admin notice:

$my_addon->admin_notice(
    "This Add-On requires WP All Import, the WP All Export Plugin and Twenty Fifteen theme.", 
	array(
		"themes"  => array( "Twenty Fifteen" ),
        	"plugins" => array( "wp-all-export/wp-all-export.php" )
    )   
);

4. Use tooltips when necessary to explain fields to users.

The fifth parameter of the add_field() function can take a string that will be used as a tooltip for the field. This will work for any of the field types.

$my_addon->add_field( 'property_price', 'Price', 'text', null, 'Numbers only, no symbols' );

5. Add entries to the import log.

The log() function must be run within the import function.

function my_addon_import( $post_id, $data, $import_options ) {

	global $my_addon;

	if ( $my_addon->can_update_image( $import_options ) ) {
		$id = $data['slider_image']['attachment_id'];

		$my_addon->log( '- Adding slider image, attachment ID: ' . $id );

		add_post_meta( $post_id, 'slider_image', $id );
	}
}

6. Disable the default images section if it’s not being used.

$my_addon->disable_default_images();