docs(ngAnimate): add `animating any scope's variable change` section #16582

FRSgit · 2018-05-27T23:49:47Z

Add a section which covers use case when user's need to animate upon every variable's value change.

What kind of change does this PR introduce? (Bug fix, feature, docs update, ...)
Added new section to ngAnimate's module page.

What is the current behavior? (You can also link to an open issue here)
That's an effect of discussion which took place under #16561

What is the new behavior (if this is a feature change)?
No, just docs.

Does this PR introduce a breaking change?
No.

Please check if the PR fulfills these requirements

The commit message follows our guidelines
Fix/Feature: Docs have been added/updated
Fix/Feature: Tests have been added; existing tests pass

Other information:

gkalpak · 2018-05-28T07:39:45Z

src/ngAnimate/module.js

 * ```
 *
+ * ### Animating any scope's variable change


I think this title isn't very clear. It makes it sound as if emphasis is put on any scope.
AFAICT, what you are trying to say is "animating between arbitrary values" (i.e. not between two states but between any number of (unknown) states; similar to Angular's * => * (from any state to any state)).

_{Not sure what's a good heading though 😳}

Maybe something like:

Animating on any value change of a directive,

Animating between subsequent value changes,

or as you've written it Animating between arbitrary values.

gkalpak · 2018-05-28T07:43:21Z

src/ngAnimate/module.js

 * ```
 *
+ * ### Animating any scope's variable change
+ *
+ * Unless possible with more proper ["animation aware" directive](#directive-support), that specific use case can always be covered with {@link ngAnimate.directive:ngAnimateSwap} as can be seen in {@link ngAnimate.directive:ngAnimateSwap#examples this example}.


I would expand here on what type of usecase ngAnimateSwap helps support. I.e. that you can animate between multiple (>2) different states (variable values), whose values don't need to be known or referenced in the CSS styles.

BTW, it is better for readability and "review-ability" if lines are wrapped at 100 chars.

Added it in newest commits.

gkalpak

Getting there 😃

gkalpak · 2018-06-01T07:41:48Z

src/ngAnimate/module.js

 * ```
 *
+ * ### Animating between subsequent value changes
+ *
+ * Sometimes you need to animate between multiple (2 and more), different expression states, whose values


2 and more --> more than 2

Actually it will work also for animating between just 2 states, so IMO it should be 2 or more

Fair enough. Since you can't animate between...one state, let's drop the multiple (2 and more) part.

Sometimes you need to animate between different expression states whose values don't necessary need to be known or referenced in CSS styles.

gkalpak · 2018-06-01T07:49:14Z

src/ngAnimate/module.js

+ * Note that {@link ngAnimate.directive:ngAnimateSwap} is a *structural directive*, which means it
+ * creates a new instance of the element (including any other/child directives it may have) and
+ * links it to a new scope every time *swap* happens. In some cases this might not be desirable
+ * (e.g. for performance reasons, or when wish to retain internal state on the original


when wish --> when you wish

gkalpak · 2018-06-01T07:50:07Z

src/ngAnimate/module.js

+ * creates a new instance of the element (including any other/child directives it may have) and
+ * links it to a new scope every time *swap* happens. In some cases this might not be desirable
+ * (e.g. for performance reasons, or when wish to retain internal state on the original
+ * element's instance).


element's instance --> element instance (maybe?)

It seems my english teacher was too much into adding 's always when you want to write about possession :D

Well, I'm not a native speaker either, so I could be wrong (😱).
But, I don't think it is about possesion here (the instance does not belong to the element).

gkalpak · 2018-06-01T07:52:50Z

src/ngAnimate/module.js

+ *
+ * Sometimes you need to animate between multiple (2 and more), different expression states, whose values
+ * don't necessary need to be known or referenced in CSS styles.
+ * Unless possible with more proper ["animation aware" directive](#directive-support), that specific


I would remove "more proper". (What is "proper" anyway? Plus ngAnimateSwap is no less "proper" than other "animation aware" directives 😁)
So, I would change "with more proper" to "with another".

What I had in mind was that sometimes "other" directive can be non-structural, and because of this is often more preferable, ergo better when it comes to performance 😄 I'll change that.

Some times a structural directive might be what you want (because for example you want to discard internal state 😉). It depends on the usecase. (It is not that structural directives are objectively inferior to non-structural ones.)

gkalpak · 2018-06-01T07:55:14Z

src/ngAnimate/module.js

 * ```
 *
+ * ### Animating between subsequent value changes


Better thatn before, but I think "arbitrary" instead of "subsequent" would be preferable (because you always want to animate "subsequent changes").

If you think so - sorry, I cannot figure out what will be meaning of arbitrary in such case. IT's like 'random'/'undetermined'/'any'?

Yeah, I had this meaning in mind:

Mathematics. undetermined; not assigned a specific value:
an arbitrary constant.

Maybe "unknown"?

Not sure about this. Maybe it should be just Animating between value changes?

Let's go with that. (It has its own issue, e.g. being too generic, but it is better than what we (don't) have now 😃)

