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