### Navigation

- index
- modules |
- next |
- previous |
- Gate One Documentation »
- Gate One Applications »
- Terminal »
- Terminal Developer Documentation »

# The Bookmarks Plugin

## JavaScript

bookmarks.js - The client-side portion of Gate One's Bookmarks plugin.

`GateOne.Bookmarks.``addFilterDateTag`(bookmarks, dateTag)

  Adds the given dateTag to the filter list. bookmarks is unused.

`GateOne.Bookmarks.``addFilterTag`(bookmarks, tag)

  Adds the given tag to the filter list. bookmarks is unused.

`GateOne.Bookmarks.``addFilterURLTypeTag`(bookmarks, typeTag)

  Adds the given typeTag to the filter list. bookmarks is unused.

`GateOne.Bookmarks.``addTagToBookmark`(URL, tag)

  Adds the given tag to the bookmark object associated with URL.

`GateOne.Bookmarks.``allTags`()

  Returns an array of all the tags in `localStorage[GateOne.prefs.prefix+'bookmarks']` ordered alphabetically.

`GateOne.Bookmarks.``bookmarks`

  All the user's bookmarks are stored in this array which is stored/loaded from `localStorage[GateOne.prefs.prefix+'bookmarks']`. Each bookmark consists of the following data structure:

      {
          created: 1356974567922,
          images: {favicon: "data:image/x-icon;base64,<gobbledygook>"},
          name: "localhost",
          notes: "Login to the Gate One server itself",
          tags: ["Linux", "Ubuntu", "Production", "Gate One"],
          updateSequenceNum: 11,
          updated: 1356974567922,
          url: "ssh://localhost",
          visits: 0
      }

  Most of that should be self-explanatory except the `updateSequenceNum` (aka USN). The USN value is used to determine when this bookmark was last changed in comparison to the highest USN stored on the server. By comparing the highest client-side USN against the highest server-side USN we can determine what (if anything) has changed since the last synchronization. It is much more efficient than enumerating all bookmarks on both the client and server in order to figure out what's different.

`GateOne.Bookmarks.``createBookmark`(bmContainer, bookmark, delay)

  Creates a new bookmark element and places it in bmContainer. Also returns the bookmark element.

  Arguments:

  - bmContainer (DOM_node) -- The DOM node we're going to be placing the bookmark.
  - bookmark (object) -- A bookmark object (presumably taken from `GateOne.Bookmarks.bookmarks`)
  - delay (number) -- The amount of milliseconds to wait before translating (sliding) the bookmark into view.
  - ad (boolean) -- If true, will not bother adding tags or edit/delete/share links.

`GateOne.Bookmarks.``createOrUpdateBookmark`(obj)

  Creates or updates a bookmark (in `GateOne.Bookmarks.bookmarks` and localStorage) using the given bookmark obj.

`GateOne.Bookmarks.``createPanel`([embedded])

  Creates the bookmarks panel. If the bookmarks panel already exists it will be destroyed and re-created, resetting the pagination.

  If embedded is true then we'll just load the header (without search).

`GateOne.Bookmarks.``createSortOpts`()

  Returns a span representing the current sort direction and "sort by" type.

`GateOne.Bookmarks.``deleteBookmark`(obj)

  Asks the user for confirmation then deletes the chosen bookmark...

  obj can either be a URL (string) or the "go_bm_delete" anchor tag.

  Note

  Not the same thing as `GateOne.Bookmarks.removeBookmark()`.

`GateOne.Bookmarks.``deletedBookmarksSyncComplete`(message)

  Handles the response from the server after we've sent the 'bookmarks_deleted' WebSocket action. Resets `localStorage[GateOne.prefs.prefix+'deletedBookmarks']` and displays a message to the user indicating how many bookmarks were just deleted.

`GateOne.Bookmarks.``editBookmark`(obj)

  Opens the bookmark editor for the given obj (the bookmark element on the page).

  Note

  Only meant to be called from a 'bm_edit' anchor tag (as the obj).

`GateOne.Bookmarks.``exportBookmarks`([bookmarks])

  Allows the user to save their bookmarks as a Netscape-style HTML file. Immediately starts the download.

  If bookmarks is given, that array will be what is exported. Otherwise the complete `GateOne.Bookmarks.bookmarks` array will be exported.

`GateOne.Bookmarks.``filterBookmarksBySearchString`(str)

  Filters bookmarks to those matching str (used by the search function).

`GateOne.Bookmarks.``flushIconQueue`()

  Loops over `localStorage[GateOne.prefs.prefix+'iconQueue']` fetching icons until it is empty.

  If the queue is currently being processed this function won't do anything when called.

