WackoWiki: Action: Navigation

https://wackowiki.org/doc     Version: 148 (11/20/2025 08:47)

Action: Navigation

Status: Implemented, work in progress, evaluation
version: 0.3 (see repo)


1. Page trail

Scroll to the previous or next page
Navigate between predefined pages / chapters

chapter navigation



chapter navigation




To be displayed at the top and bottom of the page.

Static or dynamic, formatter or action.

{{navigation
  prev="ChapterOne"
  next="ChapterThree"
  main="Overview"
}}

2. Determination of pages and context


It is possible to define the navigation on every single page or include a dedicated section as page with dynamic determination.

3. Options


CSS

Head (search engine indicator)

4. Action

4.1. via link()

source:master/src/action/navigation.php[link5]
<?php

if (!defined('IN_WACKO'))
{
    exit;
}

/* navigation action:
 *
 *
TODO:
    - add option to choose custom menu as data source
*/

$info = <<<EOD
Description:
    Generates navigation bars to navigate between chapters of a book.

Usage:
    {{navigation}}

Options:
    [main="Overview"]
        tag of overview
    [prev="PreviousPage"]
        tag of previous chapter
    [next="NextPage"]
        tag of next chapter
    [title=0|1]
        uses page title for links
    [head=0|1]
        add <link rel="prev|next" ...> to HTML <head>
EOD;

// set defaults
$head        ??= 0;
$help        ??= 0;
$main        ??= '';
$next        ??= '';
$prev        ??= '';
$table        ??= 1;
$title        ??= 0;
$track        ??= true; // seems to have no effect


if ($help)
{
    $tpl->help    = $this->help($info, 'navigation');
    return;
}

// resolve relative tag
$_main    = $this->unwrap_link($main);
$_next    = $this->unwrap_link($next);
$_prev    = $this->unwrap_link($prev);

// preload link data
$pages    = [$_prev, $_main, $_next];

foreach ($pages as $page)
{
    if ($page != '')
    {
        $q_spages[]        = $this->db->q($page);
    }
}

$pages = $this->db->load_all(
    'SELECT ' . $this->page_meta . ' ' .
    'FROM ' . $this->prefix . 'page ' .
    'WHERE tag IN ( ' . implode(', ', $q_spages) . ' ) '
    , true);

$__main    = null;
$__next    = null;
$__prev    = null;

foreach ($pages as $page)
{
    $this->cache_page($page, true);
    $page_ids[]    = $page['page_id'];
    $this->page_id_cache[$page['tag']] = $page['page_id'];

    if ($page['tag'] == $_prev)
    {
        $__prev = $page;
    }
    else if ($page['tag'] == $_main)
    {
        $__main = $page;
    }
    else if ($page['tag'] == $_next)
    {
        $__next = $page;
    }
}

// cache acls
$this->preload_acl($page_ids, ['read']);

// fall back to tag
if (!$__prev)
{
    $__prev['tag']        = $_prev;
    $__prev['title']    = '';
}
if (!$__main)
{
    $__main['tag']        = $_main;
    $__main['title']    = '';
}
if (!$__next)
{
    $__next['tag']        = $_next;
    $__next['title']    = '';
}

// link text
$__main['text'] = '↑ ' .    ($title ? $__main['title'] : $this->_t('Overview'));
$__prev['text'] = '« ' .    ($title ? $__prev['title'] : $this->_t('Back'));
$__next['text'] =            ($title ? $__next['title'] : $this->_t('Next'))        . ' »';

$__main['title'] =            ($title ? '' : $__main['title']);
$__prev['title'] =            ($title ? '' : $__prev['title']);
$__next['title'] =            ($title ? '' : $__next['title']);

// define navigation links
$tpl->enter($table ? 'tbl_' : 'div_');
$tpl->main_link            = $this->link('/' . $__main['tag'], '', $__main['text'], $__main['title'], $track, true, false);

if ($prev)
{
    $tpl->prev_link        = $this->link('/' . $__prev['tag'], '', $__prev['text'], $__prev['title'], $track, true, false);
}

if ($next)
{
    $tpl->next_link        = $this->link('/' . $__next['tag'], '', $__next['text'], $__next['title'], $track, true, false);
}

if ($prev && $next && !$table)
{
    $tpl->separator    = true;
}

$tpl->leave();

