HLC .::. Home Library Catalog

Design Document

Author: Edmond Lau
Last updated: July 13, 2003
© 2003 Home Library Catalog Development Team
All documents and codes of Home Library Catalog are released under GPL.

This is the on-going design document of the project - Home Library Catalog. Our team is currently drafting the specification and designing the structure of our project. Hence this document will change constantly in the next couple of weeks. For the newest information regarding to our project, please visit http://hlcatalog.sourceforge.net. Whereever possible, we will add diagrams to this document to make our ideas more concrete. If readers has any suggestions regarding to our specification and design, please feel free to e-mail our project leader - Edmond Lau. Any suggestions / comments are always welcome.

Introduction

The initiation of the Home Library Catalog - HLCatalog - or simply HLC - is to develop a program that help end-users to store information of their CDs, Books, DVDs, and many other types of media. But since everyone has their own personal preferences of how these information are stored, we are going to design our program in such a way that it will be able to adapt these changes in the most convinent way for the end-users.

General

We are going to use C++ to develop the HLC. The front-end Graphical User Interface (GUI) will be developed using the Qt Graphical Toolkit (3.1.0+). The data of each type of records by the user are going to be stored in separate XML documents. We are planning to use DTD files for definitions and XML validations.

Requirements:

The following is a list of requirements for the release 1.0 of HLC:

A0001 - Allow users to (add / modify) types of records.
A0002 - Allow users to (enable / disable) specific type of records being used.
A0003 - Allow users to (add / remove / modify) records of each type.
A0004 - Allow users to search records using:
- A0004.001 - Wildcard search
- A0004.002 - Exact word search
A0005 - Provide user with TableView interface for records.
A0006 - Provide user with ListView interface for records.
A0007 - Provide user with Automatic Generated Dialog boxes for display and edit. (see section Graphical User Interface)
A0008 - Configuration files will be stored in XML.
A0009 - Provide user with Dialog boxes for configuration.
X0001 - XML Parser using Qt classes
X0002 - XML Writer using Qt classes
X0003 - DTD Parser
X0004 - DTD Writer
X0005 - XML Validator
D0001 - User Help file in XML format
D0002 - User Help file in HTML format
X0006 - In cases of invalid data file, XML record recovery
A0010 - Other error handling.

Graphical User Interface

Will include more detail later on. MDI is preferred, but SDI is also cool. We will try to include prelimiary screen shots of the prefered screen layout.

Backend - XML

All the data in our program are stored in XML formats. Hence we will need tools and functions for: DTD validation, DTD parsing, XML validation, XML parsing, etc. In the first release of HLC we will include simple tools to do such work, where they will be based on the Qt XML module. We will extend these XML functionalities in later versions of HLC. Whenever possible, HLC will perform validation of the documents. In the cases where the DTD or XML files are corrupted, HLC should have functions to fix simple problems in the documents. However, this error correction functionality may not be included until later versions.

Development Cycle

We will include more information about the development cycle when our design reach certain level of maturity. In short: spiral development model. Basically we are going to state a few development milestones, and for each milestone we will do: analyse, design, allocate resources, implement, testing, documentation, and review. Our project will not deploy any major version until all requirements are met.

Implementation

C++ coding convention is still an open issue.

User Scenarios

The following is an user scenarios proposed by D'laila. We will leave this as open discussion.

When a user opens the application for the first time, HLC asks the user if he/she wants to use HLC for DVD/CD/Books. This can be a dialog box, text box, or a drop down menu.
Depending on his selection, HLC will present a general view for each of the three CD, DVD(movie), and Books. The user has the option of adding more fields if he/she so desires.
Or let the user enter the fields, as he/she desires for the option selected. (Note: between 2 and 3, I think 2 is preferable, the user sees a general GUI and then he/she can personalize it)
If the user wants to personalize the GUI, he can enter the fields that he wants.
The frontend GUI is then modified to display the GUI that the user wants.
The user can add records thru a TableView or ListView
The user can add / remove / modify / search already existing records.

Testing Approach / Procedure

Developers will decide this issue when development is started.

Open Issue

The following is a list of issues that we should discuss within our design process:

How many XML files to be supported: number of records, and file size.
How is this product available to the user?
XML convention?
C++ convention

Appendix

The following is the use case diagram:

The following is the class diagram:

The following is an example of DTD definition file for books:

<!-- By Edmond Lau for hlcatalog -->
<!-- status: draft, have not validated yet -->

<!ELEMENT books (book*)>
<!ATTLIST books name CDATA #IMPLIED>
<!ELEMENT book (title, author, publish, bought, location, extra)>
<!ELEMENT title (#PCDATA)>
<!ELEMENT author (#PCDATA)>
<!ELEMENT publish (by, date, pages, isbn, webpage)>
<!ELEMENT by (#PCDATA)>
<!ELEMENT date (#PCDATA)>
<!ELEMENT pages (#PCDATA)>
<!ELEMENT isbn (#PCDATA)>
<!ELEMENT webpage (#PCDATA)>
<!ELEMENT bought (#PCDATA)>
<!ELEMENT location (where, loan?)>
<!ELEMENT where (#PCDATA)>
<!ELEMENT loan (#PCDATA)>
<!ELEMENT extra (comments, rating)>
<!ELEMENT comments (#PCDATA)>
<!ELEMENT rating (#PCDATA)>

The following is an example of XML data file for books:

<?xml version="1.0"?>
<!DOCTYPE books SYSTEM "books.dtd">
<books xmlns:="hlcatalog.sourceforge.net/books" name="My Book Collections">
        <book>
                <title>Programming with Qt, 2nd Edition</title>
                <author>Mattbias Kalle Dalheimer</author>
                <publish>
                        <by>O Reilly</by>
                        <date>January 2002</date>
                        <pages>500</pages>
                        <isbn>0596000642</isbn>
                        <webpage>www.oreilly.com</webpage>
                </publish>
                <bought>May 2002</bought>
                <location>
                        <where>bookshelf 2</where>
                        <loan> </loan>
                </location>
                <extra>
                        <comments>This books is very useful.</comments>
                        <rating>4</rating>
                </extra>
        </book>
        <book>
                <title>Essential GIMP for Web Professionals</title>
                <author>Michael J. Hammel</author>
                <publish>
                        <by>Prentice Hall</by>
                        <date>2001</date>
                        <pages>355</pages>
                        <isbn>0130191140</isbn>
                        <webpage>www.phptr.com/essential</webpage>
                </publish>
                <bought>May 2002</bought>
                <location>
                        <where>bookshelf 2</where>
                        <loan>lend to Bob Foo</loan>
                </location>
                <extra>
                        <comments>This is not a bad book, but the authors could add more real life examples.</comments>
                        <rating>3.5</rating>
                </extra>
        </book>
</books>