Change Details

Imagine a stupid jQuery toggler: Demo: https://jsfiddle.net/fordkmp3/ Demo code: ```lang=html <div class="collapsible-container"> <div class="blabla"> <div class="collapsible-content"> <p>Stuff Stuff Stuff Stuff Stuff to be toggled!</p> </div> </div> <div class="asd"> <div class="lol"> <a href="#!" class="action-collapsible-toggle">Click to Toggle Toggle Toggle</a> </div> </div> </div> ``` Demo code with jQuery: ```javascript $('.action-collapsible-toggle').click(function() { // Traverse parents to find the right one. var $container = $(this).closest('.collapsible-container'); // Traverse children to find the right one. var $content = $container.find('.collapsible-content'); $content.toggle(); }); ``` People would love to understand how to reach the exact same thing with Javelin, since we are constrained to do so with Javelin for interesting historical reasons... So, note that in jQuery you have a `.find()` method and a `.closest()` method that just traverse up and down the tree. This is very handy, since it allows web designers to concentrate in adopting whatever HTML tag, nesting whatever divs, and the business logic always work, even if you change an `<a>` with a `<span>`, or if you change a `<div>` with a `<nav>` or stuff like these. How to reach the same... in Javelin? == Preamble, for people who don't know Javelin == Premising that Javelin introduces "sigils" that are basically a re-implementation of CSS classes... https://we.phorge.it/book/javelin/article/sigils_metadata/ Premising that I'm able to (make big efforts to) see advantages in this abstraction... Here the current status of the Javelin's documentation: https://we.phorge.it/book/javelin/ It only talks about listening, events, and setting data on sigils, but not about __finding__ sigils. == Adding missing Diviner documentation == Premising that the things that people would appreciate to understand are probably here: https://we.phorge.it/source/phorge/browse/master/webroot/rsrc/externals/javelin/lib/DOM.js It seems to me that the useful tools provided by Javelin are these (please feel free to improve this stub): THE STUB STARTS HERE ↓↓↓ ----- = Concepts: DOM traversing = Javelin DOM traversing utilities. No batteries included. == Overview == Javelin does not encourage to look for CSS classes, since Javelin introduced sigils. If sigils are unclear, read the related documentation. == scry() - look down for multiple elements == ```javascript var children = JX.DOM.scry(root, tagname, sigil); ``` The `scry` it's basically a jQuery `root.find(selector)`, but static, and it returns an array of elements that have that sigil __AND that tagname__ (??). Downside: the tagname is mandatory (!) because it relies on getElementsByTagName to get all [[ https://developer.mozilla.org/en-US/docs/Web/API/Document/getElementsByTagName | descendants ]] elements. Workaround: so, we can use this to have the "same" jQuery behavior of `$().find()` that does not encourage to hardcode by tagname, and I think we should document it: ```javascript var children = JX.DOM.scry(root, '*', sigil); ``` == find() - look down for one element == ```javascript var child = JX.DOM.find(root, tagname, sigil); ``` Same as above, but returning 1 element. Same workaround should documented to do not necessarily hardcode business logic on tag names. == findAbove() - look up for one element == ```javascript var parent = JX.DOM.findAbove(anchor, tagname, sigil) ``` It's basically a jQuery `anchor.closest(selector)`. Same workarounds as above.

Imagine a stupid jQuery toggler: Demo: https://jsfiddle.net/fordkmp3/ Demo code: ```lang=html <div class="collapsible-container"> <div class="blabla"> <div class="collapsible-content"> <p>Stuff Stuff Stuff Stuff Stuff to be toggled!</p> </div> </div> <div class="asd"> <div class="lol"> <a href="#!" class="action-collapsible-toggle">Click to Toggle Toggle Toggle</a> </div> </div> </div> ``` Demo code with jQuery: ```javascript $('.action-collapsible-toggle').click(function() { // Traverse parents to find the right one. var $container = $(this).closest('.collapsible-container'); // Traverse children to find the right one. var $content = $container.find('.collapsible-content'); $content.toggle(); }); ``` People would love to understand how to reach the exact same thing with Javelin, since we are constrained to do so with Javelin for interesting historical reasons... So, note that in jQuery you have a `.find()` method and a `.closest()` method that just traverse up and down the tree. This is very handy, since it allows web designers to concentrate in adopting whatever HTML tag, nesting whatever divs, and the business logic always work, even if you change an `<a>` with a `<span>`, or if you change a `<div>` with a `<nav>` or stuff like these. How to reach the same... in Javelin? == Preamble, for people who don't know Javelin == Premising that Javelin introduces "sigils" that are basically a re-implementation of CSS classes... https://we.phorge.it/book/javelin/article/sigils_metadata/ Premising that I'm able to (make big efforts to) see advantages in this abstraction... Here the current status of the Javelin's documentation: https://we.phorge.it/book/javelin/ It only talks about listening, events, and setting data on sigils, but not about __finding__ sigils. == Adding missing Diviner documentation == Premising that the things that people would appreciate to understand are probably here: https://we.phorge.it/source/phorge/browse/master/webroot/rsrc/externals/javelin/lib/DOM.js It seems to me that the useful tools provided by Javelin are these (please feel free to improve this stub): THE STUB STARTS HERE ↓↓↓ ----- = Concepts: DOM traversing = Javelin DOM traversing utilities. No batteries included. == Overview == Javelin does not encourage to look for CSS classes or other selectors, since Javelin introduced sigils. If the word "sigil" is new to you, enjoy this document: https://we.phorge.it/book/javelin/article/sigils_metadata/ == `$()` - find element by ID == The `$()` in Javelin is basically a shorter version for the native [[ https://developer.mozilla.org/en-US/docs/Web/API/Document/getElementById | getElementById ]]: ```javascript var element = JX.$(id); ``` == `JX.DOM.scry()` - look down for multiple elements == ```javascript var children = JX.DOM.scry(root, tagname, sigil); ``` The `scry` it's basically a jQuery `root.find(selector)`, but static, and it returns an array of elements that have that sigil __and a tagname__. Downside: the tagname is mandatory (!) because the code relies on [[ https://developer.mozilla.org/en-US/docs/Web/API/Document/getElementsByTagName | getElementsByTagName ]] to get all descendants elements. Workaround: so, we can use this to have the "same" jQuery behavior of `$().find()` that does not encourage to hardcode by tagname, and I think we should document it: ```javascript var children = JX.DOM.scry(root, '*', sigil); ``` So, To do not hardcode your selection on a specific tagname, use `*` as tagname as workaround. == `JX.DOM.find()` - look down for one element == ```javascript var child = JX.DOM.find(root, tagname, sigil); ``` Same as above, but returning 1 element. To do not hardcode your selection on a specific tagname, use `*` as tagname as workaround. == `JX.DOM.findAbove()` - look up for one element == ```javascript var parent = JX.DOM.findAbove(anchor, tagname, sigil) ``` It's basically a jQuery `anchor.closest(selector)`. To do not hardcode your selection on a specific tagname, use `*` as tagname as workaround.

