http://docs.kde.org/
Prev Next

Chapter 7. Hacking Tellico

Table of Contents

File Format
XML Data
Collection Type Values
Field Type Values
Hidden Configuration Options
[General Options]
[Options - bibtex]
Bibtex Character Translation
XSLT Tricks

In the spirit of Free Software, you are welcome to hack on Tellico as much as you like. You should be able to write scripts to import, export, or modify data very easily. This chapter gives you more information about doing that.

File Format

The default Tellico data file is a zip archive, normally with a .tc file extension. Inside the archive is a top-level tellico.xml file. Images may be included inside the images/ folder in the archive, or they may be included in the XML data directly in a base64 encoding. Images may also be saved inside the application data folder, in which case, they are not in the data file at all. Tellico can also load the XML file, by itself, uncompressed.

XML Data

Collection


<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE tellico PUBLIC "-//Robby Stephenson/DTD Tellico V11.0//EN" "http://periapsis.org/tellico/dtd/v11/tellico.dtd">
<tellico xmlns="http://periapsis.org/tellico/" syntaxVersion="11">
 <collection title="My Books" type="2">
 </collection>
</tellico>

The file begins with the required XML declaration and encoding, followed by the doctype. When a new field type is added or additional properties are set on the default fields, the doctype DTD version is incremented. Tellico is always able to open and read any previous DTD version, but will save files in the current version. The DTD location does point to an actual DTD file.

The top-level element is a <tellico> element, containing the default namespace declaration and the syntax version of the file, which should always match the DTD.

The <tellico> element contains one <collection> element. Multiple collections are ignored, for now. The title attribute contains the collection title, while the type specifies what kinds of entries are contained in the collection. The allowable types are in listed in a later section. An optional entryTitle attribute may be used to specify the title of the entries for a custom collection, and should be plural.

Fields


  <fields>
   <field flags="8" title="Title" category="General" format="1" type="1" name="title" />
   <field flags="7" title="Author" category="General" format="2" type="1" name="author" />
   <field flags="2" title="Binding" category="General" allowed="Hardback;Paperback;Trade Paperback;E-Book;Magazine;Journal" format="4" type="3" name="binding" >
    <prop name="default">Paperback</prop>
   </field>
   <field flags="6" title="Publisher" category="Publishing" format="0" type="1" name="publisher" />
   <field flags="4" title="Edition" category="Publishing" format="0" type="1" name="edition" />
   <field flags="3" title="Copyright Year" category="Publishing" format="4" type="6" name="cr_year" />
   <field flags="2" title="Publication Year" category="Publishing" format="4" type="6" name="pub_year" />
   <field flags="0" title="ISBN#" category="Publishing" format="4" type="1" name="isbn" description="International Standard Book Number" />
   <field flags="7" title="Genre" category="Classification" format="0" type="1" name="genre" />
   <field flags="7" title="Keywords" category="Classification" format="0" type="1" name="keyword" />
   <field flags="0" title="Front Cover" category="Front Cover" format="4" type="10" name="cover" />
   <field flags="0" title="Comments" category="Personal" format="4" type="1" name="comments" />
   <field title="Rating" flags="2" category="Personal" format="4" type="14" name="rating">
    <prop name="maximum">5</prop>
    <prop name="minimum">1</prop>
   </field>
   <field title="ID" flags="32" category="Personal" format="4" type="6" name="id">
    <prop name="template">%{@id}</prop>
   </field>

  </fields>

All of the fields are defined inside a <fields> element, of which there can be only one. All of the information for a field, except for any properties, are included as attributes of the <field> element. The allowable values for the flags, format, and type attributes are given in a following section.

Field properties are used for setting default field values, rating value ranges, derived value templates, etc. The examples above include a default value, a maximum rating value, and a template for a derived ID field.

Entries


  <entry>
   <title>C++ Programming Language, The</title>
   <authors>
    <author>Stroustrup, Bjarne</author>
   </authors>
   <publisher>Addison-Wesley Pub Co</publisher>
   <edition>3rd</edition>
   <pub_year>1997</pub_year>
   <isbn>0-201-88954-4</isbn>
   <genres>
    <genre>Non-Fiction</genre>
   </genres>
   <keywords>
    <keyword>Programming</keyword>
    <keyword>Computers</keyword>
   </keywords>
   <cover>cf65a2f023b6cb9e9233323dca10ac7c.jpeg</cover>
  </entry>

For every field in the collection, an <entry> may contain an element whose name is identical to the field name. If multiple values are allowed for the field, then the letter s is added to the field name to create an element, and each value is added as a child of the element, as in the case of the author, genre, and keyword fields above.

As a result, if additional fields are added to the collection, the data file will no longer conform to the DTD. However, Tellico uses a non-validating XML parser, so additional fields do not cause problems.

Images


  <images>
   <image width="111" format="JPEG" height="140" id="cf65a2f023b6cb9e9233323dca10ac7c.jpeg" />
  </images>

Inside the <images> element, each image referenced by an entry is listed, along with attributes describing the image's size, format, and id. If the image is contained inside the Zip file, the element is empty. Otherwise, the image data may be contained in the XML stream as base64-encoded text.