invisi/angular.js
1
0
Fork 0
Code Issues Pull Requests Actions Packages Releases Wiki Activity

docs(ngShow/ngHide): improve docs and fix inconsistencies between ngShow/ngHide

Browse Source 
Closes #15471
This commit is contained in:
Georgios Kalpakas
2016-12-06 13:35:32 +02:00
parent 4082fb03b6
commit 5294d208ae
1 changed files with 224 additions and 159 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/ng/directive/ngShowHide.js
+224 -159
View File
@@ -8,11 +8,13 @@ var NG_HIDE_IN_PROGRESS_CLASS = 'ng-hide-animate';
* @multiElement
*
* @description
* The `ngShow` directive shows or hides the given HTML element based on the expression
* provided to the `ngShow` attribute. The element is shown or hidden by removing or adding
* the `.ng-hide` CSS class onto the element. The `.ng-hide` CSS class is predefined
* in AngularJS and sets the display style to none (using an !important flag).
* For CSP mode please add `angular-csp.css` to your html file (see {@link ng.directive:ngCsp ngCsp}).
* The `ngShow` directive shows or hides the given HTML element based on the expression provided to
* the `ngShow` attribute.
*
* The element is shown or hidden by removing or adding the `.ng-hide` CSS class onto the element.
* The `.ng-hide` CSS class is predefined in AngularJS and sets the display style to none (using an
* `!important` flag). For CSP mode please add `angular-csp.css` to your HTML file (see
* {@link ng.directive:ngCsp ngCsp}).
*
* ```html
* <!-- when $scope.myValue is truthy (element is visible) -->
@@ -22,31 +24,32 @@ var NG_HIDE_IN_PROGRESS_CLASS = 'ng-hide-animate';
* <div ng-show="myValue" class="ng-hide"></div>
* ```
*
* When the `ngShow` expression evaluates to a falsy value then the `.ng-hide` CSS class is added to the class
* attribute on the element causing it to become hidden. When truthy, the `.ng-hide` CSS class is removed
* from the element causing the element not to appear hidden.
* When the `ngShow` expression evaluates to a falsy value then the `.ng-hide` CSS class is added
* to the class attribute on the element causing it to become hidden. When truthy, the `.ng-hide`
* CSS class is removed from the element causing the element not to appear hidden.
*
* ## Why is !important used?
* ## Why is `!important` used?
*
* You may be wondering why !important is used for the `.ng-hide` CSS class. This is because the `.ng-hide` selector
* can be easily overridden by heavier selectors. For example, something as simple
* as changing the display style on a HTML list item would make hidden elements appear visible.
* This also becomes a bigger issue when dealing with CSS frameworks.
* You may be wondering why `!important` is used for the `.ng-hide` CSS class. This is because the
* `.ng-hide` selector can be easily overridden by heavier selectors. For example, something as
* simple as changing the display style on a HTML list item would make hidden elements appear
* visible. This also becomes a bigger issue when dealing with CSS frameworks.
*
* By using !important, the show and hide behavior will work as expected despite any clash between CSS selector
* specificity (when !important isn't used with any conflicting styles). If a developer chooses to override the
* styling to change how to hide an element then it is just a matter of using !important in their own CSS code.
* By using `!important`, the show and hide behavior will work as expected despite any clash between
* CSS selector specificity (when `!important` isn't used with any conflicting styles). If a
* developer chooses to override the styling to change how to hide an element then it is just a
* matter of using `!important` in their own CSS code.
*
* ### Overriding `.ng-hide`
*
* By default, the `.ng-hide` class will style the element with `display: none!important`. If you wish to change
* the hide behavior with ngShow/ngHide then this can be achieved by restating the styles for the `.ng-hide`
* class CSS. Note that the selector that needs to be used is actually `.ng-hide:not(.ng-hide-animate)` to cope
* with extra animation classes that can be added.
* By default, the `.ng-hide` class will style the element with `display: none !important`. If you
* wish to change the hide behavior with `ngShow`/`ngHide`, you can simply overwrite the styles for
* the `.ng-hide` CSS class. Note that the selector that needs to be used is actually
* `.ng-hide:not(.ng-hide-animate)` to cope with extra animation classes that can be added.
*
* ```css
* .ng-hide:not(.ng-hide-animate) {
* /&#42; this is just another form of hiding an element &#42;/
* /&#42; These are just alternative ways of hiding an element &#42;/
* display: block!important;
* position: absolute;
* top: -9999px;
@@ -54,29 +57,20 @@ var NG_HIDE_IN_PROGRESS_CLASS = 'ng-hide-animate';
* }
* ```
*
* By default you don't need to override in CSS anything and the animations will work around the display style.
* By default you don't need to override anything in CSS and the animations will work around the
* display style.
*
* ## A note about animations with `ngShow`
*
* Animations in ngShow/ngHide work with the show and hide events that are triggered when the directive expression
* is true and false. This system works like the animation system present with ngClass except that
* you must also include the !important flag to override the display property
* so that you can perform an animation when the element is hidden during the time of the animation.
* Animations in `ngShow`/`ngHide` work with the show and hide events that are triggered when the
* directive expression is true and false. This system works like the animation system present with
* `ngClass` except that you must also include the `!important` flag to override the display
* property so that the elements are not actually hidden during the animation.
*
* ```css
* //
* //a working example can be found at the bottom of this page
* //
* /&#42; A working example can be found at the bottom of this page. &#42;/
* .my-element.ng-hide-add, .my-element.ng-hide-remove {
* /&#42; this is required as of 1.3x to properly
* apply all styling in a show/hide animation &#42;/
* transition: 0s linear all;
* }
*
* .my-element.ng-hide-add-active,
* .my-element.ng-hide-remove-active {
* /&#42; the transition is defined in the active class &#42;/
* transition: 1s linear all;
* transition: all 0.5s linear;
* }
*
* .my-element.ng-hide-add { ... }
@@ -85,76 +79,108 @@ var NG_HIDE_IN_PROGRESS_CLASS = 'ng-hide-animate';
* .my-element.ng-hide-remove.ng-hide-remove-active { ... }
* ```
*
* Keep in mind that, as of AngularJS version 1.3, there is no need to change the display
* property to block during animation states--ngAnimate will handle the style toggling automatically for you.
* Keep in mind that, as of AngularJS version 1.3, there is no need to change the display property
* to block during animation states - ngAnimate will automatically handle the style toggling for you.
*
* @animations
* | Animation | Occurs |
* |----------------------------------|-------------------------------------|
* | {@link $animate#addClass addClass} `.ng-hide` | after the `ngShow` expression evaluates to a non truthy value and just before the contents are set to hidden |
* | {@link $animate#removeClass removeClass} `.ng-hide` | after the `ngShow` expression evaluates to a truthy value and just before contents are set to visible |
* | Animation | Occurs |
* |-----------------------------------------------------|---------------------------------------------------------------------------------------------------------------|
* | {@link $animate#addClass addClass} `.ng-hide` | After the `ngShow` expression evaluates to a non truthy value and just before the contents are set to hidden. |
* | {@link $animate#removeClass removeClass} `.ng-hide` | After the `ngShow` expression evaluates to a truthy value and just before contents are set to visible. |
*
* @element ANY
* @param {expression} ngShow If the {@link guide/expression expression} is truthy
* then the element is shown or hidden respectively.
* @param {expression} ngShow If the {@link guide/expression expression} is truthy/falsy then the
* element is shown/hidden respectively.
*
* @example
<example module="ngAnimate" deps="angular-animate.js" animations="true" name="ng-show">
* A simple example, animating the element's opacity:
*
<example module="ngAnimate" deps="angular-animate.js" animations="true" name="ng-show-simple">
<file name="index.html">
Click me: <input type="checkbox" ng-model="checked" aria-label="Toggle ngHide"><br/>
<div>
Show:
<div class="check-element animate-show" ng-show="checked">
<span class="glyphicon glyphicon-thumbs-up"></span> I show up when your checkbox is checked.
</div>
Show: <input type="checkbox" ng-model="checked" aria-label="Toggle ngShow"><br />
<div class="check-element animate-show-hide" ng-show="checked">
I show up when your checkbox is checked.
</div>
<div>
Hide:
<div class="check-element animate-show" ng-hide="checked">
<span class="glyphicon glyphicon-thumbs-down"></span> I hide when your checkbox is checked.
</div>
</div>
</file>
<file name="glyphicons.css">
@import url(../../components/bootstrap-3.1.1/css/bootstrap.css);
</file>
<file name="animations.css">
.animate-show {
line-height: 20px;
opacity: 1;
padding: 10px;
border: 1px solid black;
background: white;
.animate-show-hide.ng-hide {
opacity: 0;
}
.animate-show.ng-hide-add, .animate-show.ng-hide-remove {
.animate-show-hide.ng-hide-add,
.animate-show-hide.ng-hide-remove {
transition: all linear 0.5s;
}
.animate-show.ng-hide {
line-height: 0;
opacity: 0;
padding: 0 10px;
}
.check-element {
padding: 10px;
border: 1px solid black;
background: white;
opacity: 1;
padding: 10px;
}
</file>
<file name="protractor.js" type="protractor">
var thumbsUp = element(by.css('span.glyphicon-thumbs-up'));
var thumbsDown = element(by.css('span.glyphicon-thumbs-down'));
it('should check ngShow', function() {
var checkbox = element(by.model('checked'));
var checkElem = element(by.css('.check-element'));
it('should check ng-show / ng-hide', function() {
expect(thumbsUp.isDisplayed()).toBeFalsy();
expect(thumbsDown.isDisplayed()).toBeTruthy();
expect(checkElem.isDisplayed()).toBe(false);
checkbox.click();
expect(checkElem.isDisplayed()).toBe(true);
});
</file>
</example>
*
* <hr />
* @example
* A more complex example, featuring different show/hide animations:
*
<example module="ngAnimate" deps="angular-animate.js" animations="true" name="ng-show-complex">
<file name="index.html">
Show: <input type="checkbox" ng-model="checked" aria-label="Toggle ngShow"><br />
<div class="check-element funky-show-hide" ng-show="checked">
I show up when your checkbox is checked.
</div>
</file>
<file name="animations.css">
body {
overflow: hidden;
perspective: 1000px;
}
element(by.model('checked')).click();
.funky-show-hide.ng-hide-add {
transform: rotateZ(0);
transform-origin: right;
transition: all 0.5s ease-in-out;
}
expect(thumbsUp.isDisplayed()).toBeTruthy();
expect(thumbsDown.isDisplayed()).toBeFalsy();
.funky-show-hide.ng-hide-add.ng-hide-add-active {
transform: rotateZ(-135deg);
}
.funky-show-hide.ng-hide-remove {
transform: rotateY(90deg);
transform-origin: left;
transition: all 0.5s ease;
}
.funky-show-hide.ng-hide-remove.ng-hide-remove-active {
transform: rotateY(0);
}
.check-element {
border: 1px solid black;
opacity: 1;
padding: 10px;
}
</file>
<file name="protractor.js" type="protractor">
it('should check ngShow', function() {
var checkbox = element(by.model('checked'));
var checkElem = element(by.css('.check-element'));
expect(checkElem.isDisplayed()).toBe(false);
checkbox.click();
expect(checkElem.isDisplayed()).toBe(true);
});
</file>
</example>
@@ -184,11 +210,13 @@ var ngShowDirective = ['$animate', function($animate) {
* @multiElement
*
* @description
* The `ngHide` directive shows or hides the given HTML element based on the expression
* provided to the `ngHide` attribute. The element is shown or hidden by removing or adding
* the `ng-hide` CSS class onto the element. The `.ng-hide` CSS class is predefined
* in AngularJS and sets the display style to none (using an !important flag).
* For CSP mode please add `angular-csp.css` to your html file (see {@link ng.directive:ngCsp ngCsp}).
* The `ngHide` directive shows or hides the given HTML element based on the expression provided to
* the `ngHide` attribute.
*
* The element is shown or hidden by removing or adding the `.ng-hide` CSS class onto the element.
* The `.ng-hide` CSS class is predefined in AngularJS and sets the display style to none (using an
* `!important` flag). For CSP mode please add `angular-csp.css` to your HTML file (see
* {@link ng.directive:ngCsp ngCsp}).
*
* ```html
* <!-- when $scope.myValue is truthy (element is hidden) -->
@@ -198,30 +226,32 @@ var ngShowDirective = ['$animate', function($animate) {
* <div ng-hide="myValue"></div>
* ```
*
* When the `ngHide` expression evaluates to a truthy value then the `.ng-hide` CSS class is added to the class
* attribute on the element causing it to become hidden. When falsy, the `.ng-hide` CSS class is removed
* from the element causing the element not to appear hidden.
* When the `ngHide` expression evaluates to a truthy value then the `.ng-hide` CSS class is added
* to the class attribute on the element causing it to become hidden. When falsy, the `.ng-hide`
* CSS class is removed from the element causing the element not to appear hidden.
*
* ## Why is !important used?
* ## Why is `!important` used?
*
* You may be wondering why !important is used for the `.ng-hide` CSS class. This is because the `.ng-hide` selector
* can be easily overridden by heavier selectors. For example, something as simple
* as changing the display style on a HTML list item would make hidden elements appear visible.
* This also becomes a bigger issue when dealing with CSS frameworks.
* You may be wondering why `!important` is used for the `.ng-hide` CSS class. This is because the
* `.ng-hide` selector can be easily overridden by heavier selectors. For example, something as
* simple as changing the display style on a HTML list item would make hidden elements appear
* visible. This also becomes a bigger issue when dealing with CSS frameworks.
*
* By using !important, the show and hide behavior will work as expected despite any clash between CSS selector
* specificity (when !important isn't used with any conflicting styles). If a developer chooses to override the
* styling to change how to hide an element then it is just a matter of using !important in their own CSS code.
* By using `!important`, the show and hide behavior will work as expected despite any clash between
* CSS selector specificity (when `!important` isn't used with any conflicting styles). If a
* developer chooses to override the styling to change how to hide an element then it is just a
* matter of using `!important` in their own CSS code.
*
* ### Overriding `.ng-hide`
*
* By default, the `.ng-hide` class will style the element with `display: none!important`. If you wish to change
* the hide behavior with ngShow/ngHide then this can be achieved by restating the styles for the `.ng-hide`
* class in CSS:
* By default, the `.ng-hide` class will style the element with `display: none !important`. If you
* wish to change the hide behavior with `ngShow`/`ngHide`, you can simply overwrite the styles for
* the `.ng-hide` CSS class. Note that the selector that needs to be used is actually
* `.ng-hide:not(.ng-hide-animate)` to cope with extra animation classes that can be added.
*
* ```css
* .ng-hide {
* /&#42; this is just another form of hiding an element &#42;/
* .ng-hide:not(.ng-hide-animate) {
* /&#42; These are just alternative ways of hiding an element &#42;/
* display: block!important;
* position: absolute;
* top: -9999px;
@@ -229,20 +259,20 @@ var ngShowDirective = ['$animate', function($animate) {
* }
* ```
*
* By default you don't need to override in CSS anything and the animations will work around the display style.
* By default you don't need to override in CSS anything and the animations will work around the
* display style.
*
* ## A note about animations with `ngHide`
*
* Animations in ngShow/ngHide work with the show and hide events that are triggered when the directive expression
* is true and false. This system works like the animation system present with ngClass, except that the `.ng-hide`
* CSS class is added and removed for you instead of your own CSS class.
* Animations in `ngShow`/`ngHide` work with the show and hide events that are triggered when the
* directive expression is true and false. This system works like the animation system present with
* `ngClass` except that you must also include the `!important` flag to override the display
* property so that the elements are not actually hidden during the animation.
*
* ```css
* //
* //a working example can be found at the bottom of this page
* //
* /&#42; A working example can be found at the bottom of this page. &#42;/
* .my-element.ng-hide-add, .my-element.ng-hide-remove {
* transition: 0.5s linear all;
* transition: all 0.5s linear;
* }
*
* .my-element.ng-hide-add { ... }
@@ -251,74 +281,109 @@ var ngShowDirective = ['$animate', function($animate) {
* .my-element.ng-hide-remove.ng-hide-remove-active { ... }
* ```
*
* Keep in mind that, as of AngularJS version 1.3, there is no need to change the display
* property to block during animation states--ngAnimate will handle the style toggling automatically for you.
* Keep in mind that, as of AngularJS version 1.3, there is no need to change the display property
* to block during animation states - ngAnimate will automatically handle the style toggling for you.
*
* @animations
* | Animation | Occurs |
* |----------------------------------|-------------------------------------|
* | {@link $animate#addClass addClass} `.ng-hide` | after the `ngHide` expression evaluates to a truthy value and just before the contents are set to hidden |
* | {@link $animate#removeClass removeClass} `.ng-hide` | after the `ngHide` expression evaluates to a non truthy value and just before contents are set to visible |
* | Animation | Occurs |
* |-----------------------------------------------------|------------------------------------------------------------------------------------------------------------|
* | {@link $animate#addClass addClass} `.ng-hide` | After the `ngHide` expression evaluates to a truthy value and just before the contents are set to hidden. |
* | {@link $animate#removeClass removeClass} `.ng-hide` | After the `ngHide` expression evaluates to a non truthy value and just before contents are set to visible. |
*
*
* @element ANY
* @param {expression} ngHide If the {@link guide/expression expression} is truthy then
* the element is shown or hidden respectively.
* @param {expression} ngHide If the {@link guide/expression expression} is truthy/falsy then the
* element is hidden/shown respectively.
*
* @example
<example module="ngAnimate" deps="angular-animate.js" animations="true" name="ng-hide">
* A simple example, animating the element's opacity:
*
<example module="ngAnimate" deps="angular-animate.js" animations="true" name="ng-hide-simple">
<file name="index.html">
Click me: <input type="checkbox" ng-model="checked" aria-label="Toggle ngShow"><br/>
<div>
Show:
<div class="check-element animate-hide" ng-show="checked">
<span class="glyphicon glyphicon-thumbs-up"></span> I show up when your checkbox is checked.
</div>
Hide: <input type="checkbox" ng-model="checked" aria-label="Toggle ngHide"><br />
<div class="check-element animate-show-hide" ng-hide="checked">
I hide when your checkbox is checked.
</div>
<div>
Hide:
<div class="check-element animate-hide" ng-hide="checked">
<span class="glyphicon glyphicon-thumbs-down"></span> I hide when your checkbox is checked.
</div>
</div>
</file>
<file name="glyphicons.css">
@import url(../../components/bootstrap-3.1.1/css/bootstrap.css);
</file>
<file name="animations.css">
.animate-hide {
transition: all linear 0.5s;
line-height: 20px;
opacity: 1;
padding: 10px;
border: 1px solid black;
background: white;
.animate-show-hide.ng-hide {
opacity: 0;
}
.animate-hide.ng-hide {
line-height: 0;
opacity: 0;
padding: 0 10px;
.animate-show-hide.ng-hide-add,
.animate-show-hide.ng-hide-remove {
transition: all linear 0.5s;
}
.check-element {
padding: 10px;
border: 1px solid black;
background: white;
opacity: 1;
padding: 10px;
}
</file>
<file name="protractor.js" type="protractor">
var thumbsUp = element(by.css('span.glyphicon-thumbs-up'));
var thumbsDown = element(by.css('span.glyphicon-thumbs-down'));
it('should check ngHide', function() {
var checkbox = element(by.model('checked'));
var checkElem = element(by.css('.check-element'));
it('should check ng-show / ng-hide', function() {
expect(thumbsUp.isDisplayed()).toBeFalsy();
expect(thumbsDown.isDisplayed()).toBeTruthy();
expect(checkElem.isDisplayed()).toBe(true);
checkbox.click();
expect(checkElem.isDisplayed()).toBe(false);
});
</file>
</example>
*
* <hr />
* @example
* A more complex example, featuring different show/hide animations:
*
<example module="ngAnimate" deps="angular-animate.js" animations="true" name="ng-hide-complex">
<file name="index.html">
Hide: <input type="checkbox" ng-model="checked" aria-label="Toggle ngHide"><br />
<div class="check-element funky-show-hide" ng-hide="checked">
I hide when your checkbox is checked.
</div>
</file>
<file name="animations.css">
body {
overflow: hidden;
perspective: 1000px;
}
element(by.model('checked')).click();
.funky-show-hide.ng-hide-add {
transform: rotateZ(0);
transform-origin: right;
transition: all 0.5s ease-in-out;
}
expect(thumbsUp.isDisplayed()).toBeTruthy();
expect(thumbsDown.isDisplayed()).toBeFalsy();
.funky-show-hide.ng-hide-add.ng-hide-add-active {
transform: rotateZ(-135deg);
}
.funky-show-hide.ng-hide-remove {
transform: rotateY(90deg);
transform-origin: left;
transition: all 0.5s ease;
}
.funky-show-hide.ng-hide-remove.ng-hide-remove-active {
transform: rotateY(0);
}
.check-element {
border: 1px solid black;
opacity: 1;
padding: 10px;
}
</file>
<file name="protractor.js" type="protractor">
it('should check ngHide', function() {
var checkbox = element(by.model('checked'));
var checkElem = element(by.css('.check-element'));
expect(checkElem.isDisplayed()).toBe(true);
checkbox.click();
expect(checkElem.isDisplayed()).toBe(false);
});
</file>
</example>