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

docs($compile): improve documentation on directive $scope usage #9727

Closed
wants to merge 1 commit into from
Closed

docs($compile): improve documentation on directive $scope usage #9727

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 22 additions & 4 deletions src/ng/compile.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -134,11 +134,15 @@
* and other directives used in the directive's template will also be excluded from execution.
*
* #### `scope`
* **If set to `true`,** then a new scope will be created for this directive. If multiple directives on the
* same element request a new scope, only one new scope is created. The new scope rule does not
* apply for the root of the template since the root of the template always gets a new scope.
* Scope property can have one of the following values:
*
* **If set to `{}` (object hash),** then a new "isolate" scope is created. The 'isolate' scope differs from
* * **`false`:** No scope will be created for the directive. The directive will use its parent's scope.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this implies that false is somehow different from any other non-true, non-object value. The only cases that matter are true and object

*
* * **`true`:** A new scope will be created for this directive. If multiple directives on the same element
* request a new scope, only one new scope is created. The new scope rule does not apply
* for the root of the template since the root of the template always gets a new scope.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This was incorrect before --- but it's still incorrect here =) we actually throw (except possibly under a few corner cases, which are bugs)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

https://github.com/angular/angular.js/blob/master/src/ng/compile.js#L1546 for reference

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah I also browsed this part of the angular code, but you're right, my changes didn't really improve the documentation here. I'll rewrite this part so it hopefully becomes more clear then.

*
* * **`{}`(object hash):** Then a new "isolate" scope is created. The 'isolate' scope differs from
* normal scope in that it does not prototypically inherit from the parent scope. This is useful
* when creating reusable components, which should not accidentally read or modify data in the
* parent scope.
Expand Down Expand Up @@ -178,6 +182,20 @@
* For example, if the expression is `increment(amount)` then we can specify the amount value
* by calling the `localFn` as `localFn({amount: 22})`.
*
* In general it's possible to apply more than one directive to one element, but there might be limitations depending on the type of scope required
* by the directives. Following points will help to understand these limitations. For a better understanding only two directives are taken into
* account, but it is also applicable for several directives.
*
* * **no scope** + **no scope** => Two directives which don't require their own scope will use their parent's scope
* * **child scope** + **no scope** => Both directives will share one single child scope
* * **child scope** + **no scope** => Both directives will share one single child scope
* * **isolated scope** + **no scope** => The isolated directive will use it's own created isolated scope. The other directive will use
* its parent's scope
* * **isolated scope** + **child scope** => **Won't work!** Only one scope can be related to one element. Therefore these directives cannot
* be applied to the same element.
* * **isolated scope** + **isolated scope** => **Won't work!** Only one scope can be related to one element. Therefore these directives
* cannot be applied to the same element.
*
*
* #### `bindToController`
* When an isolate scope is used for a component (see above), and `controllerAs` is used, `bindToController: true` will
Expand Down