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)[source]¶: Unescape HTML code refs; c.f. http://wiki.python.org/moin/EscapingHtml

bookmarks.parse_bookmarks_html(html)[source]¶: Reads the Netscape-style bookmarks.html in string, html and returns a list of Bookmark objects.

bookmarks.get_json_tags(bookmarks, url)[source]¶: 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)[source]¶: 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)[source]¶: Given json_str, returns a list of bookmark objects representing the data contained therein.

class bookmarks.BookmarksDB(user_dir, user)[source]¶

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()[source]¶: Opens the bookmarks stored in self.user_dir. If not present, an empty file will be created.

save_bookmarks()[source]¶: Saves self.bookmarks to self.bookmarks_path as a JSON-encoded list.

sync_bookmarks(bookmarks)[source]¶: Given bookmarks, synchronize with self.bookmarks doing conflict resolution and whatnot.

delete_bookmark(bookmark)[source]¶: Deletes the given bookmark.

get_bookmarks(updateSequenceNum=0)[source]¶: Returns a list of bookmarks newer than updateSequenceNum. If updateSequenceNum is 0 or undefined, all bookmarks will be returned.

get_highest_USN()[source]¶: Returns the highest updateSequenceNum in self.bookmarks

rename_tag(old_tag, new_tag)[source]¶: Goes through all bookmarks and renames all tags named old_tag to be new_tag.

class bookmarks.FaviconHandler(application, request, **kwargs)[source]¶

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)[source]¶

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)[source]¶: 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)[source]¶: Returns the fetched icon to the client.

class bookmarks.ImportHandler(application, request, **kwargs)[source]¶: Takes a bookmarks.html in a POST and returns a list of bookmarks in JSON format

class bookmarks.ExportHandler(application, request, **kwargs)[source]¶: Takes a JSON-encoded list of bookmarks and returns a Netscape-style HTML file.

bookmarks.send_bookmarks_css_template(self)[source]¶: 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'.