knitr::opts_chunk$set( collapse = TRUE, comment = "#>", fig.path = "README-" )
This package aims to introduce basic functionalities to access the Zotero API. Its main goal at this stage is to have enough functionalities to facilitate resizing the storage space used, by ordering items by attachment size, and by allowing to add items to a collection if certain criteria are met.
It now tenatively allows to create new Zotero items, and to take a csv file (or data frame) and import it into Zotero, as long as data are properly mapped. zoteror
has function that facilitate giving to tabular data a structure that can properly be read into Zotero. See at the bottom of this document for an example [this is still work-in-progress and not functional for all item/attribute types].
if(!require("remotes")) install.packages("remotes") remotes::install_github(repo = "giocomai/zoteror")
credentials <- zot_auth(cache = TRUE)
The verification code that appears at the end of the URL after authorization in browser should be input as verification PIN. If the parameter store is enabled - AuthZot(cache=TRUE) - zoteror
stores the credentials in a local file called "zotero_credentials.rds", which should be considered confidential since it provides access to a given Zotero account. If a pre-existing "zotero_credentials.rds" exists, it is loaded automatically.
N.B. At this stage, it may be easier to actually login on Zotero, go to the (Feeds/API page in Settings)[https://www.zotero.org/settings/keys], and create an API from there.
Instead of inputting user
and credentials
each time a function is run, it is easier to set them with ZotSetOptions
at the beginning of every session:
zot_set_options(user = 12345, credentials = "<API>")
The respective parameters can then be left empty (NULL
, which is default) when calling functions.
key <- zot_create_collection(collection_name = "zoteror")
Creates a new collection by the given name, and outputs its key. If a collection with the same name already exists, it does not create a new one, but rather outputs the key of the pre-existing collection. zot_create_collection()
requires an API key with write access.
item <- zot_read_item(id = "<item_id>")
Outputs a list with all available information on the item.
zot_which_collection
allows to find out in which collection is an item. If the ID given refers to a 'child item' (e.g. a pdf attachment to a journal article), the function looks for the collection(s) in which the parent item is included. [attachments have separate IDs, and are thus to be found in a collection only if the 'parent item' is]
item <- zot_wich_collection(id = "<item_id>")
zot_add_to_collection(id = "<item_id>", collection_id = "<collection_id>")
size <- zot_size(path = "/home/user/.zotero/XXXXXX.default/zotero/storage") # by default, this was inside .mozilla/firefox subdirectory in earlier versions
It requires the full path to the local Zotero folder. Outputs size of stored items in bytes and in human-readable Mb.
library("zoteror") library("dplyr") zot_set_options(user = 12345, credentials = "<API>") # insert user id and API credentials size <- zot_size(path = "/home/user/.zotero/XXXXXX.default/zotero/storage") # full path to Zotero storage folder bigIDs <- size %>% filter(Size>5000000) %>% pull(ID) # filters items larger than 5MB big_collection_id <- zot_create_collection(collectionName = "plus5") #creates collection "plus5", and if already existing simply outputs its key for (i in bigIDs) { try(zot_add_to_collection(id = bigIDs$ID[i]i, collection_id = big_collection_id)) }
This adds all items larger tan 5Mb to a collection called "plus5". zot_add_to_collection()
is inside try
to prevent timeout and other errors to stop the script. While running the script outputs the title of items being added to the collection. Currently it goes quite slowly, thus giving time to stop the script if something odd happens. API would allow much more efficient ways of bulk changing items; when the package will work more efficiently, it will still allow to keep the process artificially slow in order to monitor potential oddities.
zoteror
In order to make sure your data match Zotero fields for a given item type, you can first create a csv template for the given type and paste your data there. Not all columns need to be filled.
library(zoteror) zot_create_csv_template(item_type = "book", cache = FALSE)
If you enable cache=TRUE
it will store a csv file in the zot_csv_templates
sub-folder of the current working directory.
Translation in other languages of all fields are available with:
zot_get_item_types_fields(item_type = "book", cache = "FALSE", locale = "it")
Internally, Zotero does not store data in a tabular format, so some transformation will be necessary.
For example, if we have data in this format:
europe_books <- tibble::tribble(~itemType, ~creators, ~title, ~tags, "book", "Spinelli, Altiero; Rossi, Ernesto", "Il Manifesto di Ventotene", "europe; history") europe_books
We need first to transform them in a format that fully mirrors Zotero's data structure:
library(dplyr) europe_books_zot <- europe_books %>% mutate(creators = zot_convert_creators_to_df_list(creator = creators), tags = zot_convert_tags_to_df_list(tags = tags)) europe_books_zot
Having previously set your credentials, you can now upload it to your Zotero accounts.
zot_create_items(item_df = europe_books_zot, collection = "europe")
[full support for all data types and more appropriate output will be added in a future version]
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.