Calibre2OpdsCustomize
| Home Page |
User Guide | Calibre2opds Developers Guide | Issues | |||
|---|---|---|---|---|---|---|
| Overview | Building | Localization | Customization | |||
Customizing Calibre2opds
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:
Contents |
[edit] Overview
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 do customization 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 is possible 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 distribution if anyone produces any interesting ones.
[edit] Extend list of supported formats
Calibre2opds has a built-in list of the book formats that it recognizes, and the associated mime types that should be set for download links. For more details on how you can add additional formats to those that are recognised by default see the later section on Mime Types.
[edit] 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
- OPDS catalog from third parties
[edit] 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
<html> <head> <title>Using a frameset to embed calibre2opds catalog inside part of the page</title> </head> <frameset rows="3"> <frame src="my_top.htm"> <frame src="_catalog/index.html"> <frame src="my_bottom.htm"> <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 </noframes> </frameset> </html>
- Create the HTML files that you want loaded into the other panes. For this example I created my_top.htm containing:
<html> <head> <title>My Top page</title> </head> <body> <h1>This is content to be displayed above the calibre2odps catalog</h1> </body> </html> <p style="padding-left: 30px;">and <em>my_bottom.htm</em> containing</p> <p style="padding-left: 60px;"><html> <title>My Top page</title> <body> <h1>This is content to be displayed below the calibre2odps catalog</h1> </body> </html></p>
- If you now loaded the sample index.htm that you have just set up it would look something like the following:
[edit] Where should customized files be located
Calibre2opds will search for files that are on its customizable list in the following locations (in the order specified):
- Calibre2opds configuration folder: This is the folder where calibre2opds stores user specific settings. Its location can be found by using the Open Configuration Folder option from the Tools menus within Calibre2opds.
- Calibre2opds install folder: This is the folder where the calibre2opds binaries have been installed
- Built-in: Calibre2opds has the default versions of all customizable resources built in to the binaries.
If a file exists at more than one of the above locations then the first one that is found is used. 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).
[edit] Files that can be customized
The master copies of files that can be customized (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.
The following specifies which files can be customized to over-ride the calibre2opds built-in versions.
| Filename | Description | |
|---|---|---|
| Mime Types | ||
| mimetypes.txt | This is the file that contains the definitions of the ebook file types and their associated MIME types that are currently understood by Calibre2opds. A copy of the file used for any generate run of Calibre2opds is put into the folder that contains the generated catalog. | |
| Templates | ||
| 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. | |
| header.xsl | This is the XSL template that is used to generate the 'header.html' file that can provide a custom header at the top of every page in your catalog. The default template provides empty content so that by default no custom header information is displayed. | |
| generated.xsl | This is the XSL template that is used to generate the generated.html file that is included at the bottom of each HTML page and provides summary details about the last generation run. | |
| Icons | ||
| 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 | |
| Stylesheets | ||
| 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. | |
| JavaScript | ||
| functions.js | Provides some common support functions | |
| Search related files | ||
| _search/search.html _search/css/desktop.css _search/database/database.js _search/media/license-bsd.txt _search/media/css/demo_page.css _search/media/css/demo_table.css _search/media/css/demo_table_jui.css _search/media/images/back_disabled.jpg _search/media/images/back_enabled.jpg _search/media/images/favicon.ico _search/media/images/forward_disabled.jpg _search/media/images/forward_enabled.jpg _search/media/images/Sorting icons.psd _search/media/images/sort_asc.png _search/media/images/sort_asc_disabled.png _search/media/images/sort_both.png _search/media/images/sort_desc.png _search/media/images/sort_desc_disabled.png _search/media/js/jquery.dataTables.min.js _search/media/js/jquery.js |
All these files under are used to support the search facility in HTML based catalogs. Any of them can be cusomised to provide a different behavior or look-and-feel. | |
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 customization files need amending appropriately.
[edit] Information about specific file types
[edit] Mime Types
A mime type is a way of indicating what type of content is associated with a particular file. It is often used by software such as browsers to decide how to handle a particular file. In practice getting the mime type wrong often does not matter as the majority of software seems to ignore the value that has been specified. However this is not true of all software so it can be important to be able to control the mime type for particular file types.
For most common file types there is general agreement on what is the valid mime type for that type of file. However in the ebook world there is less consensus as different vendors have used their own particular values so it is quite possible that the assumption Calibre2opds makes about the mime type for a file is not what the user actually wants.
Calibre2opds has a table that maps file extensions to the mime type to be used for files with that extension. This table can be over-ridden by a user supplied table. Reasonsfor such an over-ride might be:
- The user wants to change the mime type associated with a particular file extension
- The user’s Calibre library contains a file type for which Calibre2opds has no built-in mime type so the user wants to extend the table
The contents of the mime types table that Calibre2opds used for a particular catalog generation can be seen by examining the file mimetypes.txt that is output to the root of the generated catalog. This file is a simple text file that can be viewed and/or edited by any tool capable of handling such files. examining this file also shows the format of the entries to be used for defining new types.
The user can either add additional entries for to this file to get new formats recognized by calibre2opds, or change the mime type associated with any particular format. To get any such amended file used by calibre2opds in any future generate runs, the amended mimetypes.txt file should be placed in one of the locations calibre2opds checks for customization files that are defined below under "Where Should Customized Files be Located"
Note that minimal checking is done on the contents of this file other than that any lines not marked as comments contain at least two fields. The fields are separated by whitespace which can be one or more space or tab characters. Comment lines are indicated by starting a line with the # character. There are no checks such as whether duplicates are present, so be careful when editing this file.
[edit] Icons
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 48x48 pixels.
Note: Customized icon will only be used if the user has specified the use of External icon files in the Advanced tab of the calibre2opds settings. If this setting is not active then the built-in default icons will always be used.
[edit] XSL templates
The XSL templates are used internally by calibre2opds during a generation run to generate the HTML versions of catalog 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 changes that causes an error at runtime will cause a calibre2opds run to fail to generate the expected HTML catalog correctly. If such errors occur then an entry will be written to the Calibre2opds log file, but experience has shown that it can sometimes be tricky to identify exactly which line/statement in the XSL template has triggered the error.
The XSL templates are closely tied to the format of the XML files that are generated by Calibre2opds. If you are using a customized XSL template then when installing new releases of Calibre2opds you need to check that your customized version is still valid. There is a good chance that they will as the XML format has remained relatively stable during the lifetime of Calibre2opds but it is not guaranteed that no change will be introduced in the future to either fix a bug or to support a new feature. To help with managing this it is recommended that you always keep a copy of the Calibre2opds XSL template that your changes are based on. You can then easily check if this is different in any way from the one that is built in to the new Calibre2opds binaries you have just installed.
[edit] CSS Stylesheets
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.
In particular this is where you can change the fonts and colours used by different parts of the Calibre2opds generated HTML catalog. Some examples of this can be seen if you download the different CSS.zip file that is included at the top level of the Calibre2opds source on GitHub.
[edit] JavaScript
The Javascript support functions are used to carry out tasks that can not easily be done directly in either HTML or CSS type stylesheets.
The calibre2opds developers would be very interested in any new functions that could be contributed to enhance the calibre2opds GUI.
