Skip to content

Commit f457fc7

Browse files
twhiteakertwhiteaker
committed
add index.md
1 parent 64e4445 commit f457fc7

File tree

2 files changed

+123
-1
lines changed

2 files changed

+123
-1
lines changed

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
# Zotero-JavaScript-Search-Client
2-
Example HTML, CSS, and JavaScript for searching for items within a public Zotero group
2+
Example HTML, CSS, and JavaScript for searching for items within a public Zotero user or group library
33

44
[See a live demo at RawGit](https://cdn.rawgit.com/twhiteaker/Zotero-JavaScript-Search-Client/2297dc82/zotero.html)
55

‎index.md‎

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
# Zotero-JavaScript-Search-Client
2+
Example HTML, CSS, and JavaScript for searching for items within a public Zotero
3+
user or group library
4+
5+
[See a live demo at RawGit](https://cdn.rawgit.com/twhiteaker/Zotero-JavaScript-Search-Client/2297dc82/zotero.html)
6+
7+
## Motivation
8+
9+
To help users discover your publications, you can add them to an online database like Zotero and then present a search interface to that database on your website. Modules for doing so have been written for WordPress and Drupal, but I hadn't seen one for static HTML sites, so I wrote this example to test how feasible a static HTML Zotero client would be to implement.
10+
11+
## Usage
12+
13+
Open the zotero.html file in your browser and enter a search term like
14+
`coastal`. Click the search button and see results as formatted by Zotero to the page.
15+
16+
You can click Search with no terms specified to show the entire catalog, which is the default behavior when you load the page.
17+
18+
Zotero limits the number of results returned in a single request, so the page supports pagination to get additional results.
19+
20+
To use this for your own project, you will need a free Zotero account into which you include your publications, and obviously you'll need to adapt the HTML, CSS, etc., for your particular website.
21+
22+
## Customization
23+
24+
The code finds elements via their HTML id attribute values, so in general you'll
25+
want to start with one of the example HTML documents and adapt it to your needs.
26+
27+
To change parameters such as how many search results to show at a time, see the
28+
`ZOTERO_CONFIG` variable in `zotero.js`. See comments in the code for a brief
29+
explanation and example values, or the text below for additional details.
30+
31+
### What To Search
32+
33+
You can search a user library, a group, or a collection within a user library or
34+
group.
35+
36+
* `zotId` - The user or group identifier. You can find your group identifier by
37+
browsing to your group page and copying the number in the URL. To find your
38+
user identifier, click **Settings**, and then click **Feeds/API**.
39+
* `zotIdType` - Indicates whether `zotId` is for a `group` or a `user`.
40+
* `collectionKey` - Supply a value for this if you want to limit search to a
41+
particular collection. Otherwise leave it as an empty string, "". You can
42+
find your collection identifier by browsing to the collection's page and copying the
43+
collection key from the URL.
44+
* `filterTags` - Use this to restrict results to items matching this tag filter,
45+
or leave the value as an emptry string, "", if no tag filtering is desired.
46+
Since the Zotero API supports several ways of writing a tag filter, the entire tag parameter including the preceeding ampersand is required for
47+
this value, as in `&tag=FeaturedArticle`. See the [API
48+
documentation](https://www.zotero.org/support/dev/web_api/v3/basics) for
49+
examples.
50+
51+
### Results Table
52+
53+
Results are displayed in a table with up to four columns: `Year`, `Citation`,
54+
`Item Type`, and a special column (we'll refer to it as `ShowTags`) showing the
55+
presence of particular tags.
56+
57+
* `resultsElementId` - The id of the HTML element to contain the results table.
58+
This element must already exist in your HTML document.
59+
* `includeCols` - Array of column names to include in the output table, other than
60+
`Citation` which is always included. The full set is `Year`, `Type`, and
61+
`ShowTags`. If you leave a column name out in this array, then it will not
62+
appear in the result table. If you leave all columns out (i.e., the array is
63+
empty), then only the citations are shown, and no column header is shown.
64+
* `showTags`: Array of tags to show, if present, for each result item. Use this
65+
to categorize your items if Zotero doesn't support the categories you need out
66+
of the box. For example, you could tag your items based on their relationship
67+
to your LTER site, indicating whether the item is a foundational paper for the
68+
site (`Fondational`), was funded by the site (`LTER-Funded`), or was written by someone outside of your site
69+
who used your site's data (`LTER-Enabled`). If an item has one of the tags
70+
you specify, the tag will be shown in the `ShowTags` column. Obviously, if you
71+
want to use this functionality, make sure the text `ShowTags` is included in
72+
`includeCols`.
73+
* `showTagColName` - The name to be used for the `ShowTags` column in the
74+
results table, since I can't predict what kind of categories your tags
75+
represent. `Relationship to LTER Site` would work for the example tags
76+
mentioned above.
77+
* `style` - The bibliography display style for the citations, e.g., apa. Leave
78+
blank for the default which is chicago-note-bibliography.
79+
80+
### Result Counts and Pagination
81+
82+
You can provide HTML id attribute values for elements that will contain result
83+
counts, pagination links, and so on. In general, if you do not want to show one
84+
of these elements, then provide an empty string, "", as the identifier. If the
85+
code does not find a matching element, it will skip it.
86+
87+
* `limit` - Max number of results to retrieve per page. A value of 10 is a good
88+
starting point. As you approach 100, Zotero gets awfully slow.
89+
* `urlElementId` - Supply this if your HTML document has an element in which
90+
you'd like to display the URL that was used to fetch results from Zotero.
91+
* `countElementId` - Element in your HTML document for showing the total number
92+
of results.
93+
* `pagesTopElementId` - Element to display result page links above results.
94+
* `pagesBotElementId` - Element to display result page links below results.
95+
* `showPages` - Max number of page links to show. The code assumes this is an
96+
odd number!
97+
98+
### Advanced Search Controls
99+
100+
The Zotero API has very limited advanced search functionality, though the
101+
developers say they are planning to add more features. Currently you
102+
can only filter by item type. Thus, `zotero.html` includes a collapsible
103+
**Advanced** section in which the user can choose to filter by item type. See
104+
the HTML if you're curious, but for now I suggest leaving the advanced section
105+
out until more advanced functionality is supported.
106+
107+
### Sorting
108+
109+
The Zotero API supports sorting results. If you want to allow the user to sort
110+
results, you must include an HTML `select` control with the identifier
111+
`visibleSort` and with options matching the allowable Zotero sort values. See
112+
the section on sorting and pagination parameters in the [Zotero API
113+
documentation](https://www.zotero.org/support/dev/web_api/v3/basics) for
114+
allowable values. See `zotero.html` for an example of what the `select` element
115+
should look like. This element should be contained within a `div` element,
116+
which is used to hide the control if no results were returned from the search.
117+
118+
If you do not want to allow the user to change the sorting option, then leave
119+
these HTML elements out of your document.
120+
121+
* `sortDiv` - Identifier of the HTML element containing the `select` control
122+
allowing interactive sort options.

0 commit comments

Comments
 (0)