Skip to content

Commit 2a00ed5

Browse files
edcarrolledcarroll
committed
Added initial modal documentation
1 parent e087322 commit 2a00ed5

File tree

3 files changed

+184
-4
lines changed

3 files changed

+184
-4
lines changed

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -73,6 +73,7 @@ The current list of available components with links to their docs is below:
7373
* [Dimmer](https://edcarroll.github.io/ng2-semantic-ui/#/components/dimmer)
7474
* [Dropdown](https://edcarroll.github.io/ng2-semantic-ui/#/components/dropdown)
7575
* [Message](https://edcarroll.github.io/ng2-semantic-ui/#/components/message)
76+
* [Modal](https://edcarroll.github.io/ng2-semantic-ui/#/components/modal)
7677
* [Popup](https://edcarroll.github.io/ng2-semantic-ui/#/components/popup)
7778
* [Progress](https://edcarroll.github.io/ng2-semantic-ui/#/components/progress)
7879
* [Rating](https://edcarroll.github.io/ng2-semantic-ui/#/components/rating)

‎demo/src/app/pages/modal/modal.page.html‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,92 @@
66
</demo-page-title>
77
<demo-page-content>
88
<h2 class="ui dividing header">Examples</h2>
9+
10+
<p>The modal system in <code>ng2-semantic-ui</code> is designed to be as flexible as possible.</p>
11+
12+
<p>Each modal has two possible outcomes, <code>approve</code> or <code>deny</code>, carrying a distinct result respectively, defined by the user.</p>
13+
14+
<p>Transitions are built in and fully customisable, with timing handled out of the box (i.e. events don't fire until the modal has finished transitioning).</p>
15+
16+
<p>Creating modals can be done in 3 distinct ways, each shown below:</p>
917

18+
<br>
19+
20+
<sui-tabset>
21+
<div class="ui three wide stackable tabs menu">
22+
<a class="item" suiTabHeader="auto">Automatic</a>
23+
<a class="item" suiTabHeader="template">Template Based</a>
24+
<a class="item" suiTabHeader="component">Component Based</a>
25+
</div>
26+
27+
<div class="ui segment" suiTabContent="auto">
28+
<p>This is the most simple form of modal dialog. They're created and used by adding a <code>&lt;sui-modal&gt;</code> element to your component:</p>
29+
30+
<div class="ui segment">
31+
<demo-codeblock language="markup" [src]="autoCode"></demo-codeblock>
32+
</div>
33+
34+
<p>Note the use of <code>#modal</code>, used to access the <code>approve</code> and <code>deny</code> methods.</p>
35+
36+
<p>
37+
Automatic modals are named as such because they open as soon as the component is rendered (i.e. you cannot control when they open).</p>
38+
39+
<p>
40+
Therefore, the specific use case for this modal are routes in which the route opens up a modal dialog. To do this, set the route to be
41+
a component with an automatic modal and it will open immediately. You can then set the router to navigate when the <code>dismissed</code>
42+
event fires, e.g. <code>(dismissed)="router.navigate([...])"</code>.
43+
</p>
44+
</div>
45+
<div class="ui segment" suiTabContent="template">
46+
<p>Template based modals are intended to be used as 'one off' modals, i.e. modals that cannot be easily reused elsewhere.</p>
47+
48+
<p>As with component based modals, they're controlled by the <code>SuiModalService</code> which provides the ability to open a modal on the page.</p>
49+
50+
<p>
51+
To open a template based modal, first you must write a template, using <code>let-context</code> and <code>let-modal="modal"</code> to
52+
access the context and controls respectively.
53+
</p>
54+
55+
<div class="ui segment">
56+
<demo-codeblock language="markup" [src]="templateTemplate"></demo-codeblock>
57+
</div>
58+
59+
<p>Next, get access to your template from your component, and ensure you've loaded the modal service:</p>
60+
61+
<div class="ui segment">
62+
<demo-codeblock language="typescript" [src]="templateComponent"></demo-codeblock>
63+
</div>
64+
65+
<p>The three generic type paramaters of <code>ModalTemplate</code> are:</p>
66+
67+
<div class="ui ordered list">
68+
<div class="item">The type of the modal context (usually just an interface)</div>
69+
<div class="item">The <code>approve</code> result type</div>
70+
<div class="item">The <code>deny</code> result type</div>
71+
</div>
72+
73+
<p>
74+
In this case, the context is an object with a <code>data:string</code> property, and modal
75+
passes <code>string</code> values to both <code>approve</code> and <code>deny.</code>
76+
</p>
77+
78+
<p>Lastly, the modal can be opened as follows:</p>
79+
80+
<div class="ui segment">
81+
<demo-codeblock language="typescript" [src]="templateOpen"></demo-codeblock>
82+
</div>
83+
84+
<p>So, all together:</p>
85+
86+
<modal-example-template></modal-example-template>
87+
88+
</div>
89+
<div class="ui segment" suiTabContent="component">
90+
<p>Component based modals are intended to be used as 'reusable' modals, i.e. modals that can easily be repurposed to fit elsewhere.</p>
91+
92+
<p>As with template based modals, they're controlled by the <code>SuiModalService</code> which provides the ability to open a modal on the page.</p>
93+
</div>
94+
</sui-tabset>
1095

1196
<h2 id="api" class="ui dividing header">API</h2>
1297
<demo-api [api]="api"></demo-api>

‎demo/src/app/pages/modal/modal.page.ts‎

Lines changed: 98 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,30 @@
1-
import {Component} from '@angular/core';
1+
import {Component, ViewChild} from '@angular/core';
22
import {ApiDefinition} from 'app/components/api/api.component';
3+
import {SuiModalService} from '../../../../../components/modal/modal.service';
4+
import {ModalTemplate} from '../../../../../components/modal/modal-template';
5+
import {TemplateModalConfig} from '../../../../../components/modal/modal-config';
6+
7+
const exampleTemplateModalTemplate = `
8+
<ng-template let-context let-modal="modal" #modalTemplate>
9+
<div class="header">Example</div>
10+
<div class="content">
11+
<p>{{ context.data }}</p>
12+
</div>
13+
<div class="actions">
14+
<button class="ui red button" (click)="modal.deny('denied!')">Cancel</button>
15+
<button class="ui green button" (click)="modal.approve('approved!')">OK</button>
16+
</div>
17+
</ng-template>
18+
`;
19+
20+
const exampleTemplateTemplate = `
21+
${exampleTemplateModalTemplate}
22+
23+
<div class="ui fluid action input">
24+
<input type="text" placeholder="Modal content..." [(ngModel)]="dynamicContent">
25+
<button class="ui primary button" (click)="open(dynamicContent)">Open</button>
26+
</div>
27+
`;
328

429
@Component({
530
selector: 'demo-page-modal',
@@ -71,8 +96,77 @@ export class ModalPage {
7196
]
7297
}
7398
];
74-
// public exampleStandardTemplate = exampleStandardTemplate;
75-
// public exampleVariationsTemplate = exampleVariationsTemplate;
99+
public exampleTemplateTemplate = exampleTemplateModalTemplate;
100+
101+
public autoCode = `
102+
<sui-modal [isClosable]="true" (dismissed)="alert($event)" #modal>
103+
<div class="header">Example</div>
104+
<div class="content">
105+
<p>Modal content</p>
106+
</div>
107+
<div class="actions">
108+
<button class="ui red button" (click)="modal.deny()">Cancel</button>
109+
<button class="ui green button" (click)="modal.approve('done')">OK</button>
110+
</div>
111+
</sui-modal>
112+
`;
113+
114+
public templateTemplate = exampleTemplateModalTemplate;
115+
116+
public templateComponent = `
117+
import {SuiModalService, TemplateModalConfig, ModalTemplate} from 'ng2-semantic-ui';
118+
119+
export interface IContext {
120+
data:string;
121+
}
122+
123+
@Component({})
124+
export class MyComponent {
125+
@ViewChild('modalTemplate')
126+
public modalTemplate:ModalTemplate<IContext, string, string>
127+
128+
constructor(public modalService:SuiModalService) {}
129+
}
130+
`;
131+
132+
public templateOpen = `
133+
public open(dynamicContent:string = "Example") {
134+
const config = new TemplateModalConfig<IContext, string, string>(this.modalTemplate);
135+
136+
config.isClosable = false;
137+
config.context = { data: dynamicContent };
138+
139+
this.modalService
140+
.open(config)
141+
.onApprove(result => { /* approve callback */ })
142+
.onDeny(result => { /* deny callback */});
143+
}
144+
`;
145+
}
146+
147+
@Component({
148+
selector: 'modal-example-template',
149+
template: exampleTemplateTemplate
150+
})
151+
export class ModalExampleTemplate {
152+
@ViewChild('modalTemplate')
153+
public modalTemplate:ModalTemplate<{ data:string }, string, string>
154+
155+
public dynamicContent:string = "Example of dynamic content.";
156+
157+
constructor(public modalService:SuiModalService) {}
158+
159+
public open(dynamicContent:string = "Example") {
160+
const config = new TemplateModalConfig<{ data:string }, string, string>(this.modalTemplate);
161+
162+
config.isClosable = false;
163+
config.context = { data: dynamicContent };
164+
165+
this.modalService
166+
.open(config)
167+
.onApprove(r => alert(r))
168+
.onDeny(r => alert(r));
169+
}
76170
}
77171

78-
export const ModalPageComponents = [ModalPage];
172+
export const ModalPageComponents = [ModalPage, ModalExampleTemplate];

0 commit comments

Comments
 (0)