FaviconPlugin

Display a badge, image or video in a browser tab's favicon

Description

While Foswiki itself allows you set a new favicon url per page using the %FAVICON preference setting, this plugin adds extra flexibility, for instance by adding a badge counter to an existing favicon, or replace it with an image on the page etc.

For more information see https://github.com/ejci/favico.js

Examples

Add a numeric badge counter:

%FAV{"123"}%

Or using the FavIcon jQuery module directly. Note that you'll then need to add a

%JQREQUIRE{"FavIcon"}% 

to the examples. Such as:

There are <span class='jqFavicon foswikiAlert'>12</span> unread messages in your inbox.

Use anHTML img as a favicon:

<img src='%PUBURLPATH%/Web/Topic/image.jpeg' class='jqFavico' ... />

Syntax

The %FAV{...} macro has got the following parameters:

Name	HTML5 Data	Description	Default
"..." or text	data-text	text to be displayed
bg_color	data-bg-color	background color as rgb hex code	#d00
text_color	data-text-color	font-color	#fff
font_style	data-font-style	weight of font	bold
type	data-type	shape of badge: circle or rectangle	circle
position	data-position	position where to display a badge relative to the original favicon: up, down, left, upleft	down
font_family	data-font-family	font of a badge	sans-serif
animation	data-animation	animation type, one of: none, fade, pop, popFade, slide	slide

JavaScript API

The plugin allocates one foswiki.faviconManager that can be used to control the favicon. Methods are:

• foswiki.faviconManager.setText(text [, opts]): create a text badge
• foswiki.faviconManager.setImage(img [, opts]): create an image badge
• foswiki.faviconManage.config(opts): configure the default options
• foswiki.faviconManage.reset(): clear the favicon overlay

Installation Instructions

You do not need to install anything in the browser to use this extension. The following instructions are for the administrator who installs the extension on the server.

Open configure, and open the "Extensions" section. "Extensions Operation and Maintenance" Tab → "Install, Update or Remove extensions" Tab. Click the "Search for Extensions" button. Enter part of the extension name or description and press search. Select the desired extension(s) and click install. If an extension is already installed, it will not show up in the search results.

You can also install from the shell by running the extension installer as the web server user: (Be sure to run as the webserver user, not as root!)

cd /path/to/foswiki
perl tools/extension_installer <NameOfExtension> install

If you have any problems, or if the extension isn't available in configure, then you can still install manually from the command-line. See https://foswiki.org/Support/ManuallyInstallingExtensions for more help.

Dependencies

None

Change History

20 Dec 2024	properly deconstruct the plugin at the end of a session
30 Jan 2024	rework favicon manager; added reset() api to clear a favicon overlay
26 Jan 2024	initial release