docs(guide/decorators): add decorator guide #14372

sjbarker · 2016-04-05T01:19:13Z

What kind of change does this PR introduce? (Bug fix, feature, docs update, ...)

Docs update.

What is the current behavior? (You can also link to an open issue here)

There currently is no guide for decorators.

What is the new behavior (if this is a feature change)?

Add a guide document for decorators

Does this PR introduce a breaking change?

No.

Please check if the PR fulfills these requirements

The commit message follows our guidelines: https://github.com/angular/angular.js/blob/master/CONTRIBUTING.md#commit-message-format
Tests for the changes have been added (for bug fixes / features)
Docs have been added / updated (for bug fixes / features)

Other information:

explain decorators and how they are implemented in angular
explain how different types of services can be selected
explain $delegate objects and how they differ between services
warn of the risks/caveats of $delegate modification
note the exposure of decorator through the module api
show an example of decorating a core service
show an example of decorating a core directive
show an example of decorating a core filter

closes #12163

sjbarker · 2016-04-06T16:33:20Z

Just a note: There could possibly be a content conflict through untriaged PR #14348. If merged first, 14348 could resolve the order of operations caveat with module.decorator and the relevant content (see diff L71:117-L84) should be removed prior to merging this PR. Otherwise, 14348 will need to include a change to the Decorator Guide or it will need to be handled in a subsequent PR.

gkalpak · 2016-04-11T07:27:42Z

docs/content/guide/decorators.ngdoc

+
+Decorators are used to facilitate a decorator design pattern. This pattern is used to separate modification or
+*decoration* of a class without modifying the original source code. In Angular, decorators are functions that allow a
+service to be modified after their instantiation.


It's not about services. Filters and directives can be decorated as well.

Not after their instantiation. Did you mean after their declaration/registration/definition or something ?

OK, for services, you first have to instantiate them in order to decorate them, but the current phrasing might give the impression that a service could be instantiated and used in its original form and later be decorated.

@gkalpak Thanks, I will get this reworded.

gkalpak · 2016-04-11T07:55:59Z

I left a few comments. Additonally, I think it should be mentioned that one can:

Monkey-patch $delegate.
Augment $delegate with extra stuff.
Overwrite $delegate altogether and provide their own implementation.

(Currently only (1) is shown.)

sjbarker · 2016-04-11T14:13:55Z

Thanks for taking a look @gkalpak. I am making adjustments as we speak. In regards to your should-be-mentioned list, how do you define monkey-patching? I am only asking because I experience different definitions in the community. I assume you mean to replace a property/method on the $delegate without replacing the entire $delegate.

All of that being said: I am going to make some changes noting different approaches you have mentioned above as well as changes in response to your comments. I will wait to push them, until you have had time to respond where needed so I don't overwrite the diff. Thanks, again.

Narretz · 2016-04-18T08:51:56Z

@sjbarker When you have made the changes, just push them in an extra commit to the branch. This makes it easier to review. And also write something in this issue, so that we get notified. Thanks!

sjbarker · 2016-04-18T13:00:35Z

@Narretz Okay, will do! I will have it updated here in the next few hours.

sjbarker · 2016-04-21T17:38:58Z

@Narretz Sorry for the delay. I upgraded node and didn't realize there was a known issue with the node-check-modules script. I ended up overwriting the original commit attempting to solve that issue, so I will comment the diff where necessary.

sjbarker · 2016-04-21T17:39:34Z

docs/content/guide/decorators.ngdoc

+
+Decorators are used to facilitate a decorator design pattern. This pattern is used to separate modification or
+*decoration* of a class without modifying the original source code. In Angular, decorators are functions that allow a
+service, directive or filter to be modified prior to its usage.


Reworded to avoid confusion.

sjbarker · 2016-04-25T14:58:24Z

@Narretz @gkalpak Just a ping to let you know this is ready for another look.

Narretz · 2016-04-26T11:14:09Z

docs/content/guide/decorators.ngdoc

+
+## What are decorators?
+
+Decorators are used to facilitate a decorator design pattern. This pattern is used to separate modification or


Maybe "Decorators are a design pattern that is used to separate modification or decoration of a class without modifying the original source code" There's currently a lot of repetition here.

Narretz · 2016-04-26T11:17:57Z

After "What are decorators", there should be a section called "How to use decorators" that says that there are two ways to register decorators in Angular, and both give you access to the so-called $delegate which is the instantiated service before it is passed to the dependant / service that required it. Then there should be $provide.decorator and module.decorator as subheadings of this section.

Narretz · 2016-04-26T11:18:52Z

docs/content/guide/decorators.ngdoc

