@termehui/vnotif v1.0.1

Notification

Notification is a Vue 3 plugin for managing notification.

Installation

Note: this package require animejs and shortid npm package.

CDN

This package published as vNotif module in umd.

<link
  rel="stylesheet"
  href="https://unpkg.com/@termehui/vnotif/dist/style.css"
/>
<script src="https://unpkg.com/@termehui/vnotif"></script>

NPM

npm i @termehui/vnotif

Install notification container with default name (notification):

import { createApp } from "vue";
import App from "./App.vue";
import vNotif from "@termehui/vnotif";

createApp(App).use(vNotif).mount("#app");

Install notification container with custom name:

import { createApp } from "vue";
import App from "./App.vue";
import { Container } from "@termehui/vnotif";
createApp(App).component("notif-container", Container).mount("#app");

Options

Notification has three level options:

• global options (used by default for all container)
• container options (passed as container property and override global options)
• notification options (passed on creation time and override container and global options)

Usage

Add Notification Container

To showing notification in your app you need to add notification container component in your template.

<template>
  <notification name="default" :options="{ duration: 7000 }" />
</template>

Note: you can have multiple container in your app. every container must have a unique name.

Note: you can use createNotification and createSimpleNotification to creating notification for named container or use createDefaultNotification and createDefaultSimpleNotification to creating notification for unnamed (default) container.

Show Simple Notification

Note: simple notifications has no actions. if you want notification with actions support you must use custom notification.

Note: simple notifications accept html string as content.

Note: title is optional and you can create notification without title.

import { defineComponent } from "vue";
import { createDefaultSimpleNotification } from "@termehui/vnotif";

export default defineComponent({
  setup() {
    function showNotification() {
      const globalId = createDefaultSimpleNotification(
        {
          title: "Greeting",
          content: "Welcome to our app!",
          class: "my-custom-class",
        },
        {
          duration: 10000,
          onClose: (mode: "auto" | "click" | "action") => {
            console.log(`notification closed by ${mode} mode`);
          },
        }
      );
      console.log(`new notification by globalId: ${notificationId} created!`);
    }

    return { showNotification };
  },
});

Custom Notifications

To create custom notification you need define a normal vue component with notification library composition api helpers useNotification and create notification instance using createNotification function.

Note: by default every notification received globalId and options props. you must define this props in your components and use it to define new notification component.

Note: you can define any props in your custom notification component and pass this props when you want create new notification.

useNotification Parameters

Caution: if root element not passed notification animations doesn't work!

useNotification Return Values

<template>
  <div
    class="v-notification"
    @mouseenter="pause"
    @mouseleave="resume"
    ref="container"
  >
    <div class="content">
      <p>{{ message }}</p>
      <div v-if="loading">Loading...</div>
      <p>{{ progress }} <strong>%</strong></p>
      <div class="gaper is-auto">
        <div class="filler"></div>
        <button class="is-simple" @click.stop="action('no', 'data')">
          {{ noText || "no" }}
        </button>
        <button
          class="is-primary"
          :class="{ 'is-disabled': loading }"
          @click.stop="action('yes')"
        >
          {{ yesText || "yes" }}
        </button>
      </div>
    </div>
    <div
      class="v-notification-progress"
      :style="{ width: `${progress}%` }"
    ></div>
  </div>
</template>

<script lang="ts">
import { defineComponent, ref } from "vue";
import { NotificationOptions, useNotification } from "@termehui/vnotif";
export default defineComponent({
  name: "MyNotification",
  props: {
    globalId: {
      type: String,
      required: true,
    },
    options: {
      type: Object as () => NotificationOptions,
      required: true,
    },
    // custom props
    message: String,
    yesText: String,
    noText: String,
  },
  setup(props) {
    const container = ref<HTMLElement>(); // template ref
    const { progress, loading, action, close, pause, resume } = useNotification(
      props.globalId,
      props.options,
      container
    );

    return { progress, loading, action, close, pause, resume, container };
  },
});
</script>

Use Custom Notification

createNotification method parameters:

Note: when using createDefaultNotification method, container parameters not exists.

Note: createNotification return new notification global id as result.

import { defineComponent } from "vue";
import { createDefaultNotification } from "@termehui/vnotif";
import MyNotification from "./MyNotification.vue";
export default defineComponent({
  setup() {
    const showNotification = () => {
      createDefaultNotification(
        MyNotification,
        {
          message: "are you want to delete record?",
          yesText: "Delete",
          noText: "Cancel",
          class: "is-error",
        },
        {
          onAction: async (k, _) => {
            if (k === "no") {
              return Promise.resolve(true);
            } else {
              const res = await doSomeLongAsyncWork();
              return res ? Promise.resolve(true) : Promise.resolve(false);
            }
          },
        }
      );
    };

    return { showNotification };
  },
});

Styling

for using default styles you can use one of static (CSS) or termeh (SCSS) predefined files.

Note: advanced feature (change default vars, padding classes and color classes) only available in termeh version of style.

// Static
@import "@termehui/vnotif/style.css";
@import "@termehui/vnotif/dist/style.css"; // old node version
// Termeh
@import "@termehui/vnotif/style.scss";
@import "@termehui/vnotif/dist/style.scss";// old node version

Container Styles

• is-left-top: position container to left top.
• is-right-top: position container to right top.
• is-center-top: position container to center top.
• is-left-bottom: position container to left bottom.
• is-right-bottom: position container to right bottom.
• is-center-bottom: position container to center bottom.
• is-sub: add this class to container when use container inside some part of ui (for non-fullscreen containers).

Note: Parent node of sub containers must have position: relative; style!

Notification Styles

Notification by default can contains following parts:

• content: contains notification content (headers, text, etc).
• progress: progress element.

Note: this elements must placed directly as child.

<div class="v-notification">
  <div class="content">
    <h1>{{ header }}</h1>
    <p>{{ content }}</p>
    <div class="gaper is-auto">
      <div class="filler"></div>
      <button class="is-simple">Cancel</button>
      <button class="is-primary">Approve</button>
    </div>
  </div>
  <div class="progress"></div>
</div>

Notification Classes

You could style your custom component by v-notification class.

• is-left-decorated: add left decorated border to notification.
• is-right-decorated: add right decorated border to notification.
• is-loading: add loading ui to notification.
• is-{gap}-gaped: set notification gap (padding and spacing) to registered iterable gaps (Termeh only).
• is-{color}: set notification color scheme to registered iterable colors (Termeh only).

Content Styles

Notification content by default can contains following parts:

• ... or header: notification header.

Customize Styling

You can override following pre-defined component variable to override default notification styling.

@include _var("notification", "width", 30rem);
@include _var("notification", "primary-border", (1px solid _color("primary")));