diff --git a/README.md b/README.md new file mode 100644 index 0000000..b5a8deb --- /dev/null +++ b/README.md @@ -0,0 +1,35 @@ +# BSDialog4 + +> BSDialog4 is a JavaScript helper for improving Bootstrap 4 modals. Add (and remove) modals to a page dynamically and load content with jQuery-AJAX. Bootstrap 4 is required. + +--- + +## Features + +- Add (inject) and remove modals into a page +- Load modal-content or modal-body from URL with jQuery-AJAX +- Stack multiple modals +- Movable modals + +--- + +## Releases & Builds + +See [Releases](/Ray/bsdialog4/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..5a2e7e2 --- /dev/null +++ b/wiki/USAGE.md @@ -0,0 +1,195 @@ +# View Usage + +This is the usage guide for [BSDialog4](/bootstrap-js-bsdialog4), version 0.1.4.031. + +## Show(options) + +Creates the Modal on the page and loads the body from a URL. An existing box will be reused if the ID already exists. + +### 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 body of the modal | +| URL | string | URL to load into the modal body. Use null if loading isn't needed or a text message. | +| Size | string | Size of the modal (sm, md, lg, xl). Default is medium (md). | +| Colour | Bootstrap Colour | Colour of the close button in the bottom-right. Default is "secondary". | +| ShowFooter | bool | Show footer or not. Default is true. | +| EasyClose | bool | Close on click-away. Default is true. | + +```javascript +{ + ID: null, + Title: "", + Message: "", + URL: null, + Size: "md", + Colour: "secondary", + ShowFooter: true, + EasyClose: true +} +``` + +### Examples + +```javascript +BSDialog.Show({ + ID: "modalL1", + Title: "Modal Title", + Message: "Hello Momo!", + URL: null, + Size: "md", + Colour: "secondary" +}); +``` + +## Prompt(options) + +Creates a modal as a prompt. Prompts return a value. + +```javascript +{ + Type: "button", + Title: "", + Message: "", + Size: "md", + EasyClose: true, + Buttons: [ + { Label: "Yes", Value: "Yes", Colour: "primary" }, + { Label: "No", Value: "No", Colour: "secondary" }, + { Label: "Cancel", Value: "Cancel", Colour: "secondary" } + ], + Textbox: { + Label: "", + LabelSize: 4, + Placeholder: "", + Value: "", + BoxSize: 8 + } +} +``` + +### Examples + +```javascript +let response = await BSDialog.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); +``` + +```javascript +let response = await BSDialog.Prompt({ + Type: "textbox", + Title: "Modal Title", + Message: "Are you sure want to wait for a response?", + Size: "md", + Label: "", + Placeholder: "" +}); + +alert(response); +``` + +## Update(options) + +Change the Modal's title, body, footer etc... + +```javascript +{ + ID: null, + Title: null, + Body: null, + BodyURL: null, + Footer: null, + Size: null +} +``` + +## Exists(id) + +Check if modal exists by identifier + +### Parameters + +| Parameter | Type | Description | +|-----------|------|-------------| +| id | string | A unique identifier for the modal, so you can refer to multiple modals. | + +### Returns + +| | Type | Description | +|---|------|-------------| +| | bool | True, if modal exists | + +## 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. | + +### 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: [] +} +``` + +### Examples + +```javascript +BSDialog.Find("exampleModal1"); +``` + +## Close(id) + +Close the Modal by the box identifier. + +### Parameters + +| Parameter | Type | Description | +|-----------|------|-------------| +| id | string | Unique identifier for the modal | + +### Examples + +```javascript +BSDialog.Close("exampleModal1"); +``` + +## Clear() + +Close all Modals on the page. + +### Examples + +```javascript +BSDialog.Clear(); +```