iShell API Reference

iShell supports the modern cmdAPI namespace and the legacy CmdUtils namespace from Ubiquity API. The use of native JavaScript and WebExtensions APIs is suggested whenever appropriate.

cmdAPI.createCommand(options)

Legacy name: CmdUtils.CreateCommand

Creates and registers an iShell command. Equivalent annotations for the class-based syntax are specified in parentheses.

options is a dictionary object which must have the following properties:

• name/names (@command) - the string/array of strings that will be the name or names of your command the user will type into the command line, or choose from the context menu, to activate it.
• execute - the function which gets run when the user executes your command. If your command takes arguments (see below), your execute method will be passed a dictionary object containing the arguments assigned by the parser.

The following properties are optional but strongly recommended:

• uuid (@uuid) - a unique string, such as an URL of the command homepage.
• description (@description) - an XHTML string containing a short description of your command, to be displayed on the command-list page.
• help - an XHTML string containing a longer description of your command, also displayed on the command-list page, which can go into more depth, include examples of usage, etc.

The following properties are optional:

• arguments/argument - these properties are used if you want your command to accept arguments. See the commands with arguments tutorial section.
• sticky (@sticky) since v1.1 - a boolean value that indicates if iShell popup window should be kept open after the command is executed.
• icon (@icon) - a URL string pointing to a small image (favicon-sized) to be displayed alongside the name of your command in the interface.
• author/authors, contributor/contributors (@author) - a plain text or dictionary object (which can have the name, email, and homepage properties, all plain text) describing the command's author/contributor. Can be an array of them if multiple.
• homepage (@homepage) - a URL string of the command's homepage, if any.
• license (@license) - a string naming the license under which your command is distributed, for example, "MPL".
• load - function, called exactly once after iShell is loaded.
• init - function, called each time after iShell popup window is shown. Popup window document is passed as the argument.
• preview - a description of what your command will do, to be displayed to the user before the command is executed. Can be either a string or a function. If this is a string, it will simply be displayed as-is. If preview is a function, it will be called and passed a pblock argument, which is a reference to the preview display element. Your function can generate and display arbitrary HTML by setting the value of pblock.innerHTML. Use this.previewDefault(pblock) to set the default preview. If your command takes arguments (see above), your preview method will be passed the dictionary as the second argument (as a first in the class-based syntax).
  In iShell pblock object has the following additional methods:
  • set - sets pblock.innerHTML verbatim.
  • text - sets pblock.innerHTML by adding the same margins as for the displayed description of the command.
  • error - displays an error message in the same way as the text method but in red color.
  • fetchsince v0.8 - a shorthand for previewFetch. Accepts the same arguments except for pblock. This method returns a Response object. There are also fetchText and fetchJSON variations of this shortcut. They return a string, or a parsed JSON object respectively. undefined is returned in the case of an HTTP protocol error.
  • htmlListsince v0.8 - a shorthand for previewList. Accepts the same arguments except for pblock.
  • imageListsince v0.8 - a shorthand for imagePreviewList. Accepts the same arguments except for pblock.
  • objectListsince v0.8 - a shorthand for objectPreviewList. Accepts the same arguments except for pblock.
• previewDelay (@delay) - specifies the amount of time, in milliseconds, to wait before calling the preview function defined in options.preview. If the user presses a key before this amount of time has passed, then the preview function isn't called. This option is useful, for instance, if displaying the preview involves a round-trip to a server and you only want to display it once the user has stopped typing for a bit. If options.preview isn't a function, then this option is ignored.

cmdAPI.createSearchCommand(options)

Legacy name: CmdUtils.makeSearchCommand

A specialized version of cmdAPI.createCommand(). This lets you make commands that interface with search engines, without having to write so much boilerplate code. Use the @search annotation to mark class-based search commands.

options is same as the argument of cmdAPI.createCommand(), except that instead of options.arguments, options.execute, and options.preview, you only need a single property:

• url (@url) The URL of a search results page from the search engine of your choice. Must contain the literal string {QUERY} or %s, which will be replaced with the user's search term to generate a URL that should point to the correct page of search results. (We're assuming that the user's search term appears in the URL of the search results page, which is true for most search engines.) For example http://www.google.com/search?q={QUERY}

If not specified, options.name, options.icon, options.description, options.execute will be auto generated.

Other optional parameters of options are:

