xbBooks component Documentation. This primarily deals with the admin side of managing the data. Presentation on the front-end site is straightforward with user interaction for searching filtering and sorting the data using standard Joomla facilities.

Contents:

  1. Introduction
  2. Uses
  3. Installation
  4. Options
  5. Data Structures
  6. Categories and Tags
  7. Importing Data
  8. Creating new data
  9. Admin views
  10. Front-end views

Introduction

xbBooks provides a catalogue of books, authors/editors and reviews. For basic details see the info page.

A book can have many people associated with it - authors, editor and real people mentioned in the book. For fictional works it may also have characters in the book. Characters and real people may be associated with many books - in the case of real people they may be associated with different books with different roles.

A book may have more than one review, although a review always refers to a specific book. Reviews include a star rating for 1 to 7 stars. Often 5 stars is used for simple ratings, but I find this inadequately coarse and often ended up giving half stars - in effect making it a 10 point scale. For many years I have used a 10 point scale for books and films - but reviewing it I find that I tend to be clustering my ratings between 5 and 9 and underusing the lower parts of the scale.  So for xbBooks and xbFilms I have switched to a seven point scale.

In addition I have added the option for a zero rating which is reserved for things so bad or nauseating that I simply didn't finish them, or walked out of the film - a rare event in my experience but it does happen and merits a special flag using a vomit icon. This is an option that can be disabled.

In a future version it might be possible for the admin to specify the maximum rating as well...

↑ Contents

Use case examples

  • Personal record of books read and 
  • Reviews of books from multiple readers 

Installation

Install in the usual way - by downloading the zip file from here and uploading it to Extensions-Install on your site admin, or from the direct link

After installation you can install some sample data to play with

Uninstalling

Uninstall will remove all xbBooks data tables from the database. If xbFilms or another related extension is installed then the xbpersons table itself will NOT be deleted as the names may be being used in xbFilms. The linking table from persons to books will be deleted though. 

Any images (book covers or portraits) will not be removed by uninstall - you may be sharing these with other articles on your site. If you have organised them into separate folders then it is easy to manually delete them from the media manager.

Setting Options

 

 

↑ Contents

Data Structures

xbBooks adds six new tables to the database to store the information

  1. #__xbbooks stores the information about individual books
  2. #__xbpersons stores details of individuals who may be authors, editors, the subject of a book, or simply mentioned in a book.
  3. #__xbpersonbook provides the many-to-many link between people and books
  4. #__xbcharacters allows details of fictional characters who appear in a book to be stored
  5. #__xbcharbook links characters to books - a character may appear in several books and obviously a book may have many characters
  6. #__xbbookreviews stores the reviews of individual books, allowing a book to have more than one review

Each of these tables aside from the link tables has three types of field -

  1. required fields which are the minimum that must be provided by the user
  2. optional fields which may have default values automatically added if not provided
  3. Joomla system fields which track data about the item. Generally these are added automatically, but can be overridden by the admin.

Minimal required fields from the user are:

#__xbbooks: Title, Summary (brief, plain text) or Synopsis (rich text), Type (fiction/non-fiction)

#__xbpersons: Lastname

#__xbreviews: Title, Rating, Summary or Review, Book link.

Optional fields are:

#__xbbooks: Subtitle, Cover Image (filename), Publication year, Publisher, Original language (defaults to English), External links, Category (defaults to Uncategorised), Admin note 

#__xbpersons: Firstname, Portrait (filename), Nationality, Year born, Year died, External links, Category (defaults to Uncategorised), Admin note

#__xbreviews: Reviewer (defaults to username), Date read, Format read, Edition read, Category (defaults to Uncategorised), Admin note

Standard Joomla fields for all items are:

id, asset_id, alias, state, access, created, created_by, created_by_alias, checked_out, checked_out_time, modified, modified_by, metadata, ordering, params 

xbBooks does not currently implement the Joomla version control system. It seems inappropriate as items are fairly unlikely to need revision apart from living authors' biographies

The link tables consist of three fields - id, book_id and person_id, plus for #__xbbookpersons a 'role' field which is used to flag if the link is for the person as author, editor or mentioned in a book.

 

 

↑ Contents

Categories and Tags

xbBooks uses the built-in Joomla support for Categories and Tags. These can be applied to all items. Categories are specific to the xbBooks component, Tags may be shared with articles and other components using the Joomla tagging system.

Two default categories are provided - "Uncategorised" and "Imported", others can be added ad-lib. Joomla allows categories to be presented as a hierarchy - any category can have any other category set as a parent. 

An item can only belong to one category so you need to think carefully about what to use as categories; for example genres are often not mutually exclusive - a book may belong to both historical and crime genres - so genre may be better used a a branch of tags than a category.