`GateOne.Bookmarks.``generateTip`()

  Returns a random, helpful tip for using bookmarks (as a string).

`GateOne.Bookmarks.``getAutotags`([bookmarks])

  Returns an array of all the autotags in `GateOne.Bookmarks.bookmarks` or bookmarks if given.

  Note

  Ordered alphabetically with the URL types coming before date tags.

`GateOne.Bookmarks.``getBookmarkObj`(URL)

  Returns the bookmark object associated with the given URL.

`GateOne.Bookmarks.``getDateTag`(dateObj)

  Given a `Date` object, returns a string such as "<7 days". Suitable for use as an autotag.

`GateOne.Bookmarks.``getMaxBookmarks`(elem)

  Calculates and returns the number of bookmarks that will fit in the given element (elem). elem may be an element ID or a DOM node object.

`GateOne.Bookmarks.``getTags`([bookmarks])

  Returns an array of all the tags in `GateOne.Bookmarks.bookmarks` or bookmarks if given.

  Note

  Ordered alphabetically

`GateOne.Bookmarks.``highestUSN`()

  Returns the highest `updateSequenceNum` that exists in all bookmarks.

`GateOne.Bookmarks.``httpIconHandler`(bookmark)

  Retrieves the icon for the given HTTP or HTTPS bookmark and saves it in the bookmarks DB.

`GateOne.Bookmarks.``incrementVisits`(URL)

  Increments by 1 the 'visits' value of the bookmark object associated with the given URL.

`GateOne.Bookmarks.``init`()

  Creates the bookmarks panel, initializes some important variables, registers the `Control-Alt-b` keyboard shortcut, and registers the following WebSocket actions:

      GateOne.Net.addAction('terminal:bookmarks_updated', GateOne.Bookmarks.syncBookmarks);
      GateOne.Net.addAction('terminal:bookmarks_save_result', GateOne.Bookmarks.syncComplete);
      GateOne.Net.addAction('terminal:bookmarks_delete_result', GateOne.Bookmarks.deletedBookmarksSyncComplete);
      GateOne.Net.addAction('terminal:bookmarks_renamed_tags', GateOne.Bookmarks.tagRenameComplete);

`GateOne.Bookmarks.``loadBookmarks`([delay])

  Filters/sorts/displays bookmarks and updates the bookmarks panel to reflect the current state of things (draws the tag cloud and ensures the pagination is correct).

  If delay (milliseconds) is given, loading of bookmarks will be delayed by that amount before they're drawn (for animation purposes).

`GateOne.Bookmarks.``loadPagination`(bookmarks[, page])

  Sets up the pagination for the given array of bookmarks and returns the pagination node.

  If page is given the pagination will highlight the given page number and adjust the prev/next links accordingly.

`GateOne.Bookmarks.``loadTagCloud`([active])

  Loads the tag cloud. If active is given it must be one of 'tags' or 'autotags'. It will mark the appropriate header as inactive and load the respective tags.

`GateOne.Bookmarks.``openBookmark`(URL)

  Calls the function in `GateOne.Bookmarks.URLHandlers` associated with the protocol of the given URL.

  If no function is registered for the given URL protocol a new browser window will be opened using the given URL.

`GateOne.Bookmarks.``openExportDialog`()

  Creates a dialog where the user can select some options and export their bookmarks.

`GateOne.Bookmarks.``openImportDialog`()

  Displays the form where a user can create or edit a bookmark.

  If URL is given, pre-fill the form with the associated bookmark for editing.

`GateOne.Bookmarks.``openNewBookmarkForm`([URL])

  Displays the form where a user can create or edit a bookmark.

  If URL is given, pre-fill the form with the associated bookmark for editing.

`GateOne.Bookmarks.``openRenameDialog`(tagName)

  Creates a dialog where the user can rename the given tagName.

`GateOne.Bookmarks.``openSearchDialog`(URL, title)

  Creates a dialog where the user can utilize a keyword search URL. title will be used to create the dialog title like this: "Keyword Search: title".

`GateOne.Bookmarks.``panelToggleIn`(panel)

  Called when `panel_toggle:in` event is triggered, calls `GateOne.Bookmarks.createPanel()` if panel is the Bookmarks panel.

`GateOne.Bookmarks.``registerIconHandler`(protocol, handler)

  Registers the given handler as the function to use whenever a bookmark icon needs to be retrieved for the given protocol.

  When the given handler is called it will be passed the bookmark object as the only argument. It is up to the handler to call (or not) `GateOne.Bookmarks.storeFavicon(bookmark, <icon data URI>);` to store the icon.

