Skip to content

Commit

Permalink
docs: Updated main documentation pages.
Browse files Browse the repository at this point in the history
  • Loading branch information
Jenesius committed Mar 2, 2024
1 parent b51b253 commit 3136440
Show file tree
Hide file tree
Showing 11 changed files with 387 additions and 232 deletions.
1 change: 1 addition & 0 deletions docs/guide/getting-started.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,3 +33,4 @@ close modal windows. This library provides a wide range of functions for working
- Return value
- Working with events through the `ModalObject` object
- Integration with `vue-router`
- Availability of `namespace` and the ability to open elements in different spaces.
91 changes: 54 additions & 37 deletions docs/guide/guide-methods.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Methods

This article will be divided into two blocks: methods of closing and
This article will be divided into two blocks: methods of closing and
methods closing modal windows.

## Opening a window
Expand All @@ -12,29 +12,39 @@ considered separately. However, what these methods have in common are
parameters that are passed there:

- **VueComponent** or **String**. First required parameter.
Specifies the component to be rendered. If a string is transmitted
that the component will be taken from the storage. Detailed
information about the storage can be found [here](store.md).
Specifies the component to be rendered. If a string is transmitted
that the component will be taken from the storage. Detailed
information about the storage can be found [here](store.md).
- **props**. The second parameter is optional. Represents a set
parameters that will be passed to the component as `props`.
parameters that will be passed to the component as `props`.
- **options**. Third optional parameter. it can indicate
additional parameters that will affect the behavior of modals
windows Has type `Object` with the following properties:
additional parameters that will affect the behavior of modals
windows Has type `Object` with the following properties:
- **namespace**. Optional parameter of type `string`.
Specifies which `namespace` the modal window will belong to. If
this parameter is not specified, the modal window will be opened in
this parameter is not specified, the modal window will be opened
in
standard container. You can read more about namespace
[here](namespace.md).
- **backgroundClose**. Optional parameter with type `boolean`.
By default, it uses the value specified
in [configuration](config.md). If
value is set to `false`, then closing the modal window by
clicking on
background will not be possible.

## openModal {#open-modal}

The `openModal` method is used to display the component in the container
modal window. Before showing the modal window the method will close everything
The `openModal` method is used to display the component in the
container
modal window. Before showing the modal window the method will close
everything
open windows and, if successful, will open a new one.

### Return value

The method will return a `Promise`, which, if the modal opens successfully,
The method will return a `Promise`, which, if the modal opens
successfully,
windows will return [`ModalObject`](modal-object.md).

```ts
Expand All @@ -48,44 +58,46 @@ openModal(VueComponent, props) // Promise<ModalObject>
```vue
// AnyVueComponent.vue
<template>
<p>{{title}}</p>
<p>{{title}}</p>
</template>
<script>
export default {
props: {
title: String
}
}
export default {
props: {
title: String
}
}
</script>
```

## pushModal {#push-modal}

The `pushModal` method is used to show a modal window, but, in
unlike `openModal`, it does not close previously open modal windows,
but shows the new one on top of the others. In other words, this
method is simply adds a new window to the queue.

```ts
import {pushModal} from "jenesius-vue-modal"

pushModal(VueComponent) // Promise<ModalObject>
```

:::warning
To close only the last opened modal window - use the
To close only the last opened modal window - use the
[popModal](#pop-modal) method.
:::

## promptModal {#prompt-modal}

Sometimes the main purpose of a modal window is to return data.In this
case, the modal window acts as a certain stage of your interface. It
case, the modal window acts as a certain stage of your interface. It
is for such cases that the method was developed
[`promptModal`](#prompt-modal).

Its main difference from the two previous methods is that it does not
return object [`ModalObject`](modal-object.md). Return value -
`Promise`, if successful, will return the result that you decided to
return from your modal window. Essentially the data is modal windows
`Promise`, if successful, will return the result that you decided to
return from your modal window. Essentially the data is modal windows
can be thought of as functions. You conveyed meanings in them, they
returned the result.

Expand All @@ -98,30 +110,33 @@ To return a value from a modal window, use the event
```ts
import ModalCode from "./ModalCode.vue"
import {promptModal} from "jenesius-vue-modal"

const code = await promptModal(ModalCode);
```

```vue
<!--ModalCode.vue-->
<template>
<button @click="handleClick">Click</button>
<button @click="handleClick">Click</button>
</template>
<script>
import {Modal} from "jenesius-vue-modal";
export default {
methods: {
handleClick() {
// This event will close the modal window and return Math.random()
// as a result of Promise
this.$emit(Modal.EVENT_PROMPT, Math.random());
}
}
}
import {Modal} from "jenesius-vue-modal";
export default {
methods: {
handleClick() {
// This event will close the modal window and return Math.random()
// as a result of Promise
this.$emit(Modal.EVENT_PROMPT, Math.random());
}
}
}
</script>
```

If the modal window was closed without `Modal.EVENT_PROMPT` (for example, clicking on the background), then the Promise will be executed with the value `null`.
If the modal window was closed without `Modal.EVENT_PROMPT` (for
example, clicking on the background), then the Promise will be
executed with the value `null`.

:::warning
There is no need to call the modal window's close method when you use
Expand All @@ -132,7 +147,7 @@ mechanism `Modal.EVENT_PROMPT`. The library will do this for you.

To close modal windows, you can use two methods:
[`closeModal`](#close-modal) and [`popModal`](#pop-modal).
These methods accept one optional parameter describing the closing
These methods accept one optional parameter describing the closing
settings modal she. An option represents an object with the following
properties:

Expand All @@ -146,7 +161,7 @@ closeModal();

// Closing the last modal from
// "notification" spaces
popModal({ namespace: "notification" });
popModal({namespace: "notification"});
```

