Previous Entry Share Next Entry
Release 1.1.5
jducoeur wrote in querki_project
Another release of little useful tidbits that I've always known I'd want sooner or later.

There is now a _random function. Note that, unlike most software libraries, this is not a math function. Instead, I've cut to the chase and implemented the function you are most likely to need this *for* in Querki, which is choosing something randomly.

It's best illustrated by example, in this case from my Poker encyclopedia's new Random Game page:
[[Variant._instances -> _random -> Summary]]
That is, from all the Instances of "Variant" (that is, Poker variations), choose one randomly and show me its Summary. This should make it nice and easy to build "give me a random Foo" pages like this.

(And yes, this was inspired by getting to 9:30pm in our Monday-night poker game, deciding that I was too damned tired to choose a game from the myriad of them I have in the Poker Space, and saying, "This is what I have computers for!".)

You can now add captions to photo carousels. That is, each photo can show an overlay caption. (This was needed for Kate's Cross-Stitch Gallery -- one of her firm requirements is that photos of projects should be accompanied by their copyright statements.)

The UI part of this is built into Bootstrap, but making it work in Querki is still a bit exotic. It involves the new Image Caption property, and the new _withProperty() function. _withProperty tacks an additional Property value onto a structure (a value from a Model Type Property such as a Photo) that you pass into it, like this:
[[My Photo -> Image Caption._withProperty(""I'm a caption!"")]]
If you display a List of those, the caption will show up over the photo.

This is still something of a pain to use in practice, mostly because the QL language doesn't yet support closures and lambdas; I find that I need to write separate functions to get the effect I want. Eventually, this will be easier.

The _propLink function is now working again. I'm counting this as an enhancement rather than a fix because it is more that it hadn't been re-implemented in the new Client yet. _propLink is a neat little feature that helps you use multiple "views" of the same Thing. For example, the front page of the Issue Tracking Space has several variants showing things like Issues sorted by Modification Time or All of the Closed Issues. If you look at their URLs, they are all referring to the same Thing, but have "?prop=something" appended. That something is the name of a Large Text Property, specified like this:
[[Closed Issues._propLink -> _showLink(""Closed Issues"")]]
That is, _propLink takes the named Property, and produces a link that will show *that* Property on this page. Closed Issues._propLink produces a link that, if clicked, will show the value of "Closed Issues".

It's not a huge thing, but it can be very convenient in various ways. For example, the Poker Space's front page has a long introduction, which is contained in the Introduction Property. Normally, that's simply shown in-page, but if you're on a phone (an "extra-small" screen), it is hidden and a link to that Property is shown instead, with this code:
**[[Introduction._propLink -> _showLink(""Introduction"")]]**
That is, the first clause (which simply shows the contents of Introduction right here) is hidden on an extra-small screen and shown otherwise; the second clause (which shows a link to the Introduction) is visible on an extra-small screen and hidden otherwise.

This latter bit of magic, BTW, isn't Querki per se -- it's just one example of the thousand wonderful things that you get because Querki has Bootstrap built into it. Being able to tweak your look-and-feel for different screen sizes is one of the most important features of Bootstrap, and I highly recommend using it in your Spaces.

_concat() now gives a more useful error message if you try to concatenate different types together. In general, if you come across a cryptic / unhelpful error message in Querki, please tell me about it. I've built the pathways so that I *can* write helpful error messages in most cases, but I don't always think to do so.

  • 1
What would you think of calling _random something like _choose instead, in case you need random later? (Twine calls this "either", which is somewhat confusing too.)

Hmm. I don't love "choose" -- it has connotations of deliberate choice that are pretty much the opposite of what this is doing.

I'll ponder changing it, but I think it may be the right name, and I *think* it's much more important than the inevitable math version. Versions, really, and that is suggestive that the eventual math functions likely want to be _randomInt(N) (which chooses a number from 0 to N) and _randomFloat (which chooses a float between 0 and 1) anyway.

The inconsistency from library to library on this point always drives me crazy anyway -- I can never keep straight which one "random" means. Between that and the fact that this version is probably *much* more frequently useful for typical Querki use cases (note that Querki doesn't have *any* math functions yet, which tells you something about where its focus lies), I suspect I'll want to spring for the longer names for those, and use the shorter one here.

All guesswork at this point, but that's my initial gut instinct...

Thinking about it further: I don't like _choose, but it occurs to me that Twine's version *ought* be named "any", and that's not a terrible option -- the connotations feel more correct to me. I'll ponder that...

You might consider "whatever".

Heh -- that has its own connotative issues. When I think of the common usage of "whatever" nowadays, it has connotations of, "This doesn't matter, and why are you bothering me about it?"

Literally, it makes some sense, but I suspect it's not quite right...

  • 1

Log in

No account? Create an account