• postData (@post, for example: @post q=%s&hl=en) - makes the command use POST instead of GET, and the data (key:value pairs or string) are all passed to the options.url. Instead of including the search params in the URL, pass it (along with any other params) like so: {"q": "{QUERY}", "hl": "en"} or "q={QUERY}&hl=en". In the url or postData substrings {QUERY} or %s are replaced for the value of the object argument.
• defaultUrl (@default) - a URL string that will be opened in the case where the user has not provided a search string.
• beforeSearchsince v0.8 - a function that allows to modify arguments of the command before the search is performed. Accepts and returns an object with the command arguments.
• parser - generates keyboard-navigable previews by parsing the search results. It is passed as an object containing the properties listed below. The ones marked as path expect either a jQuery selector string, or a JSON path string (like "object1.object2.property"). Each of them can also be a filter function that receives a parent context and returns a result of the same type.
  • parser.type (@parser) - a string that's passed to jQuery.ajax()'s dataType parameter when requesting. If json is specified, the parser expects a JSON path in the form: "object1.object2.property". CSS selectors are expected in the case of html.
  • parser.container (@container) - a path to each container that groups each of title/body/href/thumbnail result sets. Recommended.
  • parser.title (@title) - the path to the title of each result. Required.
  • parser.body (@body) - a path to the content of each result.
  • parser.href / parser.thumbnail (@href / @thumbnail) - paths to the link/thumbnail URL of each result. Should point to an <a> / <img> in HTML mode.
  • parser.url / parser.postData (@parser.url / @parser.post) - specifies a version of options.url / options.postData to use for preview.
  • parser.baseUrl (@base) - a URL string that will be the base for relative links, such that they will still work out of context. If not passed, it will be auto-generated from options.url (and thus may be incorrect).
  • parser.maxResults (@results) - an integer specifying the max number of results. Defaults to 10.
  • parser.plain (@plain, for example: @plain title, body) - an array of strings naming paths that should be treated as plain text (and thus be HTML-escaped).
  • parser.log - a function to which the response data and parsed results are logged. If non-function, makeSearchCommand.log() is used.
  • parser.display (@display) - output display options. Possible values: "objectPreviewList".

cmdAPI.notify(message, title)

Legacy names: displayMessage

Display a popup notification with the specified message and title.

cmdAPI.notifyError(message, title)since v0.8

Display an error popup notification with the specified message and title.

cmdAPI.previewList([prefix], pblock, htmls, [callback], [css])

Legacy name: CmdUtils.previewList

Also called cmdAPI.htmlPreviewList. Creates a simple clickable list in the preview block and returns the list element.

• prefixsince v0.8 is an HTML-string to insert before the list. Optional.
• block is the DOM element the list will be placed into.
• htmls is the array/dictionary of HTML strings to be listed.
• callback(id, ev) is the function called when one of the list items clicked or selected. Optional.
  • id: one of the keys of htmls
  • ev: the event object
• css is a CSS string inserted along with the list. Optional.

cmdAPI.imagePreviewList([prefix], pblock, imageURLs, [callback], [css])since v0.8

Creates an image preview list in the preview block and returns the list element.

• prefix is an HTML-string to insert before the list. Optional.
• block is the DOM element the list will be placed into.
• imageURLs is the array of image links to display.
• callback(id, ev) is the function called when one of the list items clicked or selected. Optional.
  • id: one of the keys of imageURLs
  • ev: the event object
• css is an CSS string inserted along with the list. Optional.

cmdAPI.objectPreviewList([prefix], pblock, items, cfg, [css])

Creates a styled clickable list in the preview block from a set of JavaScript objects and returns the list element.

• prefixsince v0.8 is an HTML-string to insert before the list. Optional.
• block is the DOM element the list will be placed into.
• items is the array of objects representing list items.
• cfg is the dictionary (e.g. {text: i => i.textContent, ...}) of the following parameters:
• text: function(item) should return the main list item text.
  • item: an object from the items array.
• subtext: function(item) should return the secondary list item text displayed in small font. Optional.
  • item: an object from the items array.
• icon: function(item) should return the url of the list item icon. May also return a jQuery object which will be used in place of the icon. Optional.
  • item: an object from the items array.
• iconSize: integersince v0.8 defines the icon element size in pixels. Optional.
• action: function(item, ev) is the function called when one of the list items is clicked or selected.
  • item: an object from the items array.
  • ev: the event object.
• css is a CSS string inserted along with the list. Optional.

cmdAPI.reduceTemplate(array, func)since v0.5

Also called R in the global namespace. Reduces the given array by concatenating the string values returned by the func applied to the array items. Useful for the generation of HTML lists with JavaScript template literals.

The function accepted through the func parameter has the following arguments:

• item is an array item being processed.
• index is the index of the array item being processed.
• array is the array passed through the array argument.

cmdAPI.getSelection()

Legacy name: CmdUtils.getSelection

