Skip to content

Customization

Jump to bottom
lat9 edited this page Apr 21, 2025 · 2 revisions

This section identifies the steps you'll take to customize your Database I/O Manager installation.

Note: The DbIo requires the PHP php-mbstring extension to be loaded for its proper operation; if it's not installed, you'll receive an error message when you attempt to use Tools :: Database I/O Manager. If you receive that message, you'll need to contact your webhost and request that the extension be loaded on your store's server.

Considerations

Here are some things to consider as you're setting up and configuring your DbIo installation:

  1. Character encoding. I know, boring stuff, but it's very important to the proper operation of DbIo! The plugin's installation verifies that your store's base character-encoding is "proper" by checking that your store's CHARSET is compatible with your store's DB_CHARSET values. It's your job to properly identify the character-set used by the spreadsheet tool you are also using (e.g. Apache OpenOffice or Microsoft Excel).

    You'll use the Configuration :: DbIo Manager Settings ::CSV: Encoding setting to instruct DbIo how to interpret the data coming from or going to a .csv file. Set that value to utf8 if you are using Apache OpenOffice (or any other known utf8-generating program) or to latin1 if you are using Microsoft Excel.

  2. File naming. DbIo uses the name of an I/O "handler" to identify files to-be-processed by that handler. For example, any .csv files to be processed by the Featured handler reside in the /YOUR_ADMIN/dbio/ folder and are named dbio.Featured.anything.csv

  3. Language-specific Fields. While EP-4 uses the convention of appending the language_id (e.g. v_products_name**_1**) to identify language-specific fields, DbIo appends the (more portable) language_code (e.g. v_products_name**_en**) when identifying language-specific values.

  4. Record removal. While EP-4 uses the convention of setting the products_status to a value of 9 to indicate a product to be removed, DbIo introduces a new column (v_dbio_command) that a handler can conditionally enable to support record-removal and/or other commands. Starting with v1.1.0, the Products handling supports this field; set that column's value to REMOVE for a particular product and, if the product exists, it will be removed.

Configure

Once you've installed DbIo, you can customize its base settings via Configuration :: DbIo Manager Settings:

