Fwd: Quick Question
1 view
Skip to first unread message
Ethan McCutchen
Dec 15, 2009, 1:50:10 PM12/15/09
to wagn...@googlegroups.com
Peter Kindfield sent this well-framed question and gave me permission to send my reply to the group. I thought it might fill in wholes for some folks who've seen this syntax and wondered how the "magic" happened.
Peter's original question:
~~~~~~~~~~~~~~~~~~
--
Ethan McCutchen
One of the Wagneers, Wagn.org
Patterns. They're not just for quilting anymore.
Peter's original question:
~~~~~~~~~~~~~~~~~~
Quick question...What does {{+*type cards}} mean?Parts of question...1) Why the double curly brackets? include and search?2) What does + mean in this context3) What does the * mean in this context?4) What does *type mean in this context?5) What does cards mean in this context?
~~~~~~~~~~~~~~~~~~
My response (with a little polishing):
~~~~~~~~~~~~~~~~~~
The double curly brackets just mean include. (See http://www.wagn.org/inclusion.) This is using the simplest inclusion syntax: {{cardname}}.
This simple symbol may be one of the most important and worst documented features in all of wagn. It is part of a "relative name", meaning that it's a short cut for a longer cardname. If, for example, you're on the card named "Ethan" and you link to or include "+address", then the full name of the card you're linking to or including is Ethan+address.
Editor's note: Peter replied "Got it... an initial + simply means the following card name is plussed to the current card... right?" Yep, that's it exactly, but better put than mine. :)
The reason relative names are important is that they open up the possibility of formatting cards based on their names. For example, I can set it up so all the users have a +address card on their own card (yours might be Peter+address) and then adjust the formatting on all the +address cards. These naming patterns let you to preserve the wiki principle of "unique names" for every card without having to spend most of your time thinking of (or typing) new names.
So, with respect to the original question, if you're on the cardtype card for, say, "Basic", then {{+*type cards}} is functionally equivalent to {{Basic+*type cards}}.
We call these cards "plus cards", and they each have a left and right part, each of which is also associated with a card. If you have a card with multiple plusses (eg. X+Y+Z), then the right is what comes after the last plus (Z), and the left is the rest (X+Y).
These three go together. They're all just part of a cardname -- it's not syntax. The key question is, where does this card called "Basic+*type cards" come from?
The answer is that this card is created dynamically. It is a virtual card. In fact, if you go to "Basic+*type cards" you will see that it looks just like a normal card, except that it has "virtual" in the upper right corner; you can't edit it.
This "virtual card" is created dynamically by combining two "real" cards: Basic and *type cards. When added together, they create a Search card (here's where the search part comes in) that searches for all of the Basic cards. How does that work? With forms.
Before I explain, let me tell you that this is about to be simplified somewhat, but here's the current state of things. There are two kinds of forms: type forms (cards ending in +*tform) which format cards of a given type, and right forms (cards ending in +*rform) which format cards ending with a given card on the right. So while User+*tform formats all User cards, address+*rform formats all cards ending in +address. With the combination of these two forms, we can build all kinds of neat structures.
There is another way forms can be divided into two types: hard and soft. Soft forms control a card's initial content but don't affect formatting thereafter. Hard forms permanently control the layout of the content of a card. If User+*tform is a hard form, then changing it will change every User card. If it's soft, it will only affect cards created in the future.
How does all of this relate to virtual cards? If I go to the url for a hard right form and the card doesn't exist, Wagn will create a virtual card for me. So, in the current example, there is a hard right form card called *type cards+*rform . That's all Wagn needs to know to create a card for us.
Now, *type cards+*rform is a Search card, and its content is {"type":"_self"}. "_self" is another example of a relative name. In the Search card Basic+*type_cards, _self refers to "Basic". So when WQL runs, it performs the search {"type":"Basic"}.
I just want to note one last thing. *type cards+*rform comes with Wagn on new installs, but there's nothing inherently special about it. The code doesn't know anything about the name "*type cards". You can build new virtual cards on your own, or change the ones built in (for example, you can add ,"sort":"name" to *type cards+*rform to make it order alphabetically. however, we have also included "by name+*tform" so that you can go to Basic+*type cards+by name as a simpler way :) Having fun yet?
The '*' is just a naming convention we use with most of the cards we provide on installation to keep them out of the shared namespace, so that people can create, say "layout" as a normal card that doesn't conflict with the functional "*layout" card. '*' is a little special in that it is the only nonalphanumeric character used in keying the cards, so while Peter, PETER, peter, peter!, peter@#$, and (peter) would all resolve to the same card, *peter would be a different one. But it has no functional meaning.
-ethan
My response (with a little polishing):
~~~~~~~~~~~~~~~~~~
1) Why the double curly brackets? include and search?
The double curly brackets just mean include. (See http://www.wagn.org/inclusion.) This is using the simplest inclusion syntax: {{cardname}}.
2) What does + mean in this context
This simple symbol may be one of the most important and worst documented features in all of wagn. It is part of a "relative name", meaning that it's a short cut for a longer cardname. If, for example, you're on the card named "Ethan" and you link to or include "+address", then the full name of the card you're linking to or including is Ethan+address.
Editor's note: Peter replied "Got it... an initial + simply means the following card name is plussed to the current card... right?" Yep, that's it exactly, but better put than mine. :)
The reason relative names are important is that they open up the possibility of formatting cards based on their names. For example, I can set it up so all the users have a +address card on their own card (yours might be Peter+address) and then adjust the formatting on all the +address cards. These naming patterns let you to preserve the wiki principle of "unique names" for every card without having to spend most of your time thinking of (or typing) new names.
So, with respect to the original question, if you're on the cardtype card for, say, "Basic", then {{+*type cards}} is functionally equivalent to {{Basic+*type cards}}.
We call these cards "plus cards", and they each have a left and right part, each of which is also associated with a card. If you have a card with multiple plusses (eg. X+Y+Z), then the right is what comes after the last plus (Z), and the left is the rest (X+Y).
3) What does the * mean in this context?4) What does *type mean in this context?5) What does cards mean in this context?
The answer is that this card is created dynamically. It is a virtual card. In fact, if you go to "Basic+*type cards" you will see that it looks just like a normal card, except that it has "virtual" in the upper right corner; you can't edit it.
This "virtual card" is created dynamically by combining two "real" cards: Basic and *type cards. When added together, they create a Search card (here's where the search part comes in) that searches for all of the Basic cards. How does that work? With forms.
Before I explain, let me tell you that this is about to be simplified somewhat, but here's the current state of things. There are two kinds of forms: type forms (cards ending in +*tform) which format cards of a given type, and right forms (cards ending in +*rform) which format cards ending with a given card on the right. So while User+*tform formats all User cards, address+*rform formats all cards ending in +address. With the combination of these two forms, we can build all kinds of neat structures.
There is another way forms can be divided into two types: hard and soft. Soft forms control a card's initial content but don't affect formatting thereafter. Hard forms permanently control the layout of the content of a card. If User+*tform is a hard form, then changing it will change every User card. If it's soft, it will only affect cards created in the future.
How does all of this relate to virtual cards? If I go to the url for a hard right form and the card doesn't exist, Wagn will create a virtual card for me. So, in the current example, there is a hard right form card called *type cards+*rform . That's all Wagn needs to know to create a card for us.
Now, *type cards+*rform is a Search card, and its content is {"type":"_self"}. "_self" is another example of a relative name. In the Search card Basic+*type_cards, _self refers to "Basic". So when WQL runs, it performs the search {"type":"Basic"}.
I just want to note one last thing. *type cards+*rform comes with Wagn on new installs, but there's nothing inherently special about it. The code doesn't know anything about the name "*type cards". You can build new virtual cards on your own, or change the ones built in (for example, you can add ,"sort":"name" to *type cards+*rform to make it order alphabetically. however, we have also included "by name+*tform" so that you can go to Basic+*type cards+by name as a simpler way :) Having fun yet?
The '*' is just a naming convention we use with most of the cards we provide on installation to keep them out of the shared namespace, so that people can create, say "layout" as a normal card that doesn't conflict with the functional "*layout" card. '*' is a little special in that it is the only nonalphanumeric character used in keying the cards, so while Peter, PETER, peter, peter!, peter@#$, and (peter) would all resolve to the same card, *peter would be a different one. But it has no functional meaning.
-ethan
--
Ethan McCutchen
One of the Wagneers, Wagn.org
Patterns. They're not just for quilting anymore.
Ethan McCutchen
One of the Wagneers, Wagn.org
Patterns. They're not just for quilting anymore.
--
Ethan McCutchen
One of the Wagneers, Wagn.org
Patterns. They're not just for quilting anymore.
Reply all
Reply to author
Forward
0 new messages