Give help for special Zotero utilities functions

[zuphilip]

Most of the functions are defined in https://github.com/zotero/zotero/blob/master/chrome/content/zotero/xpcom/utilities.js and listed at https://www.zotero.org/support/dev/translators/functions . Frequently I have to check these sources during writing Zotero translators when I want to use a special function but I forgot its name or the order of arguments which have to been passed. We can make another point in the help menu and output some static text, but maybe there are smarter ways to give here the translator developers any inline help. Any ideas?

[zuphilip]

Here is a list of the most common used functions from Zotero.Utilities and Zotero:

grep -E -o -h "(ZU|Zotero\.Utilities)\.[^\(]+\(" *.js | sort | uniq -c | sort -nr

$ grep -E -o -h "(ZU|Zotero\.Utilities)\.[^\(]+\(" *.js | sort | uniq -c | sort -nr
   1533 ZU.xpathText(
    831 ZU.xpath(
    382 ZU.trimInternal(
    272 ZU.processDocuments(
    201 ZU.cleanAuthor(
    190 Zotero.Utilities.cleanAuthor(
    155 Zotero.Utilities.processDocuments(
    124 Zotero.Utilities.trimInternal(
     98 ZU.doGet(
     84 Zotero.Utilities.capitalizeTitle(
     81 Zotero.Utilities.trim(
     79 ZU.capitalizeTitle(
     70 Zotero.Utilities.unescapeHTML(
     53 Zotero.Utilities.HTTP.doGet(
     47 ZU.strToISO(
     30 ZU.unescapeHTML(
     27 ZU.cleanISBN(
     26 ZU.doPost(
     24 ZU.trim(
     24 ZU.cleanDOI(
     24 Zotero.Utilities.superCleanString(
     20 ZU.fieldIsValidForType(
     17 Zotero.Utilities.cleanTags(
     16 Zotero.Utilities.getItemArray(
     14 ZU.cleanISSN(
     14 Zotero.Utilities.doGet(
     13 ZU.cleanTags(
     13 Zotero.Utilities.xpathText(
     13 Zotero.Utilities.xpath(
     11 Zotero.Utilities.HTTP.doPost(
      9 ZU.strToDate(
      8 ZU.removeDiacritics(
      7 ZU.lpad(
      7 ZU.getItemArray(
      6 ZU.HTTP.doGet(
      6 Zotero.Utilities.strToDate(
      5 ZU.superCleanString(
      5 Zotero.Utilities.parseContextObject(
      4 ZU.formatDate(
      4 Zotero.Utilities.getVersion(
      4 Zotero.Utilities.getCreatorsForType(
      3 ZU.XRegExp(
      3 ZU.parseContextObject(
      3 ZU.itemTypeExists(
      3 ZU.deepCopy(
      2 ZU.XRegExp.replace(
      2 ZU.quotemeta(
      2 ZU.arrayDiff(
      2 Zotero.Utilities.text2html(
      2 Zotero.Utilities.strToISO(
      2 Zotero.Utilities.lpad(
      2 Zotero.Utilities.loadDocument(
      2 Zotero.Utilities.itemTypeExists(
      2 Zotero.Utilities.getLocalizedCreatorType(
      2 Zotero.Utilities.createContextObject(
      1 ZU.xpathText (
      1 ZU.itemToCSLJSON(
      1 ZU.itemFromCSLJSON(
      1 ZU.isEmpty(
      1 ZU.getCreatorsForType(
      1 ZU.doHead(
      1 ZU.arrayUnique(
      1 Zotero.Utilities.htmlSpecialChars(
      1 Zotero.Utilities.getPageRange(
      1 Zotero.Utilities.formatDate(
      1 Zotero.Utilities.doPost(
      1 Zotero.Utilities.composeDoc(

grep -E -o -h "(Z|Zotero)\.[^\(\.]+\(" *.js | sort | uniq -c | sort -nr

$ grep -E -o -h "(Z|Zotero)\.[^\(\.]+\(" *.js | sort | uniq -c | sort -nr
    517 Z.debug(
    426 Zotero.selectItems(
    371 Zotero.debug(
    351 Zotero.Item(
    315 Zotero.loadTranslator(
    117 Zotero.done(
     99 Zotero.wait(
     43 Zotero.write(
     39 Zotero.read(
     31 Z.selectItems(
     21 Zotero.getOption(
     17 Zotero.nextItem(
     15 Z.monitorDOMChanges(
     14 Z.Item(
     13 Z.getHiddenPref(
      7 Zotero.getXML(
      5 Zotero.setCharacterSet(
      5 Zotero.monitorDOMChanges(
      5 Zotero.Collection(
      3 Zotero.setProgress(
      3 Zotero.nextCollection(
      3 Zotero.getHiddenPref(
      3 Z.loadTranslator(
      2 Zotero.addOption(
      2 Z.done(
      1 Zotero.doGaleWeb(
      1 Zotero.detectGaleWeb(
      1 Z.write(
      1 Z.wait(
      1 Z.setProgress(
      1 Z.read(
      1 Z.nextItem(
      1 Z.getXML(
      1 Z.debug (
      1 Z._]*/(
      1 Z. (

Thus, maybe we can concentrate on this and divide them into some groups, e.g.

• CSS path: text, attr
• xpath: ZU.xpath, ZU.xpathText
• call websites: ZU.doGet, ZU.processDocuments, ZU.doPost
• special cleaning functions: ZU.cleanAuthor, ZU.strToISO, ZU.cleanISBN, ZU.cleanDOI, ZU.cleanISSN
• clean text strings: ZU.trimInternal, ZU.capitalizeTitle, ZU.unescapeHTML, ZU.superCleanString, ZU.cleanTags, ZU.removeDiacritics
• debug: Z.debug
• specialized functions: Z.monitorDOMChanges, Z.selectItems, Z.loadTranslator, ...

[dstillman]

Seems like we might be able to use autocomplete:

https://github.com/ajaxorg/ace/wiki/How-to-enable-Autocomplete-in-the-Ace-editor

You can add enableLiveAutocompletion: true to the live demo there to see it in action. (enableSnippets is also an option, but not sure what that does.)

[zuphilip]

Good idea with the autocompletion. I played a little with the online example and tried to customize that as we could need. Here is what I have currently: http://plnkr.co/edit/Ep3bVPjjkm1laImq443t?p=preview . There are several options:

• define Zotero keywords and/or define Zotero snippets
• define the customized keywords, snippets in addition to the JavaScript ones, or only concentrate on the customized ones
• enable live autocompletion or the less obtrusiv basic autocompletion invoked by ctrl+space

However, I could imagine to do additional some entry in the help menu to list the possible function with a short description. Let me know what you think about this.