Plugin Usage #

The plugin for the Gitart Dialog is completely optional. It's only needed if you want adding dialogs by the method addDialog not including the dialog in the template of some component.

Installation #

// main.js
import { plugin as dialogPlugin } from 'gitart-vue-dialog'

const app = Vue.createApp(/* ... */)
app.use(dialogPlugin, {
  // options
})

Plugin options #

closeDelay #

• Type: Number

• Default: 500

• Details:
  It's time in milliseconds after the dialog is closed when the dialogs are removed from the DOM. If you want a long leaving transition, set this value higher.

props #

• Type: Object

• Default: {}

• Details:
  It's default props for all dialogs if you run them by addDialog method.

  app.use(dialogPlugin, {
    props: {
      maxWidth: '300px',
      // ...
    },
  })
  
  // You can override it
  $dialog.addDialog({
    component: InfoDialog,
    props: {
      maxWidth: '500px',
    },
  })
  

  // It works like this
  const defaultProps = options?.props ?? {}
  
  const $dialog = {
    addDialog: ({ component, props, id }, hooks) => {
      const dialogId = id ?? Date.now() + Math.random()
  
      dialogs.push({
        component,
        id: dialogId,
  
        props: reactive({
          modelValue: true,
          ...defaultProps,
          ...props,
        }),
  
        onClose: hooks?.onClose,
      })
  
      return dialogId
    },
  }
  

GDialogRoot #

We strongly recommend using GDialogRoot. It renders your dialogs. Put it somewhere at the end of the App.vue.

Or write your own alternative. Look here how GDialogRoot works

<template >
  <GDialogRoot />
</template>

<script>
import { defineComponent } from 'vue'
import { GDialogRoot } from 'gitart-vue-dialog'

export default defineComponent({
  components: {
    GDialogRoot,
  },
})
</script>

Usage #

There are two ways to access the methods and properties of the plugin (option and composition api). See below:

Option api: #

In any method you have access to this.$dialog.

import { defineComponent } from 'vue'

export default defineComponent({
  methods: {
    someMethod() {
      // this.$dialog
      // $dialog.addDialog()
      // $dialog.removeDialog()
      // $dialog.dialogs
    },
  },
})

Composition api #

Make injection inside you setup function by inject and dialogInjectionKey.

import { inject } from 'vue'
import { dialogInjectionKey } from 'gitart-vue-dialog'

import { defineComponent, inject } from 'vue'
import { dialogInjectionKey } from 'gitart-vue-dialog'

export default defineComponent({
  setup() {
    const $dialog = inject(dialogInjectionKey)
    // $dialog.addDialog()
    // $dialog.removeDialog()
    // $dialog.dialogs
  }
})

To know how all these properties work, look below.

Properties #

$dialog has such properties:

addDialog(data, hooks) #

• Type: Function

• Arguments:

  • {Object} data - {component: DialogComponent, props?: { ... }, id?: string | number }
  • {Object} hooks - { onClose: (event) => void }

• Returns: Number - dialog id

• Details:
  The method adds your extended data argument to dialogs array. The data.component will be rendered in the GDialogRoot with the props you add to data.props

  Optionaly you can add id to the data argument. It's useful if you want to remove the dialog by id.

  const dialogId = $dialog.addDialog({
    component: InfoDialog,
    props: {
      maxWidth: '500px',
    },
    id: 'my-dialog-id',
  })
  
  // ...
  
  $dialog.removeDialog(dialogId)
  

  The hooks argument is an object with the onClose method. It's called when the dialog is closing. It allows you to do something before the dialog is closed or cancel the closing.

  $dialog.addDialog({
    component: InfoDialog,
    props: {
      maxWidth: '500px',
    },
  }, {
    onClose: (event) => {
      event.cancel() // cancel the closing
      event.id // dialog id
      event.item // dialog item from $dialog.dialogs (read more below)
    },
  })
  

  WARNING

  data.props should not contain modelValue. The addDialog overwrites it

  INFO

  To close the dialog (DialogComponent.vue) you need inside emit the event update:modelValue with false inside. Take a look at the example below

removeDialog(id) #

• Type: Function

• Arguments:

  • {Number} id

• Details:
  The method removes item from dialogs by id. Useful if you want to close the dialog programmatically.

  const dialogId = $dialog.addDialog({
    component: InfoDialog,
    props: {
      maxWidth: '500px',
    },
    id: 'my-dialog-id',
  })
  
  // ...
  
  $dialog.removeDialog(dialogId)
  

  With it you can also write your own GDialogRoot

dialogs #

• Type: Array

• Details:
  Array of the IDialogItem. The array can be rendered in any part of your app. We recommend use GDialogRoot for it.

  interface IDialogItem {
    component: ShallowUnwrapRef<Component>
    id: number
    props: {
      modelValue: boolean
      // other props
    }
  
    onClose?: (event: {
      cancel: () => void
      id: number
      item: IDialogItem
    }) => void
  }
  

Example #

import {
  GDialog,
  plugin as dialogPlugin 
} from 'gitart-vue-dialog';
import 'gitart-vue-dialog/dist/style.css';

const app = Vue.createApp(/* ... */)
app.use(dialogPlugin)
app.component('GDialog', GDialog)

First, create your Dialog component to launch it from a method. Let's name it InfoDialog.vue

<GDialog v-model="dialogState" max-width="300">
  <div>
    Info Alert
  </div>

  {{ info }}
</GDialog>

import { defineComponent } from 'vue'

export default defineComponent({
  props: {
    modelValue: {
      type: Boolean,
      default: false,
    },
    info: {
      type: String,
      required: true,
    },
  },

  emits: ['update:modelValue'],

  computed: {
    dialogState: {
      get() {
        return this.modelValue
      },

      set(value) {
        this.$emit('update:modelValue', value)
      },
    },
  },
})

import { computed, defineComponent } from 'vue'

export default defineComponent({
  props: {
    modelValue: {
      type: Boolean,
      default: false,
    },
    info: {
      type: String,
      required: true,
    },
  },

  emits: ['update:modelValue'],

  setup(props, { emit }) {
    const dialogState = computed({
      get() {
        return props.modelValue
      },

      set(value) {
        emit('update:modelValue', value)
      },
    })

    return {
      dialogState,
    }
  },
})

Well. Now let's create a component where we launch InfoDialog. Name it Launcher.vue. There will be only a button in the template

<button @click="onOpen">Open</button>

import { defineComponent } from 'vue';
import InfoDialog from './InfoDialog.vue';

export default defineComponent({
  methods: {
    onOpen() {
      this.$dialog.addDialog({
        component: InfoDialog,
        props: {
          info: 'Some kind of message from outside InfoDialog',
        },
      }, {
        onClose: (event) => {
          console.log('Dialog is closing')
          console.log(event)
          // event.cancel()
        },
      });
    },
  },
});

import { inject, defineComponent } from 'vue';
import { dialogInjectionKey } from 'gitart-vue-dialog';
import InfoDialog from './InfoDialog.vue';

export default defineComponent({
  setup() {
    const $dialog = inject(dialogInjectionKey);

    const onOpen = () => {
      $dialog.addDialog({
        component: InfoDialog,
        props: {
          info: 'Some kind of message from outside InfoDialog',
        },
      }, {
        onClose: (event) => {
          console.log('Dialog is closing')
          console.log(event)
          // event.cancel()
        },
      });
    };

    return {
      onOpen,
    };
  },
});

As you see, you don't need to insert <InfoDialog /> into Launcher.vue. Now, we can even put onOpen method in a separate file and reuse it everywhere. Here is an example with using composable and composition api.