Previous Entry Share Next Entry
Release 0.4.5: Important changes to handling of Names
jducoeur wrote in querki_project
(This one's actually pretty major -- I recommend all current Querki users give this a read. Oh, and sorry for today's 20-minute downtime. I try to keep the downtime under a minute, but I caught a bug just after things went live, which had the potential to corrupt data, so I shut the system down rather than risk anybody losing anything.)

Name and Display Name

Today's release includes some minor enhancements, discussed below, but there's one really major one -- we are de-emphasizing the Name Property, in favor of Display Name.

A Little History: Querki has always had two distinct concepts of "name". On the one hand, there is Name, which is used for QL and URLs, and which has a highly restricted character set. And then there is Display Name, which lets you type nearly any bloody thing you please. The Programmer in my head has been in pitched battle with the UX Designer in my head for about six months, over the relationship of these Properties.

At first, the Programmer reasoned that Name was clearly the more important field, since it is used in Big Official things like QL and URLs. Display Name was simply a detail: a way to occasionally provide an alternate name that had things like apostrophes in it.

Increasingly over the past few months, though, the UX Designer has been pointing out that the resulting workflows suck sharp flinty rocks through a straw. Characters like apostrophes, dashes and quotes turn out to be so common as to be more the norm than the exception. As a result, I've increasingly been using Display Name on my Things, and ignoring Name entirely -- with the result that the Things have consistent-but-unpretty URLs based on the OID (the one field that *always* exists) instead. Soooo...

The Change: Display Name has now been put front-and-center, with Name relegated to being an implementation detail. Whereas the Editor used to show Name at the top of each new Thing, it now shows Display Name. Indeed, Name is deliberately suppressed most of the time.

Instead of specifying Name explicitly, you usually let it be derived, based on the Display Name. There's nothing complicated here: the system strips out all characters except alphanumerics and spaces, and uses the result as the Name. If that Name is already taken, it adds a number to the end. (Since Names must be unique within a given Space.)

The _deriveName Property: In general, I think the new behaviour should Just Work most of the time, and I hope folks will like it. That said, there are some tradeoffs involved, so I've added a new Property, available on all Things, called _deriveName. It has three possible values:
  • Derive Name Initially is the default, and I think strikes a good balance. When you create the Thing, the system will derive a Name for it based on the Display Name; after that, it will leave the Name alone. This option means that you will get an initially-sensible Name, which is stable to refer to. (That is, URLs and QL references pointing to this Thing will stay good, even if you change the Display Name.) I believe this is usually optimal, but it *does* mean that the Name can get wildly out of synch with the Display Name over time.

  • Always Derive Name: this is the really aggressive version -- every time you change the Thing's Display Name, it will change the Name to match. This means that the Name is highly predictable based on the Display Name, so in a sense it is easier to understand. But it means that, if you change the Display Name, references to this Thing may stop working. (Specifically, the URL of the Thing may change, QL references to it may break, and Tag references to it may break. Links to it will *not* break -- Links go by OID instead, and that never changes.)

  • Never Derive Name: this is the dumbed-down manual case, more like the old behaviour. If this is set, it will never try to derive the Name automatically. With this set, you can add the Name Property explicitly, and edit it by hand. This is the way to go if you need to change the Name to something specific. (Which I expect to be an edge case, but will probably be occasionally necessary.)
Note that none of this takes effect until you next edit the Thing -- until then, nothing will change.

To make this a bit easier to work with, I've added the Name to the subheader, underneath the title, when you look at a Thing. It is labeled "Link Name", and I might well change "Name" to that, to emphasize that this is the name that you want to *point* to. It is clickable, and provides a way to get to the version of the URL that uses the Name. (Matching the OID that was already there, which gets you to the URL that uses the OID.)

Note that, for the time being, you officially can't change the Name of a Space. That will change in the future, but that was the aforementioned bug: it turns out that the new mechanism interacts *horribly* with changing the name of a Space, so it simply does nothing for now.

Play around with this, and please tell me if you find bugs or seams. This is a sufficiently major change that I would be honestly surprised *not* to find some bugs. I've already hypothesized a few.

For example, I'm fairly sure that this change will completely hose Unicode support -- if you enter a Display Name in, say, Cyrillic, the only characters that will be legal are the spaces, so you will probably end up with an error for an illegal Name. I've already entered a bug for me to investigate this, and I suspect that it will result in me changing the rules for Names. Currently, we whitelist a very small number of characters that are legal in Names; I suspect that, for internationalization to work properly, I need to instead blacklist the characters that are *not* legal -- mostly the punctuation and control characters. Expect a fix for this in the not-too-distant future.[ETA: huh -- no, it actually just works. Looks like the isLetterOrDigit() function I've been using has an appropriately expansive definition of "letter". There's a bug in the URL it sends to right after creating the Thing, but the Thing itself looks fine. Excellent!]

Other recent changes

The other changes and fixes over the past few days include:

The _class Function: I'm currently helping a friend with a use case that is going to demand fairly precise formatting, and I found that, while the {{style:...}} mechanism works in *most* cases, it doesn't always cut it. For some experiments, I really wanted a way to assign a CSS class to a *specific* HTML element (in particular, the input elements generated by the _edit function), instead of just wrapping it in div or span.

So I've added _class, as sort of the QL version of QText's {{}}. You use it like this:
[[My Thing -> My Property._edit -> _class(""myClass"")]]
That is, _class receives an HTML value, and adds the specified classes to it. It is mainly designed for use with _edit for now, but you can also use it with any Text block that generates a *single* HTML element:
[[""This is my paragraph"" -> _class(""style1 style2"")]]
Please don't expect too much from this yet. It explicitly does not work with complex Text blocks -- if you try to feed it multiple HTML elements, it will choke. (I hope to fix this, but that's going to require some major rewrites of the internal data chain.) For now, consider _class experimental.

Deprecate Simple Page: as mentioned a while ago, I've concluded that the distinction between Simple Page and Simple Thing was *way* too subtle, and is just complicating people learning the system. So I have squished them together: Simple Page now inherits from Simple Thing, and Simple Thing has picked up the Default View Property that was previously on Simple Page.

I also added a new flag Property, Deprecated. I suspect that in the long run this will be a very useful tool for both the system and more complex user Spaces, but for now it just does one thing: when applied to a Model, that Model is no longer listed in the "Create any Thing" dialog box. The semantics of Deprecated are essentially, "You shouldn't create any more of these, and it would be nice if you moved away from them, but for now Things that use it will continue to work." Simple Page is now Deprecated, and won't be offered any more -- when in doubt, you should usually just use Simple Thing.

Feel free to suggest other places where Deprecated should affect the UI -- I suspect there are at least a dozen ways in which it would be useful. (Changes that will affect the now-Deprecated Simple Page are particularly relevant, and will be higher priority.)

Added the Features Tag to the Issues Space: folks who are logging Issues should note that there is now a new field, Features. This is a Tag Set of which "features" each Issue is associated with. Please don't invent new Features without checking with me first. You can see the Features that I have defined so far on this new page. (The list will get much, much longer over time.)


Log in

No account? Create an account