Collections and Types
In the previous section, we showed how to create a new Property, but glossed over the concept of Collections and Types, saying that you need to set them but not what they are. Let's get into that now.
Types
Each Property is mostly defined by its Type and its Collection. The Type is the more straightforward: that says what kind of Property this is. It is easiest to understand Type with some examples of the most commonly-used Types:
- Whole Number -- as it says, a number with no fractional part. (What programmers call an "Integer".)
- YesNo -- a Yes/No, true/false value. (What programmers call a "Boolean". Yes, I gave up on coming up with a better name.)
- Text and Large Text -- a block of text. The only real difference between these is how much text: Text means a one-liner, usually just a word or phrase, whereas Large Text is intended for one or more paragraphs.
- Link -- a link to another Thing.
- Tag -- a tag, which can also be thought of as the name of a Thing.
There are a bunch of other Types built-in, and you can essentially define your own Types (that's what the "Base it on a Model..." drop-down is about in the Create a New Property panel), but 95% of the time, you want one of those five. Indeed, you will probably find that you mostly care about Text, Large Text, Link and Tag -- you can do an amazing amount with just those. We'll be talking more about each of them in later sections here.
Collections
The Collection is a little less obvious, especially to programmers who have been trained to assume that you always have one of something unless stated otherwise. That's not true in Querki: you have to explicitly say how many of each Type you want. There are four possible Collections at this point:
- Exactly One -- the default Collection, this means that, yes, there is always exactly one value of this Type in this Property. It's important to understand this properly: if you say that a Property is Exactly One, that means it is not possible for it to be empty. Even if it looks empty, there is a value there: for example, if you define an Exactly One Text Property and don't put anything in it, it's still a Text value, that just happens to have a length of zero. This is often what you want, but it often isn't, which is why Querki forces you to think about it.
- Optional -- this means that this Property may contain a value of this Type, or it may be empty. (What is often called "Option" or "nullable" in programming and databases.) This is the right answer at least as often as Exactly One, and you should always ask yourself whether this Property should be Exactly One or Optional.
- List -- as you'd expect, this means that this Property contains a list of values of this Type. A List is always ordered -- you decide on the order explicitly, dragging and dropping values into the order you want -- and may contain duplicate values. There is in principle no limit to the length of a List. (Although we haven't tested with really long ones yet, and we don't yet have a good UI for them.)
- Set -- this is similar to a List, but different in some important ways: a Set means a collection of values of this Type that is not ordered, and which may not contain duplicate values. You will find that Tags should almost always be in Sets, and Links often should. In general, Set is more often the right answer than List -- use List only if you care about the order.
Editing
The user interface for editing a Property depends on both its Type and its Collection. Sometimes, the Collection affects the editing in subtle ways, sometimes in dramatic ones. One of the subtle ones is when editing a Text or Whole Number Property and leaving it blank. If the Property is Exactly One, that means that this is a Text with a length of zero; if it is Optional, that means it is actually empty, and there is no value there. This is why you want to choose carefully between Exactly One and Optional -- ask yourself, "Does it make sense for this Property to be completely empty?" If so, you usually want Optional; if not, Exactly One.
YesNo editing actually changes dramatically between Exactly One and Optional. An Exactly One YesNo Property shows up as a checkbox: it is yes/true if it is checked, no/false if not. But what does "empty" means in that case? So an Optional YesNo Property instead shows up as three radio buttons, marked Yes, Maybe and No. "Maybe" is the empty state, reflecting that you haven't given it a value. (Yes, we'll probably add a mechanism to change these labels for a particular Property eventually; yell if it really matters to you.)
The most special editing UI is for editing Sets of Links or Tags. Remember way back in
Editing Things, when we showed the Owners Property, and the way that the system would prompt you when you started typing?
This is what shows up for Sets of Links of Tags. If it is a Set of Links, it will prompt you with the Things of the correct Model whose names match what you are typing. If it is a Set of Tags, it will prompt you with the Tags you have already used that match the typing. This is part of why Links and Tags are usually best used in Sets, unless you have a specific reason to do otherwise. Indeed, it is uncommon to use Links with Collections other than Set, and you almost always should use Tags in Sets. (You can define a Property that is an Optional Tag, but it usually proves to be wrong in retrospect.)
So now, let's begin to dive into the various Types, and talk more about them...
