As well as providing a convenient means to create a database of documents to include in a bibliography, using the standard LaTeX/BibTeX route, BibDesk can also export a whole database, or a selection of the database to a number of other formats, including HTML, RTF, and the Word DOC format. You can find an explanation of the use of templates for export in the Manual, also included in the BibDesk Help Menu. This page will expand upon the information in the Manual, and describe how to create templates to meet your own needs, and how to set up BibDesk to use your own templates. This document will mainly concentrate on the export to HTML files. Beyond their obvious application as files for web bibliographies, HTML is a common import format in many word processors, such as Apple's Pages and TextEdit, Microsoft Word et al. Thus an HTML template can also be used as a template for export to these programs. There will also be links to templates which have been written by BibDesk users; for further discussion or to post templates, use the BibDesk-users mailing list.
Other Uses for Templates
BibDesk uses templates in various places. Apart from export, templates are used for the pretty printed previews in the main window, copying, and services, and moreover can be used for dragging and emailing.
How to Export
The Export submenus can be found in the File menu of BibDesk. You can either export the whole database, or just the references which you have selected.
To use the default template, select the "HTML" item from the export submenu. A standard save box will then open, allowing you to choose the name of the html file, and also the location on your hard drive. In order to use a non-default template the last menu item "Using Template" should be selected. This also leads to a save box, but with the addition of a dropdown menu at the bottom of the save box where a template can be selected. The file extension should change to reflect the output format, i.e. html, rtf, doc etc.
Modifying a Template
You can find a set of default template files in the folder ~/Library/Application Support/Bibdesk/Templates. For HTML export, there are 3 template files: htmlExportTemplate.html, htmlItemExportTemplate.html and htmlExportStyleSheet.css. Generally, only the first of these template files is required. You can also find these template files from the Templates pref pane. Click on the triangle to the left of "Default HTML template" to reveal the list of template files for this template. Control-click or right-click on a file in this list to either reveal it in a Finder window, or open the file with your favorite viewer or editor.
Looking at the htmlExportTemplate.html file first, this is a relatively simple html document, with a standard header, a link to the external CSS file, and a single "content" div in the body. The formatting of the individual entries into the html file is done using the htmlItemExportTemplate.html file. Opening this file, you will see that the template files comprise a series of items enclosed in < and > signs, the same as those used in HTML to enclose formatting tags, but starting with an extra $. These entities are known as Template Tags. They are parsed by BibDesk to include the relevant parts of the BibDesk database in the html file. E.G. <$fields.Title/> will be replaced by the contents of the "Title" field in the BibDesk database. A list of the different kinds of Tag is given in the Export Template Keys page. It is also possible to apply modifiers to the field Tags in order to format the contents. One example is the <$fields.Authors/> Tag where the full name or an abbreviated name can be chosen, and the "and"s between authors can be replaced by commas. These modifier keys are also explained at the Export Template Keys page.
Examples of Tags
- <$authors.abbreviatedName.@componentsJoinedByCommaAndAnd/> → F.R. Bloggs, T. Smith, and R.P. Jones
- <$authors.name.@componentsJoinedByComma/> → Fred Richard Bloggs, Tim Smith, Ronald Percival Jones
- <$authors.normalizedAbbreviatedName.@componentsJoinedByCommaAndAndWithEtAlAfterTwo/> → Bloggs, F.R., Smith, T., et al.
- <$authors.name.@firstObject/> → Fred Richard Bloggs
- <$fields.Title.capitalizedString/> → The Meaning Of Life
For the formatting of the fields, I have set each field as a <div> or <span> with a class or id. Then I have used a separate CSS file to define the formatting of each field. This also allows for different formatting to be used for online view or for printing out. In my case, the online view is part of my base.css file, while I have a separate print.css file, which removes most of the colouring, and the different font sizes, and makes it more plain. Since this is not meant to be an HTML/CSS tutorial, I will not explain further how to achieve the desired effects. One point of note is that I use the print.css file when importing bibliographies into a word processor. Different programs have different import methods. One thing I have noticed is that Pages, part of Apple's iWork suite, will take account of CSS formatting, although it reads from both the base.css and the print.css files. Microsoft Word on the other hand, completely ignores any CSS formatting, and imports the plain HTML file. Score one for Pages.
You can save your templates anywhere in principle. However, it is probably tidiest to keep them in the aforementioned Templates folder. Before you are able to use them however, you need to tell BibDesk where they are, and what role each file should play in the template.
Adding a Template to BibDesk
In order to make use of your own template, go to the Templates preference pane in BibDesk, and follow these steps. Let's assume that you have created two files, "NewMainTemplate.html" and NewItemTemplate.html".
- Click on the "+" button at the bottom right corner. This will create a new template named "Click twice to change name." Make sure it's select and click on it to change its name to something else, e.g. "New Template."
- Click on the triangle to the left of this template name, which will bring up another item in red called "Double-click to choose file."
- Double-click on the red message to bring up a standard dialog box where you choose the main template file, in this case "NewMainTemplate.html".
- Check to the right of the template name ("New Template" in this example) in the "Role" column, it should say "html." If it does not, click on the up-down arrow pair to the right. This brings up a menu, select "html." This tells BibDesk which file extension to use for files exported using this template. Alternatively, double-click on the text and start typing "html" and it will autocomplete.
- With "NewMainTemplate.html" selected, click on the "+" button again, to add a second template file. Repeat step 3 on this second file to select "NewItemTemplate.html."
- Then click to the right of where it says "Choose role" in red text in the "Role" column. Click on the up-down arrow pair or double-click to tell BibDesk about the role this file plays for the template. In this case it should be set to "Default Item." You did not have to do this for the first file, as that is always supposed to have its role set to "Main Page." You can also add template files for other roles. Files whose role is "Accessory File" are always copied as they are when exporting. This could be an accompanying .css file. Other roles are publication types, such as "article" or "book," which are used instead of the "Default Item" template file for items of the corresponding publication type.
You can also drop all the template files on the table to add the templates. If there is more than one file, you will be asked to select which one to use as the main template file (the one with role Main Page). This will replace (most of) steps 1, 3, and 5 above.
Export Using a Template
In order to generate an html file, go to your BibDesk database file (.bib file), select one or more references, go to the File menu, select "Export Selection..." and then "Using Template". This will bring up a save dialog box. At the bottom of the dialog box, there is a button marked "Using Template" where you can select which template to use. Choose either "Default Template" or "New Template". Type in the name of the output html file at the top, select a folder for it to save to, and click "Save". If your new template does not show up in this list, then try quitting BibDesk and restarting it to clear up any glitches.
This is a list of custom templates you can use with BibDesk.
- A template simulating the plain bibtex style, or as a multiple file template
- A template simulating the abbrv bibtex style, or as a multiple file template
- A condensed version of the default RTF template, more useful in the side pane preview.
- An RTF template for title, authors and abstract, useful for the preview.
- An RTF template for title, authors and annotations, useful for the preview.
- A template for export to Comma Separated Values (.csv) format
- A template for export to Tab Separated Values (.tsv) format
- A template for APA style Author + Year citations
- A template for APA style Author + Year citations without comma before ampersand
- A template for APA style full citations
- A template for Harvard style Author + Year citations
- A template for Harvard style full citations
- A template for Chicago style Author + Year citations
- A template for Chicago style full citations
- Templates for export to expanded BibTeX, expanding macros and inherited values, expanding macros, expanding inherited values
- A template to export minimal BibTeX including a Local-Url field, getting the Local-Url field from the first linked file.
- A template for American Anthropological Association style
- Templates for a preview pane layout that includes abstracts, annotations and Skim notes, and Applescripts and templates for a similar summary display of lists of selected references in TextEdit and Pages.
- A RTF Template for film studies and German speaking humanities in general.
- An iPhone Template, partly based on the one Steve Richardson posted to the bibdesk-users list. It will be very helpful to also install the Find in this page bookmarklet from http://www.lifeclever.com/17-powerful-bookmarklets-for-your-iphone/. You also need a server to host the HTML & css output. The zip includes a copy of the BibDesk icon which can be posted on the server as well to allow you to customize the icon on the phone. Recommended for bibliographies of a few hundred items of less to keep the iPhone Safari stable. The template features:
- formats refs. for article, book, inbook
- default display is author, date, title
- click on a record to reveal
- further reference info
- the first two URLs associated with the record
- an auto-generated URL for a google scholar search for the item
- a link to compose a new e-mail containing the reference (convenient for sending off references @ conferences etc.)
- A two columns RTF template for a preview pane layout in two columns
- Your custom template?
Things to Do
- Need help on the Key Value Pairs front. More examples are needed, and I am not sure myself what some of the options do.
- Explain single file templates and separate templates for special pub types.
- Add some links to example templates, and example output.
- Add images of the Export menu.
- Notes about things the export process doesn't do.
- Explain existing service templates.