Imagine a stupid jQuery toggler:

Demo:

https://jsfiddle.net/fordkmp3/

Demo code:

<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:

$('.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 getElementById:

var element = JX.$(id);

JX.DOM.scry() - look down for multiple elements

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 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:

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

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

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.