ISBN

Summary

Validates and stores an ISBN value.

Properties

Name	Internal name	Searchable	Information collector
ISBN	ezisbn	Yes.	No.

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.

#	Name	Description	Example
1	Prefix	A three digit prefix that can be either 978 or 979. Note that the new 979 prefix will not be utilized until all 978 prefixes have been assigned.	978
2	Registration group	A variable set of digits that identify the country/region in which the ISBN code was assigned. Zero ("0") means that the book belongs to an English speaking area.	0
3	Registrant	A variable set of digits that identify the publisher to whom the ISBN code was originally allocated.	14026
4	Publication	A variable set of digits that identify the title of the book.	690
5	Check digit	A one digit control number that makes it possible to validate the ISBN code. The check digit is calculated using a formula that makes use of the preceding parts (Prefix, Registration group, Registrant and Publication).	0

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:

Download a ".js" file containing the list of ranges using the following link: http://www.isbn-international.org/converter/ranges.js
Navigate into the eZ Publish directory and copy the downloaded file there.
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 "range.js" file 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" checkbox 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.

Key	Type	Description
prefix	string	The "Prefix" part of the ISBN code (for example 978).
field1	string	The "Registration group" part of the ISBN code (for example 0).
field2	string	The "Registrant" part of the ISBN code (for example 14026).
field3	string	The "Publication group" part of the ISBN code (for example 690).
field4	string	The "Check digit" part of the ISBN code (for example 0).
value	string	The entire ISBN code with dashes (for example 978-0-14026-690-0).
value_without_hyphens	string	The entire ISBN code without dashes (for example 9780140266900).
value_with_spaces	string	The entire ISBN code with spaces (for example 978 0 14026 690 0).

Written by:Balazs Halasy (21/02/2005 2:38 pm)

Last updated by:Julia Shymova (20/03/2008 3:56 pm)

Maintainers:Balazs Halasy, Julia Shymova

Comments

Compatible with the 10 ?

Thursday 18 October 2007 8:20:10 am

Xavier dutoit

It reads like it's either the old 10 or the new 13, but not the both. I hope that's just the doc that isn't clear, because in real life, it will still have both formats in the publication sold, and it would be not so smart to have to create to datatypes.

Anyway, the tests on the format should be a warning, not an error, as given how complex the rules are, an error is more likely due to a missing update on the share/rules than on an error.

Beside, trying to tell a user that the number he just retyped in a lot of separated fields (why not a big one, so copy paste works ?) that the number of the book he has in front of him is wrong is asking for trouble.

end of the rant, I'll convert the isbn field into a text one.
- Re: Compatible with the 10 ?
  
  Thursday 18 October 2007 9:48:29 am
  
  Bjørn Reiten
  
  The datatype supports either the old (ISBN-10) or the new (ISBN-13) but not both of them at the same time.
  
  You have a script that will convert all existing ISBN-10 numbers to ISBN-13 when you want to switch (where the last check-digit will be changed automatically).
  
  The ISBN-13 value will be presented in one big field with ISBN-13.
  
  If you don't want the strict validation for the isbn-numbers, it is possible to turn this of in the content.ini setting:
  
  [ISBNSettings] StrictValidation=false

Path

Table of contents