From c15b08bfe07622a7fc5de3a380ab4242d65cfc97 Mon Sep 17 00:00:00 2001 From: Dario Kampkaspar Date: Sat, 24 Nov 2018 13:56:42 +0100 Subject: [PATCH] Update readme to include config and user functions Cf. https://github.com/dariok/officeEntityPlugin/issues/11 --- README.md | 38 +++++++++++++++++++++++++++++++++++++- 1 file changed, 37 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index af7ccc3..c5819c7 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,7 @@ # officeEntityPlugin -A MS Office plug-in to access and link a controlled vocab loaded from a remote server +A MS Office plug-in to access and link a controlled vocab loaded from a remote server. + +It provides a configurable auto complete that writes some form of ID to a Link in Word for text selected by the user. ## Usage: @@ -21,3 +23,37 @@ A MS Office plug-in to access and link a controlled vocab loaded from a remote s 1. The data endpoint from which the data is fetched needs to be HTTPS if the HTML and/or manifest is stored on an HTTPS web server. 1. For **Windows 10:** If the plugin does not seem to accept any keyboard input in a setting with the plugin code stored on local/intranet location, open Internet Explorer 11 (which is what is used internally by Word on Windows to display the plugin html code), navigate to "compatibility preferences" (not in general internet prefs!) and uncheck the "run intranet pages in compatibility mode" checkbox. 1. For **Word 2016 on Windows**: If the plugin is active while saving a .dotx Word Template file (and entity.html and .js are in a readable place), it will be added for new users automatically as soon as they start with a new .docx based on the .dotx. (If this instance is the first time the plugin is used, Word asks for trust, and the Windows 10 note above applies as well.) + +## Configuration and adaptation to endpoints + +All configuration options are to be stored in `config.json`. All functions to deal with your specific query endpoint can +be set in `process.js`. Please read the sections below to learn about the options and their effect. + +### config.json + +* *server*:"The URL of the server and endpoint up until where the different types of a query are distinguished; e.g. + `https://example.org/api/v1/` +* *suffix*: any additional parts of the URL that have to be added after the type and before the query string; e.g. + `fastsearch/` +* `authMode`: which means of authentication is to be used; may be one of "static token" or "dynamic token", or emtpy. + A static token is one that does not change regularly and may be stored in `config.json` (and may thus be world + readable!). A dynamic token is one that needs to be requested regularly; it will be read from and stored to local + storage; see `function handleError` below for this mode of authentication. +* `types`: a list of key/value pairs for the types of queries to be displayed above the text input. The key will be part + of the URL while the value will be display in the dropdown. Example: `{"person":"Person", "place":"Ort"}` + +The query URL generated by typing a string into the text input will be `server + type + suffix` while the query data is +generated by evaluating function `queryString(conf, params)` (see below). + +### process.js + +* *function evalResult (result, data)* evaluate the response by the query endpoint. `data` is whatever has been returned + by the endpoint. Needs to push to `result.results` for every entry to be displayed an array of key/value pairs: + `{"id": $id, "text": $display}` where `$id` is the value that is to be written into the URL in Word and `$display` is + the text to be displayed in the autocomplete preview. +* *function queryString (conf, params)* returns the query data. `conf` is the configuration loaded from `config.json`; + `params.term` is what has been entered into the text input. +* *function handleError (jqXHR, textStatus, errorThrown)* handle errors returned by the query to the endpoint. Most + notably, for `dynamic token` authentication, this must include a subroutine to re-authenticate with the query endpoint. + This subroutine needs to write the new token to local storage: `localStorage.setItem('oepDynamicToken', newToken)` + and call `setConf()` afterwards. \ No newline at end of file