A module for easily traversing through a Riot.js tag hierarchy, using a simple custom query language. Can be used stand-alone or as a tag mixin.
## Why you might need this
* Riot.js is inconsistent in how it exposes its `tags` - it will be an array if there are multiple, and a single element if there's only one. This means you constantly have to normalize the results.
* While selecting direct descendants is easy, it's a lot trickier when you need to search in the entire hierarchy, for example because you have a wrapper element that `yield`s its content.
## License
@ -8,9 +13,9 @@ TODO
## Donate
My income consists largely of donations for my projects. If this module is useful to you, consider [making a donation](http://cryto.net/~joepie91/donate.html)!
Maintaining open-source projects takes a lot of time, and the more donations I receive, the more time I can dedicate to open-source. If this module is useful to you, consider [making a donation](http://cryto.net/~joepie91/donate.html)!
You can donate using Bitcoin, PayPal, Flattr, cash-in-mail, SEPA transfers, and pretty much anything else.
You can donate using Bitcoin, PayPal, Flattr, cash-in-mail, SEPA transfers, and pretty much anything else. Thank you!
## Contributing
@ -20,10 +25,163 @@ Build tool of choice is `gulp`; simply run `gulp` while developing, and it will
Be aware that by making a pull request, you agree to release your modifications under the licenses stated above.
## Query language
A query consists of two parts: a Riot query and a DOM query. Both are optional, but you must always specify *at least one of them*.
In the Riot part of a query, the structure always refers to the hierarchy of *Riot tags*, not other DOM elements. In other words, the hierarchy follows the one you'd find in `this.tags`. In the DOM part of the query, you can specify DOM elements to select in the set of Riot tags that you've selected.
The `riot-query` language is somewhat syntactically similar to shell expansion. Below is a reference chart:
| `foo/bar` | Each `bar` tag that is a direct descendant of a `foo` tag. |
| `foo/**/bar` | Each `bar` tag that is a child of a `foo` tag, *anywhere* in its subtree - it does *not* have to be a direct descendant. |
| `{foo,bar}` | Each `foo` and `bar` tag |
| `foo/{bar,baz}` | Each `bar` and `baz` tag that is a direct descendant of a `foo` tag. |
| `foo/{bar,baz,}` | Each `foo`, `foo/bar` and `foo/baz` tag (note the last comma!) |
| `foo//.someClass` | Each DOM element matching `.someClass` that exists somewhere within a `foo` tag. |
| `foo//.someClass > .sub` | Each DOM element matching `.someClass > .sub` that exists somewhere within a `foo` tag. |
These are only some simplified examples - *any* combination of the above is valid, as long as the (optional) DOM part of the query comes last. `riot-query` uses a real query parser, so there are no edge cases.
## Usage
TODO
An example of a simple query:
```
menu-bar/{menu-button,menu-submenu}
```
This would select every `menu-button` and `menu-submenu` that is directly nested within a `menu-bar`.
This would select every DOM element matching `.domFoo .domBar` that exists within any of the following paths:
* `foo/bar/**/baz/duck`
* `foo/bar/**/baz/swan`
* `foo/bar/**/qux/quz/duck`
* `foo/bar/**/qux/quz/swan`
* `foo/bar/**/something/hai/duck`
* `foo/bar/**/something/hai/swan`
* `foo/bar/**/something/bai/duck`
* `foo/bar/**/something/bai/swan`
* `foo/bar/**/duck`
* `foo/bar/**/swan`
The last two might seem a little odd, but note the extra comma at the end of the first group - a trailing comma is considered to indicate an empty item, similar to how it works in Bash, and in `riot-query` that means that the entire segment is ignored.
An example of making a query using `riot-query` as a mixin:
Run a `query` on a given `tag`, and return the results.
* __tag:__ The Riot.js tag to query from. This *cannot* be a regular DOM element, it *must* be a tag.
* __query:__ The query to run, following the query syntax described above.
If the `query` contains a DOM query, this function will return DOM elements. If it doesn't, it will return Riot tags. If only a DOM query is specified without a Riot query (eg. `//.someClass`), then `riot-query` will search through the DOM tree for the tag that `riotQuery` was called on.
Keep in mind that if your query selects DOM nodes rather than Riot tags, __they will be returned as an array, not as a NodeList.__ Additionally, DOM queries will *also* include DOM elements in child tags, not just those that are a part of the tag you're querying from.
### riotQuery.one(tag, query)
The same as `riotQuery`, but it only ever returns the *first* result, without being wrapped in an array.
### riotQuery.mixin
A mixin object that you can pass into the `this.mixin` method for any Riot tag.
## Mixin API
### this.query(query)
The same as `riotQuery`, but without the need to specify a `tag` - it will always apply to the current tag.
### this.queryOne(query)
The same as `riotQuery.one`, but without the need to specify a `tag`.
Sven Slootweg
8 years ago