Previous Entry Share Next Entry
jducoeur wrote in querki_project
Lots of major, visible changes this time around, at various levels. Some of this is pretty important to advanced Querki users. Most of it is about "usability" at one level or another; that's going to be an ongoing theme for the time being.

Enhancements and Features

First, and in some ways most usefully, there is new Documentation by Category page. I've been coming to the conclusion that *I* can't find things in the docs any more -- there's just too much there -- which means they're getting to be useless for everybody else. So I've created a new page that shows the high-level functional categories, and lets you dive in and see what's in each of those. This lets you, say, just look at the functions for Photos, and ignore the Logic functions.

Internally, we now have a categorization scheme for all of the Functions, Properties, Things and Types, and I've done a first pass at that. This is not the last word there: I strongly encourage comments along the lines of, "I expected to find _foo in the category Bars and Bazzes". At the moment each item is in only one category, but the system should allow items to be listed in multiple categories (it's a Tag Set under the hood, of course), so it should be decently flexible.

Also, you'll find that that page is far more interactive than the old docs -- everything happens directly in that page. I found that I've been getting annoyed by all the page flips and Back buttons required in looking things up in the old reference pages, so the new one does everything in-page, using _QLLink very deeply. Indeed, the hardcore Querki hackers may want to take a look at the source for that page, which involves what may be the most complex and sophisticated QL expression written to date. You'll have a lot of WTF moments looking at it, all of which should be explained below: many of this week's changes were driven by my desire to make this page work correctly, without compromises.

BTW, this page is a fine illustration of how to use _QLButton/_QLLink to make a very complex page highly responsive. Overall, this contains all the documentation -- it's a huge amount of data. But the page only initially shows an outline, which you can dive down into, so each level is nicely quick. I strongly recommend this pattern, and will be thinking about ways to make it easier to code.

