https://github.com/zotero/publications
Easily display Zotero items on a webpage
https://github.com/zotero/publications
Last synced: about 1 year ago
JSON representation
Easily display Zotero items on a webpage
- Host: GitHub
- URL: https://github.com/zotero/publications
- Owner: zotero
- License: other
- Created: 2015-11-10T03:34:51.000Z (over 10 years ago)
- Default Branch: master
- Last Pushed: 2023-03-04T02:52:02.000Z (over 3 years ago)
- Last Synced: 2024-10-30T11:03:34.722Z (over 1 year ago)
- Language: JavaScript
- Homepage:
- Size: 6.19 MB
- Stars: 32
- Watchers: 8
- Forks: 8
- Open Issues: 17
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: COPYING
Awesome Lists containing this project
README
# Zotero Publications
[](https://github.com/zotero/publications/actions/workflows/ci.yml)
[](https://coveralls.io/github/zotero/publications?branch=master)
[](https://www.npmjs.com/package/zotero-publications)
Overview
--------
This library will pull "My Publications" items from Zotero API and display them in a user friendly way. It is intended to be easily embeddable on your own page. We're offering variety of builds to maximize potential use cases. Basic usage documentation and description of available builds are included below. For advanced usage please see examples and comments in the code.
Getting The Library
-------------------
The easiest way to obtain the latest version is to use npm:
npm i zotero-publications
This version will work in node and a browser:
const ZoteroPublications = require('zotero-publications');
If you're using sass/scss, you can simply point your sass include-path at your node_modules directory and import it like this.
@import "zotero-publications/lib/scss/zotero-publications.scss";
The npm package also contains a `dist` folder with both minified sources (js & css), which can be used in a browser directly.
Javascript files in `dist` folder are following the [Universal Module Definition](https://github.com/umdjs/umd) pattern which means you can also use this library in systems that use AMD (e.g. [RequireJS](http://requirejs.org/)) or CommonJS module loader mechanism.
You will need to include one *css* and one *js* file on your page. The easiest way to do that is to add css file somewhere within `` on your page:
And add js file somewhere at the end of the file but before final ``:
Usage
-----
Use the following code to fetch "My Publications" for user ID 1234 and render them inside #container:
new ZoteroPublications(1234, document.getElementById('container'));
You can also specify additional configuration by passing a config object to the constructor, for example to enable grouping by item type:
new ZoteroPublications(1234, document.getElementById('container'), {group: 'type'});
Please see "Config Options" below to see all accepted parameters.
Finally if you need more control over what happens while data is being retrieved, would like to introduce custom error handling or data processing, you can use the following syntax:
var zp = new ZoteroPublications();
var promise = zp.getPublications(1234);
//optionally do something here while data is being fetched
promise.then(function(data) {
//optionally process your data here
zp.render(data, document.getElementById('container'));
});
promise.catch(function(reason) {
//optionally implement custom error handling here
console.warn(reason);
});
See [src/demo/index.html](src/demo/index.html) for a complete example.
Usage in Node
-------------
As of version 0.4.0 Zotero Publications offers node compatibility for server-side rendering etc.. Please note the following limitations when using zotero-publications in node:
* Since there's no DOM available, the library will return HTML as a string rather than attach it to the container provided in DOM as it happens in the browser
* HTML provided is the same that would be rendered in the browser, including all the interactive elements (e.g. 'details link'). However these will not work out-of-the box because event hanlders are not installed when workin in Node
* Shortcut syntax (first couple of examples above) cannot be used in Node.
Here's an example usage in Node:
var ZoteroPublications = require('zotero-publications');
var zp = new ZoteroPublications({group: 'type'});
var promise = zp.render(1234); // fetch "my publications" for user id 1234
promise.then(function(html) {
console.log(html);
});
promise.catch(function(err) {
console.error(err);
});
Config Options
--------------
`ZoteroPublications` takes the following configuration options:
**apiBase**
Host name of the API.
Default: 'api.zotero.org'
**citationStyle**
Which [Citation style](https://www.zotero.org/styles/) if *useCitationStyle* is enabled, defined which citation style will be used for item rendering.
Default: '' (none, API decides)
**storeCitationPreference**
Whether to store citation preference in local storage. If enabled returning users that use "Cite" functionality will have the last-selected citation style preselected.
Default: false
**group**
Enable grouping. Accepted values are: 'type' to group by type, 'collection' to group by top-level collections and *false* to disable grouping
Default: false
**useCitationStyle**
Whether to use citation style instead of templated item rendering.
Default: false
**showBranding**
Whether to display minimalisic Zotero branding
Default: true
**useHistory**
Whether to store currently opened item (details pane) in the url fragment identifier. If used and fragment is present in the url, matching item will be opened scrolled to when page has first loaded.
Default: true
**expand**
Only applicable if grouping is enable, pre-expands selected groups. Can be an array of group names (type names if grouping by type and collection names if grouping by top-level collections), e.g. `['book', 'journalArticle']` or a keyword 'all'.
Default: 'all'
**citeStyleOptions**
A map of citation styles (key => user friendly name) available in the "Cite" functionality select box.
Default: List similar to citations styles pre-installed in Zotero Client
**exportFormats**
Definitions for export formats available in "Export" functionality.
Default: Definitions for BibTeX, RIS and Zotero RDF
**getQueryParamsDefault**
Contains default query params included in all the GET requests made by the library.
Default: Parameters that trigger sorting by date, batching requests by 100 items etc.
Browser Compatibility
=====================
Chrome| EDGE | Firefox | IE | Opera | Safari
--- | --- | --- | --- | --- | --- |
Latest ✔ | Latest ✔ | Latest ✔ | 11+ ✔ | Latest ✔ | Latest ✔ |
Development & Contributing
===========
For setup, build, tests etc. as well as contribution guidelines please see [CONTRIBUTING.md](CONTRIBUTING.md).