SupportArea

BoltWire is a FREE content management system written in PHP.

Its innovative architecture combined with best-in-class forms processing makes it ideal for creating complex, interactive, web applications fast...


Documentation

Markups
Variables
Conditions
Functions
Forms
Commands
Cheatsheet

Documentation

Handbook > Commands > Source

This command/function can be used to retrieve various kinds of information. In a form command it can take user input and then use the retrieved content elsewhere in the form. Or in a field, the content is inserted into the page. In both cases, the source function escapes the content. To insert content from another page into a page with the markup processed, use the include function. There is not an include command.

The form expects a page to be supplied, either using the page parameter, or by default the parameter in position 1. This command/function accepts pageshortcuts. Here's how the basic function works:

[(source some.page)]

This retrieves the content of the specified page and displays it escaped, in a code box. You can also retrieve a section of a page:

[(source some.pagesection)]

This returns the content between [[#section]] and the next anchor (or the end of the page). You can also retrieve specific lines:

[(source some.page lines=5)]
[(source some.pagesection lines=3-5)]

I can also use this to function to extract a data or info var:

[(source some.page:datafield)]
[(source.some.page::infofield)]

In fact I can even do the following:

[(source some.page::infofield::1)]
[(source.some.pagesection::infofield)]
[(source.some.pagesection::infofield::1)]

The first retrieves part one of the infofield value. The second only retrieves it, if it exists in the specified anchored section. The third returns part one if the info value is set in the anchor.

A user must have view permissions for the page to retrieve content, and also appropriate info and data permissions for those vars.

You can set escape=false if you wish, though normally that is turned on. You can also retrieve content from stamp pages by setting dir=stamps.

Source in Forms

Source can be a very powerful command in forms because it can retrieve different data based on user input. Notice this simple example:


[form]
[radio id bob] Bob   [radio id dave] Dave   [radio id joe] Joe
[submit]
[command source ~{=id}:color]
[command passdata source]
[form]

{?source}

The user selects a user. Source retrieve the color data value from their member page (using page shortcuts). That value is passed back to the pages as a get value when the form is submitted. And when the page reloads, the get variable picks it up and displays it.

Lines

Suppose you had the following section defined on a page showing off some BoltWire markup rules:


[[#demo]]
//italics//
**bold**
__underline__
[[#end]]

The source is returned to the page exactly as it appears in the original without any markup processing--meaning line returns will not be converted to line returns in the html causing the output to be all jumbled together. This is probably what you want in most cases. But if you want to display the source (like the source action, or code pages), simply set fmt=lines and they will be artificially inserted. You can also wish to wrap the function in the <box> markup to show that it is source code. Compare the two


<(source {p}#demo lines=3)>
----
<(source {p}#demo lines=3 fmt=lines)>

//italics// **bold** __underline__


//italics//
**bold**
__underline__


If however you are retrieving content from a page to prefill an edit box for example, you do not want fmt=lines, as the HTML that generates the lines will appear in your textarea. Notice how the second example inserts HTML code that will end up getting saved if the edit form is submitted:


[box rows=5 cols=40]<(source {p}#demo lines=3)>[box]
[box rows=5 cols=40]<(source {p}#demo lines=3 fmt=lines)>[box]



Request Values

Source can do even more. If you set a post, cookie, get or command parameter to some field (in that order) source will try and find those fields. If successful it returns the first one it finds. So, the following two lines are roughly equivalent:

[(source post=name cookie=name get=name)]
{?name}

Both look for all three values in the same order (regardless of the order of the parameters in the function).

The source function, however can keep looking for values, like regular page content. This allows for a very nice feature for forms. Consider the following form:


[form]
[box content rows=10 cols=60]<(source some.page post=content)>[box]
[submit]
[command passdata content mode=post]
[command warn true]
[form]

When the page is first constructed, no post value is found, so source goes on to load the content of some.page into the input box. Presumably, the user edits it and makes some changes, and clicks submit. Passdata sets up the post value to be submitted back to the page. (This line has to be before the warn command). Then warn aborts the form. The page reloads and source finds the post value and inserts those changes ito the content box instead of the source from page some.page. In other words, it allows me to preserve my edits.

In the real world, the form would be designed to save the changes on some.page, and only abort because the user failed some test. This approach would then preserve his edits until he can fix his mistakes and finally save his work. The same technique could be used in other kinds of input fields.