vue-alerts

0.2.0 • Public • Published

Vue-Alerts

npm version

Vue-Alerts is a Vue 2.x plugin that delivers UIViewController-like alerts with customisable alert actions and more. Check out the demo here.

Installing Vue-Alerts

Vue-Alert is published on npm. You can add it to your project via:

yarn

yarn add vue-alerts

npm

npm install vue-alerts

Using Vue-Alerts

To use Vue-Alerts, you'll need to import the plugin.

In main.js, or the JavaScript where initialised Vue, add:

import Vue from 'vue' // Should have already been imported in the file.
import vueAlerts from "vue-alerts"

Then, register the plugin with Vue:

Vue.use(vueAlerts, options)

Once that's done, specify a root Vue Model for the alerts. Please note that you may only register one root VM per application so we would recommend that to be the root VM of your app, i.e. in App.vue:

<div id="app">

  <!-- BEGIN INSERT -->
  <alert></alert>
  <!-- END INSERT -->

  <router-view></router-view>
  
</div>

You're all set! Now you can refer to the module through:

this.$alert

in any VM.

Presenting an alert with async present()

Parameters

# Parameter Type Required Default
0 title String Yes
1 message String Yes
2 actions Array[Object] No An OK button that dismissess the alert
3 < Multiple > Object No {}

Additional Parameters

Those configurations can be passed into the function via #3. They're essentially named keyword arguments.

You typically don't need to worry about those additionally configurations.

Name Type Required Default Description
defaultAction Integer No null The index of action when enter is pressed. If null, then it will become the first action with type cancel. See below.
defaultEscapeAction Integer No null The index of action when escape is pressed. If null, then it will become the first action with type cancel. See below.
preventKeyboard Boolean No true Whether we would prevent the keyboard from interaction with the elements on the page
allowMultipleClicks Boolean No false Allows the user to click an option (or multiple options) multiple times before it's handled.
immediately Boolean No false Whether the alert should be presented immediately. If false, the alert will be placed in a presentation queue.

Resolution

present() will never reject. It resolves after the alert is presented, as it moves to the front of the presentation queue.

When it resolves, it will yield an integer alert identifier. With the identifier, you can:

  • Access the alert info
this.$alert.alerts[identifier]

It's read-only

  • Dismiss the alert.

Documented below. Check out dismiss()

Example

this.$alert.present("Vue-Alerts Message", "Helloworld!", [
  {
    title: "OK",
    type: "cancel",
  }
], {
  preventKeyboard: false
})

For more examples, check out the demo

Defining the Actions

The actions parameter is an array of objects that defines the type of action and its handler.

General Structure

actions = [
  { action },
  { action },
  ...
]

The Action Object

For each action object, you can define the following properties:

Name Type Required Default Description
title String Yes The name of the action (button)
type String Yes This can be one of: cancel, normal or destructive
handler Function Depends For action with type cancel, the handler will never be called. For all other types, a handler will be required. More explained later.

Handling Action Calls

When a user clicks on an action, the handler will be called with the following parameters:

# Type Description
0 Integer The identifier of the alert
1 Integer The index of the action, as defined in actions.

The handler can be either async or sync. In either case, the handler should return a boolean value indicating whether the alert should be automatically dismissed.

Example

async function handler(){
  let response = await SomeAPIRequest()
  if(response.status === true) {
    console.log("Success")
    // return true is not neccessary here. It dismissess by default.
  } else {
    this.$alert.present("Request Failed", response.message)
    return false // Stops the current alert from dismissing
  }
}

this.$alert.present("Get API?", "Are you sure?", [
  {
    title: "Yes",
    type: "normal",
    handler: handler
  },
  {
    title: "No",
    type: "cancel",
  }
])

Dismissing an alert programatically with async dismiss()

Note that, by default, the alert will dismiss after an action is clicked and the handler does not return false. You would not need to call dismiss() manually.

However, if for some reasons you want to dismiss the alert programmatically, you can do so by calling dismiss()

Parameters

# Parameter Type Required Default
0 identifier integer No The last alert
1 < Multiple > Object No {}

Additional Parameters

Name Type Required Default Description
immediately Boolean No false Whether the alert should be presented immediately. If false, the dismissal will be placed in a queue.

Resolution

present() will never reject. It resolves after the alert is dismissed with a boolean value indicating whether or not the alert was dismissed.

Demo

Check out the demo here:

License

Vue-Alerts is licensed under the Apache License 2.0 .

Copyright @yyjlincoln

Readme

Keywords

Package Sidebar

Install

npm i vue-alerts

Weekly Downloads

1

Version

0.2.0

License

Apache-2.0

Unpacked Size

35.2 kB

Total Files

5

Last publish

Collaborators

  • yyjlincoln