Add a section which covers use case when user's need to animate upon every variable's value change. Refers angular#16561

FRSgit · 2018-06-04T21:48:47Z

@gkalpak done!

Add a section which covers use case when users need to animate upon a variable's value changes (not between two states). Refers #16561 Closes #16582

googlebot added cla: yes labels May 27, 2018

gkalpak added type: docs component: ngAnimate labels May 28, 2018

gkalpak added this to the 1.7.x milestone May 28, 2018

gkalpak suggested changes May 28, 2018

View reviewed changes

gkalpak self-assigned this May 28, 2018

FRSgit force-pushed the animate-swap-docs branch from 357b0d2 to 4df3ba0 Compare June 1, 2018 02:23

gkalpak suggested changes Jun 1, 2018

View reviewed changes

FRSgit force-pushed the animate-swap-docs branch from 4df3ba0 to b5644d8 Compare June 4, 2018 21:45

0docs(ngAnimate): add animating between value changes section

41f19c1

Add a section which covers use case when user's need to animate upon every variable's value change. Refers angular#16561

FRSgit force-pushed the animate-swap-docs branch from b5644d8 to 41f19c1 Compare June 4, 2018 21:48

gkalpak closed this in 0ed3643 Jun 5, 2018

gkalpak pushed a commit that referenced this pull request Jun 5, 2018

docs(ngAnimate): add "animating between value changes" section

b011ae9

Add a section which covers use case when users need to animate upon a variable's value changes (not between two states). Refers #16561 Closes #16582

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs(ngAnimate): add `animating any scope's variable change` section #16582

docs(ngAnimate): add `animating any scope's variable change` section #16582

FRSgit commented May 27, 2018

gkalpak May 28, 2018

FRSgit Jun 1, 2018 •

edited

Loading

gkalpak May 28, 2018

FRSgit Jun 1, 2018

gkalpak left a comment

gkalpak Jun 1, 2018

FRSgit Jun 1, 2018 •

edited

Loading

gkalpak Jun 2, 2018

FRSgit Jun 2, 2018

gkalpak Jun 1, 2018

FRSgit Jun 1, 2018

gkalpak Jun 1, 2018

FRSgit Jun 1, 2018

gkalpak Jun 2, 2018

gkalpak Jun 1, 2018

FRSgit Jun 1, 2018

gkalpak Jun 2, 2018

FRSgit Jun 2, 2018

gkalpak Jun 1, 2018

FRSgit Jun 1, 2018

gkalpak Jun 2, 2018

FRSgit Jun 2, 2018

gkalpak Jun 4, 2018

FRSgit commented Jun 4, 2018

docs(ngAnimate): add animating any scope's variable change section #16582

docs(ngAnimate): add animating any scope's variable change section #16582

Conversation

FRSgit commented May 27, 2018

Choose a reason for hiding this comment

FRSgit Jun 1, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

gkalpak left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

FRSgit Jun 1, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

FRSgit commented Jun 4, 2018

docs(ngAnimate): add `animating any scope's variable change` section #16582

docs(ngAnimate): add `animating any scope's variable change` section #16582

FRSgit Jun 1, 2018 •

edited

Loading

FRSgit Jun 1, 2018 •

edited

Loading