https://github.com/reecem/h-bar
An Announcement Banner that is lightweight and based on tailwindcss for the styling
https://github.com/reecem/h-bar
announcement-banner banner javascript javascript-library notification npm-package tailwindcss
Last synced: 7 months ago
JSON representation
An Announcement Banner that is lightweight and based on tailwindcss for the styling
- Host: GitHub
- URL: https://github.com/reecem/h-bar
- Owner: ReeceM
- License: mit
- Created: 2020-02-15T19:03:13.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2023-03-30T14:09:44.000Z (about 3 years ago)
- Last Synced: 2024-10-12T08:21:49.854Z (over 1 year ago)
- Topics: announcement-banner, banner, javascript, javascript-library, notification, npm-package, tailwindcss
- Language: JavaScript
- Homepage: https://reecem.github.io/h-bar
- Size: 1.22 MB
- Stars: 4
- Watchers: 1
- Forks: 1
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE.md
- Security: SECURITY.md
Awesome Lists containing this project
README
# h-bar lightweight announcement bar
An Announcement Banner that is lightweight and based on tailwindcss for the styling
[](https://www.npmjs.com/package/@reecem/h-bar)
[](https://www.npmjs.com/package/@reecem/h-bar)
h-bar Announcement banner
The announcement bar uses native methods to make the library lightweight so that it can be loaded quickly, bar the webpack stuff.
**Note**
The initial version makes use of the WordPress API to be able to get the latest post.
i.e. it expects a json structure like so:
From a url like `http://blog.example.com/wp-json/wp/v2/posts?per_page=1&_fields=id,title,link`
```json
[
{
"id": 175,
"link": "https:\/\/blog.example.com\/how-to-hunt-a-vole\/",
"title": {
"rendered": "How To Hunt A Vole"
}
}
]
```
I plan to add more options and a parser callback that can be defined to extract a standard format.
## Installation
You can install the package via npm:
```bash
npm i @reecem/h-bar
```
Or use jsDelivr:
```html
...
...
```
> If you are customising the styling and overriding it with your own styling then you will also need an instance of your css or a tailwindcss file installed as only the classes needed are packaged with h-bar
## Usage
You can import it directly into your javascript app or use it in the html.
### Example
```html
hBar.init({
url: "http://blog.example.com/wp-json/wp/v2/posts?per_page=1&_fields=id,excerpt,title,link",
secondaryLinks: [
{
title: "Docs",
link: "http:://docs.example.com"
},
{
title: "Support",
link: "http://help.example.com"
}
],
options: {
theme: "blue",
}
});
hBar.fetchData()
```
### All config values
The initialization object currently has this structure and defaults:
```javascript
{
url: "https://your.blog/api/....",
onCompleted: "callback function",
link: "The link url, can be force and no need to fetch from API",
title: "The link url, can be force and no need to fetch from API",
secondaryLinks: [
{
title: "Docs",
link: "http:://docs.example.com"
}
],
parser: (data) => {/** Parser function */}
dismissible: false, // dismissible banner flag
dismissFor: new Date('2020-03-30'), // would dismiss it till end of March 30th 2020
theme: "gray",
headers: {
"Authorization": "Bearer {TOKEN}"
},
customStyles: {
wrapper: "hb-flex hb-w-full hd-flex-col md:hb-flex-row sm:hb-flex-row hb-text-sm hb-py-2 md:hb-px-20 hb-px-1 hb-items-center hb-justify-between",
linkWrapper: "hb-flex hb-items-center",
badge: "hb-px-2 hb-mx-2 hb-leading-relaxed hb-tracking-wider hb-uppercase hb-font-semibold hb-rounded-full hb-text-xs",
postTitle: "hover:hb-underline",
secondaryLink: "hb-mx-5 hb-cursor-pointer hover:hb-underline",
}
}
```
### Themes
Theme colors available: `gray`, `lightGray`, `blue`, `green`, `indigo`, `orange`, `yellow`, `teal`, `red`
(the below images are in the order they exits)
### Parser function
There is the availability of adding a custom parser function to override any of the default ones provided by the package.
This is handy if you have a custom endpoint that say would return also the secondary links or has a different data structure.
The parser function should always return an object with the structure:
```javascript
{
title: String,
link: String,
/** the secondaryLinks is optional.
* It will also override the links parsed in the init() arguments.
*/
secondaryLinks: [
{
title: String,
link: String,
},
]
}
```
You can define the function inside the `init()` method as follows:
```javascript
hBar.init({
url: "https://api.github.com/repos/ReeceM/h-bar/releases",
parser: (data) => {
// getting the first release on the list of releases from github.
const {name, html_url} = data[0];
return {
title: `Lateset version available ${name}`,
link: html_url
};
}
})
```
### Dismissing Notifications
> Available from `v0.3.0`/`v1.0.0`
**Temporary Dismissing**
To be able to dismiss a notification, please note it currently removes secondary links. It is therefore useful that you use this feature when just making announcements of a event or brief notification.
The way to activate session based dismissal is:
```javascript
{
//... rest of config
dismissible: true,
//... rest of config
}
```
This will just disable the banner for the current page visit, if the user reloads, its back.
**Time based dismissing**
To dismiss the banner until another time, you can set the `dismissFor` variable, this requires a `Date()` object.
When you set this and the banner is dismissed, the UTC milliseconds are stored in the localStorage, this is then read back when loading h-Bar.
```javascript
{
//... rest of config
dismissible: true,
dismissFor: new Date('2020-03-30'), // would dismiss it till end of march 30th
}
```
If you fail to set the value properly, it won't dismiss and the banner will show by default.
## Testing
_to come_ please make a PR if you know how to do it on JS.
## Changelog
Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.
## Contributing
Please see [CONTRIBUTING](CONTRIBUTING.md) for details.
## Security
If you discover any security related issues, please email zsh.rce@gmail.com instead of using the issue tracker. You can also use the [SECURITY](SECURITY.md) doc.
## Credits
- [ReeceM](https://github.com/ReeceM)
- [All Contributors](../../contributors)
## Support
[](https://ko-fi.com/S6S7UQ66)
## License
The MIT License (MIT). Please see [License File](LICENSE.md) for more information.