`GateOne.Bookmarks.``registerURLHandler`(protocol, handler)

  Registers the given handler as the function to use whenever a bookmark is opened with a matching protocol.

  When the given handler is called it will be passed the URL as the only argument.

`GateOne.Bookmarks.``removeBookmark`(url[, callback])

  Removes the bookmark matching url from `GateOne.Bookmarks.bookmarks` and saves the change to localStorage.

  If callback is given it will be called after the bookmark has been deleted.

  Note

  Not the same thing as `GateOne.Bookmarks.deleteBookmark()`.

`GateOne.Bookmarks.``removeFilterDateTag`(bookmarks, dateTag)

  Removes the given dateTag from the filter list. bookmarks is unused.

`GateOne.Bookmarks.``removeFilterTag`(bookmarks, tag)

  Removes the given tag from the filter list. bookmarks is unused.

`GateOne.Bookmarks.``removeFilterURLTypeTag`(bookmarks, typeTag)

  Removes the given typeTag from the filter list. bookmarks is unused.

`GateOne.Bookmarks.``renameTag`(oldName, newName)

  Renames the tag matching oldName to be newName for all bookmarks that have it.

`GateOne.Bookmarks.``sortFunctions`

  An associative array of functions that are used to sort bookmarks. When the user clicks on one of the sorting options it assigns one of these functions to `GateOne.Bookmarks.sortfunc()` which is then applied like so:

      bookmarks.sort(GateOne.Bookmarks.sortfunc);

  `GateOne.Bookmarks.sortFunctions.``alphabetical`(a, b)

    Sorts bookmarks alphabetically.

  `GateOne.Bookmarks.sortFunctions.``created`(a, b)

    Sorts bookmarks by date modified followed by alphabetical.

  `GateOne.Bookmarks.sortFunctions.``visits`(a, b)

    Sorts bookmarks according to the number of visits followed by alphabetical.

`GateOne.Bookmarks.``storeBookmark`(bookmarkObj[, callback])

  Stores the given bookmarkObj in localStorage.

  if callback is given it will be executed after the bookmark is stored with the bookmarkObj as the only argument.

`GateOne.Bookmarks.``storeBookmarks`(bookmarks[, recreatePanel[, skipTags]])

  Takes an array of bookmarks and stores them in `GateOne.Bookmarks.bookmarks`.

  If recreatePanel is true, the panel will be re-drawn after bookmarks are stored.

  If skipTags is true, bookmark tags will be ignored when saving bookmarks.

`GateOne.Bookmarks.``storeFavicon`(bookmark, dataURI)

  Stores the given dataURI as the 'favicon' image for the given bookmark.

  Note

  dataURI must be pre-encoded data:URI

`GateOne.Bookmarks.``syncBookmarks`(response)

  Called when the `terminal:bookmarks_updated` WebSocket action is received from the server. Removes bookmarks marked as deleted on the server, uploads new bookmarks that are not on the server (yet), and processes any tags that have been renamed.

`GateOne.Bookmarks.``syncComplete`(response)

  Called when the sync (download) is completed. Stores the current highest `updateSequenceNum` in localStorage, and notifies the user of any errors that occurred during synchronization.

`GateOne.Bookmarks.``tagContextMenu`(elem)

  Called when we right-click on a tag elem. Gives the user the option to rename the tag or cancel the context menu.

`GateOne.Bookmarks.``tagRenameComplete`(result)

  Called when the 'bookmarks_renamed_tags' WebSocket action is received from the server. Deletes `localStorage[GateOne.prefs.prefix+'renamedTags']` (which stores tags that have been renamed and are awaiting sync) and displays a message to the user indicating that tags were renamed successfully.

`GateOne.Bookmarks.``toggleSortOrder`()

  Reverses the order of the bookmarks list.

`GateOne.Bookmarks.``updateIcon`(bookmark)

  Calls the handler in `GateOne.Bookmarks.iconHandlers` associated with the given bookmark.url protocol.

  If no handler can be found no operation will be performed.

`GateOne.Bookmarks.``updateIcons`(urls)

  Loops over the given urls attempting to fetch and store their respective favicons.

  Note

  This function is only used when debugging. It is called by no other functions.

`GateOne.Bookmarks.``updateProgress`(name, total, num[, desc])

  Creates/updates a progress bar given a name, a total, and num representing the current state of an action.

  Optionally, a description (desc) may be provided that will be placed above the progress bar.

`GateOne.Bookmarks.``updateUSN`(obj)

  Updates the `updateSequenceNum` of the bookmark matching obj in `GateOne.Bookmarks.bookmarks` (and in localStorage via `storeBookmark()`).