if ($head)
{
    if ($prev)
    {
        $this->add_html('header', '<link rel="prev" title="' . $__prev['title'] . '" href="' . $this->href('', $_prev) . '">');
    }
    if ($next)
    {
        $this->add_html('header', '<link rel="next" title="' . $__next['title'] . '" href="' . $this->href('', $_next) . '">');
    }
}

4.2. via href()

static, no metadata lookup

<?php

if (!defined('IN_WACKO'))
{
    exit;
}

/* navigation action:
 *
 *
TODO:
    - add option to choose custom menu as data source
*/

$info = <<<EOD
Description:
    Generates navigation bars to navigate between chapters of a book.

Usage:
    {{navigation}}

Options:
    [main="Overview"]
        tag of overview
    [prev="PreviousPage"]
        tag of previous chapter
    [next="NextPage"]
        tag of next chapter
EOD;

// set defaults
$help            ??= 0;
$main            ??= '';
$next            ??= '';
$prev            ??= '';

if ($help)
{
    $tpl->help    = $this->help($info, 'navigation');
    return;
}


$tpl->enter('table_');
$tpl->main_href        = $this->href('', $this->unwrap_link($main));
$tpl->prev_href        = $this->href('', $this->unwrap_link($prev));
$tpl->next_href        = $this->href('', $this->unwrap_link($next));
$tpl->leave();

5. Template

The main goal is to have a customizable standard template for scrolling between pages.

« Previous Content
Next »
← Back to overview « Back | Next »
← Back to overview ↑ Up « Back | Next »

The content section even could hold a drop down or fly-out menu with all available pages / chapters.
The next and previous button should show the page title via title="Chapter Two" of the page.
The link text can be set individually.

5.1. via link()

source:master/src/action/template/navigation.tpl[link6]
[ === main === ]
<!--noinclude-->
	[ ' help ' ] 
	<nav class="nav-chapter no-print">
	[= tbl _ =
		<table>
			<tr>
				<td>
				[= prev _ =
					[ ' link ' ]
				=]
				</td>
				<td>
				[= main _ =
					[ ' link ' ]
				=]
				</td>
				<td>
				[= next _ =
					[ ' link ' ]
				=]
				</td>
			</tr>
		</table>
	=]
	[= div _ =
		[= main _ =
			[ ' link ' ]
		=]
		<div class="pagination">
		[= prev _ =
			[ ' link ' ]
		=]
		[= separator _ =
			[ ' nonstatic ' ]
		 | 
		=]
		[= next _ =
			[ ' link ' ]
		=]
		</div>
	=]
	</nav>
<!--/noinclude-->

5.2. via href()

[ === main === ]
<!--noinclude-->
	[ ' help ' ] 
	<nav class="nav-capter no-print">
	[= table _ =
		<table>
			<tr>
				<td>
				[= prev _ =
					<a href="[ ' href ' ]">« [ ' _t: Back ' ]</a>
				=]
				</td>
				<td>
				[= main _ =
					<a href="[ ' href ' ]">↑ [ ' _t: Overview ' ]</a>
				=]
				</td>
				<td>
				[= next _ =
					<a href="[ ' href ' ]">[ ' _t: Next ' ] »</a>
				=]
				</td>
			</tr>
		</table>
	=]
	[= div _ =
		<div class="nav-capter">

		</div>
	=]
	</nav>
<!--/noinclude-->

5.3. CSS

add to default.css
/* navigation action ------------- */
.nav-chapter {
	background-color: rgb(241, 241, 241);
	padding: 10px 10px;
}
.nav-chapter td:nth-child(1) {
	text-align:left;
	white-space: nowrap;
}
.nav-chapter td:nth-child(2) {
	text-align: center;
width: 100%;
}
.nav-chapter td:nth-child(3) {
	text-align:right;
	white-space: nowrap;
} 


6. ToDo

workout of details

Add a good enough version (that will do for most cases) to the core, add some examples here for more advanced templates for copy and paste.

7. Example

/Book/ChapterOne
{{navigation main="/Book" next="ChapterTwo"}}


/Book/ChapterTwo
{{navigation main="/Book" prev="ChapterOne" next="ChapterThree"}}


/Book/ChapterThree
{{navigation 
  main="/Book" 
  prev="ChapterTwo" 
  next="ChapterFour"
  title=1
}}

8. Changelog

0.1 Intitial version
0.2 adds nav-chapter class to CSS and message set for 'Overview'
0.3 adds parameter title=0|1, shows page title as link text

9. See also