For books there is one virtual category built in to xbBooks - the type Fiction/non-Fiction. All books will be assigned to a one of these two types as well as a category.

Tags can be freely created when entering or editing items on the admin side. Joomla does allow for tags to be arranged in a hierarchy, 

 

↑ Contents

Importing Data

There are currently two basic options for importing existing data, either from an SQL file containing INSERT statements with the correct field names or from a CSV file containing a header row specifying the fields and rows of data separated by commas and enclosed by double quotes ("xyz","23",.."2020-10-18").

SQL import file can contain data for several tables. In order to ensure that links are built correctly the tables should be imported in the order Books, Persons, Characters, Reviews, BookPerson, whether the data is all in one file or split between separate files. Clearly a review or person cannot be linked to a book if the book is not already in the database.

The SQL import file uses the alias field to identify duplicates (existing books or people) and to create the links. There is no need to have id fields specified in the SQL. Most of the standard Joomla fields (id, access, created and modified info etc) will be ignored if they are in the file and default values set. Various options for defaults are available on the Import page.

 

SQL import can optionally create categories if they do not already exist. Categories are specified by their alias rather than id to allow for transferring data between sites where the id's will change.  Items without a category will default to the "Imported" category.

There is currently no facility to import tags with either SQL or CSV imports.  

A sample data SQL import file can be found in the /media/com_xbbooks/samples folder after installation

CSV import file can include related items on the same row - book, review, and a single person (defaults to the author), or can split items onto separate rows or even separate files.

 

Currently (v0.5) there is no facility for importing or assigning categories or tags in CSV files. All items in a file can be given a default category chosen from the existing list. The default default will be "imported"

The header row must contain required field names, and any optional fields being used, in lower case in the first line (header row). Thereafter each row contains data for a single item or set of related items.

As with the SQL import the alias fields are used to identify existing items to be ignored as duplicates and the links between items. If the alias fields are not present then the alias will be constructed from the title (or names, for people) field. This has the potential to cause errors if an existing but different item has the same title. For example 2 books with the same title: Life After Life by Jill McCorkle and Life After Life by Kate Atkinson. If the McCorkle book is already in the catalogue with the alias life-after-life, which would be the default assigned by Joomla, then the import will be unable to determine if it is a duplicate or the Atkinson book, which should get the alias life-after-life-2.

Aliases are constructed by removing punctuation and replacing spaces with hyphens in the title (or firstname lastname for people).

The following fields (columns) are required (in bold) and optional for each item type.

Books: book_title, book_alias, subtitle, book_summary, synopsis, pubyear, publisher, orig_lang, fiction, book_note

The "fiction" column should contain "0" for non-fiction and "1" for fiction. A default for missing values can be set on the Import page.

People: firstname, lastname, fullname, person_alias, person_summary, biography, nationality, year_born, year_died, person_note

The "fullname" column is an optional alternative to lastname and firstname. If it is present the text will be split at the last space to create a firstname,lastname pair. This may have undesirable effects. For example the fullname "John le Carre" will become firstname "John le" and lastname "Carre" which is probably not what you want. You can work around this by including a firstname and lastname column as well and leaving it blank for all entries except the ones which need correcting - "John" and "le Carre". The lastname will always be taken in preference to the fullname if it is present.

Only lastname is required in order to handle people with only one name - for example "Homer" author of the Illiad.

Reviews: title, review_alias, book_alias, rating, review_summary, review, date_read, reviewer, rev_edition, rev_format, review_note

For reviews the book_alias, rating and date_read are all required in addition to the title. The rating is a numeric value from 0 to 7 - see the note on ratings for more details. The "reviewer" can be set to a default for all missing values on the import page. "rev_edition" is used if the review refers to a particular edition of the book, rather than the default one in the catalogue entry - it can be left blank. "rev_format" is used to specify which format the book was read in (eg Hardback, paperback, Kindle, Audiobook ...) and can be blank.

Review titles for import will default to "Review of 'Book Name' " if there is no text in the title field - this largely because when I was bulk importing data to one of my sites the reviews did not have titles, but were simply directly linked to the book.

 

For all items the summary and full text (synopsis, biography, review) can be blank when importing, whereas when entering data direct you are required to put something in one or other field. This means that if you import books with no summary or synopsis if you edit them after editing you will be required to enter something.

 

 

Admin views

Control Panel

The xbBooks Control Panel provides an overview of the data. 

 

↑ Contents

Creating new data

blah blah

 

↑ Contents

Books

dfgdfg

 

↑ Contents

People

sfsfsfsfs

 

↑ Contents

Reviews

sdfsdgsdhsfh

 

↑ Contents

Categories

sfsgdg 

 

↑ Contents

Tags Views

sdgdfgsdfg

 

↑ Contents

Import/Export/Delete

sfSFSF

 

↑ Contents

Front-end views

 

 

↑ Contents