Summary

Properties

Description

The "ISBN" datatype allows the validation, storage and retrieval of a single ISBN (International Standard Book Number) code. From version 3.10 of eZ Publish, this datatype uses the new ISBN-13 format by default.

Note that from the 1st of January, 2007, the book industry started using 13 digit ISBN codes (ISBN-13) to identify all books in their supply chains.

According to the ISBN-13 standard, the 13-digit number consists of five parts. The parts are separated by dashes. The following table describes each of the five parts using the ISBN-13 code "978-0-14026-690-0" as an example.

While the "Prefix" and "Check digit" elements have a fixed length (3 and 1 digits accordingly), the length of the remaining elements may vary. However, the total length of an ISBN-13 is always 13 digits. The length of the "Registration group", "Registrant" and "Publication" elements can be calculated according to the rules set by the International ISBN Agency. The calculation of these elements is based on the distribution of ranges for the different regions.

In eZ Publish, the ISBN codes are stored as text. The digits are separated by dashes. The different ranges are stored in the database, allowing the system to fix up incorrectly entered ISBN-13 codes (codes with misplaced or missing dashes). When a new version of eZ Publish is released, the latest information about the different ranges is downloaded from http://www.isbn-international.org and stored in the "db_data.dba" file located in the "kernel/classes/datatypes/ezisbn/share/" directory. During the installation process, the setup wizard imports this information to the database. If the information about ranges is missing from the database, the system will display a warning at the class attribute edit interface for this datatype (see below).

Note that the calculation rules can be changed on a monthly basis and thus you should run the "updateisbn13.php" script regularly in order to keep the range-information in the database up to date. The following example shows how to get the latest ranges from the ISBN International website:

Run the "updateisbn13.php" script using the following shell command:

php bin/php/updateisbn13.php --file=ranges.js

The script will import information from the isbn international website to the database.

The following screenshot shows the class attribute edit interface for this datatype.

Class attribute edit interface for the "ISBN" datatype.

The "ISBN-13 format" checkbox makes it possible to configure the datatype so that it validates and stores ISBN codes according to the ISBN-13 standard. From version 3.10, this checkbox is checked by default when a new attribute using the ISBN datatype is created. Note that the object edit interface will appear differently (four input fields instead of one) when the checkbox is unchecked (see below).

The following screenshot shows how the class attribute edit interface for the ISBN datatype looks like if the information about ranges is missing from the database.

Class attribute edit interface for the "ISBN" datatype if the range data for ISBN-13 was not imported.

Click the "Import ISBN range data" button to import ranges to the database.

Object attribute edit interface

The following screenshot shows the default object attribute edit interface for this datatype.

Object attribute edit interface for the "ISBN" datatype.

As the screenshot shows, an ISBN-13 code consists of five parts separated by dashes.

The system will automatically add dashes in case they were omitted during input (for example, "9780140266900" will be converted to "978-0-14026-690-0"). The system will also automatically fix incorrectly placed dashes (for example, "978-0-140266-90-0" will be converted to "978-0-14026-690-0"). If an ISBN-10 code is entered, the system will automatically convert it into a valid ISBN-13 code unless the "ISBN-13 format" check-box is disabled at the class level. Note that there is no support for automatic conversion of ISBN-13 codes to ISBN-10 codes since the ISBN-10 format is considered to be obsolete.

In eZ Publish 3.10, a feature for checking the validity of ISBN codes has been introduced. By default, the system will check all elements of an ISBN-13 code and display a warning if one or more of the entered elements are invalid. For example, "978-0-14026-690-6" is considered to be an invalid code; according to the standard, the last digit should have been a zero ("0"). The validity checking feature can be turned on (default) or off. It is controlled by the "StrictValidation" setting located in the [ISBNSettings] section of the "settings/content.ini" configuration file. Note that the "Prefix" and "Check digit" parts will be validated regardless if the "StrictValidation" setting is enabled or not.

The following screenshot shows the object attribute edit interface for this datatype when ISBN-13 support is disabled.

Object attribute edit interface for the "ISBN" datatype when in ISBN-10 mode.

Raw output

The ".content" of an ezcontentobjectattribute object using this datatype returns a hash containing eight elements. The hash-structure of the elements is given in the table below.