Learning from Examples: View Source
(Caveat: this is another "programming"-centric page. Just skip it if you want to avoid getting into that sort of thing.)
Once you get the basics of QL down, you start to look at pages in Querki and ask, "How did they do that?". As much as possible, Querki plays fair: this Documentation Space is just another Space, like any other, and there's nothing going on here that you can't do yourself. So the answer to that question is usually all about looking at the Thing you're wondering about in detail, and you usually do that with View Source. View Source is kind of like a read-only version of the Editor, and you should use it whenever you want to understand a Thing without changing it.
For this example, let's actually use this Documentation Space itself. You might notice that the subtitle of each of these pages says that their Model is
Manual Section. If you clicked on that link you'd be at the Manual Section Model. (If it's convenient, I recommend right-clicking on the link, saying "Open in New Tab" or something like that, and following along.) From there, choose "View Source" off of the Actions menu:
That brings you to the View Source page:
View Source lists all of the Properties of this Thing. (Truth to tell, it isn't as important as it used to be -- Models by default show much of this information nowadays -- but View Source is available even if there is a Model View preventing the Model from showing it all upfront.) This lets you see that Manual Section is a bit complicated, but let's disentangle it:
[[Description]]
[[Subsections -> _section(""### Sections"", _bulleted)]]
{{navLinks:
[[_prevInList(Subsections._refs -> Subsections) -> ""__<- Prev: [[Display Name]]__ |""]] [[Subsections._refs -> _first -> ""__Up: [[Display Name]]__""]] [[_nextInList(Subsections._refs -> Subsections) -> ""| __Next: [[Display Name]] ->__""]]
}}The first line is straightforward:
[[Description]]
Description is the main body of a Manual Section -- the text itself, as a Large Text Property. So this part just shows the guts of the page. Everything else is the stuff at the bottom.
[[Subsections -> _section(""### Sections"", _bulleted)]]
Now it gets more interesting. This bit is how the chapters, like
Creating Your Own Spaces, show the pages under them them. Those pages go into
Subsections -- if you click on that link, you'll see that Property is a List of Links, which makes sense.
What is
_section? To figure out things like this, it's best to keep the
Method Reference handy, so you can look these functions up. If you go to the page on
_section, you find its documentation. It is a very useful function: it expects to receive a List, and
only if that List is non-empty, it shows the parts in the parentheses. The first parameter is a header, the second the contents.
The next line looks a bit daunting, but let's pull it apart. It mainly consists of three separate QL expressions. Let's start with the one in the middle, which is a little less complex:
[[Subsections._refs -> _first -> ""__Up: [[Display Name]]__""]]
Okay, it starts with
Subsections._refs. As we learned in
Links and Link Model,
_refs produces the Things that point to
this thing through the given Property -- in this case, the Thing that has this page in its Subsections, aka the parent page.
_first means the first element in the List (probably not necessary in this case, since we generally expect a page to only belong to one manual). And the end is a Text stage that displays the link to that parent page as "Up:", followed by its Display Name. So this is simply the link to the parent page.
The first part of the line is:
[[_prevInList(Subsections._refs -> Subsections) -> ""__<- Prev: [[Display Name]]__ |""]]
This looks kind of similar, with some twists. We already established that Subsections._refs is the parent page, so Subsections._refs -> Subsections is the complete list of Subsections under this parent. _prevInList() is a weird but useful little function, that produces the element before the current context in the given list -- so it's the Subsection before this page. And the Text stage at the end is pretty much like the earlier one, showing that previous Subsection with the given text.
And then the final part no longer looks so weird:
[[_nextInList(Subsections._refs -> Subsections) -> ""| __Next: [[Display Name]] ->__""]]
That's just like the above clause, but using _nextInList -- which, as you'd expect, produces the element after the current context in the given list.
It's a complicated example (it's probably the most complex single part of the Documentation Space), but it's not too bad if you sit down and dissect it. If you want to play with it to understand it better, choose a Documentation page (such as this one), open
Querki Explorer on it, and play with some of these QL expressions. Everything gets easier to understand after you mess around with it a bit, and Querki Explorer is great for helping you answer, "What the heck is that doing?".