Field Name Field Description
Version/Release Date Displays the plugin's version number and release date.
CSV: Delimiter Enter the single character that is used to separate columns within any DbIo CSV file. To use the tab-character as the delimiter value, enter the word TAB. Defaults to the comma (,) character.
CSV: Enclosure Enter the single character used to enclose fields within any DbIo CSV file. Defaults to the double-quote (") character.
CSV: Escape Enter the single character used as the escape-character within any DbIo CSV file. Defaults to the backslash () character.
CSV: Encoding Choose the type of encoding to be associated with all DbIo I/O files. If you use Microsoft® Excel, choose latin1; if you use Apache OpenOffice, choose utf8.
CSV: Import Date Format Choose the format used by any DbIo CSV file when importing date and datetime fields, one of:
m-d-y
d-m-y
y-m-d
Default: m-d-y
Maximum Execution Time (seconds) Enter the maximum execution time for a DbIo operation, in seconds. Default: 60
Split File: Record Count Sometimes, splitting a .csv file into multiple, smaller files can help if your server is timing out on an import operation or if an exported .csv is too large to download in a single chunk. Enter the number of records (Default: 2000) at which to split these files using the Database I/O Manager.
Default File Sort Order Choose the default sort-order that the Database I/O Manager uses when displaying the I/O files it has discovered, one of:
1a: File name, ascending
1d: File name, descending
2a: File size, ascending
2d: File size, descending
3a: File date, ascending
3d: File date, descending (default)
Products Import: Allow Duplicate Models? Choose whether (Yes) or not (No) any Products import should be allowed to change an existing product's "model number". Default: No. (Introduced in v1.1.0)
Products: Product Creation Requires Command? Does a Products import require a DbIo ADD command? Choose No (the default) to allow products to be created if no matching products_id and/or products_model is found. Choose Yes to disallow any product-import that results in a new product unless the ADD command is present. (Introduced in v1.6.4)
Products: Auto-Create Categories on Import? How should the DbIo handle missing categories on a Products import? Choose Yes to have any missing categories automatically generated; choose No (the default) to disallow any product imports when the categories don't previously exist. (Introduced in v1.3.0)
Enable Debug? Identify whether (true) or not (false, the default) the DbIo debug is to be enabled. When enabled, all I/O status is written to a dbio-*.log file in your store's /YOUR_ADMIN/dbio/logs folder.
Debug Date Format Enter the formatting string used to timestamp all DbIo log entries; see the description of the PHP date function for more information. (Default: Y-m-d H:i:s).

I/O Handlers

DbIo uses "Handler" scripts to customize an I/O action; the following table shows the Handlers currently provided.

Handler Name Actions Export Filters Customizable? Description EP-4 Name
Customers Export None No This handler provides the export-only of all fields in the database's customers table. —
Featured Import, Export None No This handler provides the import and export of all fields in the database's featured table. Featured Products
Manufacturers Import, Export None No This handler provides the import and export of all fields in the database's manufacturers and manufacturers_info tables, added in v1.2.0. —
Orders Export Orders Status, ID Range, Date Range Yes This handler supports export-only of all fields within the orders table. The information does not include the associated products or their attributes. Starting with v2.0.0, the values of all orders_totals (other than 'ot_tax' and 'ot_total') are also included. —
OrdersProducts Export Orders Status, ID Range, Date Range No This handler supports the export-only of an order's customer information and associated products' model-numbers and names. —
OrdersProductsAttributes Export Orders Status, ID Range, Date Range No This handler supports an export-only of an order's customer information and associated products' model-numbers, names and attributes (option name/value pairs). Filterable Order Exports: Orders Full
Products Import, Export Product Status, Manufacturer, Category Yes This handler supports import/export of all fields within the products, products_description and meta_tags_products_description tables, the basic product information.
  1. Starting with DbIo v1.1.0, a product's record can be located via either its products_id or products_model (both columns are *required* in the import file) and an existing product can be removed by creating a v_dbio_command column with a product's entry set to REMOVE. Starting with v1.4.0, a product's record can be forced to be created when the v_dbio_command column for the product is set to ADD.
  2. Starting with v1.3.0, if a non-existent category is specified in a v_categories_name field, you control whether that category is automatically generated; see the Configure tab for more information. Note that categories cannot be created within categories that currently contain products and that products cannot be added to categories that currently contain sub-categories.
  3. Starting with v1.6.4, you can use the UNLINK command to unlink a product from the category identified by the v_categories_name field. The product and the category must both exist and the categories_id assocated with that category's name must not be the product's "master_categories_id".
 Complete Products
ProductsOptions Import, Export None No This handler supports import/export of all fields within the products_options table, the products' options' information. When importing new records for a multi-language store, the import should be run once per language value. Otherwise, the products_options_id will get "out-of-sync" between the multiple languages. —
ProductsOptionsValues Import, Export None No This handler supports import/export of all fields within the products_options_values table, the products' options' values' information. When importing new records for a multi-language store, the import should be run once per language value. Otherwise, the products_options_id will get "out-of-sync" between the multiple languages. —
ProductsAttribsBasic Import, Export None No This handler supports import/export of the basic fields associated with the products_attributes table, using a products_model value to associate a product to the attribute-values (products_options_type, products_options_name, and products_options_values name). Basic Products Attributes
ProductsAttribsRaw Import, Export None No This handler supports import/export of all fields associated with the products_attributes table, using the products_id, options_id, and options_values_id values to identify a record in the table and, thus, whether the record is an insert or an update. Detailed Products Attributes
ProductsDiscountQuantity Import, Export None No This handler supports import/export of fields associated with the products_discount_quantity table, using the products_id value to identify the product for which the discount-quantities are to be updated. Refer to the handler's on-screen instructions for additional information. —
Specials Import, Export None No This handler supports the import/export of fields associated with the specials table, using the products_id value to identify the product for which a special-price is to be updated. Refer to the handler's on-screen instructions for additional information. A product's special price can be removed using a v_dbio_command column with the value set to REMOVE. —
Stats Export None No This handler supports export of all fields present in the dbio_stats table, where DbIo records its statistics. Starting with v1.6.0, once the table is exported, the table is emptied. —

Naming Conventions

Following are the naming conventions used by the Database I/O Manager:

  1. Handler Names. A handler's name consists of characters matching [a-zA-Z0-9_], allowing the handler name to be presumed as its class name. No checks performed; you'll get a PHP error if the name's not a "good" PHP variable.
  2. Handler Files. A handler named MyHandler provides two files (and, yes, case is significant):
    1. /YOUR_ADMIN/includes/classes/dbio/DbIoMyHandlerHandler.php
    2. /YOUR_ADMIN/includes/languages/english/dbio/DbIoMyHandlerHandler.php
  3. Handler Messages. Message defines in a handler's language-file should be named based on the handlerName: DBIO_HANDLERNAME_*.

Clone this wiki locally