A jQuery plugin which highlights new items since the last time a site was visited
- SYNOPSIS
- INSTALLATION
- DESCRIPTION
- STATIC PROPERTIES
- COMPATIBILITY
- SEE ALSO
- VERSION
- AUTHOR
- COPYRIGHT AND LICENSE
// ==UserScript==
// @name Example.com Highlighter
// @description Highlight new articles on Example.com
// @include https://www.example.com/news
// @require https://code.jquery.com/jquery-3.7.1.min.js
// @require https://cdn.jsdelivr.net/gh/chocolateboy/jquery-highlighter@v3.0.4/dist/highlighter.min.js
// @grant GM_deleteValue
// @grant GM_getValue
// @grant GM_listValues
// @grant GM_registerMenuCommand
// @grant GM_setValue
// ==/UserScript==
$.highlight({
item: 'div.story',
target: 'a.title',
id: 'data-story-id',
})Grab a file from the dist directory or use a CDN, e.g.:
jQuery Highlighter has the following prerequisites:
- jQuery (see compatibility)
- jQuery-onMutate (for dynamic items - see
item)
In order for highlighting to work in userscripts, the following permissions must be granted:
GM_deleteValue- used to clear seen IDs after they've expiredGM_getValue- used to retrieve seen IDsGM_listValues- used to enumerate seen IDsGM_registerMenuCommand- used to add a userscript menu command to clear all seen IDsGM_setValue- used to store seen IDs
jQuery Highlighter is a jQuery plugin which can be used to highlight new items (e.g. articles, stories, comments) on news sites, blogs, forums and other sites where old content is replaced by new content.
For some examples of this plugin in action, see here.
Highlighting is enabled by calling a method on the jQuery factory object. This method hides the implementation details behind a declarative API with defaults suitable for typical blog/news/aggregator sites. In most cases, only two or three parameters are needed to configure highlighting, only one of which is mandatory:
item: a selector for each article/story etc. (required)target: selects the element(s) within each item that should be highlighted (defaults to the item itself if not specified)id: a way to uniquely identify each item (defaults to the value of the item'sidattribute if not specified)
With these settings, and a few optional extras, the following behavior is enabled:
- the first time a news page/site is visited, all of its items are highlighted in yellow (by default)
- on subsequent visits, only new content (i.e. content that has been added since the last visit) is highlighted
- eventually, after a period of time (7 days by default), the cached entries for seen items are purged to save space
Signature: (options: Object) ⇒ Promise<void>
$.highlight({
item: 'div.story',
target: 'a.title',
id: 'data-story-id',
ttl: { days: 28 },
})Highlight new items on the current page. Takes an object with the following options.
Type: boolean, default: true
$.highlight({
item: 'div.story',
cache: false,
})If false, the cache is neither read from nor written to. This allows highlighters to be modified and reloaded without having to manually clear the cache every time.
Type: string, default: "#FFFD66"
$.highlight({
item: 'div.story',
color: '#FFFFAB',
})The background color to use as a HTML color string. The background of the target element(s) of new items is set to this color.
Type: boolean, default: false
$.highlight({
item: 'div.article',
debug: true,
})If true, debug/diagnostic messages for some methods are logged to the console. Note that this logs unencrypted IDs (as well as their encrypted values), and so should only be used temporarily, for troubleshooting, to avoid exposing sensitive data.
Type: boolean, default: true
$.highlight({
item: 'div.story',
cache: false,
dedup: false,
})If false, items are highlighted even if their IDs have already been seen. If
true (the default), items are deduplicated, i.e. items with IDs that have
already been seen/highlighted are skipped (not highlighted) if they appear
again on the same page. Turning off the cache (with cache) and
deduplication can be useful when developing highlighters and troubleshooting
selectors.
Type: string | (this: HTMLElement, target: JQuery) ⇒ string
$.highlight({
item: 'div.story',
id: 'data-story-id',
})A unique identifier for the item. If it's a string, the ID is the value of the
attribute of that name in the item. If it's a function, it's passed the DOM
element of each item as its this parameter and the jQuery wrapper for the
selected target element(s) as a parameter and returns a unique ID for the item.
If not supplied, it defaults to a function which returns the value of the
item's id attribute. If the ID is not defined, a TypeError is raised.
All IDs are encrypted before being written to the cache to avoid exposing private information.
Type: string | () ⇒ JQuery, required
$.highlight({
item: 'div.story'
})A selector for items. An item is a piece of updatable content, e.g. a news story, article, or comment. The selector can either be a jQuery selector string, or a function which returns the items as a jQuery collection.
If the item selector is a string and the jQuery-onMutate plugin is loaded, it is used to (also) detect items that are loaded dynamically, i.e. to highlight items loaded or displayed after the initial page load.
Type: (this: HTMLElement, target: JQuery, { id: string, color: string }) ⇒ void
// if the text is inverted (white on black), make it dark so that it remains
// legible on a yellow background
function onHighlight ($target) {
if ($target.css('color') === 'rgb(255, 255, 255)') {
$target.css('color', 'rgb(34, 34, 34)')
}
}
$.highlight({ item: 'div.story', onHighlight })A callback called after the target has been highlighted. Passed the item
element as its this parameter, the target element(s) as a jQuery collection,
and a second argument containing the item ID and background color. Can be used
e.g. to customize or override a target's foreground or background color.
Type: string | (this: HTMLElement, item: HTMLElement) ⇒ JQuery
$.highlight({
item: 'div.story',
target: 'a.title',
})The target element(s) to highlight. Can be a jQuery selector string, which is
evaluated relative to the item, or a function, which is passed the item element
as its this parameter and first parameter, and which returns a jQuery
collection containing the target element(s).
If not supplied, it defaults to a function which returns the item.
Highlighted target elements have a class attached to them which allows them to
be styled separately. The class name is available via
$.highlight.className. It can also be accessed as a selector
string (i.e. with a leading .) via $.highlight.selector.
Type: Object, default: { days: 7 }
$.highlight({
item: 'div.story',
ttl: { days: 28 },
})The "time to live" for cached entries, i.e. how long each item ID should be remembered for. If an entry expires, it is removed from the cache, and an item with the same ID will be considered new and highlighted again.
The ttl object is a sort of mini-DSL in data form for specifying the
duration: the value is the sum of each unit * value product where each unit
denotes the corresponding number of seconds:
| unit | seconds |
|---|---|
| second/seconds | 1 |
| minute/minutes | 60 |
| hour/hours | 60 * 60 |
| day/days | 24 * 60 * 60 |
| week/weeks | 7 * 24 * 60 * 60 |
These pairs can be combined, e.g.:
{
days: 28,
hours: 6,
minutes: 42,
seconds: 12,
}The singular and plural versions of each unit are equivalent, e.g. { minute: 10 } and { minutes: 10 } both represent 600 seconds.
If not supplied, it defaults to 7 days.
The following properties are defined on the highlight method.
Type: string
function isHighlighted (el) {
return el.classList.contains($.highlight.className)
}The name of the CSS class added to highlighted elements. See target for more details.
Type: string
const $highlighted = $($.highlight.selector)A CSS selector string which matches highlighted elements, i.e. the highlighted
class name with a dot (.) prepended. See target
for more details.
- This plugin should work in any browser with ES6 support.
- It has been tested with jQuery 3.x, and may not work with earlier versions.
- It has been tested on Greasemonkey 3 and Violentmonkey, but should work in all userscript engines which support the Greasemonkey 3 API.
- chocolateboy/userscripts - highlighter userscripts which use this plugin
- theoky/HistoryOfTheSeen - a userscript which greys out seen links on several sites
3.0.4
Copyright © 2013-2024 by chocolateboy.
This is free software; you can redistribute it and/or modify it under the terms of the Artistic License 2.0.