This page is an overview of the various ways you can reference stuff from one place in an Informl wiki to another place in the wiki. This page uses terms like pages, books, and fields, and if you aren't familiar with them, you should take a look at the wiki organization.
The referencing in Informl is evolving. Many of the basic referencing schemes are in place, but there are currently some 'holes'. These holes, although not implemented yet, are documented in the "Future Plans" section.
Some of the examples of wiki mark-up on this page refer to the content in the Wine Store Example book in this wiki. The following is a short overview of how it's organized:
Book name: Wine Store Example
Page: regions
Fields: name
Page: wineries
Fields: name, region (the values come from the regions page)
Page: wines
Fields: name, wine_type, year, winery (the values come from the wineries page)
Page: inventory
fields: wine (from wines page), on_hand, cost, date_added
Generally, the examples here assume you are editing pages in the wine book.
The general format for references is actually explained near the end of this page, whereas the following sections show you specific examples of how to use the reference mark-up and build up to the general format.
You can create a link to another wiki page within the same book. Here are some examples.
This will link to the page "regions" and will display the text "regions" as the link text.
[[regions]]
This will link to the page "regions" and will display the text "The wine regions of Australia".
[[regions | The wine regions of Australia]]
On any given page, you can reference the data from another page with a field reference.
For any given reference, there must be a unique submission ID available. You can make the ID available in one of 3 ways:
<<iterate>> block?submission_id={id} parameter as part of the page URLThere also must be a page name available to the reference, and there are 3 ways it can be supplied:
{base page}:extension, the page name is taken as the base pageThe examples in this section show how <<iterate>> and scoping can be used to provide the submission ID which hopefully will make sense as is, but don't worry too much if this doesn't make sense right away, because there are sections below that explain more about both of these types of mark-up.
Here are some examples of how field references can be used.
This creates a bullet list of all the wine regions filled in for the regions page.
<<iterate regions>>
* [:name:]
This is replaced with the name of the 3rd wine region.
[:(id=3)name::regions:]
This does the same thing but on the "regions:result" page which assumes the page context is "regions".
[:(id=3)name:]
And this does the same thing but from another book in the wiki.
Rutherglen
An iterator loops over all or some of the submissions to a particular page. You can use page references to get information from a different page and scoping to limit the submissions you want to iterate over.
The following iterate on the wines:result page would create a list of all the wine names.
<<iterate>>
* [:name:]
This does the same thing from another page.
<<iterate wines>>
* [:name:]
This lists the names of all the red wines.
<<iterate (wine_type=Red)wines>>
* [:name:]
This creates a table showing the name, year and winery for all the red wines.
[ !Name|!Year|!Winery| ]
<<iterate (wine_type=Red)wines>>
[ |[:name:]||[:year:]||[:name.winery:]| ]
Scoping is a general way of limiting which submissions to a page you are trying to access. The simplest form is (id=1) or some other number, which restricts the reference to one specific submission. We saw the following example earlier for getting the 3rd name submitted to the regions page:
[:(id=3)name::regions:]
In general, the scope is a comma separated list of {name}={value} pairs such that each of the pairs have to match to for each submission to be included.
So, we can create an iterate that lists all the red wines from 1998 as follows:
<<iterate (year=1998, wine_type=red)wines>>
* [:name:], _[:name.winery:]_
You may have noticed the use of the [:name.winery:] reference in the Iterator and Scoping sections above. It means "show the name of the winery where the winery is defined by a submission to the wineries page". If you are familiar with database lingo, this is basically a join.
Why do you need these cross page references? Well, if you just use [:winery:] from, say the wines:summary page, you will get the numeric ID of the winery and not its name, so you need some way to get the name. In the same fashion, you could use [:year.wine:] from the inventory:summary page to get the year a wine was bottled.
You can chain things further. For instance, from the wines:summary page, you could get the name of region of the winery with [:name.region.winery:].
Here are couple of examples for how you can use cross page references.
Get the name, region, cost, and number on hand for the third wine in the inventory
[:(id=3)name.wine:] from [:(id=3)name.region.winery.wine:] [:(id=3)on_hand:]@[:(id=3)cost:]
Or do the same thing with an iterate to save typing.
<<iterate (id=3)>>
[:name.wine:] from [:name.region.winery.wine:] [:on_hand:]@[:cost:]
You can create a drop-down list consisting of the elements of another page. For instance, if you wanted to create a drop-down of all the region names from the submissions to the regions page, you would use:
<<refers_to name::regions>>
This would create a drop-down field in the current form.
When you submit a form, by default you end up on the results page ({page}:result). To mark up the submit button for that case you can use:
((send))
If instead you want to be taken to the inventory page, you would use:
((inventory|send))
Notice that this is very much like the wiki link syntax with the page destination as the first element followed by the display text but with parentheses instead of square brackets. Also note, though, that if there is no "|" that the text in the mark-up is the text of the button and the location is defaulted which is the reverse of the sense of a wiki-link.
You can insert the text of one page into another page using an include mark-up. So if you wanted to include the text of the 'message of the day' page into the page you are editing, could use:
{{message of the day}}
Be careful including pages that have form content; currently, doing so will end up defining the fields in the current page and possibly creating a new form. In the future, including a page (that contains a form) will display an independent form -- making it possible to have more than one form in a page.
In general, references from one place in the wiki to another have the following overall format:
({name1}={value1},{name2}={value2}){field name n}...{field name 2}.{field name 1}::{page name}::{book name}
That's a bit daunting, but the examples in the earlier sections of the page should help show that references are usually pretty simple. The overall syntax allows for a lot of flexibility, all of which is seldom needed at the same time.
There still some bits missing in how the overall referencing scheme is implemented. All the 'holes' and "not quite right" elements are recorded here. Hopefully this section will get sorter (and maybe go away) fairly soon.
Here are some specific mark-up cases that don't currently work:
[[page name::book name | link text]]
{{page name::book name}}
(()) -> <input type="submit">
[[(id=42)"page.ref.field"."page.name"::book name]]
[[wines#section name]]
<<refers_to (year=1999)name::wines>>
We'd like a more general format for creating form elements whose content comes from another page. Here's what we've come up with:
<>[:field name:] dropdown list
()[:field name:] radio button set
[][:field name:] check-box set
{}[:field name:] multiple selection
The intention here is to be able to specify the type of the selection along with the previously described field reference scheme. This assumes that the field placed in the form would automatically be set to {pagename}_id and the <option> elements of the <select> statement would have a value equal to table row ID of the item and the body would be the text of the field name.
So a drop-down list specifier might look like
<>[:name::regions:]