high-msg-manager (HMM)

It is a custom element that makes you able to manage your HTML/Javascript project's messages that you want to notify your users by.

Live Demo

Scenario

There is a message manager(high-msg-manager) which control messages(high-msg) it contains. we can add messages by putting high-msg tags in manager or using add method of the manager. messages could be stored by having an id attribute. then we show the message by using manager's show method or just simply removing message's hidden attribute/property.

• so if you want to store your messages in the manager give them an id attribute so later you could target them.

• or if you want to regenerate a message anytime you need one, just add it at the moment. (remember you still can store messages using manager's add method by giving them an id property.)

• if you have a message with dynamic content you can use templating.

Installation

You can use high-msg-manager via script tag or npm.

Script Tag

add below tag to your html document

<script  type="module" src='https://unpkg.com/[email protected]/lib/high-msg-manager.js'></script>

npm

 npm install high-msg-manager --save

once you installed the package, you can add this tag to your html document

<script  type="module" src='node_modules/high-msg-manager/lib/high-msg-manager.js'></script>

dependencies

To make Edge and most of another old modern browsers support HMM, add pollyfill to your project like this:

<!-- try to check the latest version of polyfill -->
<script src="https://unpkg.com/@webcomponents/[email protected]/webcomponents-loader.js"></script>

also Edge does not read the internal styles so if you want Edge support add this tag to your document too:

<!-- with npm -->
<link rel="stylesheet" type="text/css" href="node_modules/high-msg-manager/style/high-msg-manager.css">

<!-- without npm -->
<link rel="stylesheet" type="text/css" href="https://unpkg.com/[email protected]/style/high-msg-manager.css">

Usage

First, you need to create your HMM tag.

<high-msg-manager></high-msg-manager>

HMM atributes

animate

messages will fade out when they disappear.

position

HMM's position could be changed at any seconds. by default, it floats on the center of the page but could be changed to static which makes it not float or top, topleft, topright, bottom, bottomleft and bottomright.

duration

a message's duration could be specifically set but if it doesn't get duration attribute, it gets the HMM's default duration. it written in seconds like "5".

example

<high-msg-manager animate duration="5" position="topleft"></high-msg-manager>

high-msg

So HMM manages messages, lets define one.

<high-msg-manager>
    <high-msg type="success"> You did right! </high-msg>
</high-msg-manager>

high-msg attributes

static

messages with a static attribute, won't disappear until the user clicks on them, so defining a duration for them would be useless.

hidden

simply hide the message. if you define a stored message you must give it a hidden attribute unless you mean that.

duration

Message's appearing duration depends on how long or important it is so you can give messages a specific duration.

id

when you give a message an id attribute it means you want to target that message later, so they won't be deleted on disappearing, they just got hidden(messages without an id will be deleted on disappearing as you guessed). so later you can just show them.

type

default message's types are warn, success and error which you can expand them by adding some types of styles in your CSS, like this:

// defining a new type
high-msg[type=whatever]{
    some styles
}

templating

consider a situation that you need a stored message with dynamic content meaning parts of message's content is relative. for example we want to show time to user every minute. using templating in this situation is reasonable. we define some variable and when we want to show the message we provide the values. variable define like this ${...}

<high-msg> The time is ${time}</high-msg>

javascript

we have to method to manipulate messages by javascript, add and show.

add method

to add a message dynamically, select the high-msg-manager and use add method. it accept an key value javascript's object.

document.querySelector("high-msg-manager").add({
    'id': string, // it is optional, using it make the message stored.
    'type': string, // type of message, could be warn, success, error or a custom type
    'content': string, // using ${...} inside of it define a template for the message
    'values': object, // if you use templating, providing this as a javascript object with key of variable name and custom value makes the template work.
    'static': boolean, // message should be static or not
    'duration': number,
    'hidden': boolean, // do you want to show it right after? then make hidden false
    'priority': string, // high or nothing, appear at the top of appearing messages list.
});

example

document.querySelector("high-msg-manager").add({
    'id': 'showing_time',
    'type': 'warn',
    'content': 'the time is ${time}',
    'values': {time: '12:30:12'}
    'duration': 3
    'priority': true
});

show method

to show a message using show method we must have that message with a known id.

document.querySelector("high-msg-manager").show({
    'id': string, // which mesage you want to show?
    'content': string, // if you want to use original content of message don't provide this
    'values': object, // template's values
    'static': boolean, // message should be static or not
    'duration': number
});

example

document.querySelector("high-msg-manager").show({
    'id': 'showing_time',
    'values': {time: '12:32:55'}
});

Contributing

1. Fork it!
2. Create your feature branch: git checkout -b new-feature
3. Commit your changes: git commit -am 'Add some feature'
4. Push to the branch: git push origin new-feature
5. Submit a pull request :D

License

MIT LICENSE