==================================== ISBN datatype Techical specifications ===================================== :authors: Bjørn Reiten :Version: 0.1 This spesification describes the technical implementation of the isbn datatype. Class diagram ============= +------------+ | eZDataType | +------------+ 1| +----------+ |oo +------------+ ... ... ... | eZISBNType | ... ... ... +------------+ 1| | |1 oo +------------+ +----------------| eZISBN13 | | +------------+ | 1 +-------------+ 1 +-----------------------+ | eZISBNGroup |-------| eZISBNRegistrantRange | +-------------+ oo +-----------------------+ | oo | 1 +------------------+ +---------------| eZISBNGroupRange | +------------------+ Desciption of the classes for the isbn datatype =============================================== eZISBNType ---------- Is the main class for the isbn datatype, which inherit from eZDataType. This class is also handling all processing of ISBN-10 numbers, that is the old standard of ISBN, which now is deprecated and should not be used. The isbn Number is stored in one field, data_text in the table ezcontentobject_attribute, which will allways be stored with separator as hyphen stored at the correct place, depending on each areas ranges. Example: 978-0-11-000222-4 The field that shows if the value is stored as isbn-10 or isbn-13 is the field data_int1. The different combinations are: isbn-10: 0 isbn-13: 1 The default value will be set to isbn-13 when you try to add a new ISBN datatype in the contentclass. eZISBN13 -------- Will handle all isbn-13 related tasks. The The different parts of the isbn number will be extracted and hyphens will be placed between each grup. The isbn-13 number consists of: Prefix element Registration group element Registrant element Publication element Checkdigit How to derive the different groups are calculated based on information stored in the different classes eZISBNGroup, eZISBNGroupRange and eZISBNRegistrantRange which contains information about ranges from each area (registration group). The Prefix element should allways be 978. The prefix 979 is recerved for later use. eZISBNGroup ----------- Contains information about all areas (group elements) and a short desciption. All group numbers should follow the rules set in eZISBNGroup, which describes the length of the group element. eZISBNGroupRange ---------------- Contains information about all valid ranges for the group element. From and to number is the test range the isbn number can contain. The test number is based on the 5 numbers after the Prefix number. Example: 978-0-11-000222-4 where the testnumber will be 01100. The number is stored in the database as an integer. If the range is from 0 - 59999, we get get lengt of the group number to be 1, which gives the group number 0. group_from and group_to are a similar description of the from and to field of the test number and contains the range with the correct amount of digits. Is stored as a string, since the value may start with 0 because og the length of the field. Example: 02. group_length is how many digits the registration group value will require. eZISBNRegistrantRange --------------------- Is similar to the group range class. Contains information about all valid ranges for registrant elements, which can be different for each group element. Therefore you have an isbn_group_id, which relates to an eZISBNGroup object. from_number and to_number contains information about all valid ranges from the registrant element. The registrant test range is based on the 5 numbers after the prefix and the group element. By that reason you need to calculate the group element before you can find the registrant element. Example: 978-0-11-000222-4 where the testnumber will be 11000. The range 0 - 19999 has the length 2, which gives the registrant value 11. registrant_from and registrant_to are a similar description of the from and to field of the test number and contains the range with the correct amount of digits. Is stored as a string, since the value may start with 0 because og the length of the field. Example: 02. registrant_length is how many digits the registrant value will require. isbn_group_id is a numer to the id in eZISBNGroup. Additional scripts ================== Script to update all isbn numbers to a valid isbn-13 number ----------------------------------------------------------- The script: bin/php/ezconvert2isbn13.php Will go through contentobject attributes with the isbn datatype and convert them to a valid isbn-13 number and should be run after you've set the ISBN-13 option for the contentclass attribute, when changing the contentclass. The script has the following commandline options: --class-id=2 Will Go through all ezisbn attributes in the class with id 2 and convert everyone which is a isbn-10 value. --attribute-id=12 will check if this is a isbn datatype and convert all isbn-13 values in the attribute with id 12. --all-classes Does not have any argument, and converts all contentobject attributes that is set to isbn-13. --force or -f will work in addition to all the options above and set the class attribute to isbn-13, even if it was isbn10 before and will also set the option isbn-13 in the contentclass for the isbn attribute. Script to read isbn data from the dba file ------------------------------------------ When you do an upgrade of a site and need to insert the isbn data, you can run this script to update the necessary tables. The script: bin/php/ezimportdbafile.php Parameters: --datatype=ezisbn Will try to find a dba file in the specified datatype. Example: kernel/classes/datatypes/ezisbn/share/db_data.dba Each datatype is responsible to clean up the necessary tables before the data is inserted. This is done by reimplement the function: cleanDBDataBeforeImport() in the datatype, which knows which tables you need to clean. The file db_data.bda will only contain the data for the tables and not the defenition of the table itself. The file db_data.dba can be generated by the script bin/php/ezsqldumpisbndata.php Note: You need to create the necessary tables before running this script, which should exist in the sql updates for the eZ Publish version (3.10). Script to update the isbn group and ranges ------------------------------------------ The script: cronjobs/updateisbn13.php Which should be run with: php runcronjobs.php isbn13 --file=ranges.js Where: isbn13 is an own group in cronjob.ini --file=ranges.js are refering to a javascript file that contains information about the different ranges. The ranges are located at: http://www.isbn-international.org/converter/ranges.js (Used by http://www.isbn-international.org/converter/ranges.htm). Which you need to copy to a local place on your server first. Each time the script is run, all info in tables related to eZISBNGroup, eZISBNGroupRange, eZISBNRegistrantRange will be removed and replaced with info based on this file. Example: The information that will be extracted are lines containing the information: gi.area0.text="English speaking area"; which contains a description about the name of the area (registration group element) and gi.area0.pubrange="00-19;200-699;7000-8499;85000-89999;900000-949999"; which contains information about the different ranges for the registrant. The registration group class will be calculated by how the values of registration group elements are used. Note: You should ensure that this file still contains this structure.