This section covers what facilities are available for the user to customize the look-and-feel aspects of calibre2opds. It is most likely to be of interest to those who make heavy use of the HTML versions of the catalogs.
The topics covered are:
- Adding External Links
- Calibre2opds catalog as part of a frameset
- Where should customized files be located
- Files that can be customized
- Information about specific file types
Note that this section does not cover options that control the structure of the library such as the sections that should be generated; the rules for splitting by letter; page sizes and so on. This sort of setting is controlled by the options that the users can set within the GUI and is not amenable to change beyond what can be specified there without altering calibre2opds source code.
Reasons for wanting to docustomization can vary widely, but some of the commonest ones will be:
- To ‘Skin’ Calibre2opds. By changing some of the stylesheets used by the calibre2opds HTML catalogs it ispossible to supply your won color scheme and font selections.
- Change page structure. The HTML catalog pages are generated by using XSLT transforms on the XML file used by the OPDS version of the catalog. Amending these transformation files can change the way that individual pages are laid out.
There is limited customization that can be done with the look-and feel of OPDS catalogs as the look-and-feel of such catalogs is largely determined by the OPDS client software. The main option that can be changed here is the icons.
The look and feel of the HTML catalogs can be customized far more highly. You can alter the XSLT template that is used to generate the HTML from the XML catalogs, and you can also provide runtime stylesheets to replace the ones that are shipped as part of calibre2opds.
If users take advantage of this capability it would be nice if they could feed back examples of what they have achieved so that other users can see what is possible. In fact we would be more than happy to include alternative stylesheets as part of the standard distribtion if anyone produces any interesting ones.
Adding External Links
This is covered here just to point out that it is not necessary to do any of the customization covered in this section of the documentation simply to add new external links to the top level of a calibre2opds generated catalog. One can do this by setting up entries on the Custom Catalogs tab in the GUI based configuration.
These external links can be one any of:
- external web pages. There is no restriction on how such pages are formatted so the content can be anything you like.
- other catalogs generated by calibre2opds
Calibre2Opds catalog as part of an frameset
One thing that is not strictly a calibre2opds customization feature, but that can affect how a calibre2opds HTML catalog is presented to the user is to embed the calibre2opds catalog into a pane of an HTML iframe.
An example of how one might do this is as follows:
- Create a file called index.html and put it into the root folder of your calibre library. It could contain contents that look a bit like the following
<title>Using a frameset to embed calibre2opds catalog inside part of the page</title>
<noframes> Sorry – this browser cannot handle frames <p> click <a src=”_catalog.index.html”>here</a> to get to the first page of the catalog
- Create the HTML files that you want loaded into the other panes.
For this example I created my_top.htm containing:
<title>My Top page</title>
<h1>This is content to be displayed above the calibre2odps catalog</h1>
and my_bottom.htm containing
<title>My Top page</title>
<h1>This is content to be displayed below the calibre2odps catalog</h1>
- If you now loaded the sample index.htm that you have just set up it would look something like the following:
Where should customized files be located
Calibre2opds will search for files that are on its customizable list in the following locations:
- Calibre2opds configuration folder
This is the folder where calibre2opds stores user specific settings.
- Calibre2opds install folder
This is the folder where the calibre2opds binaries have been installed
Calibre2opds has the default versions of all customizable resources built in to the binaries.
To over-ride the built-in version the user must put their customized versions in one of the locations that are checked before the built-in versions are used. for most cases it would make no difference whether the calibre2opds configuration or install folders are used. Both are provided simply to allow the user to use whichever is the most convenient.
Note that whenever calibre2opd uses a user supplied resource then this information will be written to the log file. This allows the user to check that their resource is being picked up by calibre2opds, and also allow calibre2opds support to see if the user is not using the default files (and thus possibly causing an error in calibre2opds).
Files that can be customized
The following specifies which files can be customized to over-ride the calibre2opds built-in versions.
|catalog.xsl||This is the XSL template that is used to transfrom the XML format catalog pages into the equivalent HTML format pages.|
|fullentry.xsl||This is the XSL template that is used to transform the XML entry for a Book’s details into the equivalent HTML page.|
|allbooks.png||The icon used to indicate the ‘allbooks’ catalog entry or catalog section. Is also used elsewhere when a ‘books’ type icon would be appropriate.|
|authors.png||The icon used to indicate an ‘authors’ catalog entry or catalog section|
|custom.png||The icon used to indicate a ‘custom catalog’ catalog entry|
|external.png||The icon used to indicate an ‘external catalog’ catalog entry|
|featured.png||The icon used to indicate a ‘featured books’ catalog entry|
|ratings.png||The icon used to indicate a ‘ratings’ catalog entry or catalog section|
|search.png||The icon used to indicate a ‘search’ catalog entry|
|recent.png||The icon used to indicate a ‘Recent Books’ catalog entry|
|series.png||The icon used to indicate a ‘series’ catalog entry or catalog section|
|tags.png||The icon used to indicate a ‘tag’ catalog entry or catalog section|
|catalog.css||The main stylesheet affecting the runtime look-and-feel aspects of the HTML.It is expected that in addition to this stylesheet there will also be either the ‘desktop’ or ‘mobile’ stylesheets active|
|destop.css||A stylesheet that is invoked to provide formatting specific to a desktop browser. A browser is determined to be a desktop version by testing for the maximim screen resolution that is supported.|
|mobile.css||A stylesheet that is invoked to provide formatting specific to a mobile browser. A browser is determined to be mobile by testing for the maximim screen resolution that is supported.|
|functions.js||Provides some common support f8nctions|
The master copies of these files (i.e. the ones that are built into calibre2opds) can be obtained from the calibre2opds source code repository. These can be used as the starting point for any customization changes that you might be considering.
CAUTION: Any time that a new version of calibre2opds is made available then any customization changes that have been made should be reviewed against the new master copies of the files that have been changed. It is possible some change to the calibre2opds features might have meant that changes were made in the master copies of the files that mean that the user custoization files need amending appropriately.
Information about specific file types
Icons are the little images displayed against entries in the different catalog sections. The images are particular to the section they are being used in, and the type of entry.
Icons are expected to be in .png format and have a resolution of 48×48 pixels.
Note: Customized icon will only be used if the user has specified the use of External icon files in the Dvanced tab of the calibre2opds settings. If this setting is not active then the built-in default icons will always be used.
The XSL templates are used internally by calibre2opds during a generation run to generate the HTML versions of files from their corresponding XML variants. The XSL templates are used to do a XSLT tranform on the XML files.
One needs to be very careful when changing these files as change that causes an error at runtime will cause a calibre2opds run to fail.
The CSS stylesheets are only used with HTML catalogs. They only take effect when the user is attempting to browse a catalog that has been generated by calibre2opds and have no effect on the generation process itself. They are used to determine many of the the look-and-feel aspects of the HTML catalogs.