Skip to content
This repository was archived by the owner on Apr 12, 2024. It is now read-only.

Commit a38d298

Browse files
petebacondarwinpetebacondarwin
committed
docs(ngTransclude): add better multi-slot translusion docs
1 parent 711e7fb commit a38d298

File tree

1 file changed

+134
-123
lines changed

1 file changed

+134
-123
lines changed

‎src/ng/directive/ngTransclude.js

Lines changed: 134 additions & 123 deletions
Original file line numberDiff line numberDiff line change
@@ -11,142 +11,153 @@
1111
* You can specify that you want to insert a named transclusion slot, instead of the default slot, by providing the slot name
1212
* as the value of the `ng-transclude` or `ng-transclude-slot` attribute.
1313
*
14-
* Any existing content of this element will be removed before the transcluded content is inserted,
15-
* but only if the transcluded content is not empty.
14+
* If the transcluded content is not empty (i.e. contains one or more DOM nodes, including whitespace text nodes), any existing
15+
* content of this element will be removed before the transcluded content is inserted.
16+
* If the transcluded content is empty, the existing content is left intact. This lets you provide fallback content in the case
17+
* that no transcluded content is provided.
1618
*
1719
* @element ANY
1820
*
1921
* @param {string} ngTransclude|ngTranscludeSlot the name of the slot to insert at this point. If this is not provided, is empty
2022
* or its value is the same as the name of the attribute then the default slot is used.
2123
*
2224
* @example
23-
* ### Default transclusion
24-
* This example demonstrates simple transclusion.
25-
<example name="simpleTranscludeExample" module="transcludeExample">
26-
<file name="index.html">
27-
<script>
28-
angular.module('transcludeExample', [])
29-
.directive('pane', function(){
30-
return {
31-
restrict: 'E',
32-
transclude: true,
33-
scope: { title:'@' },
34-
template: '<div style="border: 1px solid black;">' +
35-
'<div style="background-color: gray">{{title}}</div>' +
36-
'<ng-transclude></ng-transclude>' +
37-
'</div>'
38-
};
39-
})
40-
.controller('ExampleController', ['$scope', function($scope) {
41-
$scope.title = 'Lorem Ipsum';
42-
$scope.text = 'Neque porro quisquam est qui dolorem ipsum quia dolor...';
43-
}]);
44-
</script>
45-
<div ng-controller="ExampleController">
46-
<input ng-model="title" aria-label="title"> <br/>
47-
<textarea ng-model="text" aria-label="text"></textarea> <br/>
48-
<pane title="{{title}}">{{text}}</pane>
49-
</div>
50-
</file>
51-
<file name="protractor.js" type="protractor">
52-
it('should have transcluded', function() {
53-
var titleElement = element(by.model('title'));
54-
titleElement.clear();
55-
titleElement.sendKeys('TITLE');
56-
var textElement = element(by.model('text'));
57-
textElement.clear();
58-
textElement.sendKeys('TEXT');
59-
expect(element(by.binding('title')).getText()).toEqual('TITLE');
60-
expect(element(by.binding('text')).getText()).toEqual('TEXT');
61-
});
62-
</file>
63-
</example>
25+
* ### Basic transclusion
26+
* This example demonstrates basic transclusion of content into a component directive.
27+
* <example name="simpleTranscludeExample" module="transcludeExample">
28+
* <file name="index.html">
29+
* <script>
30+
* angular.module('transcludeExample', [])
31+
* .directive('pane', function(){
32+
* return {
33+
* restrict: 'E',
34+
* transclude: true,
35+
* scope: { title:'@' },
36+
* template: '<div style="border: 1px solid black;">' +
37+
* '<div style="background-color: gray">{{title}}</div>' +
38+
* '<ng-transclude></ng-transclude>' +
39+
* '</div>'
40+
* };
41+
* })
42+
* .controller('ExampleController', ['$scope', function($scope) {
43+
* $scope.title = 'Lorem Ipsum';
44+
* $scope.text = 'Neque porro quisquam est qui dolorem ipsum quia dolor...';
45+
* }]);
46+
* </script>
47+
* <div ng-controller="ExampleController">
48+
* <input ng-model="title" aria-label="title"> <br/>
49+
* <textarea ng-model="text" aria-label="text"></textarea> <br/>
50+
* <pane title="{{title}}">{{text}}</pane>
51+
* </div>
52+
* </file>
53+
* <file name="protractor.js" type="protractor">
54+
* it('should have transcluded', function() {
55+
* var titleElement = element(by.model('title'));
56+
* titleElement.clear();
57+
* titleElement.sendKeys('TITLE');
58+
* var textElement = element(by.model('text'));
59+
* textElement.clear();
60+
* textElement.sendKeys('TEXT');
61+
* expect(element(by.binding('title')).getText()).toEqual('TITLE');
62+
* expect(element(by.binding('text')).getText()).toEqual('TEXT');
63+
* });
64+
* </file>
65+
* </example>
6466
*
6567
* @example
66-
* ### Transclude default content
67-
* This example shows how to use `NgTransclude` with default ng-transclude element content
68+
* ### Transclude fallback content
69+
* This example shows how to use `NgTransclude` with fallback content, that
70+
* is displayed if no transcluded content is provided.
6871
*
69-
* <example module="transcludeDefaultContentExample">
70-
<file name="index.html">
71-
<script>
72-
angular.module('transcludeDefaultContentExample', [])
73-
.directive('myButton', function(){
74-
return {
75-
restrict: 'E',
76-
transclude: true,
77-
scope: true,
78-
template: '<button style="cursor: pointer;">' +
79-
'<ng-transclude>' +
80-
'<b style="color: red;">Button1</b>' +
81-
'</ng-transclude>' +
82-
'</button>'
83-
};
84-
});
85-
</script>
86-
<!-- default button content -->
87-
<my-button id="default"></my-button>
88-
<!-- modified button content -->
89-
<my-button id="modified">
90-
<i style="color: green;">Button2</i>
91-
</my-button>
92-
</file>
93-
<file name="protractor.js" type="protractor">
94-
it('should have different transclude element content', function() {
95-
expect(element(by.id('default')).getText()).toBe('Button1');
96-
expect(element(by.id('modified')).getText()).toBe('Button2');
97-
});
98-
</file>
99-
</example>
72+
* <example module="transcludeFallbackContentExample">
73+
* <file name="index.html">
74+
* <script>
75+
* angular.module('transcludeFallbackContentExample', [])
76+
* .directive('myButton', function(){
77+
* return {
78+
* restrict: 'E',
79+
* transclude: true,
80+
* scope: true,
81+
* template: '<button style="cursor: pointer;">' +
82+
* '<ng-transclude>' +
83+
* '<b style="color: red;">Button1</b>' +
84+
* '</ng-transclude>' +
85+
* '</button>'
86+
* };
87+
* });
88+
* </script>
89+
* <!-- fallback button content -->
90+
* <my-button id="fallback"></my-button>
91+
* <!-- modified button content -->
92+
* <my-button id="modified">
93+
* <i style="color: green;">Button2</i>
94+
* </my-button>
95+
* </file>
96+
* <file name="protractor.js" type="protractor">
97+
* it('should have different transclude element content', function() {
98+
* expect(element(by.id('fallback')).getText()).toBe('Button1');
99+
* expect(element(by.id('modified')).getText()).toBe('Button2');
100+
* });
101+
* </file>
102+
* </example>
100103
*
101104
* @example
102105
* ### Multi-slot transclusion
103-
<example name="multiSlotTranscludeExample" module="multiSlotTranscludeExample">
104-
<file name="index.html">
105-
<div ng-controller="ExampleController">
106-
<input ng-model="title" aria-label="title"> <br/>
107-
<textarea ng-model="text" aria-label="text"></textarea> <br/>
108-
<pane>
109-
<pane-title><a ng-href="{{link}}">{{title}}</a></pane-title>
110-
<pane-body><p>{{text}}</p></pane-body>
111-
</pane>
112-
</div>
113-
</file>
114-
<file name="app.js">
115-
angular.module('multiSlotTranscludeExample', [])
116-
.directive('pane', function(){
117-
return {
118-
restrict: 'E',
119-
transclude: {
120-
'title': '?pane-title',
121-
'body': 'pane-body',
122-
'footer': '?pane-footer'
123-
},
124-
template: '<div style="border: 1px solid black;">' +
125-
'<div ng-transclude="title" style="background-color: gray"></div>' +
126-
'<div ng-transclude="body"></div>' +
127-
'<div ng-transclude="footer" style="background-color: gray">Default Footer</div>' +
128-
'</div>'
129-
};
130-
})
131-
.controller('ExampleController', ['$scope', function($scope) {
132-
$scope.title = 'Lorem Ipsum';
133-
$scope.link = "https://google.com";
134-
$scope.text = 'Neque porro quisquam est qui dolorem ipsum quia dolor...';
135-
}]);
136-
</file>
137-
<file name="protractor.js" type="protractor">
138-
it('should have transcluded the title and the body', function() {
139-
var titleElement = element(by.model('title'));
140-
titleElement.clear();
141-
titleElement.sendKeys('TITLE');
142-
var textElement = element(by.model('text'));
143-
textElement.clear();
144-
textElement.sendKeys('TEXT');
145-
expect(element(by.binding('title')).getText()).toEqual('TITLE');
146-
expect(element(by.binding('text')).getText()).toEqual('TEXT');
147-
});
148-
</file>
149-
</example> */
106+
* This example demonstrates using multi-slot transclusion in a component directive.
107+
* <example name="multiSlotTranscludeExample" module="multiSlotTranscludeExample">
108+
* <file name="index.html">
109+
* <style>
110+
* .title, .footer {
111+
* background-color: gray
112+
* }
113+
* </style>
114+
* <div ng-controller="ExampleController">
115+
* <input ng-model="title" aria-label="title"> <br/>
116+
* <textarea ng-model="text" aria-label="text"></textarea> <br/>
117+
* <pane>
118+
* <pane-title><a ng-href="{{link}}">{{title}}</a></pane-title>
119+
* <pane-body><p>{{text}}</p></pane-body>
120+
* </pane>
121+
* </div>
122+
* </file>
123+
* <file name="app.js">
124+
* angular.module('multiSlotTranscludeExample', [])
125+
* .directive('pane', function(){
126+
* return {
127+
* restrict: 'E',
128+
* transclude: {
129+
* 'title': '?pane-title',
130+
* 'body': 'pane-body',
131+
* 'footer': '?pane-footer'
132+
* },
133+
* template: '<div style="border: 1px solid black;">' +
134+
* '<div class="title" ng-transclude="title">Fallback Title</div>' +
135+
* '<div ng-transclude="body"></div>' +
136+
* '<div class="footer" ng-transclude="footer">Fallback Footer</div>' +
137+
* '</div>'
138+
* };
139+
* })
140+
* .controller('ExampleController', ['$scope', function($scope) {
141+
* $scope.title = 'Lorem Ipsum';
142+
* $scope.link = "https://google.com";
143+
* $scope.text = 'Neque porro quisquam est qui dolorem ipsum quia dolor...';
144+
* }]);
145+
* </file>
146+
* <file name="protractor.js" type="protractor">
147+
* it('should have transcluded the title and the body', function() {
148+
* var titleElement = element(by.model('title'));
149+
* titleElement.clear();
150+
* titleElement.sendKeys('TITLE');
151+
* var textElement = element(by.model('text'));
152+
* textElement.clear();
153+
* textElement.sendKeys('TEXT');
154+
* expect(element(by.css('.title')).getText()).toEqual('TITLE');
155+
* expect(element(by.binding('text')).getText()).toEqual('TEXT');
156+
* expect(element(by.css('.footer')).getText()).toEqual('Fallback Footer');
157+
* });
158+
* </file>
159+
* </example>
160+
*/
150161
var ngTranscludeMinErr = minErr('ngTransclude');
151162
var ngTranscludeDirective = ngDirective({
152163
restrict: 'EAC',

0 commit comments

Comments
 (0)