## closeModal {#close-modal}
Expand All @@ -157,15 +172,17 @@ required one space.

```ts
import {closeModal} from "jenesius-vue-modal"

closeModal()
```

## popModal {#pop-modal}

To close **only the last** modal window that was open using
To close **only the last** modal window that was open using
[`pushModal`](#push_modal).

```ts
import {popModal} from "jenesius-vue-modal"

popModal()
```
93 changes: 61 additions & 32 deletions docs/guide/guide-navigation-guards.md
Original file line number Diff line number Diff line change
@@ -1,33 +1,45 @@
# Navigation Guards

## Information
Sometimes it is necessary to catch the closing of a modal and manage
this state. This can be useful to prevent the user from closing the
modal until they have entered input, or to send a request to the server.

If the handler returns **false** or **throws an error** , closing
Sometimes it is necessary to catch the closing of a modal and manage
this state. This can be useful to prevent the user from closing the
modal until they have entered input, or to send a request to the
server.

If the handler returns **false** or **throws an error** , closing
the modal window will be interrupted.

Jenesius Vue Modal provides three ways to catch closures:

## Onclose
The [openModal](/guide/guide-methods#open-modal) and [pushModal](/guide/guide-methods#push-modal)

The [openModal](/guide/guide-methods#open-modal)
and [pushModal](/guide/guide-methods#push-modal)
methods return Promise, which, if successful,
will return the [modalObject](/guide/modal-object) object. In order to catch the closing of
will return the [modalObject](/guide/modal-object) object. In order to
catch the closing of
a modal window, you need to add an event **onclose** to this object:

```ts
import {openModal} from "jenesius-vue-modal";
const modal = await openModal(VueComponent);

const modal = await openModal(VueComponent);
let count = 5;

modal.onclose = () => {
count--;
if (count > 0 ) return false; //The modal window will be closed after five attempts.
count--;
//The modal window will be closed after five attempts.
if (count > 0) return false;
}
```
EXAMPLE
If several modal windows are open, and one of them will have an onclose handler that returns false, you can close only those modal windows that were opened after it.

### Example

If several modal windows are open, and one of them will have an
onclose handler that returns false, you can close only those modal
windows that were opened after it.

```ts
import {pushModal, closeModal} from "jenesius-vue-modal";

Expand All @@ -41,8 +53,12 @@ closeModal(); // close only modal3
```

## In-Component Guards
Finally, the navigation hook can be specified directly in the component using the following options:

Finally, the navigation hook can be specified directly in the
component using the following options:

- beforeModalClose

```ts
const Foo = {
template: "...",
Expand All @@ -51,48 +67,61 @@ const Foo = {
}
}
```

## Composition Api
While you can still use built-in functions, Jenesius Vue Modal provides functions for the Composition API:

While you can still use built-in functions, Jenesius Vue Modal
provides functions for the Composition API:

```ts
import {onBeforeModalClose} from "jenesius-vue-modal"

export default {
setup() {
onBeforeModalClose(() => {
const answer = window.confirm(
"Do you really want to leave? You have unsaved changes!"
)
if (!answer) return false
})
}
setup() {
onBeforeModalClose(() => {
const answer = window.confirm(
"Do you really want to leave? You have unsaved changes!"
)
if (!answer) return false
})
}
}
```

## Async Guards
The navigation hook can be asynchronous. The modal window will be closed only when it finishes its work:

The navigation hook can be asynchronous. The modal window will be
closed only when it finishes its work:

```ts
{
async beforeModalClose(){
await updateData();
}
export default {
async beforeModalClose() {
await updateData();
}
}
```

```ts
const modal = await openModal(Modal);

modal.onclose = () => {
return new Promise(resolve => {
setTimeout(resolve, 1000); // The modal will be closed after one second.
})
return new Promise(resolve => {
setTimeout(resolve, 1000); // The modal will be closed after one second.
})
}
```

## Close event

Each modal close handler get window parameter: event-close

```ts
modal.onclose = (event) => {
// ...
}
```
This *event* stores information about how the modal window is closed. Detailed information about it, about the way to prevent
Closing a modal window by background or by pressing the Esc key can be read [here](/guide/event-close).

This *event* stores information about how the modal window is closed.
Detailed information about it, about the way to prevent
Closing a modal window by background or by pressing the Esc key can be
read [here](/guide/event-close).
Loading

0 comments on commit 3136440

Please sign in to comment.