Returns a string containing the text and just the text of the user's current selection, i.e. with HTML tags stripped out.

cmdAPI.getHtmlSelection()

Legacy name: CmdUtils.getHtmlSelection

Returns a string containing the HTML representation of the user's current selection, i.e. text including tags.

cmdAPI.setSelection(content)

Legacy name: CmdUtils.setSelection

Replaces the current selection with content.

cmdAPI.copyToClipboard(text)

Legacy name: CmdUtils.copyToClipboard

This function places the passed-in text into the OS's clipboard. If the text is empty, the copy isn't performed.

• text is a plaintext string that will be put into the clipboard.

cmdAPI.getLocation()

Legacy name: CmdUtils.getLocation

Returns the location URL of the active tab, if available.

cmdAPI.newTab(url, callback)

Legacy names: Utils.openUrlInBrowser

Opens the given URL in the user's browser, using their current preferences for how new URLs should be opened (e.g., in a new window vs. a new tab, etc). Passes the newly opened tab object to the callback function or returns it as a promise if the callback is omitted.

• url a URL to be opened.

cmdAPI.getActiveTab()

Also available as a read-only property cmdAPI.activeTab. Returns the Tab object of the currently active tab. May return null for the special tabs.

cmdAPI.executeScript(tabId, options)since v0.5

Executes a content script in the tab with the given ID.

• tabId - ID of the tab in which to execute the script, optional. If not specified, the active tab is used.
• options - an object with the following properties:
  • func - a function to execute. Because the function is cloned, all local context is lost.
  • args - an array of function arguments, optional. Must be JSON-serializable.
  • file - a file to execute. Only files bundled with the add-on may be used.
  • allFrames - a boolean that indicates that the script should be executed in all frames.
  • frameId - ID of the frame to execute the script in.
  • jQuery - enable use of jQuery in content scripts.

Returns an array of objects with the following properties:

• result - the result of the script evaluation.
• frameId - the frame ID from which the result is obtained (MV3 only).
• error - the details of the script evaluation error (MV3 only).

cmdAPI.previewFetch(pblock, resource, init)since v0.2

Does an asynchronous request to a remote web service. It is a wrapper around the standard fetch() function. The difference is that cmdAPI.previewFetch() is designed to handle command previews, which can be canceled by a user action between the time it is requested and the time it displays. If the preview is canceled, an "AbortError" exception is thrown.

The init argument may contain the following additional properties:

• _timeoutsince v0.5 - request timeout in milliseconds.
• _displayErrorsince v0.5 - a boolean or string that will be displayed in the case of exceptions other than "AbortError" thrown by the underlying fetch function. Exception message will be displayed if a boolean value is used.

cmdAPI.fetchAborted(error)since v0.2

Determines if the call to cmdAPI.previewFetch was aborted by a user action.

• error - exception thrown by cmdAPI.previewFetch or one of the Response object methods returned by it.

cmdAPI.backendFetch(pblock, path, init)since v0.5

Does an asynchronous request to the web server being run by the iShell native backend application. If pblock parameter is specified, cmdAPI.previewFetch() function is used to make a request. Built-in JavaScript fetch is used otherwise. If the backend application could not be run, the function throws "IShellNoBackendApp" exception.

• pblock - the preview block element that could be obtained through the pblock or display parameter of a command preview handler. Optional.
• path - a relative path to the retrieved resource. For example, "/my_handler".
• init - the init parameter passed to the fetch function.

cmdAPI.previewAjax(pblock, options)

Legacy name: CmdUtils.previewAjax

Does an asynchronous request to a remote web service. It is used just like jQuery.ajax(), which is documented here.
The difference is that cmdAPI.previewAjax() is designed to handle command previews, which can be canceled by a user action between the time it is requested and the time it displays. If the preview is canceled, no callbacks in the options object will be called.

cmdAPI.previewGet(pblock, url, data, callback, type)
cmdAPI.previewPost(pblock, url, data, callback, type)

Legacy names: CmdUtils.previewGet, CmdUtils.previewPost

Does an asynchronous request to a remote web service. It is used just like jQuery.get()/jQuery.post(), which is documented here.
The difference is that previewGet()/previewPost() is designed to handle command previews, which can be canceled by a user action between the time it is requested and the time it displays. If the preview is canceled, the given callback will not be called.

cmdAPI.absUrl(data, baseUrl)

Legacy name: CmdUtils.absUrl

Fixes relative URLs in data (e.g. as returned by Ajax calls). Useful for displaying fetched content in command previews.

• data is the data containing relative URLs, which can be an HTML string or a jQuery/DOM object.
• baseUrl is the URL used for the base.

