{"id":14989093,"url":"https://github.com/chocolateboy/jquery-highlighter","last_synced_at":"2025-04-12T01:30:42.043Z","repository":{"id":11469815,"uuid":"69773222","full_name":"chocolateboy/jquery-highlighter","owner":"chocolateboy","description":"A jQuery plugin to highlight new items since the last time a site was visited","archived":false,"fork":false,"pushed_at":"2024-08-10T13:12:26.000Z","size":141,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-25T21:12:28.481Z","etag":null,"topics":["greasemonkey","highlighter","jquery","jquery-plugin","tampermonkey","userscript","userscripts","violentmonkey"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"artistic-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/chocolateboy.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-10-02T01:40:14.000Z","updated_at":"2024-08-10T13:11:16.000Z","dependencies_parsed_at":"2024-09-15T15:20:57.398Z","dependency_job_id":null,"html_url":"https://github.com/chocolateboy/jquery-highlighter","commit_stats":{"total_commits":33,"total_committers":1,"mean_commits":33.0,"dds":0.0,"last_synced_commit":"e6fb3b2ed89c6a2c8fc2b92b7a57ca033ee1421f"},"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chocolateboy%2Fjquery-highlighter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chocolateboy%2Fjquery-highlighter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chocolateboy%2Fjquery-highlighter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chocolateboy%2Fjquery-highlighter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chocolateboy","download_url":"https://codeload.github.com/chocolateboy/jquery-highlighter/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248504195,"owners_count":21115133,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["greasemonkey","highlighter","jquery","jquery-plugin","tampermonkey","userscript","userscripts","violentmonkey"],"created_at":"2024-09-24T14:17:41.405Z","updated_at":"2025-04-12T01:30:41.702Z","avatar_url":"https://github.com/chocolateboy.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# jquery-highlighter\n\nA jQuery plugin which highlights new items since the last time a site was visited\n\n\u003c!-- TOC --\u003e\n\n- [SYNOPSIS](#synopsis)\n- [INSTALLATION](#installation)\n  - [Dependencies](#dependencies)\n    - [Required](#required)\n    - [Optional](#optional)\n  - [Permissions](#permissions)\n- [DESCRIPTION](#description)\n- [STATIC PROPERTIES](#static-properties)\n  - [highlight](#highlight)\n    - [Options](#options)\n      - [cache](#cache)\n      - [color](#color)\n      - [debug](#debug)\n      - [dedup](#dedup)\n      - [id](#id)\n      - [item](#item)\n      - [onHighlight](#onhighlight)\n      - [target](#target)\n      - [ttl](#ttl)\n    - [Properties](#properties)\n      - [className](#classname)\n      - [selector](#selector)\n- [COMPATIBILITY](#compatibility)\n- [SEE ALSO](#see-also)\n- [VERSION](#version)\n- [AUTHOR](#author)\n- [COPYRIGHT AND LICENSE](#copyright-and-license)\n\n\u003c!-- TOC END --\u003e\n\n# SYNOPSIS\n\n\u003ca href=\"https://github.com/chocolateboy/userscripts#highlighters\"\u003e\u003cimg src=\"https://i.imgur.com/y0goAMH.png\" alt=\"Hacker News Highlighter\"/\u003e\u003c/a\u003e\n\n```javascript\n// ==UserScript==\n// @name          Example.com Highlighter\n// @description   Highlight new articles on Example.com\n// @include       https://www.example.com/news\n// @require       https://code.jquery.com/jquery-3.7.1.min.js\n// @require       https://cdn.jsdelivr.net/gh/chocolateboy/jquery-highlighter@v3.0.4/dist/highlighter.min.js\n// @grant         GM_deleteValue\n// @grant         GM_getValue\n// @grant         GM_listValues\n// @grant         GM_registerMenuCommand\n// @grant         GM_setValue\n// ==/UserScript==\n\n$.highlight({\n    item:   'div.story',\n    target: 'a.title',\n    id:     'data-story-id',\n})\n```\n\n# INSTALLATION\n\nGrab a file from the [`dist`](dist) directory or use a CDN, e.g.:\n\n- [jsDelivr](https://cdn.jsdelivr.net/gh/chocolateboy/jquery-highlighter@v3.0.4/dist/highlighter.min.js)\n- [Git CDN](https://gitcdn.xyz/repo/chocolateboy/jquery-highlighter/v3.0.4/dist/highlighter.min.js)\n\n## Dependencies\n\njQuery Highlighter has the following prerequisites:\n\n### Required\n\n- [jQuery](https://jquery.com/) (see [compatibility](#compatibility))\n\n### Optional\n\n- [jQuery-onMutate](https://github.com/eclecto/jQuery-onMutate) (for dynamic items - see [`item`](#item))\n\n## Permissions\n\nIn order for highlighting to work in userscripts, the following permissions must be granted:\n\n- `GM_deleteValue` - used to clear seen IDs after they've expired\n- `GM_getValue` - used to retrieve seen IDs\n- `GM_listValues` - used to enumerate seen IDs\n- `GM_registerMenuCommand` - used to add a userscript menu command to clear all seen IDs\n- `GM_setValue` - used to store seen IDs\n\n# DESCRIPTION\n\njQuery Highlighter is a [jQuery](https://jquery.com/) plugin which can be used\nto highlight new items (e.g. articles, stories, comments) on news sites, blogs,\nforums and other sites where old content is replaced by new content.\n\nFor some examples of this plugin in action, see\n[here](https://github.com/chocolateboy/userscripts#highlighters).\n\nHighlighting is enabled by calling a method on the jQuery factory object. This\nmethod hides the implementation details behind a declarative API with defaults\nsuitable for typical blog/news/aggregator sites. In most cases, only two or\nthree parameters are needed to configure highlighting, only one of which is\nmandatory:\n\n- [`item`](#item): a selector for each article/story etc. (required)\n- [`target`](#target): selects the element(s) within each item that should be highlighted (defaults to the item itself if not specified)\n- [`id`](#id): a way to uniquely identify each item (defaults to the value of the item's `id` attribute if not specified)\n\nWith these settings, and a few optional extras, the following behavior is enabled:\n\n- the first time a news page/site is visited, all of its items are highlighted in yellow (by default)\n- on subsequent visits, only new content (i.e. content that has been added since the last visit) is highlighted\n- eventually, after a period of time (7 days by default), the cached entries for seen items are purged to save space\n\n# STATIC PROPERTIES\n\n## highlight\n\n**Signature**: `(options: Object) ⇒ Promise\u003cvoid\u003e`\n\n```javascript\n$.highlight({\n    item:   'div.story',\n    target: 'a.title',\n    id:     'data-story-id',\n    ttl:    { days: 28 },\n})\n```\n\nHighlight new items on the current page. Takes an object with the following options.\n\n### Options\n\n#### cache\n\n**Type**: `boolean`, default: `true`\n\n```javascript\n$.highlight({\n    item: 'div.story',\n    cache: false,\n})\n```\n\nIf false, the cache is neither read from nor written to. This allows\nhighlighters to be modified and reloaded without having to manually clear the\ncache every time.\n\n#### color\n\n**Type**: `string`, default: `\"#FFFD66\"`\n\n```javascript\n$.highlight({\n    item: 'div.story',\n    color: '#FFFFAB',\n})\n```\n\nThe background color to use as a HTML color string. The background of the\ntarget element(s) of new items is set to this color.\n\n#### debug\n\n**Type**: `boolean`, default: `false`\n\n```javascript\n$.highlight({\n    item: 'div.article',\n    debug: true,\n})\n```\n\nIf true, debug/diagnostic messages for some methods are logged to the console.\nNote that this logs **unencrypted** IDs (as well as their encrypted values),\nand so should only be used temporarily, for troubleshooting, to avoid exposing\nsensitive data.\n\n#### dedup\n\n**Type**: `boolean`, default: `true`\n\n```javascript\n$.highlight({\n    item: 'div.story',\n    cache: false,\n    dedup: false,\n})\n```\n\nIf false, items are highlighted even if their IDs have already been seen. If\ntrue (the default), items are deduplicated, i.e. items with IDs that have\nalready been seen/highlighted are skipped (not highlighted) if they appear\nagain on the same page. Turning off the cache (with [`cache`](#cache)) and\ndeduplication can be useful when developing highlighters and troubleshooting\nselectors.\n\n#### id\n\n**Type**: `string | (this: HTMLElement, target: JQuery) ⇒ string`\n\n```javascript\n$.highlight({\n    item: 'div.story',\n    id:   'data-story-id',\n})\n```\n\nA unique identifier for the item. If it's a string, the ID is the value of the\nattribute of that name in the item. If it's a function, it's passed the DOM\nelement of each item as its `this` parameter and the jQuery wrapper for the\nselected target element(s) as a parameter and returns a unique ID for the item.\n\nIf not supplied, it defaults to a function which returns the value of the\nitem's `id` attribute. If the ID is not defined, a TypeError is raised.\n\nAll IDs are encrypted before being written to the cache to avoid exposing\nprivate information.\n\n#### item\n\n**Type**: `string | () ⇒ JQuery`, required\n\n```javascript\n$.highlight({\n    item: 'div.story'\n})\n```\n\nA selector for items. An item is a piece of updatable content, e.g. a news\nstory, article, or comment. The selector can either be a jQuery selector\nstring, or a function which returns the items as a jQuery collection.\n\nIf the item selector is a string and the\n[jQuery-onMutate](https://github.com/eclecto/jQuery-onMutate) plugin is loaded,\nit is used to (also) detect items that are loaded dynamically, i.e. to\nhighlight items loaded or displayed after the initial page load.\n\n#### onHighlight\n\n**Type**: `(this: HTMLElement, target: JQuery, { id: string, color: string }) ⇒ void`\n\n```javascript\n// if the text is inverted (white on black), make it dark so that it remains\n// legible on a yellow background\nfunction onHighlight ($target) {\n    if ($target.css('color') === 'rgb(255, 255, 255)') {\n        $target.css('color', 'rgb(34, 34, 34)')\n    }\n}\n\n$.highlight({ item: 'div.story', onHighlight })\n```\n\nA callback called after the target has been highlighted. Passed the item\nelement as its `this` parameter, the target element(s) as a jQuery collection,\nand a second argument containing the item ID and background color. Can be used\ne.g. to customize or override a target's foreground or background color.\n\n#### target\n\n**Type**: `string | (this: HTMLElement, item: HTMLElement) ⇒ JQuery`\n\n```javascript\n$.highlight({\n    item:   'div.story',\n    target: 'a.title',\n})\n```\n\nThe target element(s) to highlight. Can be a jQuery selector string, which is\nevaluated relative to the item, or a function, which is passed the item element\nas its `this` parameter and first parameter, and which returns a jQuery\ncollection containing the target element(s).\n\nIf not supplied, it defaults to a function which returns the item.\n\nHighlighted target elements have a class attached to them which allows them to\nbe styled separately. The class name is available via\n[`$.highlight.className`](#classname). It can also be accessed as a selector\nstring (i.e. with a leading `.`) via [`$.highlight.selector`](#selector).\n\n#### ttl\n\n**Type**: `Object`, default: `{ days: 7 }`\n\n```javascript\n$.highlight({\n    item: 'div.story',\n    ttl: { days: 28 },\n})\n```\n\nThe \"time to live\" for cached entries, i.e. how long each item ID should be\nremembered for. If an entry expires, it is removed from the cache, and an item\nwith the same ID will be considered new and highlighted again.\n\nThe `ttl` object is a sort of mini-DSL in data form for specifying the\nduration: the value is the sum of each `unit * value` product where each unit\ndenotes the corresponding number of seconds:\n\n| unit           | seconds          |\n|----------------|-----------------:|\n| second/seconds |                1 |\n| minute/minutes |               60 |\n| hour/hours     |          60 * 60 |\n| day/days       |     24 * 60 * 60 |\n| week/weeks     | 7 * 24 * 60 * 60 |\n\nThese pairs can be combined, e.g.:\n\n```javascript\n{\n    days: 28,\n    hours: 6,\n    minutes: 42,\n    seconds: 12,\n}\n```\n\nThe singular and plural versions of each unit are equivalent, e.g. `{ minute: 10\n}` and `{ minutes: 10 }` both represent 600 seconds.\n\nIf not supplied, it defaults to 7 days.\n\n### Properties\n\nThe following properties are defined on the [`highlight`](#highlight) method.\n\n#### className\n\n**Type**: `string`\n\n```javascript\nfunction isHighlighted (el) {\n    return el.classList.contains($.highlight.className)\n}\n```\n\nThe name of the CSS class added to highlighted elements. See [`target`](#target) for more details.\n\n#### selector\n\n**Type**: `string`\n\n```javascript\nconst $highlighted = $($.highlight.selector)\n```\n\nA CSS selector string which matches highlighted elements, i.e. the highlighted\n[class name](#classname) with a dot (`.`) prepended. See [`target`](#target)\nfor more details.\n\n# COMPATIBILITY\n\n- This plugin should work in any browser with ES6 support.\n- It has been tested with jQuery 3.x, and may not work with earlier versions.\n- It has been tested on Greasemonkey 3 and Violentmonkey, but should work in all userscript engines which support the Greasemonkey 3 API.\n\n# SEE ALSO\n\n- [chocolateboy/userscripts](https://github.com/chocolateboy/userscripts#highlighters) - highlighter userscripts which use this plugin\n- [theoky/HistoryOfTheSeen](https://github.com/theoky/HistoryOfTheSeen) - a userscript which greys out seen links on several sites\n\n# VERSION\n\n3.0.4\n\n# AUTHOR\n\n[chocolateboy](mailto:chocolate@cpan.org)\n\n# COPYRIGHT AND LICENSE\n\nCopyright © 2013-2024 by chocolateboy.\n\nThis is free software; you can redistribute it and/or modify it under the terms\nof the [Artistic License 2.0](http://www.opensource.org/licenses/artistic-license-2.0.php).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchocolateboy%2Fjquery-highlighter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchocolateboy%2Fjquery-highlighter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchocolateboy%2Fjquery-highlighter/lists"}