`GateOne.Bookmarks.``userLoginSync`(username)

  This gets attached to the `go:js_loaded` event. Calls the server-side `terminal:bookmarks_get` WebSocket action with the current USN (Update Sequence Number) to ensure the user's bookmarks are in sync with what's on the server.

## Python

bookmarks.py - A plugin for Gate One that adds fancy bookmarking capabilities.

### Hooks

This Python plugin file implements the following hooks:

    hooks = {
        'Web': [
            (r"/bookmarks/fetchicon", FaviconHandler),
            (r"/bookmarks/export", ExportHandler),
            (r"/bookmarks/import", ImportHandler),
        ],
        'WebSocket': {
            'terminal:bookmarks_sync': save_bookmarks,
            'terminal:bookmarks_get': get_bookmarks,
            'terminal:bookmarks_deleted': delete_bookmarks,
            'terminal:bookmarks_rename_tags': rename_tags,
        },
        'Events': {
            'terminal:authenticate': send_bookmarks_css_template
        }
    }

### Docstrings

`bookmarks.``unescape`(s)

  Unescape HTML code refs; c.f. http://wiki.python.org/moin/EscapingHtml

`bookmarks.``parse_bookmarks_html`(html)

  Reads the Netscape-style bookmarks.html in string, html and returns a list of Bookmark objects.

`bookmarks.``get_json_tags`(bookmarks, url)

  Iterates over bookmarks (dict) trying to find tags associated with the given url. Returns the tags found as a list.

`bookmarks.``get_ns_json_bookmarks`(json_dict, bookmarks)

  Given a json_dict, updates bookmarks with each URL as it is found within.

  Note

  Only works with Netscape-style bookmarks.json files.

`bookmarks.``parse_bookmarks_json`(json_str)

  Given json_str, returns a list of bookmark objects representing the data contained therein.

class `bookmarks.``BookmarksDB`(user_dir, user)

  Used to read and write bookmarks to a file on disk. Can also synchronize a given list of bookmarks with what's on disk. Uses a given bookmark's `updateSequenceNum` to track what wins the "who is newer?" comparison.

  Sets up our bookmarks database object and reads everything in.

  `open_bookmarks`()

    Opens the bookmarks stored in self.user_dir. If not present, an empty file will be created.

  `save_bookmarks`()

    Saves self.bookmarks to self.bookmarks_path as a JSON-encoded list.

  `sync_bookmarks`(bookmarks)

    Given bookmarks, synchronize with self.bookmarks doing conflict resolution and whatnot.

  `delete_bookmark`(bookmark)

    Deletes the given bookmark.

  `get_bookmarks`(updateSequenceNum=0)

    Returns a list of bookmarks newer than updateSequenceNum. If updateSequenceNum is 0 or undefined, all bookmarks will be returned.

  `get_highest_USN`()

    Returns the highest updateSequenceNum in self.bookmarks

  `rename_tag`(old_tag, new_tag)

    Goes through all bookmarks and renames all tags named old_tag to be new_tag.

class `bookmarks.``FaviconHandler`(application, request, **kwargs)

  Retrives the biggest favicon-like icon at the given URL. It will try to fetch apple-touch-icons (which can be nice and big) before it falls back to grabbing the favicon.

  Note

  Works with GET and POST requests but POST is preferred since it keeps the URL from winding up in the server logs.

  `get_favicon_url`(html)

    Parses html looking for a favicon URL. Returns a tuple of:

        (<url>, <mimetype>)

    If no favicon can be found, returns:

        (None, None)

  `icon_multifetch`(urls, response)

    Fetches the icon at the given URLs, stopping when it finds the biggest. If an icon is not found, calls itself again with the next icon URL. If the icon is found, writes it to the client and finishes the request.

  `icon_fetch`(url, mimetype, response)

    Returns the fetched icon to the client.

class `bookmarks.``ImportHandler`(application, request, **kwargs)

  Takes a bookmarks.html in a POST and returns a list of bookmarks in JSON format

class `bookmarks.``ExportHandler`(application, request, **kwargs)

  Takes a JSON-encoded list of bookmarks and returns a Netscape-style HTML file.

`bookmarks.``send_bookmarks_css_template`(self)

  Sends our bookmarks.css template to the client using the 'load_style' WebSocket action. The rendered template will be saved in Gate One's 'cache_dir'.

### Navigation

- index
- modules |
- next |
- previous |
- Gate One Documentation »
- Gate One Applications »
- Terminal »
- Terminal Developer Documentation »