Querki now has local function definitions: this is only interesting to power users, but it is *huge* for power users, one of the most important enhancements this year. Enough so that I'm going to give it its own post tomorrow, describing it in detail and going through the implications. But to whet your whistle, this means you can now say things like (from one of the unit tests):
[[Album._instances -> _groupBy(Artists) -> +$byArtist
  _def $From First Album($artist, $field) = $byArtist -> _groupGet($artist) -> _first -> $field
  $From First Album(Blackmores Night, Link Name)
  $From First Album(Eurythmics, Artists -> Genres)
Between this and the local value bindings introduced last time, it's finally possible to build *good*, properly-factored, relatively maintainable, complex expressions in QL.

The _QL[Button | Link | Input] functions can now receive most Types, not just Things: mindways hit this recently, and I've encountered it once or twice myself -- _QLButton is turning out to be one of the most powerful functions in Querki for producing really nice UI, but it has so far required you to pass a Thing into it, even when that made no sense. This turned out to be a blocker for the Documentation by Category page, which needed to be able to pass Tags into _QLLink.

So I've finally bitten the bullet, and made this work more correctly. Mind, it still can't handle absolutely everything -- in particular, if you pass it a List, it'll only use the first value. And it will only work for the "real" Types, which have a defined serialization scheme. But in principle it should work with all of those, which should cover most use cases.

Added the _uniqueHtmlId function: this is mainly useful for _QLButton patterns, where you often want to create a pair of a _QLButton and a div to show the results in, linked by the div's ID. If the button is based on a Thing, you could use its OID to create the div's ID, but otherwise it was a real problem. So this function deals very specifically with that: it simply generates a random ID that you can use for this purpose. (Obviously, you can use it for other purposes as well, but this is the only use case I currently know of.)

Four-space indent in QText is no longer interpreted as "code": one of the problems that has been plaguing the serious users has been that, if you indent your QText four spaces or more, it automatically goes into "code" mode, showing everything as fixed-width and ignoring the rest of the QText. This holdover from Markdown has been making it hard to build interesting pages. So I've tracked down the code that makes that happen, and disabled it. So this misfeature is now officially removed from QText -- if you need the "code" look and feel, surround it with triple-backticks, like this:
This is my code

Introduced the _groupGet() function: _groupBy() has been turning out to be one of Querki's more important and useful functions, and I use it a lot. But it has had a weakness: the only way to use the groups found is to iterate over them, in whatever order they happen to be in. That's often fine, but sometimes (as in the Documentation by Category page), you know what the expected keys are, and you want to pick the values out based on the keys.

Hence, _groupGet(). This receives the results from _groupBy, and takes one parameter, a key. It produces all of the elements that have that key. Thus, you can use _groupBy to split some Things up, and then use _groupGet to display them in the order you choose.

Login is now in-place: one of the more common annoyances, I've found, is that I go to a page, only to realize that I'm not logged in, but when I choose "Log in", it takes me to a separate screen so I lose my place. This is now reworked to catch up with the 2010s: login now happens in-page, so your workflow is preserved. (There is a known bug, that you have to press the "Log in" button instead of just hitting Enter to log in; I'll deal with that soon.)

_QLButton and _QLLink now have open/close affordances: thanks to metahacker for recently reminding me about the importance of affordances. This reminded me about the fact that *I* may be comfortable with the behavior of _QLButton and _QLLink -- in particular, the fact that clicking them once opens something up, and clicking again closes that -- but it's entirely opaque to the naive user. So I've added simple up/down arrows to make this a bit more obvious. It's not especially *pretty*, but it should make things clearer, and serves as a first pass fix.

This icon won't be shown if you are using the "append" or "replace" flags, or with _QLInput. You can manually suppress it in _QLButton/_QLLink by using the new "noIcon" parameter.

We are now using Bootstrap Modals instead of jQuery UI Dialogs: or in human-speak, the dialog boxes now look different. I have mixed feelings about whether the Bootstrap look-and-feel is better or worse than the jQuery UI one, but it *works* better, and lets me fix some long-standing bugs in the dialog boxes.

Note: I've encountered some edge cases with the new dialogs, where after using a dialog, you turn out to have lost your scrollbars. At this point, I understand the bug, and I *think* I've fixed it everywhere, but if you encounter this problem, please tell me ASAP.

The default Default View of Models and Things is now slightly clearer: not a dramatic change, but it now omits a few internal fields that you shouldn't ever care about, which were adding bulk with no benefit. And when displaying a Model, it separates the Instance and Model Properties, the same way as you see in the Model Designer.

Added the _usingSpace() function: this is a pretty obscure function -- I'm not sure anybody outside of system will care -- but it's available if you need it. This takes a Space as its parameter: either the current Space or one of its Apps. It alters the context so that that Space will be used for the rest of this QL phrase. Basically, it allows you to ignore everything in the "child" Space, and only use the contents of the App.


You now get a proper error if you try to go to a Space you can't read: there was a subtle bug, such that if you tried to navigate to Space thingy, with URL!thingy, and you weren't allowed to read that Space, you would get redirected to!thingy, and the client would hang at "Loading...". This one was actually a pain, relating to the way the stuff after the "#" is handled in the browser, but it should now properly redirect you to Index with an error.

_tagRefs now finds all references, not just the ones in ordinary Things: not something that the average user will hit, but as part of building the new Documentation by Category, I added Tags to all the Functions -- and discovered that _tagRefs wasn't finding them! So this now works as expected -- _tagRefs finds *everything* with the specified Tags, not just Things.

TextTypes can now be considered as ParsedTextType: that's generally meaningless to you, but the upshot is that many function parameters now work better than they used to. In particular, parameters that have previous only worked with text literals (such as the label parameter for _QLButton) now accept Properties as well.

  • 1
The new docs page is very snazzy!

I'd suggest/request an "Expand All Categories" button/link? I find page-search to be a faster and more reliable method of finding things in this sort of uber-list than categorization, because some functions deal with more than one concept. Eg: most of the list-manipulation functions are in Collection Manipulation, but _join is in Text, and _section is in UI and HTML. Also, if there's a function I already know the name of and just need to look up details of syntax, I have to scan-and-evaluate a long list of categories rather than just typing
CMD-F _bullet CR

(Speaking of which, I'd have guessed _bulleted and _commas would be under either "UI and HTML" or maybe "Text", not "Querki Core".)

I'd suggest/request an "Expand All Categories" button/link?

Interesting. Okay, I'll add a story for that. I'll have to think about how to make it work, which isn't obvious -- maybe some mechanism for labeling _QLLinks with a class, and a way to specify a button that activates everything with that class. That'll require some pondering; thanks for the suggestion.

(And I should note that the complete, alphabetized lists aren't going away. This is just an alternative way of getting to stuff.)

(Speaking of which, I'd have guessed _bulleted and _commas would be under either "UI and HTML" or maybe "Text", not "Querki Core".)

Roight -- makes sense. I'll make a note to move, or at least cross-index, those. (And now that I notice it, they need Summaries.)

  • 1

Log in

No account? Create an account