cmdAPI.paramsToString(params, prefix = "?")

Legacy name: Utils.paramsToString

Takes the given object containing keys and values into a query string suitable for inclusion in an HTTP GET or POST request.

• params - is the object of key-value pairs.
• prefix - is an optional string prepended to the result.

cmdAPI.urlToParams(url)

Legacy name: Utils.urlToParams

Given a url, returns an object containing keys and values retrieved from its query-part.

cmdAPI.parseHtml(htmlText)

Legacy name: Utils.parseHtml

An alternative to jQuery() which allows access to the entire document content. Returns HTML document object.

cmdAPI.escapeHtml(string)

Legacy names: Utils.escapeHtml, H()

Returns a version of the string safe for insertion into HTML.

cmdAPI.matchScore(match)

Legacy name: NounUtils.matchScore

Calculates the score for use in suggestions from a result array (match) of RegExp#exec run against user input.

cmdAPI.makeSugg(text, html, data, score, selectionIndices)

Legacy name: NounUtils.makeSugg

Creates a suggestion object that are used by the parser to make suggestions displayed at the popup window. Fills in text and html if missing and constructs summary from text and selectionIndices. At least one of text, html, or data is required.

• text can be any string.
• html must be a valid HTML string.
• data can be of any value.
• score is an optional float number representing the score of the suggestion. Defaults to 1.0.
• selectionIndices is an optional array containing the start and end indices of selection (displayed at the interface) within the text.

cmdAPI.grepSuggs(input, suggs, key)

Legacy name: NounUtils.grepSuggs

A helper function to grep a list of suggestion objects by the user input. Returns an array of filtered suggetions, each of them assigned score calculated by cmdAPI.matchScore().

• input is a string that filters the list.
• suggs is an array or dictionary of suggestion objects.
• key is an optional string to specify the target property of a suggestion to match with. Defaults to text.

cmdAPI.createBin(uuid, callback)

Creates an instance of the Bin interface and passes it to the supplied callback function or returns it as a promise. This allows to conveniently share persistent storage between commands or noun types.

• uuid - unique identifier that defines storage space.
• callback - a callback function that receives the Bin object. The result is returned as a promise if not specified.

cmdAPI.getCommandLine()

Returns the current user input.

cmdAPI.setCommandLine(text)

Sets the content of the command line.

• text - command text.

cmdAPI.closeCommandLine()since v0.8

Close the iShell popup window.

cmdAPI.getCommandAttributes(className)since v0.8

For a class-based command returns the command attributes as they are defined in the object-based syntax (passed to cmdAPI.createCommand).

cmdAPI.executeCommand(commandText, suggestion = 0)since v1.0

Runs command parser on the commandText and calls the execute method of the suggested command with the index defined by the suggestion parameter. The function could be used to make shortcuts for commands that are tedious to type.

cmdAPI.settings

Returns an object with key/value pairs customizable through the main setting page (read-only).

cmdAPI.arrowSelectionsince v0.8

A boolean property that indicates whether Ctrl+ARROWS selection is active. Could be used in the event handlers of cmdAPI.previewList and cmdAPI.objectPreviewList.

Bin

A persistent data storage interface that is available through the last argument of any command handler function. Calling any method of this interface with an argument will persistently store the supplied value. Calling the same method without arguments will return the value stored by the earlier call of this method.

    preview: function(pblock, args, Bin) {
        pblock.innerHTML = Bin.myProperty() || "Nothing stored yet";
        Bin.myProperty("this value persists between browser restarts");
        Bin.anotherProperty("this call persists another value");
    }
    

The interface offers separate storage space for each command.

jQuery, $

The entry points of jQuery API.

Built-in Noun Types

NounType system of the iShell parser is a powerful tool that allows adding of dynamic entities (such as the set of current tabs) to argument autocompletion and suggestion list. See the command authoring tutorial for an example.

Currently, the following noun types are built-in into iShell:

• noun_arb_text - an arbitrary text that suggests the input as is.
• noun_type_number - a numeric value.
• noun_type_percentage - a percentage value.
• noun_type_date, noun_type_time, noun_type_date_time - date and time, parseable by JavaScript's Date constructor.
• noun_type_email - email address.
• noun_type_contact - will suggest email addresses used with the email and compose commands.
• noun_type_tab - will suggest active tabs matched by title or url.
• noun_type_search - the list of available search engines.
• noun_type_container - suggests Firefox identity containers.
• noun_type_lang_google - language name/code pairs supported by Google Translator.
• noun_type_lang_wikipedia - language name/code pairs supported by Wikipedia.
• noun_type_lang_microsoft - language name/code pairs supported by Bing Translator.