jQuery.announce - A micro-plugin for displaying unobtrusive announcements.
Developed by Cory LaViska for A Beautiful Site, LLC, 2017
Extended by Philip Mayer 2019
Licensed under the MIT license: http://opensource.org/licenses/MIT
Overview:
This plugin provides a minimal, lightweight, and customizable notification API for showing unobtrusive announcements in various styles. It's flexible enough to mold to your application's existing stylesheet and markup.
Features:
- Simple syntax:
$.announce.info('Hello there!')
$.announce.danger('Delete this?')
$.announce.success('All done?')
$.announce.warning('Are you sure?')
- Minimal default styles; easy to customize or write your own.
- Show/hide hooks for adding custom animation (works well with Velocity.js).
- Responsive
- Works well with Bootstrap and other frameworks
- Same colorscheme as Bootstrap 4
- Compact! (about 160 lines)
Demo
A quick demo can be found on CodePen: https://codepen.io/Shadowsith/pen/bJXqYQ
A local demo can be found in example.html
.
Installing
Include the minified version of this plugin in your project or install via NPM:
npm install --save jquery-announce
For webpage usage you can also use the jsDelivr CDN:
<!--Bind jquery here-->
Using the plugin
// Minimal example$announce; // Example with options$announce; // Use own colors$announce;
Methods
The following announcements are included by default:
$announce$announce$announce$announce$announce$announce$announce$announce
There is also a method to create custom announcements:
$.announce.say('your-custom-type', options)
In this case, the resulting announcement will be assigned the following classes that you can use for styling purposes: announce announce-your-custom-type
Note: By design, only one announcement will ever be shown at a time. Multiple notifications (i.e. stacking or growl-style) are outside the scope of this micro-plugin.
Options
If options
is a string, it will be used as the message. If options is an object, it will be merged with $.announce.defaults
.
Available options:
className
: The class name to assign to the announcement.duration
: The length of time in milliseconds to show the announcement.hideOnClick
: If true, the announcement will be hidden when the user clicks on it.html
: If true, HTML will not be escaped when setting the message.show
: Function for showing the announcement. Usethis
to reference the announcement element. Must return a promise-compatible object that resolves when the promise is completely visible. (This promise is currently not used, but is included for future enhancements.) Default value:outline
: If true, the announcement will be outlinedoutlineColor
: Color of announcement background-color. Default value:'transparent'
hPos
: Horizontal position, valuestop|bottom|center
. Default value:top
vPos
: Vertical position, valuesleft|right|center
. Default value:center
customColors
: If true, custom color/colorschemes for announcement can be used. By default the custom color set are bootstrap 4 colors.colors
: Color set for custom colors. Usable options are:info danger warning success primary secondary light text dark
.text
is for css color property.{var defer = $;;return defer;}hide
: Function for hiding the announcement. Usethis
to reference the announcement element. Must return a promise-compatible object that resolves when the announcement is completely hidden. Default value:{var defer = $;;return defer;}
You may also update the default options before calling either method:
$announcedefaultsoptionName = yourValue;
Promises
All announcements return a promise-compatible (jQuery-deferred) object that will resolve once the announcement is completely hidden:
$announce;