Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/wheely/ember-dialog
An Ember Addon able you to easily create routable dialog windows
https://github.com/wheely/ember-dialog
ember ember-addon
Last synced: about 2 months ago
JSON representation
An Ember Addon able you to easily create routable dialog windows
- Host: GitHub
- URL: https://github.com/wheely/ember-dialog
- Owner: wheely
- License: mit
- Created: 2014-11-19T13:52:06.000Z (about 10 years ago)
- Default Branch: master
- Last Pushed: 2020-02-03T18:42:24.000Z (almost 5 years ago)
- Last Synced: 2024-10-31T11:41:30.567Z (about 2 months ago)
- Topics: ember, ember-addon
- Language: CSS
- Homepage: http://wheely.github.io/ember-dialog/
- Size: 2.25 MB
- Stars: 37
- Watchers: 16
- Forks: 12
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.md
Awesome Lists containing this project
README
# ember-dialog [](https://github.com/wheely/ember-dialog/blob/master/LICENSE.md) [](https://travis-ci.org/wheely/ember-dialog) [](https://codeclimate.com/github/wheely/ember-dialog) [](https://www.codacy.com/app/ajile/ember-dialog?utm_source=github.com&utm_medium=referral&utm_content=wheely/ember-dialog&utm_campaign=Badge_Grade) [](https://www.codacy.com/app/ajile/ember-dialog?utm_source=github.com&utm_medium=referral&utm_content=wheely/ember-dialog&utm_campaign=Badge_Coverage) [](https://david-dm.org/wheely/ember-dialog) [](https://david-dm.org/wheely/ember-dialog?type=dev)
A lightweight and powerful Ember Addon that allows you to easily create routable dialog windows and control their closing. It consists of a service that is available from any object and a component which is a dialog-window itself.
With ember-dialog you can create any popups like dialogs, modals, notices, bubbles etc. We have decided do not include realization of all this features to the library for minification reasons. Instead of it we have written absolute documentation how you can make it your own (see cookbook and tutorial with examples). You can look the library's code on github and get surprised how much code on aboard to realize all features, presented on this site.
## Installation
Installing the library is as easy as:
```shell
ember install ember-dialog
```
## About
The principle of work is simple. Service is instructed to display a modal window (`show`, `alert`, `confirm` or `blank` methods), creates a component instance with required layout and template, then renders it, and attaches it to the body. At this point, it also creates a Promise, "handles" of which puts into the component and returns it. The component has 2 actions on aboard: one for `resolved` closing, another one for `rejected` closing. Actions available within the template and can be called, for instance by clicking on the button (in the layout or in the template). When you call an action, one of the Promise's method is executed and triggered independent "accepted" or "declined" event. The dialog service when gets the event destroys component object and detaches it from the DOM.
Let's say you want to ask user confirm an action. You should call `show` method of the dialog service with a layout path (you needed dialog window with two buttons - `confirm` layout what you need) and a path to template that you want to show the user in the modal window. Method creates and shows dialog window and returns a Promise, that will become resolved or rejected when window closed (it's depend on which button user has clicked).
```javascript
// The `dialog/confirm` - predefined layout template
// The `messages/hello` - template that you'd like to show.
// Notice: this template should be found in your project by path `app/templates/messages/hello`
const layoutName = "dialog/confirm";
const templateName = "messages/hello";
const promise = this.get("dialog").show(layoutName, templateName);
const yes = () => { console.log(`yes pressed`); };
const no = () => { console.log(`no pressed`); };
promise.then(yes, no);
```
For more information and demos, visit the [site](http://wheely.github.io/ember-dialog/).
## Dialog types (predefined layouts)
ember-dialog has next layouts on aboard: `alert`, `confirm` and `blank`.
### Alert
This layout has only 'yes' - button clicking on which the modal window closes as `resolved`. It also has X-button which closes modal window as `resolved`. The `promise` object always resolved on modal closing. May be used for showing an information to the user. See [docs](http://wheely.github.io/ember-dialog/docs/module-ember-dialog_services_dialog.html#-inner-alert__anchor).
### Confirm
In practice, the most widely used layout. It has 2 buttons, which closes dialog window. One of them closes window as `resolved`, another one closes as `rejected`. It also has X-button which closes window as `rejected` (for obvious reasons). See [docs](http://wheely.github.io/ember-dialog/docs/module-ember-dialog_services_dialog.html#-inner-confirm__anchor).
### Blank
The most simple layout. It has nothing on aboard. May be used for creating custom dialog windows with its own logic of showing elements and closing. In practice often used for showing forms, in this cases accept closing carried on submit action. Convenient to use in conjunction with ember-validation (TBD:Usecase). See [docs](http://wheely.github.io/ember-dialog/docs/module-ember-dialog_services_dialog.html#-inner-blank__anchor).
## Styles
Styles were written on sass language, you're able to include them into you project.
Add path to `sassOptions.includePaths` in your `ember-cli-build.js` (example below).
```javascript
var app = new EmberApp(defaults, {
sassOptions: {
includePaths: [ 'node_modules/ember-dialog/addon/styles' ]
}
});
```
Include them in your `app/styles/app.scss`:
```sass
@import "ember-dialog";
```
If you have your own style of the dialog windows you may use just structure styles:
```sass
@import "ember-dialog/structure";
```
## Usage
### Showing user a simple message from controller
```javascript
export default Ember.Controller({
showDialog() {
// Will be used `app/templates/error-message.hbs`
this.get("dialog").alert("error-message");
}
});
```
### Showing user a simple message from template
```hbs
Delete record
```
### Showing user a simple message to confirm action
```javascript
export default Ember.Controller({
showDialog() {
const yes = () => { console.log("Yes"); };
const no = () => { console.log("No"); };
// Will be used `app/templates/messages/are-you-sure.hbs`
this.get("dialog").confirm("messages/are-you-sure").then(yes, no);
}
});
```
### Binding data in the dialog
Controller:
```javascript
export default Ember.Controller({
now: now Date(),
model: { username: "ajile" },
showDialog() {
// Will be used `app/templates/messages/hello.hbs`
this.get("dialog").alert("messages/hello", this);
}
});
```
Template `messages/hello.hbs`:
```hbs
Hello, {{contextObject.model.username}}! Now: {{contextObject.now}}. Click the button to close the dialog.
```
### Interrupt closing of the dialog window
```javascript
export default Ember.Controller({
count: 0,
showDialog() {
// Will be used `app/templates/messages/click-counter.hbs`
this.get("dialog").alert("messages/click-counter", null, {
acceptHandler: "yesHandler"
});
},
actions: {
yesHandler(presenter) {
const count = this.get("count");
if (count < 5) {
console.log("Count less then five");
this.set("count", ++count);
} else {
presenter.accept();
}
}
}
});
```
### Manual closing dialog window
```javascript
export default Ember.Controller({
showDialog() {
// Any created dialog will be closed in 1s
this.get("dialog").on("created", (presenter) => {
Ember.run.later(presenter, presenter.accept, 1000);
});
// Will be used `app/templates/messages/something.hbs`
this.get("dialog").alert("messages/something");
}
});
```
### Creating new layouts
Controller:
```javascript
export default Ember.Controller({
showDialog() {
// Will be used `app/templates/dialog-layouts/delete.hbs` as layout and
// `app/templates/messages/are-you-sure.hbs` as template.
this.get("dialog").show("dialog-layouts/delete", "messages/delete-user");
}
});
```
Template `dialog-layouts/delete.hbs`:
```hbs
Confirm Deletion
{{#if templateName}}
{{partial templateName}}
{{else}}
{{component "dialog-body" layout=template contextObject=contextObject context=context class="dialog-body"}}
{{/if}}
DELETE!
Cancel
```
Template `messages/delete-user.hbs`:
```hbs
Really?
```
The result:
```html
Confirm Deletion
Really?
DELETE!
Cancel
```
### Extend dialog manager
Execute `ember g service dialog`.
File `app/services/dialog.js`:
```javascript
import Dialog from "ember-dialog/services/dialog";
export default Dialog.extend({
confirmDelete() {
const args = Array.prototype.slice.apply(arguments);
args.unshift("dialog-layouts/delete");
this.show(...args);
}
});
```
## Contributing
The library is under constant develoment. We stick to concept of Ember releases - every 6 monthes we release new version. We do so to sync with new Ember features.
If you find something lacking in the library functions - add issue on github, we shall process it. We are open to any cooperation. Feel free to send us Pull Requests.
Also you may send all incoming issues to [slack](https://ember-dialog.slack.com/).