From 8eeb22b7b8600864eaaea4914d2b5817cae9eb97 Mon Sep 17 00:00:00 2001 From: Sven Slootweg Date: Tue, 23 Aug 2016 14:45:28 +0200 Subject: [PATCH] Add documentation and changelog --- CHANGELOG.md | 21 +++++++ README.md | 170 +++++++++++++++++++++++++++++++++++++++++++++++++-- src/index.js | 2 - 3 files changed, 185 insertions(+), 8 deletions(-) create mode 100644 CHANGELOG.md diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..143471c --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,21 @@ +## 1.0.0 (August 23, 2016) + +First stable and documented release - however, the functionality or API has not changed from `0.0.3`. + +* __Documentation:__ Updated donation text. +* __Documentation:__ Added documentation and a changelog. + +## 0.0.3 (May 10, 2016) + +* __Minor:__ Made the Riot query segment optional. +* __Minor:__ Added mixin interface. +* __Minor:__ Added support for `query.one`. +* __Package:__ Changed `gulpfile` to use presets. + +## 0.0.2 (April 16, 2016) + +* _Patch:__ Added `.npmignore` file to ensure that `lib/` is included in the published module. + +## 0.0.1 (April 16, 2016) + +Initial release. \ No newline at end of file diff --git a/README.md b/README.md index 4e82cf4..f9b63c7 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,11 @@ -# packagename +# riot-query -TODO +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: + +| Syntax | Meaning | +|-----------------------------|---------------------------------------------------| +| `foo` | Each `foo` tag. | +| `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`. + + +An example of a contrived, complex query: + +``` +foo/bar/**/{baz,qux/quz,something/{hai,bai},}/{duck,swan}//.domFoo .domBar +``` + +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: + +```html + + + Text 1 + Text 2 + + + + +``` + +A similar example, but selecting DOM nodes rather than Riot tags: + +```html + + + + + Text 1 + + + + Text 2 + + + + + +``` + +An example using `riot-query` stand-alone rather than as a mixin: + +```html + + + + + Text 1 + + + + Text 2 + + + + + +``` ## API -TODO \ No newline at end of file +### riotQuery(tag, query) + +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`. \ No newline at end of file diff --git a/src/index.js b/src/index.js index 75b6b0f..7f155d4 100644 --- a/src/index.js +++ b/src/index.js @@ -97,8 +97,6 @@ function query(tag, queryString) { queryCache[queryString] = createQuery(queryString); } - // TODO: DOM traversal - return queryCache[queryString](tag); }