svn commit: r1730003 - /sling/site/trunk/content/documentation/bundles/resource-merger.mdtext

[kw...@apache.org]

Author: kwin
Date: Fri Feb 12 12:02:45 2016
New Revision: 1730003

URL: http://svn.apache.org/viewvc?rev=1730003&view=rev
Log:
document child resource order,  document changes for wildcard behaviour in sling:hideProperties and sling:hideChildren

Modified:
    sling/site/trunk/content/documentation/bundles/resource-merger.mdtext

Modified: sling/site/trunk/content/documentation/bundles/resource-merger.mdtext
URL: http://svn.apache.org/viewvc/sling/site/trunk/content/documentation/bundles/resource-merger.mdtext?rev=1730003&r1=1730002&r2=1730003&view=diff
==============================================================================
--- sling/site/trunk/content/documentation/bundles/resource-merger.mdtext (original)
+++ sling/site/trunk/content/documentation/bundles/resource-merger.mdtext Fri Feb 12 12:02:45 2016
@@ -23,17 +23,39 @@ It is possible to
 
 You may use any of the merge properties described below to influence the merging behaviour. All those special properties are not exposed below the mount point. 
 
-The `CRUDMergingResourceProvider` not only gives read-access to the merged resources but even allows to write. This provider always writes inside the topmost resource path (being returned as last item by the resource picker). Currently both resource pickers shipped with the Sling Resource Merger bundle do not allow to write.
+The `CRUDMergingResourceProvider` not only gives read-access to the merged resources but even allows to write. This provider always writes inside the topmost resource path (being returned as last item by the resource picker). Currently both resource pickers shipped with the Sling Resource Merger bundle do not allow to write though. Further details can be found in the description of [SLING-3909](https://issues.apache.org/jira/browse/SLING-3909).
 
 
 # Merge Properties
 
 Property Name | Type | Description
 ------------- | ---- | ---------
-sling:hideProperties | String[] | Hides the properties with the given names from the underlying resource. `*` hides all properties.
-sling:hideChildren| String[] | Hides the child resources with the given names from the underlying resource. `*` hides all child resources. If one value starts with `!` this is a negation (which means the property with the given value should not be hidden). Since by default nothing is hidden the negation is only useful if you specify multiple values for this property. E.g. giving the values `[!child1,*]` hides all children except for the one with the name `child1`. If you have a resource name starting with `!` you must escape it with an additional `!` in front if you want to reference it in `sling:hideChildren`, e.g. `!!child1` means that the resource with the name `!child1` should be hidden.
+sling:hideProperties | String[] | Hides the properties with the given names. `*` hides all properties (since version 1.3.2 the wildcard only affects underlying properties and no longer local ones, see also [SLING-5468](https://issues.apache.org/jira/browse/SLING-5468)).
+sling:hideChildren| String[] | Hides the child resources with the given names. `*` hides all child resources (since version 1.3.2 the wildcard only affects underlying child resources and no longer local ones, see also [SLING-5468](https://issues.apache.org/jira/browse/SLING-5468)). If one value starts with `!` this is a negation (which means the property with the given value should not be hidden). Since by default nothing is hidden the negation is only useful if you specify multiple values for this property. E.g. giving the values `[!child1,*]` hides all children except for the one with the name `child1`. If you have a resource name starting with `!` you must escape it with an additional `!` in front if you want to reference it in `sling:hideChildren`, e.g. `!!child1` means that the resource with the name `!child1` should be hidden.
 sling:hideResource | Boolean | If `true` then the resource with the name which contains this property should not be exposed!
-sling:orderBefore | String | Contains the name of the preceeding sibling resource. This is influencing the order of resources when calling e.g. `Resource.listChildren()` or `Resource.getChildren()` on the merged resource.
+sling:orderBefore | String | Contains the name of the preceeding sibling resource. This is influencing the order of resources when calling e.g. `Resource.listChildren()` or `Resource.getChildren()` on the merged resource. This is only necessary if the default resource order is not sufficient (see below).
+
+# Child Resource Order
+
+For a merged resource the order of its child resources is the following:
+First the ones from the base resource, then the ones from the overlaying resources. The children only defined by the topmost resource come last.
+
+In case the same child is defined in more than one resource, its position is taken from the highest overlaying resource (since version 1.3.2, see also [SLING-4915](https://issues.apache.org/jira/browse/SLING-4915)).
+For example:
+    
+    base/
+    	+--child1
+    	+--child2
+    	+--child3
+    	
+    overlay/
+        +--child4
+    	+--child2
+    	+--child3
+    	
+    resulting order: child1, child4, child2, child3
+
+You can overwrite that behaviour by leveraging the `sling:orderBefore` property.
 
 # Resource Pickers
 
@@ -41,7 +63,7 @@ sling:orderBefore | String | Contains th
 
  Description | Merged Resource Path | Merging Order | Read-Only | Related Ticket 
 ------------ | -------------------- | ------------- | --------- | ---------------
-Merging based on the resource resolver's search path | `/mnt/overlay/<relative resource path>` | Last resource resolver search path first (Order = Descending search paths). | `true` |  [SLING-2986](https://issues.apache.org/jira/browse/SLING-2986) 
+Merging based on the resource resolver's search path | `/mnt/overlay/<relative resource path>` | Last resource resolver search path first (Order = Descending search paths). | `true` |  [SLING-2986](http://issues.apache.org/jira/browse/SLING-2986) 
 
 This picker is thought for globally overlaying content by placing the diff-resource in "/apps" without actually touching anything in "/libs" (since this is only thought for Sling itself). This should be used whenever some deviation of content is desired which is initially shipped with Sling. The client (i.e. the code using the merged resource) does not have to know if there is an overlay in place.