How to create or change Things with a button-click
Most data entry in Querki is done directly in the UI -- you create or edit Things by pressing the standard buttons for those purposes.
But sometimes you want to do something more automated -- for example, have a button that creates and pre-populates a Thing using some standard Properties, or which makes some standard changes to a Thing. For these cases, we have the _createThing() and _changeProperties() functions.
_createThing
_createThing takes one required parameter (which should come first): the model = parameter, which tells Querki which Model this new Thing is based on.
After that, you make provide any number of Property Value Setters: the name of a Property, followed by parentheses containing the value to put in that Property.
So for example, say you had a simple Querki Space consisting of (music) Albums and their Artists. Album has a Performed By Property, which is a List of Artists.
Now, say that you wanted to add a button on Artist, that added a new Album for this Artist. That would look like this:
[[_QLButton(label = ""Add Album"",
ql = _createThing(model = Album, Performed By($_context)))]]
Looking at that in detail:
_QLButton() displays a button that can do something. The label says what the button should display; the ql says what to do when somebody presses it._createThing() is going to go create something; model = Album says that it'll be an Album.Performed By($_context) sets the Performed By Property to the current "context" -- typically, the page that you are looking at, which is the Artist.
Doing Something With the Thing
As shown above, when you press the button, it will simply show a link to the newly-created Thing. That works, but isn't usually what you want. There are a couple of common options.
Edit in Place
If you want to show an editor for the newly-created Thing, finish you QL phrase with -> _edit:
[[_QLButton(label = ""Add Album"",
ql = _createThing(model = Album, Performed By($_context)) -> _edit)]]
That passes the newly-created instance to _edit, and displays the Instance Editor right here.
Navigate
On the other hand, you often want to go to the newly-created Thing. For that you use _navigateTo:
[[_QLButton(label = ""Add Album"",
ql = _createThing(model = Album, Performed By($_context)) -> _navigateTo)]]
This will immediately change pages to the newly-created Thing.
_changeProperties
The _changeProperties is similar to _createThing, but it should receive an existing Thing, and says what to do with it.
For example, say that our Album had a Property named Number In Stock; we want to create a Sold button that reduces Number in Stock. That would look something like:
[[_QLButton(label = "Sold", ql = _changeProperties(Number in Stock(Number in Stock -> _minus(1))))]]
As with _createThing, you often want to do something with the changed Thing. Most often you just want to redisplay it, which you do with _navigateTo:
[[_QLButton(label = "Sold", ql = _changeProperties(Number in Stock(Number in Stock -> _minus(1))) -> _navigateTo)]]
