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:
- Introduction
- Uses
- Installation
- Options
- Data Structures
- Categories and Tags
- Importing Data
- Creating new data
- Admin views
- 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...(see roadmap)
Use case examples
- Personal record of books read
- Reviews of books from multiple readers
Installation
Install in the usual way - by downloading the zip file from here and uploading it to Extensions-|-Manage on your site admin, or from the direct link.
Immediately after installing it is recommended you review the Options (button on top right of toolbar for xbBooks Control Panel) and set any defaults. These mostly affect the appearance of the front end pages - see below.
After installation you can install some sample data to play with from the Control Panel toolbar. Once installed Sample data can be removed with the Control Panel toolbar button. NB Removing sample data simply deletes everything assigned to the "Samples" category. If you have moved sample items to a new category they will not be deleted.
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
The following are the Optional settings and their defaults. Most apply only to the front-end views and can be overridden on the menu options for each type.
The options are divided into 5 tabs - General, List Layouts, Item Layouts, Metadata, and Permissions.
General Options
- Categories
- Show Categories - Yes/No (default Yes). As discussed elsewhere categories have the limitation that each item (eg a Book) can only belong to one category, so it may be that you do not have any classification that can be used as categories. Many things, like genres, may not be mutually exclusive, and would be better handled as tags. Setting this option to "No" will prevent the display of categories on the front-end pages, although they will still appear in the admin pages and will be assigned a default value.
- Default Categories - Drop down list. You can define a separate default category for books, reviews, people and characters.
- External Links target - Same/New window or tab (default New).
Data Structures
xbBooks adds six new tables to the database to store the information
- #__xbbooks stores the information about individual books
- #__xbpersons stores details of individuals who may be authors, editors, the subject of a book, or simply mentioned in a book.
- #__xbpersonbook provides the many-to-many link between people and books
- #__xbcharacters allows details of fictional characters who appear in a book to be stored
- #__xbcharbook links characters to books - a character may appear in several books and obviously a book may have many characters
- #__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 -
- required fields which are the minimum that must be provided by the user
- optional fields which may have default values automatically added if not provided
- 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.
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,
Importing Data
Data can be imported either from an xbBooks SQL export file created with a compatible version of xbBooks, or from a CSV file which matches the required layout - for details see the CSV file section below.
A set of sample data is provided in SQL format and can be installed from the xbBooks Control Panel. The sample install/uninstall button can be hidden by an xbBook options. The sample data SQL file can be found in the /media/com_xbbooks/samples folder after installation together with some sample images for covers and portraits.
SQL export and import is used for transferring or copying data between sites - the export section allows export of a sub-set of data filtered by type (Book/Review/Person) and category. Export filtering by tag is planned for a future version.
There is currently no facility to import tags with either SQL or CSV imports.
Further details on import and export are found in the Admin Import/Export page section below.
Admin views
Control Panel
The xbBooks Control Panel provides an overview of the data.
Creating new data & editing data
Each of the list views below has a corresponding form page for creating new entries and editing existing items.
Books list view
People list view
sfsfsfsfs
Reviews list view
sdfsdgsdhsfh
Categories view
The Admin categories list view simply displays the standard Joomla category list for a component. The associated New and Edit views are provided by the categories component.
Tags list view
sdgdfgsdfg
Import/Export/Delete
The Import/Export page provides options for manipulating data in bulk including cleaning and deleting. There are separate tabs for Import and Export each offering various options.
The Delete tab is only available to Super Users and provides options for cleaning the data (removing orphan people and reviews with no book reference) and deleting some or all data. These are dangerous options as once deleted there is no recovery unless you have exported the data first.
Import
The primary import option is to take data from either an SQL or a CSV file.
The SQL option is only intended for importing data that has been exported from another site's instance of xbBooks. The xbBooks version on the exporting site must be compatible with the importing one. The CSV option allows for import from a spreadsheet or other database that can export data in comma separated variable (csv) format. a CSV file is a plain text file, but it must follow specific format requirements for xbBooks to be able to recognise the data. (see below)
Alias fields
In both cases the import system uses the 'alias' field to check whether items already exist in the database, (the item ID numbers are specific to the particular site, so cannot be used to reliably merge data onto another site). Aliases within a Joomla database table have to be unique so as well as being used for SEF URLs they can also be used as an identifier.
Generally alias names are automatically generated from titles and should be consistent between sites, but be aware that if, for example, two books have the same title or two people share the same name then it may not be possible to determine which one is being referred to when transferring between systems. Typically the first one created will have an alias created from the title, the second created one will have the same alias with '-2' appended to it. Thus if the importing site already has an entry for the second item from the exporting site, then an entry in the file for the first item will be likely to have an alias which will match the existing (second) item when imported and so will be falsely detected as already present.
In addition aliases in Joomla can be edited, for example to improve the SEF name, so might not match the standard format (title converted to lower case with non-alphanumeric characters stripped out and spaces replaced by hyphens).
CSV file format
A CSV file for import must conform to the required format to be successfully imported.
The first row must be a header row containing the field names exactly matching the specification below. For each type of item (Category, Book, Person, Review, Book-person Link) there are certain required fields, and other optional fields which may be included as columns. Any unrecognised field names in the header row will be ignored. It is not important what order the columns are in.
All data must be enclosed in double quotes with the fields separated by commas. Fields cannot include newline or carriage return characters. This might mean that you might need to check the formatting of text box fields (eg summary) and re-instate line breaks. Description fields (synopsis, biography, review) can include html so may use html formatting tags.
Comment rows. Any field containing just a single '#' character will cause that row to be treated as a comment and ignored. Files created by xbBooks csv export will have the second row flagged as a comment by setting cell A2 to '#' and with metadata about the export in the rest of the fields for row 2. The '#' field does not have to be the first one although it normally would be.
Rows are parsed and imported (if valid) in order from the top of the file. The file may contain entries for one type of item (eg only Books, with People and Book-People links in separate files) or they may be combined in a single file.
A row may contain entries for more than one type of items (eg a row might contain the author name as well as the book details). The row contents are parsed in the order Books, Persons, Reviews, Links irrespective of the column order. Thus the book will be created before the review so that they can be correctly linked. Both Book and any persons will be created before the links so that orphans are not created.
NB a row can contain only one entry of each type - Book, Review, Person. If a book has multiple reviews or multiple people associated with it in then the second review or person will need to be on a second row with the book alias or title repeated so that it can be correctly linked.
Valid header row entries:
For each type of item this lists the valid required and optional names to be used in the column headings. The name must exactly match (case sensitive) to be recognised. Optional fields may be filled with default values. All other column headings will be ignored. Optional fields can be left blank even if the column header is present. The _note fields are only displayed on the admin screens and can optional be auto-filled with the date and source of the import (prepending any existing data).
As noted above in all cases it is preferred to provide the alias field rather than reply on creating the correct alias from the title or names during import. However if you are confident that none of your titles are already in the database then not providing alias columns will be work ok.
All fields are presented as plain text fields except the Synopsis, Biography and Review fields which may include basic html tags.
Book
- Required column names: book_title
- Optional column names: subtitle, book_alias, book_summary, synopsis, cover_img, pubyear, publisher, orig_lang, fiction, cat_date, book_note
Notes: if book_alias not provided the alias will be derived from the title
cover_img will have any path information stripped and the default folder for the site will be added
pubyear is a 4 digit year number only.
fiction is a flag digit to indicate whether the book is fiction or non-fiction. Set to 1 for fiction, 0 for non-fiction. Defaults to non-fiction (0).
cat_date is a date field in any format that can be recognised as a valid date by php. This is used for the date the book was acquired for the collection, or alternatively for the date you first finished reading it. Reviews have a separate rev_date field. You can use one, or the other, or both, or neither.
Books may be imported without an author or editor assignment.
Person
- Required column names: lastname OR fullname.
- Optional column names: firstname, person_alias, person_summary, biography, portrait, nationality, year_born, year_died, person_note
Notes: Normally firstname and lastname are preferred to fullname due to potential ambiguity in splitting names like "John le Carre" and "John Paul Sartre". If lastname is not provided then fullname is used and the name is split at the last space. Firstname is not required since some authors publish with a single name (eg Homer) and this will be used as lastname.
portrait will have any path information stripped and just the filename and extension will be used with the default folder for the site added.
year_born and year_died are used simply as four digit year, the exact date is not stored.
People can be imported without any book assignments.
Review
- Required column names: rev_date, rating
- Optional column names: title, review_alias, book_alias OR book_title, review_summary, rev_edition, rev_format, rev_date, reviewer, review_note
Notes: A title is not required for a review, if not supplied it will default to "Review of [book_title] by [reviewer]".
book_alias or book_title link the review to a specific book. If absent the review will still be imported as an orphan.
rev_edition is intended to flag a particular edition of the book as being reviewed.
rev_format may be one of 'Hardback', 'Paperback', 'Kindle', 'eBook', 'Other'. Further options may be added in future.
rev_date is intended for the date the review was written, or that date the reviewer finished reading the book, as you prefer. Any text format that php can recognise as a valid date.
reviewer is the name of the person writing the review. If absent this will default to the value set on the import page.
Book-Person Link
- Required column names: role, book_title OR book_alias, lastname OR person_alias
- Optional column names: role_note
Notes: role can have any value but at present only 'author', 'editor' and 'mention' are recognised.
role_note is not currently used. It is intended for extended information.
Export
Delete
Front-end views
Front-end views are provided for lists of data and individual item views. Both can be created as menu entries, the individual item pages are also linked from the lists.
Most list views can optionally have user driven search and filtering facilities and/or can be filtered in the menu entry options. Details of the filtering available are given in each sub-section below. Some options may be set at a global level and overridden at menu or page level. If you get unexpected results check the global option settings.
Category List view
Books List view
People List view
Reviews List view
Tag List view
Single Category view
Single Book view
Single Person view
Single Review view
Single Tag view
