bib2tpl API

Talking to BibtexConverter

Provided that all files contained in the src folder are accessible, all you have to do is include the main source file, create a new instance of the converter class and use its method. This would be the minimal usage scenario:

<?php
  require('bibtex_converter.php');
  $conv = new BibtexConverter(array());
  echo $conv->convert($bibtex, $template);
?>

You can put the following options in an array passed to the constructor:

  • 'only' => array('field' => 'regexp', ...)
    This option filters out all entries that do not conform to the specified restrictions. For an entry to conform, all its fields that occur as keys have to match the corresponding regular expression (case insensitively). You can easily allow entries by, say, two authors by using doe|sue as regexp for author as field. Default is not filtering.
  • 'group' => 'field'
    Entries are grouped by the specified field. You can use any field or none, firstauthor, entrytype. Entries that do not define the specified field are collected in a separate group. Default is year.
  • 'order_groups' => '(asc|desc)'
    Determines in which order groups will be shown. Default is desc.
  • 'sort_by' => 'field'
    Determines by which field entries are sorted inside their group. field can be any field or DATE which uses both year and month. Default is DATE.
  • 'order' => '(asc|desc)'
    Determines in which order entries will be shown inside their group. Default is desc.
  • 'lang' => 'la'
    Sets the language used for group headings and month comparison. Take care the file lang/la.php exists and has the same structure as the shipped ones. Default is en.

In a second parameter, you may pass a function callback that sanitises BibTeX field contents as they may contain \(\LaTeX\) syntax you want purged or converted. The specified function has to take one string parameter and return a string; by default, no sanitisation is performed.

Method convert has two basic modes of operation. While the second parameter invariably holds a template string, the first can hold either a BibTeX string or an array of already parsed BibTeX. You may want to use the latter option to increase performance. You can parse BibTeX to its array form with static method parse; the example above therefore is equivalent to

<?php
  require('bibtex_converter.php');
  $conv = new BibtexConverter(array());
  $parsed = BibtexConverter::parse($bibtex);
  echo $conv->convert($parsed, $template);
?>

convert takes a third, optional parameter that can be used to replace entry keys in the result; to this end, pass array('oldkey' => 'newkey', ...). By default, the original keys are used.

Language Files

bib2tpl currently ships with files for the following languages:

  • English (en)
  • German (de)

If you create a new language file, please let me know so I can include it.