{page}

Renders another page of the application - its PHP and its template - in place of the tag.

Pages and execution Single tags

Syntax 

{page 'dir/name'}
{page 'products/42'}
{page 'name', include=false}
{page 'name', sandbox}
{page 'name', reset}
{page 'name', clean}
{page 'name', function='name'}
{page 'name', app='other', ajax=false}

Parameters

page
The page, named from the application root as in a URL - 'orders/list'. A directory is its index, a .html page counts, and a clean URL route binds its segments: 'products/42' renders products/[id].pad with $id set.

Options

include
Whether the page renders bare. TRUE by default - the _inits.pad/_exits.pad wrappers are left out; include=false wraps it as a request would.
sandbox
Bare option: the page runs isolated - it sees none of the variables and stores of the page around it, and leaves none behind.
reset
Bare option: the level arrays and the stores are cleared for the pass and restored after it; the application's variables stay visible.
clean
Bare option: the page sees everything around it, but whatever it creates or changes is undone afterwards.
function
Runs the page inside a PHP function of that name, so its PHP has a scope of its own; what it creates is copied out unless sandbox is given too.
app
A page of another application. It cannot be built in this process, so it is fetched over HTTP - by the browser by default (as {ajax} does).
ajax
With app=: ajax=false fetches the other application's page on the server and inserts its body instead of leaving it to the browser.

Description

{page 'name'} builds another page of the same application in a nested engine pass and puts its output where the tag stands. It is not a second request: the page's PHP runs in this request, its template renders, and the result is the tag's value. The page is named from the application root, as in a URL, and resolved as the router resolves one - a directory means its index, a .html template counts, and a clean URL route binds its segments, so {page 'products/42'} renders products/[id].pad with $id set to 42.

By default the page renders bare (include is TRUE): the _inits.pad and _exits.pad wrappers are not added a second time. The page's directory guards still decide - a _guard.php that refuses makes the tag render as nothing instead of refusing the whole request. A page that does not exist is an error under the strict check; without it the tag is empty and the rest of the page lives.

How isolated the page is

A plain {page} shares the request: it reads the variables set before it, and what its PHP creates stays behind for the rest of the page. Four options change that, the same four {code} takes:

  • sandbox - the page sees nothing of the page around it and leaves nothing behind (the {sandbox} tag runs content this way);
  • reset - the levels and stores are cleared for the pass, the variables stay;
  • clean - the page sees everything, but what it changes is undone afterwards;
  • function='name' - the page's PHP runs inside a PHP function, with a scope of its own.

Other applications

With app='other' the page belongs to another application, with its own configuration, _lib and database, so it cannot be built here: it is fetched over HTTP. By default the browser fetches it, as {ajax} does; ajax=false has the server fetch it and insert its body. For a page of this application fetched as a real second request, see {get}.

Examples

Another page inside this one

The page runs its PHP and its template, and its output takes the tag's place.

Templateexamples/page/1-basic.pad 
<p>Before the page.</p>
{page 'examples/page/parts/greeting'}
<p>After it.</p>
Resultopen alone

Before the page.

Hello from parts/greeting

  • its own PHP ran
  • its template rendered

After it.

It sees the variables

The included page is built in the same request and reads what is set before the tag.

Templateexamples/page/2-variables.pad 
{set $colour = 'red'}
<p>{page 'examples/page/parts/badge'}</p>
{set $colour = 'green'}
<p>{page 'examples/page/parts/badge'}</p>
Resultopen alone

red

green

Isolated with sandbox

With sandbox the page sees nothing of the page around it.

Templateexamples/page/3-sandbox.pad 
{set $colour = 'red'}
<p>plain: {page 'examples/page/parts/badge'}</p>
<p>sandbox: {page 'examples/page/parts/badge', sandbox}</p>
Resultopen alone

plain: red

sandbox: no colour

See also

  • {get} Fetches another page of the application over HTTP, as a second request, and inserts its output.
  • {ajax} Writes an empty div and a script that has the browser fetch another page into it after the page has loaded.
  • {code} Runs its content as PAD source in a separate engine pass and outputs what that pass produced.
  • {sandbox} Runs its content as PAD source in an isolated pass that cannot see or leave behind anything of the page.
  • {restart} Abandons the page being built and renders another page in its place, in the same request.