node package manager

citation-js

Citation.js

Citation.js converts formats like BibTeX, Wikidata JSON and ContentMine JSON to CSL-JSON to convert to other formats like APA, Vancouver and back to BibTeX.

NPM version NPM total downloads Build Status Dependency Status

Table of Contents

Get Started

Install

Node.js

Install the package (citation-js) like this:

npm install -g citation-js

To run the program, use

citation-js  [options]

Options:

  -h, --help                      output usage information
  -V, --version                   output the version number
  
  -i, --input <path>              Input file
  -u, --url <url>                 Input url
  -t, --text <string>             Input text
  
  -o, --output <path>             Output file (omit file extension)
  
  -R, --output-non-real           Do not output the file in its mime type, but as a string
  -f, --output-type <option>      Output structure type: string, html, json
  -s, --output-style <option>     Ouput scheme. A combination of --output-format json and --output-style citation-* is considered invalid. Options: csl (Citation Style Lanugage JSON), bibtex, citation-* (where * is any formatting style)
  -l, --output-language <option>  Output language. [RFC 5646](https://tools.ietf.org/html/rfc5646) codes

To use the Cite constructor, require() the module like this:

var Cite = require('citation-js')

Browser

Download citation.js (citation.min.js), include it in you page, and you can require('citation-js') to get the Cite contructor.

<script src="path/to/citation.js" type="text/javascript"></script>
<script>
  var Cite = require('citation.js')
</script> 

Example

var Cite = require('citation-js@0.3.0-6')
 
var data = new Cite('Q21972834', {
  format: 'string',
  type: 'html',
  style: 'citation-apa',
  lang: 'en-US'
})
 
data.get() // Should implicitly display  

To test this code, go to RunKit.

Use

Cite

Use the object constructor Cite() to parse input and get output.

Input

Make a Cite object like this:

var example = new Cite( <data>, <options> )
  1. In the first parameter you pass the input data. Input types
  2. In the second parameter you pass the options.

Input types

Input type doesn't have to be specified. The identifiers below are used by internal functions.

DOI
  • api/doi: URL in the form of http[s]://doi.org/$DOI where $DOI is the DOI
  • string/doi: A DOI surrounded by whitespace
  • list/doi: A whitespace-separated list of DOIs
  • array/doi: An array of strings of type string/doi
  • There's no url/doi, because that's equivalent to api/doi through DOI Content Negotiation
  • There's no object/doi, because the API output is CSL-JSON (it currently does need some minor changes, see CrossRef/rest-api-doc#222).
Wikidata
  • url/wikidata: URL with Wikidata Entity ID. Gets and parses the entity data
  • list/wikidata: List of Wikidata Entity IDs, separated by spaces, newlines or commas. Gets and parses the entity data
  • string/wikidata: Single Wikidata Entity ID. Gets and parses the entity data
  • array/wikidata: Array of strings of type string/wikidata
  • api/wikidata: Wikidata API URL. Gets and parses the entity data
  • object/wikidata: Wikidata Entity data. Parses the entity data
BibTeX
  • string/bibtex: BibTeX string. Parses the data
  • object/bibtex: BibTeX JSON. Nothing special, or standardised. Parses the data
  • string/bibtxt: Bib.TXT string. Parses the data
BibJSON
  • object/contentmine: Actually BibJSON, all references to ContentMine will be removed when the parser is fully done. Parses the data
CSL-JSON
  • object/csl: CSL-JSON. Adds the data
  • array/csl: Array of CSL-JSON. Adds the data
Intermediary formats

These formats are not input-ready, but are rather parsed and re-evaluated, e.g. html/else (DOM element) to string/json to json/csl.

  • string/json: JSON or JavaScript Object string. Parses and re-evaluates the data
  • jquery/else: jQuery element. Fetches and re-evaluates the contents
  • html/else: HTML DOM element. Fetches and re-evaluates the contents
  • url/else: URL. Fetches and re-evaluates the file
  • array/else: JavaScript array. Re-evaluates every element in the array

Options

These are the default options for using .get(). More options will follow.

  1. format: The output format: "real" (default) or "string"
  2. type: The output type: "html", "string" or "json" (default).
  3. style: The output style. See Output. "csl" is default
  4. lang: The language of the output. RFC 5646 codes. Currently supported: "en-US" (default), "fr-FR", "es-ES" ,"de-DE" and "nl-NL"

Ouput

When using the .get() function, your output depends on the options you pass. If you don't pass any options, the values you passed as default are used. When you didn't pass default options, standard options are passed.

Type

  • json: Output as JSON. Not possible together with style:"citation-*"
  • html: Output as HTML
  • string: Output as string

Style

  • csl: Outputs raw CSL-JSON data
  • bibtex: Outputs a BibTeX string, or BibTeX-JSON if type: "json"
  • citation-*: Formatted citation, formatted with citeproc-js. * is a CSL Template name.

CSL Templates

Currently, the following CSL Templates are suppported in Citation.js.

  • apa
  • vancouver
  • harvard1

Different CSL Templates can be used by passing an XML string to .get() with the option template:<string>. E.g.

var data = new Cite(...)
 
data.get({
  format: 'string',
  type: 'html',
  style: 'citation-<TEMPLATE NAME>',
  lang: 'en-US',
  
  template: '...' // XML String 
})

Replace <TEMPLATE NAME> with the template name you want to use. After calling .get() with these options once, you can omit the template property, if you use the same locale.

CSL Locales

If you want different languages than the standard, you can pass a CSL Locale as an XML string to .get() with the option locale:<string>. E.g.

var data = new Cite(...)
 
data.get({
  format: 'string',
  type: 'html',
  style: 'citation-apa',
  
  locale: '...' // XML String 
})

Misc

Cite instances have some more functions:

  • .options(<options>): Change default options
  • .set(<data>): Replace all data with new data
  • .add(<data>): Add data
  • .reset(): Remove all data and options
  • .currentVersion(): Get current version number
  • .retrieveVersion(<version number>): Retrieve a certain version of the object
  • .retrieveLastVersion(): Retrieve the last saved version of the object
  • .undo(<number>): Restore the n to last version (default: 1)
  • .save(): Save the current object
  • .sort(): Sort all entries on basis of their BibTeX label

Iterator

Every Cite instance is an Iterator, so you can loop over an instance with for of:

const data = new Cite([{id: 1}, {id: 2}, {id: 3}])
let array = []
 
for (let {id} of data) {
  array.push(id)
}
 
array // [1, 2, 3] 

Internal functions

Cite holds all internal functions, too. These are documented here and can be accessed like this:

Note that most get* functions expect CSL-JSON normalised with Cite.parse.csl: [Function: parseCsl].

{
  async: [Function: async],
  get: 
   { bibtex: 
      { json: [Function: getBibTeXJSON],
        text: [Function: getBibTeX],
        label: [Function: getBibTeXLabel],
        type: [Function: fetchBibTeXType] },
     bibtxt: [Function: getBibTxt],
     dict: { htmlDict: [Object], textDict: [Object] },
     json: [Function: getJSON],
     date: [Function: getDate],
     name: [Function: getName],
     label: [Function: getLabel] },
  CSL: 
   { style: [Function: fetchCSLStyle],
     locale: [Function: fetchCSLLocale],
     engine: [Function: fetchCSLEngine],
     item: [Function: fetchCSLItemCallback] },
  parse: 
   { input: 
      { type: [Function: parseInputType],
        data: [Function: parseInputData],
        chain: [Function: parseInput],
        chainLink: [Function: parseInputChainLink],
        async: 
         { data: [Function: parseInputDataAsync],
           chain: [Function: parseInputAsync],
           chainLink: [Function: parseInputChainLinkAsync] } },
     wikidata: 
      { list: [Function: parseWikidata],
        json: [Function: parseWikidataJSON],
        prop: [Function: parseWikidataProp],
        type: [Function: fetchWikidataType],
        async: 
         { json: [Function: parseWikidataJSONAsync],
           prop: [Function: parseWikidataPropAsync] } },
     bibtex: 
      { json: [Function: parseBibTeXJSON],
        text: [Function: parseBibTeX],
        prop: [Function: parseBibTeXProp],
        type: [Function: parseBibTeXType] },
     bibtxt: 
      { text: [Function: parseBibTxt],
        textEntry: [Function: parseBibTxtEntry] },
     bibjson: [Function: parseContentMine],
     doi: 
      { id: [Function: parseDoi],
        api: [Function: parseDoiApi],
        async: { api: [Function: parseDoiApiAsync] } },
     date: [Function: parseDate],
     name: [Function: parseName],
     json: [Function: parseJSON],
     csl: [Function: parseCsl] },
  util: 
   { attr: 
      { getAttributedEntry: [Function: getAttributedEntry],
        getPrefixedEntry: [Function: getPrefixedEntry] },
     deepCopy: [Function: deepCopy],
     fetchFile: [Function: fetchFile],
     fetchFileAsync: [Function: fetchFileAsync],
     fetchId: [Function: fetchId] } }

Async

Use the async api (recommended for Wikidata, URL, and DOI input) like this (with callback):

Cite.async(<DATA>, <OPTIONS>, function (data) {
  data // instance of Cite 
  
  // Further manipulations... 
  console.log(data.get())
})

Or with a promise, like this:

Cite.async(<DATA>, <OPTIONS>).then(function (data) {
  data // instance of Cite 
  
  // Further manipulations... 
  console.log(data.get())
})

Where <DATA> is the input data and <OPTIONS> is the input options. <OPTIONS> is optional in both examples.

More

More Docs

Further explanation can be found here.

Demo

NPM Demo

NPM Demo. Example code:

var Cite = require('citation-js')
 
var data = new Cite('Q21972834', {
  format: 'string',
  type: 'html',
  style: 'citation-apa',
  lang: 'en-US'
})
 
data.get() // Should implicitly display 

Browser Demos