You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@sling.apache.org by to...@apache.org on 2017/09/25 10:28:26 UTC
svn commit: r1809599 - in
/sling/site/trunk/content/documentation/bundles/sling-query: ./
basic-ideas.mdtext examples.mdtext hierarchy-operators.mdtext
methods.mdtext modifiers.mdtext operators.mdtext selectors.mdtext
vs-jcr.mdtext
Author: tomekr
Date: Mon Sep 25 10:28:26 2017
New Revision: 1809599
URL: http://svn.apache.org/viewvc?rev=1809599&view=rev
Log:
SLING-6676: Get more documentation for Sling Query
Added:
sling/site/trunk/content/documentation/bundles/sling-query/
sling/site/trunk/content/documentation/bundles/sling-query/basic-ideas.mdtext
sling/site/trunk/content/documentation/bundles/sling-query/examples.mdtext
sling/site/trunk/content/documentation/bundles/sling-query/hierarchy-operators.mdtext
sling/site/trunk/content/documentation/bundles/sling-query/methods.mdtext
sling/site/trunk/content/documentation/bundles/sling-query/modifiers.mdtext
sling/site/trunk/content/documentation/bundles/sling-query/operators.mdtext
sling/site/trunk/content/documentation/bundles/sling-query/selectors.mdtext
sling/site/trunk/content/documentation/bundles/sling-query/vs-jcr.mdtext
Added: sling/site/trunk/content/documentation/bundles/sling-query/basic-ideas.mdtext
URL: http://svn.apache.org/viewvc/sling/site/trunk/content/documentation/bundles/sling-query/basic-ideas.mdtext?rev=1809599&view=auto
==============================================================================
--- sling/site/trunk/content/documentation/bundles/sling-query/basic-ideas.mdtext (added)
+++ sling/site/trunk/content/documentation/bundles/sling-query/basic-ideas.mdtext Mon Sep 25 10:28:26 2017
@@ -0,0 +1,75 @@
+Title: Basic ideas
+
+### Collections
+
+`SlingQuery` class represents a collection of resources. Basic collection can be created explicitly via a dollar method:
+
+ $(resource1, resource2, resource3)
+
+Above method creates a new `SlingQuery` object that consists of 3 resources. This object implements `Iterable<Resource>` interface, so can be used in foreach statements directly:
+
+ for (Resource resource in $(...)) { }
+
+### Operations
+
+`SlingQuery` class defines a number of methods which can be used to transform current collection into a new one. Following code:
+
+ $(resource1, resource2).parent()
+
+will replace each resource with its direct parent. If some resource is a repository root, it will be skipped. Some methods replace each resource with another resource (eg. `parent()` or `closest()`). Other methods can replace each resource with a set of resources:
+
+ $(resource1, resource2).children();
+
+Resulting object will contain direct children of both `resource1` and `resource2` objects. There are also methods that doesn't add any new resources, but removes existing:
+
+ $(resource1, resource2).first();
+
+Methods can be chained to create more complex query. Eg. following code will return last direct child of the `resource`:
+
+ $(resource).children().last();
+
+#### Laziness
+
+All operations are lazy (except `prev()` and sometimes `not()`). It means that `SlingQuery` won't read any resources until it's actually necessary. Example:
+
+ $(resource).children().children().first();
+
+`children().children()` construction reads all grand-children of the given resource. However, the last method limits the output to the first found resource. As a result, `SlingQuery` won't iterate over all children and grand-children, but it will simply take the first child of the `resource` and return its first child.
+
+#### Immutability
+
+`SlingQuery` object is immutable and each operation creates a new one. We can "freeze" some collection before performing more operations on it:
+
+ SlingQuery children = $(resource).children();
+ SlingQuery firstChild = children.first();
+ for (Resource child : children) { /* will display all children */ }
+ for (Resource child : firstChild) { /* will display the first child */ }
+
+### Selectors
+
+Some operations may take an additional string selector parameter that defines a filtering. Selector could be used to define resource type, resource attributes and additional modifiers. Example selector could look like this:
+
+ "cq:Page"
+
+It will match all resources with the given resource type. Example:
+
+ $(resource).children("cq:Page")
+
+will return only children with `cq:Page` resource type. You could also filter these resources defining any number of attributes in the square brackets:
+
+ $(resource).children("cq:Page[jcr:title=Some title][jcr:description=Some desc]")
+
+And finally, you could add some modifiers at the end:
+
+ $(resource).children("cq:Page[jcr:content/cq:template=my/template]:even")
+
+Above resources will find `cq:Page` children of the resource, using template `my/template` and return not all of them, but only those with even indices (eg. if matching children of the `resource` are `page_0`, `page_1` and `page_2`, only the first and the last will be returned).
+
+All parts of the selector are optional. In fact, an empty string (`""`) is a valid selector, accepting all resources. However, the defined order (resource type, attributes in square brackets and modifiers) has to be followed. Example selectors:
+
+ "foundation/components/richtext" // resource type
+ "foundation/components/richtext:first" // resource type with modifier
+ "[property=value][property2=value2]" // two attributes
+ ":even" // modifier
+ ":even:not(:first)" // two modifiers, the second one is nested
+
Added: sling/site/trunk/content/documentation/bundles/sling-query/examples.mdtext
URL: http://svn.apache.org/viewvc/sling/site/trunk/content/documentation/bundles/sling-query/examples.mdtext?rev=1809599&view=auto
==============================================================================
--- sling/site/trunk/content/documentation/bundles/sling-query/examples.mdtext (added)
+++ sling/site/trunk/content/documentation/bundles/sling-query/examples.mdtext Mon Sep 25 10:28:26 2017
@@ -0,0 +1,59 @@
+Title: Examples
+
+Get containing page (like [PageManager#getContainingPage](http://dev.day.com/docs/en/cq/current/javadoc/com/day/cq/wcm/api/PageManager.html))
+
+ $(resource).closest("cq:Page")
+
+Get first ancestor with a given template
+
+ $(resource).closest("cq:Page[jcr:content/cq:template=/apps/geometrixx/templates/homepage]")
+
+List siblings of the current page which can be displayed in the navigation
+
+ $(resource).closest("cq:Page").siblings("cq:Page[jcr:content/hiddenInNav=false]")
+
+Get the first sibling of the current page
+
+ $(resource).closest("cq:Page").siblings("cq:Page").first()
+
+Get page ancestor closest to the root
+
+ $(resource).parents("cq:Page").last()
+
+Get the second child of each resource:
+
+ $(resource1, resource2, resource3).children(":eq(1)")
+
+Get the first two children of each resource:
+
+ $(resource1, resource2, resource3).children(":lt(2)")
+
+Closest ancestor page having non-empty parsys
+
+ $(resource).closest("cq:Page foundation/components/parsys:parent")
+
+Get all parents of the current resource and adapt them to Page object
+
+ Iterable<Page> breadcrumbs = $(resource).parents("cq:Page").map(Page.class);
+
+Get all parents of the current resource up to the home page
+
+ Iterable<Page> breadcrumbs;
+ breadcrumbs = $(resource).parentsUntil(
+ "cq:Page[jcr:content/cq:template=/apps/geometrixx/templates/homepage]",
+ "cq:Page").map(Page.class);
+
+List all grand-children pages having empty parsys
+
+ $(resource).children("cq:Page").children("cq:Page").has("foundation/components/parsys:empty)
+
+Use JCR query to find all `cq:Page`s with a given template
+
+ $(resourceResolver)
+ .searchStrategy(SearchStrategy.QUERY)
+ .find("cq:PageContent[cq:template=/apps/geometrixx/templates/homepage]")
+ .parent()
+
+Find children named `en` or `de`
+
+ $(resource).children("#en, #de")
Added: sling/site/trunk/content/documentation/bundles/sling-query/hierarchy-operators.mdtext
URL: http://svn.apache.org/viewvc/sling/site/trunk/content/documentation/bundles/sling-query/hierarchy-operators.mdtext?rev=1809599&view=auto
==============================================================================
--- sling/site/trunk/content/documentation/bundles/sling-query/hierarchy-operators.mdtext (added)
+++ sling/site/trunk/content/documentation/bundles/sling-query/hierarchy-operators.mdtext Mon Sep 25 10:28:26 2017
@@ -0,0 +1,37 @@
+Title: Hierarchy operators
+
+### Child operator (`parent > child`)
+
+Select all direct child resources specified by `child` of resources specified by `parent`
+
+ // find all richtext components placed directly into parsys resources
+ $(resource).find('foundation/components/parsys > foundation/components/richtext')
+ // alternative version
+ $(resource).find('foundation/components/parsys').children('foundation/components/richtext')
+
+### Descendant operator (`ancestor descendant`)
+
+Select all resources that are `descendant`s of a given `ancestor`
+
+ // find all resources containing `someAttribute` on the `cq:Page`s being direct children of the resource
+ $(resource).children('cq:Page [someAttribute]')
+ // alternative version
+ $(resource).children('cq:Page').find('[someAttribute]')
+
+### Next adjacent operator (`prev + next`)
+
+Selects all next resources matching `next` that are immediately preceded by a sibling `prev`
+
+ // find next sibling of the cq:Page containing the resource
+ $(resource).closest('cq:Page + cq:Page')
+ // alternative version
+ $(resource).closest('cq:Page').next('cq:Page')
+
+### Next siblings operator (`prev ~ next`)
+
+Selects all sibling resources that follow after the `prev` element, have the same parent, and match the filtering `siblings` selector
+
+ // find all next siblings of the cq:Page containing the resource
+ $(resource).closest('cq:Page ~ cq:Page')
+ // alternative version
+ $(resource).closest('cq:Page').nextAll('cq:Page')
Added: sling/site/trunk/content/documentation/bundles/sling-query/methods.mdtext
URL: http://svn.apache.org/viewvc/sling/site/trunk/content/documentation/bundles/sling-query/methods.mdtext?rev=1809599&view=auto
==============================================================================
--- sling/site/trunk/content/documentation/bundles/sling-query/methods.mdtext (added)
+++ sling/site/trunk/content/documentation/bundles/sling-query/methods.mdtext Mon Sep 25 10:28:26 2017
@@ -0,0 +1,184 @@
+Title: Method list
+
+### `$(Resource... resources)`
+
+Create a new SlingQuery object, using passed resources as an initial collection. Example:
+
+ $(resource); // a simple SlingQuery collection containing one resource
+
+### `.add(Resource... resources)`
+
+Add resources to the collection.
+
+ $(resource).children().add(resource); // collection contains resource and all its children
+
+### `.asList()`
+
+Transform SlingQuery collection into a lazy list.
+
+ $(resource).children("cq:Page").asList().get(0); // get the first child page
+ $(resource).children().asList().isEmpty(); // return true if the resource have no children
+
+### `.children([selector])`
+
+Get list of the children for each resource in the collection. Pass `selector` to filter children. Example:
+
+ $(resource).children("cq:Page"); // get all page children of the resource
+ $(resource).children().children(); // get all grand-children of the resource
+
+### `.closest(selector)`
+
+For each resource in the collection, return the first element matching the selector testing the resource itself and traversing up its ancestors. Example:
+
+ $(resource).closest("cq:Page"); // find containing page, like PageManager#getContainingPage
+ // let's assume that someCqPageResource is a cq:Page
+ $(someCqPageResource).closest("cq:Page"); // return the same resource
+
+### `.eq(index)`
+
+Reduce resource collection to the one resource at the given 0-based index. Example:
+
+ $(resource0, resource1, resource2).eq(1); // return resource1
+ $(resource).children().eq(0); // return first child of the resource
+
+### `.filter(selector)`
+
+Filter resource collection using given selector.
+
+ final Calendar someTimeAgo = Calendar.getInstance();
+ someTimeAgo.add(Calendar.HOUR, -5);
+
+ // get children pages modified in the last 5 hours
+ SlingQuery query = $(resource).children("cq:Page").filter(new Predicate<Resource>() {
+ @Override
+ public boolean accepts(Resource resource) {
+ return resource.adaptTo(Page.class).getLastModified().after(someTimeAgo);
+ }
+ });
+
+### `.find([selector])`
+
+For each resource in collection return all its descendants using [selected strategy](#searchstrategystrategy). Please notice that invoking this method on a resource being a root of a large subtree may and will cause performance problems.
+
+ $(resource).find("cq:Page"); // find all descendant pages
+
+### `.first()`
+
+Filter resource collection to the first element. Equivalent to `.eq(0)` or `.slice(0, 0)`.
+
+ $(resource).siblings().first(); // get the first sibling of the current resource
+
+### `.has(selector)`
+
+Pick such resources from the collection that have descendant matching the selector. Example:
+
+ $(...).children('cq:Page').has(foundation/components/richtext) // find children pages containing some richtext component
+
+This method uses [selected strategy](#searchstrategystrategy) to iterate over resource descendants.
+
+### `.last()`
+
+Filter resource collection to the last element.
+
+ $(resource).siblings().last(); // get the last sibling of the current resource
+
+### `.map(Class<T> clazz)`
+
+Transform the whole collection to a new `Iterable<T>` object, invoking `adaptTo(clazz)` method on each resource. If some resource can't be adapted to the class (eg. `adaptTo()` returns `null`), it will be skipped. Example:
+
+ for (Page page : $(resource).parents("cq:Page").map(Page.class)) {
+ // display breadcrumbs
+ }
+
+### `.next([selector])`
+
+Return the next sibling for each resource in the collection and optionally filter it by a selector. If the selector is given, but the sibling doesn't match it, empty collection will be returned.
+
+ // let's assume that resource have 3 children: child1, child2 and child3
+ $(resource).children().first().next(); // return child2
+
+### `.nextAll([selector])`
+
+Return all following siblings for each resource in the collection, optionally filtering them by a selector.
+
+ // let's assume that resource have 3 children: child1, child2 and child3
+ $(resource).children().first().nextAll(); // return child2 and child3
+
+### `.nextUntil(selector)`
+
+Return all following siblings for each resource in the collection up to, but not including, resource matched by a selector.
+
+ // let's assume that resource have 4 children: child1, child2, child3 and child4
+ // additionaly, child4 has property jcr:title=Page
+ $(resource).children().first().nextUntil("[jcr:title=Page]"); // return child2 and child3
+
+### `.not(selector)`
+
+Remove elements from the collection.
+
+ $(resource).children().not("cq:Page"); // remove all cq:Pages from the collection
+ $(resource).children().not(":first").not(":last"); // remove the first and the last element of the collection
+
+### `.parent()`
+
+Replace each element in the collection with its parent.
+
+ $(resource).find("cq:PageContent[jcr:title=My page]:first").parent(); // find the parent of the first `cq:PageContent` resource with given attribute in the subtree
+
+### `.parents([selector])`
+
+For each element in the collection find all of its ancestors, optionally filtering them by a selector.
+
+ ($resource).parents("cq:Page"); // create page breadcrumbs for the given resources
+
+### `.parentsUntil(selector)`
+
+For each element in the collection find all of its ancestors until a resource matching the selector is found.
+
+ ($currentResource).parentsUntil("cq:Page"); // find all ancestor components on the current page
+
+### `.prev([selector])`
+
+Return the previous sibling for each resource in the collection and optionally filter it by a selector. If the selector is given, but the sibling doesn't match it, empty collection will be returned.
+
+ // let's assume that resource have 3 children: child1, child2 and child3
+ $(resource).children().last().prev(); // return child2
+
+### `.prevAll([selector])`
+
+Return all preceding siblings for each resource in the collection, optionally filtering them by a selector.
+
+ // let's assume that resource have 3 children: child1, child2 and child3
+ $(resource).children().last().prevAll(); // return child1 and child2
+
+### `.prevUntil(selector)`
+
+Return all preceding siblings for each resource in the collection up to, but not including, resource matched by a selector.
+
+ // let's assume that resource have 4 children: child1, child2, child3 and child4
+ // additionally, child1 has property jcr:title=Page
+ $(resource).children().last().prevUntil("[jcr:title=Page]"); // return child2 and child3
+
+### `.searchStrategy(strategy)`
+
+Select new search strategy, which will be used in following [`find()`](#findselector) and [`has()`](#hasselector) function invocations. There 3 options:
+
+* `SearchStrategy.DFS` - [depth-first search](http://en.wikipedia.org/wiki/Depth-first_search)
+* `SearchStrategy.BFS` - [breadth-first search](http://en.wikipedia.org/wiki/Breadth-first_search)
+* `SearchStrategy.QUERY` - use JCR SQL2 query (default since 1.4.0)
+
+DFS and BFS iterate through descendants using appropriate algorithm. QUERY strategy tries to transform SlingQuery selector into a SQL2 query and invokes it. Because there are SlingQuery operations that can't be translated (eg. `:has()` modifier), the SQL2 query result is treated as a initial collection that needs further processing.
+
+### `.siblings([selector])`
+
+Return siblings for the given resources, optionally filtered by a selector.
+
+ $(resource).closest("cq:Page").siblings("cq:Page"); // return all sibling pages
+
+### `.slice(from[, to])`
+
+Reduce the collection to a sub-collection specified by a given range. Both `from` and `to` are inclusive and 0-based indices. If the `to` parameter is not specified, the whole sub-collection starting with `from` will be returned.
+
+ // let's assume that resource have 4 children: child1, child2, child3 and child4
+ $(resource).children().slice(1, 2); // return child1 and child2
+
Added: sling/site/trunk/content/documentation/bundles/sling-query/modifiers.mdtext
URL: http://svn.apache.org/viewvc/sling/site/trunk/content/documentation/bundles/sling-query/modifiers.mdtext?rev=1809599&view=auto
==============================================================================
--- sling/site/trunk/content/documentation/bundles/sling-query/modifiers.mdtext (added)
+++ sling/site/trunk/content/documentation/bundles/sling-query/modifiers.mdtext Mon Sep 25 10:28:26 2017
@@ -0,0 +1,61 @@
+Title: Modifiers
+
+### `:eq(index)`
+
+Reduce the set of matched elements to the one at the specified 0-based index. Example:
+
+ $(...).find("foundation/components/richtext:eq(2)"); // find the third richtext in the subtree
+
+### `:even`
+
+Reduce the set of matched elements to those which indexes are even numbers:
+
+ $(...).children("cq:Page:even"); // get even children pages for each resource in the collection
+
+### `:first`
+
+Reduce the set of matched elements to the first one:
+
+ $(...).find("foundation/components/richtext:first"); // find the first richtext in the subtree
+
+### `:gt(index)`
+
+Reduce the set of matched elements to those which indexes are greater than the argument:
+
+ $(...).children("cq:Page:gt(2)"); // filter out first 3 pages
+
+### `:has(selector)`
+
+Reduce the set of the matched elements to those which have descendant matching the selector:
+
+ $(...).children("cq:Page:has(foundation/components/richtext)]"); // get children pages containing richtext component
+
+### `:last`
+
+Reduce the set of matched elements to the last one:
+
+ $(...).find("foundation/components/richtext:last"); // find the last richtext in the subtree
+
+### `:lt(index)`
+
+Reduce the set of matched elements to those which indexes are lesser than the argument:
+
+ $(...).children("cq:Page:lt(3)"); // get first 3 matches
+
+### `:not(selector)`
+
+Reduce the set of matched elements to those which doesn't match the selector. The selector may contain other modifiers as well, however in this case the function will be evaluated eagerly:
+
+ $(...).find(":not(:parent)"); // ancestor resources that doesn't contain any children
+
+### `:odd`
+
+Reduce the set of matched elements to those which indexes are odd numbers:
+
+ $(...).children("cq:Page:odd"); // get odd children pages for each resource in the collection
+
+### `:parent`
+
+Reduce the set of the matched elements to those which have any descendant resource.
+
+ $(...).children(":parent]"); // get children resources containing any resource
Added: sling/site/trunk/content/documentation/bundles/sling-query/operators.mdtext
URL: http://svn.apache.org/viewvc/sling/site/trunk/content/documentation/bundles/sling-query/operators.mdtext?rev=1809599&view=auto
==============================================================================
--- sling/site/trunk/content/documentation/bundles/sling-query/operators.mdtext (added)
+++ sling/site/trunk/content/documentation/bundles/sling-query/operators.mdtext Mon Sep 25 10:28:26 2017
@@ -0,0 +1,47 @@
+Title: Operators
+
+### Contains `[name*=value]`
+
+Select resources that have property `name` containing `value`:
+
+ // select children pages titled 'foo', 'foo bar', 'bar foo bar', 'foofoofoo', etc.
+ $(resources).children("cq:Page[jcr:content/jcr:title*=foo]")
+
+### Contains a word `[name~=value]`
+
+Select resources that have property `name` containing word `value` delimited with spaces:
+
+ // select children pages titled 'foo', 'foo bar', 'bar foo bar', but not 'foofoofoo'
+ $(resources).children("cq:Page[jcr:content/jcr:title~=foo]")
+
+### Ends with `[name$=value]`
+
+Select resources that have property `name` ending with `value`:
+
+ // select children pages titled 'foo', 'bar foo', etc.
+ $(resources).children("cq:Page[jcr:content/jcr:title$=foo]")
+
+### Equals `[name=value]`
+
+Select resources that have property `name` that equals to `value`:
+
+ $(resources).children("cq:Page[jcr:content/jcr:title=foo]")
+
+### Not equal `[name!=value]`
+
+Select resources that have property `name` that not equals to `value`:
+
+ $(resources).children("cq:Page[jcr:content/jcr:title!=foo]")
+
+### Starts with `[name^=value]`
+
+Select resources that have property `name` starting with `value`:
+
+ // select children pages titled 'foo', 'foo bar', etc.
+ $(resources).children("cq:Page[jcr:content/jcr:title^=foo]")
+
+### Has attribute `[name]`
+
+Select resources that have property `name`:
+
+ $(resources).find("[markerProperty]")
Added: sling/site/trunk/content/documentation/bundles/sling-query/selectors.mdtext
URL: http://svn.apache.org/viewvc/sling/site/trunk/content/documentation/bundles/sling-query/selectors.mdtext?rev=1809599&view=auto
==============================================================================
--- sling/site/trunk/content/documentation/bundles/sling-query/selectors.mdtext (added)
+++ sling/site/trunk/content/documentation/bundles/sling-query/selectors.mdtext Mon Sep 25 10:28:26 2017
@@ -0,0 +1,67 @@
+Title: Selectors
+
+Selector string are something between filters and content descriptors. Selector can filter resources by their [type](#resource-type), [name](#resource-name), [attributes](#attributes) and [additional modifiers](#modifiers). They can be also [chained together](#joining-selectors) to describe more sophisticated hierarchy structure or [combined with comma](#combining-selectors).
+
+## Syntax
+
+Selector consists of four parts:
+
+### Resource type
+
+Resource type, which could be a `sling:resourceType`, like `foundation/components/richtext` or the underlying JCR node type, like `cq:Page` or `nt:unstructured`. In the latter case, SlingQuery takes types hierarchy into consideration (eg. `nt:base` matches everything). JCR mixin types could be used as well.
+
+### Resource name
+
+Resource name can be defined with a hash `#` character, after the resource type (or instead of it):
+
+ $(resource).children("cq:Page#some-name")
+
+If the desired resource name contains colon (`:`) character, the whole string should be escaped with apostrophes:
+
+ $(resource).children("#'jcr:content'[jcr:title=My title]")
+
+### Attributes
+
+After the resource type and resource name one could pass a number of filtering attributes. Each attribute has following form: `[property=value]`. Passing multiple attributes will match only those resources that have all of them set. Property name could contain `/`. In this case property will be taken from the child resource, eg.:
+
+ $(resource).children("cq:Page[jcr:content/jcr:title=My title]")
+
+will return only children of type `cq:Page` that have sub-resource called `jcr:content` with property `jcr:title` set to `My title`. Besides the `=` you may use other operators like `*=`, which means *contains*:
+
+ $(resource).children("cq:Page[jcr:content/jcr:title*=title]")
+
+See the [fulll list of operators](Operator list).
+
+### Modifiers
+
+At the end of the selector one could define any number of modifiers that will be used to filter out the resources matched by the resource type and attributes. Each modifier starts with colon, some of them accepts a parameter set in parentheses. Example:
+
+ $(resource).children("cq:Page:first");
+ $(resource).children("cq:Page:eq(0)"); // the same
+ $(resource).children(":first"); // modifier can be used alone
+
+It is important that modifier filters out sub-collection created for each node, before it is merged. Eg.:, there is a difference between:
+
+ $(resource1, resource2).children().first();
+
+and
+
+ $(resource1, resource2).children(":first");
+
+In the first case we create a new collection consisting of children of the `resource1` and `resource2` and then we get the first element of the merged collection. On the other hand, the second example takes *first child* of each resource and creates a collection from them.
+
+See the [full list of modifiers](Modifier list).
+
+## Joining selectors
+
+Selectors can be joined together using [hierarchy operators](Hierarchy operator list). This feature enables the developer to create sophisticated filters describing desired resource structure, eg.:
+
+ $(resource).children("cq:Page foundation/components/parsys > foundation/components/richtext")
+
+will all `cq:Page`s containing paragraph systems with a richtext inside.
+
+## Combining selectors
+
+You may specify any number of selectors to combine into a single result. Use comma to join a few conditions. Comma is treated as `OR` statement:
+
+ $(resource).children("#en, #de, #fr"); // return all direct children named `en` or `de` or `fr`.
Added: sling/site/trunk/content/documentation/bundles/sling-query/vs-jcr.mdtext
URL: http://svn.apache.org/viewvc/sling/site/trunk/content/documentation/bundles/sling-query/vs-jcr.mdtext?rev=1809599&view=auto
==============================================================================
--- sling/site/trunk/content/documentation/bundles/sling-query/vs-jcr.mdtext (added)
+++ sling/site/trunk/content/documentation/bundles/sling-query/vs-jcr.mdtext Mon Sep 25 10:28:26 2017
@@ -0,0 +1,17 @@
+Title: Sling Query vs JCR
+
+Sling Query is not meant to replace JCR queries (XPath, JCR-SQL, JCR-SQL2). It doesn't use indexes and generally in queries traversing large subtrees (like `/` or `/content` or `/content/mysite/en`) it'll be much slower than well written JCR query.
+
+Purpose of the SlingQuery is to provide a convenient way to traverse resource tree. All SlingQuery operations are eventually transformed into a series of `listChildren()` and `getParent()` operations [1].
+
+As a rule of thumb - if you have a complex Java loop reading resource children or parents and processing them somehow, rewritting it to SlingQuery will be a good choice. If you have a recursive method trying to get some resource ancestor, using SlingQuery will be a good choice. On the other hand, if you have a large resource subtree and want to find all `cq:Page`s, using SlingQuery is a bad choice.
+
+| Description | JCR query | SlingQuery |
+| ------------------------------------------------------|-----------|------------|
+| You have a complex logic using Sling Resource API | - | Yes! |
+| You want to find resource ancestor | - | Yes! |
+| You want to find all descendants with given attribute | Yes! | - |
+| You want to find all descendants of given type | Yes! | - |
+| You'd like to get ordered results | Yes! | - |
+
+[1] - Actually, the `find()` operation uses QUERY strategy by default, which means that the selector string is transformed to a SQL2 query. However, the transformation process is very naïve and simply skips all conditions that can't be easily transformed to SQL2 (eg. selector `[jcr:content/jcr:title=some title]` won't be transformed as it contains some subresource reference). The result of this query is then filtere manually. See [searchStrategy](Method list#searchstrategystrategy) for more details.