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

Commit e94b37e

Browse files
petebacondarwinpetebacondarwin
committed
docs(ngTransclude): add better multi-slot translusion docs
1 parent f5ebcba commit e94b37e

File tree

1 file changed

+134
-124
lines changed

1 file changed

+134
-124
lines changed

‎src/ng/directive/ngTransclude.js

+134-124
Original file line numberDiff line numberDiff line change
@@ -11,143 +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-
* For required slots and the default transclusion, existing content will be removed before the transcluded content is inserted.
15-
*
16-
* For optional slots, existing content is left in place, if the slot was not filled.
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.
1718
*
1819
* @element ANY
1920
*
2021
* @param {string} ngTransclude|ngTranscludeSlot the name of the slot to insert at this point. If this is not provided, is empty
2122
* or its value is the same as the name of the attribute then the default slot is used.
2223
*
2324
* @example
24-
* ### Default transclusion
25-
* This example demonstrates simple transclusion.
26-
<example name="simpleTranscludeExample" module="transcludeExample">
27-
<file name="index.html">
28-
<script>
29-
angular.module('transcludeExample', [])
30-
.directive('pane', function(){
31-
return {
32-
restrict: 'E',
33-
transclude: true,
34-
scope: { title:'@' },
35-
template: '<div style="border: 1px solid black;">' +
36-
'<div style="background-color: gray">{{title}}</div>' +
37-
'<ng-transclude></ng-transclude>' +
38-
'</div>'
39-
};
40-
})
41-
.controller('ExampleController', ['$scope', function($scope) {
42-
$scope.title = 'Lorem Ipsum';
43-
$scope.text = 'Neque porro quisquam est qui dolorem ipsum quia dolor...';
44-
}]);
45-
</script>
46-
<div ng-controller="ExampleController">
47-
<input ng-model="title" aria-label="title"> <br/>
48-
<textarea ng-model="text" aria-label="text"></textarea> <br/>
49-
<pane title="{{title}}">{{text}}</pane>
50-
</div>
51-
</file>
52-
<file name="protractor.js" type="protractor">
53-
it('should have transcluded', function() {
54-
var titleElement = element(by.model('title'));
55-
titleElement.clear();
56-
titleElement.sendKeys('TITLE');
57-
var textElement = element(by.model('text'));
58-
textElement.clear();
59-
textElement.sendKeys('TEXT');
60-
expect(element(by.binding('title')).getText()).toEqual('TITLE');
61-
expect(element(by.binding('text')).getText()).toEqual('TEXT');
62-
});
63-
</file>
64-
</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>
6566
*
6667
* @example
67-
* ### Transclude default content
68-
* 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.
6971
*
70-
* <example module="transcludeDefaultContentExample">
71-
<file name="index.html">
72-
<script>
73-
angular.module('transcludeDefaultContentExample', [])
74-
.directive('myButton', function(){
75-
return {
76-
restrict: 'E',
77-
transclude: true,
78-
scope: true,
79-
template: '<button style="cursor: pointer;">' +
80-
'<ng-transclude>' +
81-
'<b style="color: red;">Button1</b>' +
82-
'</ng-transclude>' +
83-
'</button>'
84-
};
85-
});
86-
</script>
87-
<!-- default button content -->
88-
<my-button id="default"></my-button>
89-
<!-- modified button content -->
90-
<my-button id="modified">
91-
<i style="color: green;">Button2</i>
92-
</my-button>
93-
</file>
94-
<file name="protractor.js" type="protractor">
95-
it('should have different transclude element content', function() {
96-
expect(element(by.id('default')).getText()).toBe('Button1');
97-
expect(element(by.id('modified')).getText()).toBe('Button2');
98-
});
99-
</file>
100-
</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>
101103
*
102104
* @example
103105
* ### Multi-slot transclusion
104-
<example name="multiSlotTranscludeExample" module="multiSlotTranscludeExample">
105-
<file name="index.html">
106-
<div ng-controller="ExampleController">
107-
<input ng-model="title" aria-label="title"> <br/>
108-
<textarea ng-model="text" aria-label="text"></textarea> <br/>
109-
<pane>
110-
<pane-title><a ng-href="{{link}}">{{title}}</a></pane-title>
111-
<pane-body><p>{{text}}</p></pane-body>
112-
</pane>
113-
</div>
114-
</file>
115-
<file name="app.js">
116-
angular.module('multiSlotTranscludeExample', [])
117-
.directive('pane', function(){
118-
return {
119-
restrict: 'E',
120-
transclude: {
121-
'paneTitle': '?title',
122-
'paneBody': 'body',
123-
'paneFooter': '?footer'
124-
},
125-
template: '<div style="border: 1px solid black;">' +
126-
'<div ng-transclude="title" style="background-color: gray"></div>' +
127-
'<div ng-transclude="body"></div>' +
128-
'<div ng-transclude="footer" style="background-color: gray">Default Footer</div>' +
129-
'</div>'
130-
};
131-
})
132-
.controller('ExampleController', ['$scope', function($scope) {
133-
$scope.title = 'Lorem Ipsum';
134-
$scope.link = "https://google.com";
135-
$scope.text = 'Neque porro quisquam est qui dolorem ipsum quia dolor...';
136-
}]);
137-
</file>
138-
<file name="protractor.js" type="protractor">
139-
it('should have transcluded the title and the body', function() {
140-
var titleElement = element(by.model('title'));
141-
titleElement.clear();
142-
titleElement.sendKeys('TITLE');
143-
var textElement = element(by.model('text'));
144-
textElement.clear();
145-
textElement.sendKeys('TEXT');
146-
expect(element(by.binding('title')).getText()).toEqual('TITLE');
147-
expect(element(by.binding('text')).getText()).toEqual('TEXT');
148-
});
149-
</file>
150-
</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+
*/
151161
var ngTranscludeMinErr = minErr('ngTransclude');
152162
var ngTranscludeDirective = ngDirective({
153163
restrict: 'EAC',

0 commit comments

Comments
 (0)