diff --git a/README.md b/README.md new file mode 100644 index 0000000..73e97fe --- /dev/null +++ b/README.md @@ -0,0 +1,36 @@ +# BSDialog5 + +> BSDialog5 is a JavaScript class for improving Bootstrap 5 modals. Add (and remove) modals to a page dynamically and load content. Bootstrap 5 is required. JQuery is supported but no longer required. + +--- + +## Features + +- Add and remove modals into a page (with or without jQuery) +- Load modals from URL with the JavaScript Fetch API +- Support stacking of multiple modals +- Support prompt modals that returns a response +- Support movable modals + +--- + +## Releases & Builds + +See [Releases](/Ray/bsdialog5/releases) + +## Documentation + +See [Usage](wiki/USAGE.md) + +## Acknowledgements + +This software uses a number of dependencies and assets from third-parties. +These developers and artists deserve due credit for their work and for their commitment to sharing their work freely. +Each product is released under their own particular license, for more information please visit their websites. + +- [Bootstrap](https://getbootstrap.com/) +- [jQuery](https://jquery.com/) + +## License + +This project is licensed under the least restrictive terms of its dependencies, viz. MIT License. \ No newline at end of file diff --git a/wiki/USAGE.md b/wiki/USAGE.md new file mode 100644 index 0000000..0d7170f --- /dev/null +++ b/wiki/USAGE.md @@ -0,0 +1,192 @@ +# Usage: v0.2.0.013 + +This is the usage guide for [BSDialog5](/bootstrap-js-bsdialog5), version 0.2.0.013. + +## Show(options) + +Creates a Modal on the page (and loads the body from a URL, if applicable). An existing box will be reused if the ID already exists. + +**Options** + +```javascript +{ + ID: "modalL1", + Title: "Modal Title", + Message: "Hello Momo!", + URL: null, + Size: "md", + Colour: "secondary" +} +``` + +**Parameters** + +| Parameter | Type | Description | +|---|---|---| +| ID | string | A unique identifier for the modal, so you can refer to multiple modals. | +| Title | string | Label at the top of the modal | +| Message | string | Text content of the modal | +| URL | URL/string | URL to load into the modal body. Use `null` if loading isn't needed. | +| Size | string | Size of the modal (`sm`, `md`, `lg`, `xl`). Default is medium (`md`). | +| Colour | CSS/string | CSS style of the close button at the lower-right. Default is "secondary". | + +**Examples** + +```javascript +BSDialog5.Show({ + ID: "modalL1", + Title: "Modal Title", + Message: "Hello Momo!", + URL: null, + Size: "md", + Colour: "secondary" +}); +``` + +## Prompt(options) + +Opens a Prompt modal that returns a value from buttons. The default is "Yes", "No" and "Cancel" buttons. Closing the modal will return an empty string. + +**Options** + +```javascript +{ + Title: "Modal Title", + Message: "Are you sure want to wait for a response?", + Size: "md", + Buttons: [ + { Label: "Yes", Value: "Yes", Colour: "primary" }, + { Label: "No", Value: "No", Colour: "secondary" }, + { Label: "Cancel", Value: "Cancel", Colour: "secondary" } + ] +} +``` + +**Parameters** + +| Parameter | Type | Description | +|---|---|---| +| Title | string | Label at the top of the modal | +| Message | string | Text content of the modal | +| Size | string | Size of the modal (`sm`, `md`, `lg`, `xl`). Default is medium (`md`). | +| Buttons | Array of buttons | An array of buttons with individual labels, return values and button styles. Default is Yes/No/Cancel. | + +**Examples** + +```javascript +let response = await BSDialog5.Prompt({ + Title: "Modal Title", + Message: "Are you sure want to wait for a response?", + Size: "md", + Buttons: [ + { Label: "Yes", Value: "Yes", Colour: "primary" }, + { Label: "No", Value: "No", Colour: "secondary" }, + { Label: "Cancel", Value: "Cancel", Colour: "secondary" } + ] +}); + +alert(response); +``` + +## Update(options) + +Change a modal's title, message body, size and/or footer after it is open. + +**Options** + +```javascript +{ + ID: "modalR1", + Title: "Modal Changed Title", + Body: "Hello momo again!", + BodyURL: null, + Size: "lg", + Footer: null +} +``` + +**Parameters** + +| Parameter | Type | Description | +|---|---|---| +| ID | string | A unique identifier for the modal | +| Title | string | Label at the top of the modal | +| Body | string | Text content of the modal | +| BodyURL | URL/string | URL to load into the modal body. Use `null` if loading isn't needed. | +| Size | string | Size of the modal (`sm`, `md`, `lg`, `xl`). Default is medium (`md`). | +| Footer | string | Content of the modal footer. | + +**Examples** + +```javascript +BSDialog5.Update({ + ID: "modalR1", + Title: "Modal Changed Title", + Body: "Hello momo again!", + BodyURL: null, + Size: "lg", + Footer: null +}); +``` + +## Find(id) + +Find Modal by its identifier. + +**Parameters** + +| Parameter | Type | Description | +|---|---|---| +| id | string | A unique identifier for the modal, so you can refer to multiple modals. | + +**Examples** + +```javascript +BSDialog5.Find("exampleModal1"); +``` + +**Returns** + +| Property | Type | Description | +|---|---|---| +| Title | array of elements | An array of Modal title elements, for the first modal only. | +| Body | array of elements | An array of Modal body elements, for the first modal only. | +| Footer | array of elements | An array of Modal footer elements, for the first modal only. | +| Close | array of elements | An array of *close* elements, for the first modal only. | +| Modal | array of elements | An array of Modal elements | + +```javascript +{ + Title: [], + Body: [], + Footer: [], + Close: [], + Modal: [] +} +``` + +## Close(id) + +Close the Modal by the box identifier. + +**Parameters** + +| Parameter | Type | Description | +|---|---|---| +| id | string | Unique identifier for the modal | + +**Examples** + +```javascript +BSDialog5.Close("exampleModal1"); +``` + +## Clear() + +Close all Modals on the page. + +**Examples** + +```javascript +BSDialog5.Clear(); +```