Imagine a stupid jQuery toggler: Demo: https://jsfiddle.net/fordkmp3/ Demo code: ```lang=html <div class="collapsible-container"> <div class="blabla"> <div class="collapsible-content"> <p>Stuff Stuff Stuff Stuff Stuff to be toggled!</p> </div> </div> <div class="asd"> <div class="lol"> <a href="#!" class="action-collapsible-toggle">Click to Toggle Toggle Toggle</a> </div> </div> </div> ``` Demo code with jQuery: ```javascript $('.action-collapsible-toggle').click(function() { // Traverse parents to find the right one. var $container = $(this).closest('.collapsible-container'); // Traverse children to find the right one. var $content = $container.find('.collapsible-content'); $content.toggle(); }); ``` People would love to understand how to reach the exact same thing with Javelin, since we are constrained to do so with Javelin for interesting historical reasons... So, note that in jQuery you have a `.find()` method and a `.closest()` method that just traverse up and down the tree. This is very handy, since it allows web designers to concentrate in adopting whatever HTML tag, nesting whatever divs, and the business logic always work, even if you change an `<a>` with a `<span>`, or if you change a `<div>` with a `<nav>` or stuff like these. How to reach the same... in Javelin? == Preamble, for people who don't know Javelin == Premising that Javelin introduces "sigils" that are basically a re-implementation of CSS classes... https://we.phorge.it/book/javelin/article/sigils_metadata/ Premising that I'm able to (make big efforts to) see advantages in this abstraction... Here the current status of the Javelin's documentation: https://we.phorge.it/book/javelin/ It only talks about listening, events, and setting data on sigils, but not about __finding__ sigils. == Adding missing Diviner documentation == Premising that the things that people would appreciate to understand are probably here: https://we.phorge.it/source/phorge/browse/master/webroot/rsrc/externals/javelin/lib/DOM.js It seems to me that the useful tools provided by Javelin are these (please feel free to improve this stub): THE STUB STARTS HERE ↓↓↓ ----- = Concepts: DOM traversing = Javelin DOM traversing utilities. No batteries included. == Overview == Javelin does not encourage to look for CSS classes, since Javelin introduced sigils. If sigils are unclear or other selectors, read the related documentationsince Javelin introduced sigils. == scry()If the word "sigil" is new to you, enjoy this document: https://we.phorge.it/book/javelin/article/sigils_metadata/ == `$()` - find element by ID == The `$()` in Javelin is basically a shorter version for the native [[ https://developer.mozilla.org/en-US/docs/Web/API/Document/getElementById | getElementById ]]: ```javascript var element = JX.$(id); ``` == `JX.DOM.scry()` - look down for multiple elements == ```javascript var children = JX.DOM.scry(root, tagname, sigil); ``` The `scry` it's basically a jQuery `root.find(selector)`, but static, and it returns an array of elements that have that sigil __AND that__and a tagname__ (??). Downside: the tagname is mandatory (!) because it relies on getElementsByTagName to get allthe code relies on [[ https://developer.mozilla.org/en-US/docs/Web/API/Document/getElementsByTagName | getElementsByTagName ]] to get all descendants ]] elements. Workaround: so, we can use this to have the "same" jQuery behavior of `$().find()` that does not encourage to hardcode by tagname, and I think we should document it: ```javascript var children = JX.DOM.scry(root, '*', sigil); ``` == So, To do not hardcode your selection on a specific tagname, use `*` as tagname as workaround. == `JX.DOM.find()` - look down for one element == ```javascript var child = JX.DOM.find(root, tagname, sigil); ``` Same as above, but returning 1 element. To do not hardcode your selection on a specific tagname, Same workaround should documented to do not necessarily hardcode business logic on tag namesuse `*` as tagname as workaround. == == `JX.DOM.findAbove()` - look up for one element == ```javascript var parent = JX.DOM.findAbove(anchor, tagname, sigil) ``` It's basically a jQuery `anchor.closest(selector)`. To do not hardcode your selection on a specific tagname, Same workaroundsuse `*` as tagname as aboveworkaround.