Sign Up for Free

RunKit +

Try any Node.js package right in your browser

This is a playground to test code. It runs a full Node.js environment and already has all of npm’s 400,000 packages pre-installed, including citation-js with all npm packages installed. Try it out:

var citationJs = require("citation-js")

This service is provided by RunKit and is not affiliated with npm, Inc or the package authors.

citation-js v0.2.15

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.

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.

Generate docs with jsdoc ./src README.md -c docs/conf.json.

NPM version NPM total downloads Build Status

Table of Contents

Citation.js

Use

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')

Dependencies

  • commander
  • striptags
  • wikidata-sdk
  • citeproc-js (included automatically)

Browser

With the following code, the Cite contructor is available.

<script src="path/to/citation-0.2.js" type="text/javascript"></script>

Dependencies

  • citeproc-js (included in the src/ folder)
    Include like <script src="path/to/citeproc.js" type="text/javascript"></script>

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 settings. It contains the following properties. These are the default options for using .get()
  3. format: The output format: "real" (default) or "string"
  4. type: The output type: "html", "string" or "json" (default).
  5. style: The output style. See Output. "csl" is default
  6. lang: The language of the output. RFC 5646 codes. Currently supported: "en-US" (default), "fr-FR", "es-ES" ,"de-DE" and "nl-NL"

Input types

  • 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
  • json/wikidata: Wikidata Entity data. Parses the data
  • json/contentmine: ContentMine data, as outputted by quickscrape. Parses the data
  • json/csl: CSL-JSON. Adds the data
  • string/json: JSON or JavaScript Object string. Parses and re-evaluates the data
  • string/bibtex: BibTeX string. Parses 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
  • list/else: JavaScript array. Re-evaluates every element in the array

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',
  lang: 'en-US',
  
  template: '...' // XML String
})

Currently, you need to pass "citation" to the style option for this to work.

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 has some more functions:

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

jquery.Citation.js

This plugin builds a form for input for the Cite object.

Use

After including the necessary files like below, you can make a new jQueryCite object.

<script type="text/javascript" src="path/to/jquery.js"></script>
<script type="text/javascript" src="path/to/citeproc.js"></script>
<script type="text/javascript" src="path/to/citation-0.2.js"></script>
<script type="text/javascript" src="path/to/jquery.citation-0.2.js"></script>

jQueryCite

Make a new jQueryCite object like this:

var example = new jQueryCite( <options> )

The options are:

  1. defaultOptions: Options to be passed to Cite
  2. saveInCookies: Save data in cookies when .save()d
  3. add: Callback to execute when data is submitted to collection
  4. inputForm and outputForm: HTML template (see docs)

See also API Docs

HTML templates

Of course, you can include all sorts of things in the templates, but the following things are going to get used. Templates below are in Jade/Pug. Elements may be wrapped in containers, but the general hierarchy should be like this

Input form

.cjs-in
  .cjs-piece.cjs-input
    // List of fieldsets, see below
  .cjs-piece.cjs-import
    .cjs-import-name // Text input to hold input value names
    .cjs-import-file // File input
  .cjs-piece.cjs-preview
    .cjs-draft // Element holding draft
    .cjs-add // Submit (and clear) draft
    .cjs-delete // Clear draft

Input form fields

Form fields consist of a fieldset element and inside an input element, with the following attributes:

  • fieldset
    • data-cjs-field-type: For what publication types should this field be visible (omit when it should always be visible)
    • data-cjs-field-state: "hidden", omitted or "visible". Assigned by program
  • input
    • data-cjs-field: Name of the corresponding CSL property. When CSL properties are complex, jQueryCite usually helps out
    • type: Usually "text", but depends on CSL property. If it gives input to jQuery in the correct format, it's okay

Exceptions:

  • The field or the page property should have two inputs
  • Fields author, container-author, editor and publisher-title get .CJSMultipleInput(), so multiple inputs aren't necessary, as they're added dynamically
  • One of the fields, preferably the first one, should be a select (data-cjs-field="type"), containing publication type options

Output form

.cjs-out
  .cjs-piece.cjs-settings
    .cjs-opt
      fieldset
        select.cjs-type // HTML text or plain text
          option(value="html")
          option(value="string")
      fieldset
        select.cjs-style // Formatting style
          option(value="citation.apa")
          option(value="citation.vancouver")
          option(value="citation.harvard1")
          // Formatted citations can be expanded, if correct material is provided to Cite
          option(value="bibtex")
          option(value="csl")
      fieldset
        select.cjs-lan // Output language
          option(value="en-US")
          option(value="es-ES")
          option(value="du-DU")
          option(value="fr-FR")
          option(value="nl-NL")
          // Langs can be expanded, if correct material is provided to Cite
  .cjs-piece
    .cjs-output // Holds data
  .cjs-piece.cjs-export
    .cjs-export-copy // Copy data on click
    .cjs-export-save // Download data on click

Dependencies

  • jQuery
  • Citeproc-js
  • Citation.js

More

More Docs

Further explanation can be found here. The explanation of the jQuery plugin can be found there too.

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

RunKit is a free, in-browser JavaScript dev environment for prototyping Node.js code, with every npm package installed. Sign up to share your code.
Sign Up for Free