+following could all be viable solutions:
+
+```js
+// replace the $delegate completely


This and the two other ones (patching, augmenting) should be sub-headings and not comments

Narretz · 2016-04-26T11:24:52Z

Good stuff @sjbarker. Left a few minor comments.

sjbarker · 2016-04-26T12:09:49Z

Thanks @Narretz. I just pushed the updates. I went ahead and squashed the extra commit since it outdated the diff anyways.

sjbarker · 2016-04-26T12:10:42Z

docs/content/guide/decorators.ngdoc

+
+## What are decorators?
+
+Decorators are a design pattern that is used to separate modification or *decoration* of a class without modifying the


Reworded to remove redundancy.

+ explain decorators and how they are implemented in angular + explain how different types of services can be selected + explain `$delegate` objects and how they differ between services + warn of the risks/caveats of `$delegate` modification + note the exposure of `decorator` through the module api + show an example of decorating a core service + show an example of decorating a core directive + show an example of decorating a core filter closes angular#12163

sjbarker · 2016-04-26T13:38:12Z

docs/content/guide/decorators.ngdoc

+following could all be viable solutions:
+
+
+#### Completely Replace the $delegate


Fixed typo @Narretz

Narretz · 2016-05-06T12:51:34Z

Thanks again @sjbarker !

sjbarker · 2016-05-06T13:40:52Z

Glad to help @Narretz!

+ explain decorators and how they are implemented in angular + explain how different types of services can be selected + explain `$delegate` objects and how they differ between services + warn of the risks/caveats of `$delegate` modification + note the exposure of `decorator` through the module api + show an example of decorating a core service + show an example of decorating a core directive + show an example of decorating a core filter Closes #12163 Closes #14372

Commit 6a2ebdb removes the caveat of declaring a provider prior to decorating it through the module.decorator function. Remove statements warning of the prior requirement for order of operations. See angular#12382, PR angular#14348, and [angular#14372 comment 206452412] (angular#14372 (comment))

googlebot added the cla: yes label Apr 5, 2016

sjbarker force-pushed the decorator-guide branch 3 times, most recently from 31044cc to 013098e Compare April 5, 2016 18:31

Narretz added the type: docs label Apr 5, 2016

Narretz added this to the 1.5.x milestone Apr 5, 2016

Narretz self-assigned this Apr 5, 2016

sjbarker force-pushed the decorator-guide branch from 013098e to a91b4eb Compare April 6, 2016 13:07

Narretz added type: docs and removed type: docs labels Apr 7, 2016

gkalpak reviewed Apr 11, 2016
View reviewed changes

sjbarker force-pushed the decorator-guide branch from a91b4eb to 551eb17 Compare April 21, 2016 16:07

sjbarker reviewed Apr 21, 2016
View reviewed changes

Narretz reviewed Apr 26, 2016
View reviewed changes

sjbarker force-pushed the decorator-guide branch 2 times, most recently from f6fedb7 to ea0ebcf Compare April 26, 2016 12:08

sjbarker reviewed Apr 26, 2016
View reviewed changes

sjbarker force-pushed the decorator-guide branch from ea0ebcf to 429b890 Compare April 26, 2016 13:36

sjbarker reviewed Apr 26, 2016
View reviewed changes

Narretz merged commit 938bd45 into angular:master May 6, 2016

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs(guide/decorators): add decorator guide #14372

docs(guide/decorators): add decorator guide #14372

sjbarker commented Apr 5, 2016

sjbarker commented Apr 6, 2016

gkalpak Apr 11, 2016

gkalpak Apr 11, 2016

sjbarker Apr 11, 2016

gkalpak commented Apr 11, 2016

sjbarker commented Apr 11, 2016

Narretz commented Apr 18, 2016

sjbarker commented Apr 18, 2016

sjbarker commented Apr 21, 2016

sjbarker Apr 21, 2016

sjbarker commented Apr 25, 2016

Narretz Apr 26, 2016

Narretz commented Apr 26, 2016

Narretz Apr 26, 2016

Narretz commented Apr 26, 2016

sjbarker commented Apr 26, 2016

sjbarker Apr 26, 2016

sjbarker Apr 26, 2016

Narretz commented May 6, 2016

sjbarker commented May 6, 2016


		## What are decorators?

		Decorators are used to facilitate a decorator design pattern. This pattern is used to separate modification or


		## What are decorators?

		Decorators are a design pattern that is used to separate modification or decoration of a class without modifying the

		following could all be viable solutions:


		#### Completely Replace the $delegate

docs(guide/decorators): add decorator guide #14372

docs(guide/decorators): add decorator guide #14372

Conversation

sjbarker commented Apr 5, 2016

sjbarker commented Apr 6, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

gkalpak commented Apr 11, 2016

sjbarker commented Apr 11, 2016

Narretz commented Apr 18, 2016

sjbarker commented Apr 18, 2016

sjbarker commented Apr 21, 2016

Choose a reason for hiding this comment

sjbarker commented Apr 25, 2016

Choose a reason for hiding this comment

Narretz commented Apr 26, 2016

Choose a reason for hiding this comment

Narretz commented Apr 26, 2016

sjbarker commented Apr 26, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Narretz commented May 6, 2016

sjbarker commented May 6, 2016