Create Links

This page covers the different kinds of links you can create in a module: callback links that run a function, variable links that set request values, back links, and confirmation links.

Links are the most basic way to navigate between pages and trigger actions in epesi. There are several ways to create one, depending on what you need — but every one of these functions returns a string in the same format:

href="<here goes link parameter>"

Note that the <a> tag itself isn't included — you need to wrap the returned string in one yourself.

Callback Links

This is the most useful type of link. It lets you choose which function runs when the link is clicked, and optionally pass that function some parameters. To create one, open <module_name>_0.php and define the body() function like this:

public function body() {
    print('This is a page no. 1 <br>');
    print('<a '.$this->create_callback_href(array($this,'second_page')).'>Link to the second page</a><br>');
}

The result of create_callback_href() is placed inside the <a ...> tag. Now define the second_page() function:

public function second_page() {
    print('This is a page no. 2<br>');
    return true;
}

Returning true tells epesi not to call the module's main function (body() in this case) after second_page() runs. Try clicking the link in epesi to see this in action.

Now redefine second_page() like this:

public function second_page() {
    print('This text will be displayed above page 1 contents<br>');
    return false;
}

Reload the page in epesi and see how the module's behavior changes.

So when should you return true versus false? Return true whenever you want to move to a new section of your module — this skips the main section's output when the page content is meant to change.

Return false for simple actions like deleting or flagging something. In that case, the function called by the callback link doesn't display anything — it just modifies module data or the database. Afterward, the module falls back to displaying what it was showing before.

Keep in mind the callback function runs before the main module function, so any data the main function displays afterward will already reflect the callback's changes.

Variable Links

You can also create links that set variables to a given value, using either create_href() or create_unique_href(). The difference matters: create_href() sets a variable visible to every module currently displayed, while create_unique_href() makes the value visible only to the module that created the link. Use create_href() with caution — because it's global, it can produce side effects that break other parts of the page.

Both functions are called the same way:

$this->create_href( array('key1'=>'value1', 'key2'=>'value2', ...) );
$this->create_unique_href( array('key1'=>'value1', 'key2'=>'value2', ...) );

Reading the values back works differently, though. Values set via create_href() are read from $_REQUEST['key1']. Values set via create_unique_href() are read with $this->get_unique_href_variable().

In general, you won't need either function if you rely on create_callback_href() instead. There is one handy use for create_href(), though:

$this->create_href(array('box_main_module'=>'<module_name>'));

If your epesi installation uses Base_Box as its main module (the default), a link like this forces epesi to display the module named under the box_main_module key. You can also set which function gets called via box_main_function (body by default), and pass it arguments via box_main_arguments.

Back Links

epesi also provides a link type built specifically for back buttons. To create one:

$this->create_back_href();

Or as a full link:

print('<a '.$this->create_back_href().'>Back</a>');

To check whether the back link was clicked, use:

$this->is_back();

This returns true if a link created with create_back_href() was clicked. By default, is_back() returns true only once per click. To make it return true multiple times, define the link as:

$this->create_back_href($x);

$x is the number of times is_back() will return true on subsequent processing (1 by default).

Here's a sample module showing is_back() and create_callback_href() working together:

<?php
defined("_VALID_ACCESS") || die('Direct access forbidden'); 

class Test_MyModule extends Module {

    public function body($arg) {
        print('<a '.$this->create_callback_href(array($this,'instead')).'>Instead</a> :: ');
        print('<a '.$this->create_callback_href(array($this,'before')).'>Before</a> :: ');
    }

    public function instead() {
        if($this->is_back()) return false;
        print('instead main function<hr>');
        print('<a '.$this->create_back_href().'>Back</a>');
        return true;
    }

    public function before() {
        print('before<hr>');
        return false;
    }
}
?>

Confirm Links

To require confirmation before a link's action runs — recommended for anything destructive, like deletion — add confirm to the function name:

$this->create_confirm_callback_href('<message>',$function,$arguments);
$this->create_confirm_href('<message>',$array_with_variables);
$this->create_confirm_unique_href('<message>',$array_with_variables);

Clicking the link shows a confirmation dialog with the message you provided and OK/Cancel buttons. Choosing OK proceeds as normal; choosing Cancel cancels the action and nothing happens.