xbFilms 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.
(click on the screengrab images to enlarge)
Contents:
- Introduction
- Uses
- Installation
- Options
- Data Structures
- Categories and Tags
- Importing Data
- Creating new data
- Admin views
- Front-end views
Introduction
xbFilms provides a catalogue of films, directors/cast/crew and reviews. For basic details see the info page.
A film can have many people associated with it - directors, cast, crew and real people featured in the film. People may be associated with many films and they may be associated with different films in different roles. They may also be subjects or authors of books which may be listed in the xbBooks component if it is installed.
A film may have more than one review, although a review always refers to a specific film. 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 films seen
- Reviews of films by different family members and friends (or others).
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 xbFilms 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 xbFilms data tables from the database. If xbBooks or another related extension is installed then the xbpersons table itself will NOT be deleted as the names may be being used in xbBooks. The linking table from persons to films will be deleted though.
Any images (posters, stills 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
xbFilms adds six new tables to the database to store the information
- #__xbfilms 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.
NB #__xbpersons is shared with the xbBooks component if it is instlled - #__xbfilmperson provides the many-to-many link between people and books
- #__xbcharacters allows details of fictional characters who appear in a book to be stored
NB #__xbcharacters is also shared with xbBooks if installed as a character may appear in both a film and a book - #__xbfilmcharacter links characters to films - a character may appear in several films and obviously a film may have many characters
- #__xbfilmreviews stores the reviews of individual films, allowing a film 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 are:
- #__xbfilms: Title, Type (fiction/non-fiction)
- #__xbpersons: Lastname (some people only have one name)
- #__xbreviews: Title, Rating, Book link.
Optional fields are:
- #__xbfilms: Subtitle, Summary (brief, plain text), Synopsis (rich text), Poster Image (filename),
Setting, Release_year, Studio, Country, Original_lang, runtime, Colour, aspect_ratio, Format, filmsound, 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: Summary (brief plain text), Review (rich text), Reviewer (defaults to username), Date read, Format read, Edition read, Category (defaults to Uncategorised), Admin note
Standard Joomla fields for all items are:
- id, category_id, asset_id, alias, state, access, created, created_by, created_by_alias, checked_out, checked_out_time, modified, modified_by, metadata, ordering, params
xbFilms does not currently implement the Joomla version control system. It seems unnecessary as items are fairly unlikely to need revision apart from living authors' biographies
The filmperson link table has six fields - id, film_id, person_id, listorder, plus a 'role' field is used as a category for the person's role on the film, and a role_note which can be used to provide additional information. The role field values are Director|Producer|Crew|Actor|Appears-In. For crew and actor roles the role_note is used to indicate the specific job or part played. The Appears-In role is for real people appearing as themselves in the film - typically used for documentaries and may also be used to flag cameo roles where a person appears as themselves, often in a no speaking part. (eg Alfred Hitchock's appearances in all his films)
The filmcharacter link table has five fields - id, film_id, char_id, listorder, char_note and actor_id to optionally link to the actor playing the role in the specific film. It is envisaged that the character table is only used for significant characters that appear in several films. eg James Bond, and that most parts in films that merit a mention will be included with the actor role in the filmperson link table.
The listorder field in both link tables controls the order in which the people or characters will be listed in a specific film on the film details view - this allows actors to be listed in billboard order rather than alphabetically. In the person view the films linked to the person are listed alphabetically by title, or optionally by release year to give a chronology for the person's films.
Categories and Tags
xbFilms uses the built-in Joomla support for Categories and Tags. These can be applied to all items. Categories for films and reviews are specific to the xbFilms component, Tags may be shared with articles and any other components using the Joomla tagging system including xbBooks.
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.
For people (and characters) there is a separate set of categories belonging to a 'virtual' component called xbpeople. The defaults categories are called "Uncat.People" and "Import.People". These categories, like the people themselves, are shared with xbBooks if it is installed
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 film may belong to both historical and crime genres - so genre may be better used a a branch of tags than a category.
Since most categorisation is better handled by tags there is an option to not display any category information on the front end, They will still appear on the admin screens, where they may be used or ignored.
Tags can be freely created when entering or editing items on the admin side. Joomla does also allow for tags to be arranged in a hierarchy using the built in Tags component,
Importing Data
Data can be imported either from an xbFilms SQL export file created with a compatible version of xbFilms 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 xbFilms Control Panel. The sample install/uninstall button can be hidden by an option setting. The sample data SQL file can be found in the /media/com_xbfilms/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 (Film/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
Admin Contents:
- General
- Control Panel
- Film List
- Edit/New Film
- Review List
- Edit/New Review
- People List
- Edit/New People
- Character List
- Edit/New Character
- xbPeople
- Category views
- Tag Views
- Data Management (import/Export/Delete)
General
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.
Film Edit/New
The film edit form has two areas - a full width top area,with three tabs below.
In the top area you can enter the Title (required), any subtitle, and a short summary. The alias, which is used to create SEF urls, is normally derived from the tile (lower case with spaces replaced by hyphens) but can also be edited. A preview of any poster image set for the film is shown on the right.
The three tabs are "General", "Contents" and "Publication".
"Publication" is the Joomla standard settings for created, modified, metadata etc. "Content" are fields related to the on-screen content of the film - a synopsis, actor and character lists, the location or setting.
'The "General" tab is for information about the film. On the right is the standard Joomla column for category, published state, and tags. Also here are a selector for an image for the film (often the poster), and a notes field. The notes here are only shown on the admin pages, not on the front-end.
Some common aspect ratio values:
- Standard (generic) - use this for anything which is not a widescreen format (most films prior to 1950) where you are not sure of the exact value
- Widescreen (generic) - use this for anything which is a widescreen format (most films since 1970) where you are not sure of the exact value
- 1.19 - Movietone standard
- 1.33 (4:3) - most silent films standard
- 1.37 Academy - the gold standard for Hollywood's heyday 1930-1960
- 1.43 iMax - standard for the original giant iMax screens - often presented in multiscreen to give a super-wide view
- 1.77 (16:9) - TV widescreen
- 1.85 widescreen - Film widescreen
- 2.19 Todd-AO -
- 2.39 anamorphic
- Cinemascope (2:35-2.66)
- Cinerama (2:59-2.65)
- 2.76 Panavision 70mm
Some common values used for 'Medium'
- Film (generic) - most traditional films are shot on 35mm negative stock
- 70mm film - used for wide screen and high quality.
- 35mm film - most films using conventional film stock. Standard or some widescreen formats - widescreen usually using an anamorphic lens.
- 16mm film - original an amateur, then a TV format. Typically used in features for handheld grainy or newsreel look.
- Video - where the recording medium is analogue videotape. TV 1960s-1980s. Most video formats too low resolution for cinema presentation.
- Digital - a digital (solid-state) sensor recorded either on digital videotape (1990-2000) or more recently direct to solid state or disk storage.
- Animation - each frame is individually produced (drawn or stop-motion animation where a single frame is shot, then the models moved slightly)
- Cartoon - animation using drawn cells. Originally hand drawn, more recently drawn on computer.
- Computer - pure computer graphics
Review Edit/New
Person Edit/New
Character Edit/New
Films list view
This view provides a list of all the films in the catalogue. You can sort the table by Title, Release Year, Date Seen, Category, ID, or Ordering (using the left side drag and drop column - this sorts _within_ each category)
You can search in title and subtitle, or by prefixing the search term with s: in the summary and description. Filters are provided for Status, to find films associated with a person or character, by category, and by tag. NB as always the filters are additive - so if you have already filtered by category searching by tag will only find tagged films in that category.
Tag filtering allows for multiple tags to be selected and the filter to require all, or any, or none (exclude) the tags. Tip: setting the tag logic to "Exclude" with no tag selected will show you all films without a tag.
In each row clicking on the film Title, the director's name, or the reviewer name and date will take you to the edit page for the item. There is also a button to directly add a new review for the film. Clicking on a Category or Tag will take you to the page listing all films with the same category or tag.
In the Toolbar at the top of the page the Batch button allows you to assign a Category or Tag to any selected items. NB you can't currently batch-remove tags.
Reviews list view
sdfsdgsdhsfh
People list view
sfsfsfsfs
Characters list view
sfsfsfsfs
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
