Looks like you've got JavaScript disabled in your browser - you'll get a better site experience if you enable JavaScript

How to use module views to perform actions

Ultrajam » Documentation » Code » How to use module views to perform actions

You might have it in mind that a view is for creating a form for a module, but they can be used for other things as well, for example, performing actions.

A simple scenario: Adding an on/off switch to your module. Generally you would do that from the settings view in config.php, but not in our example.

Switching a setting on and off is a very simple thing to do with a view, but any action can be performed using the same button/view pattern simply by adapting the view function. Take a look at how "delete" works in a module such as jrAction, it’s very similar. You click the button, are directed to the view which performs the action and then returns you to where you were. It all happens quickly, so the perception is that you click the button, the page reloads and the action has been done.

So for our example, you want a button, which when clicked, toggles your module's config setting.

The Button Function

First we need a function which returns the button itself. This function should be in include.php.

function myModule_live_button() 
{
	global $_post, $_conf;
	
	if ($_conf['myModule_live'] == 'on') {
		$button_text = 'turn off';
	} else {
		$button_text = 'go live';
	}
	return jrCore_page_button('live',  $button_text,  "window.location='{$_conf['jrCore_base_url']}/{$_post['module_url']}/live'");
}

The button (created using the jrCore_page_button function) is very simple, it shows the status, and when clicked takes the browser to the module view named "live": mysite.com/mymoduleurl/live

The View Function

So next we need a function to return that view which will toggle the setting and return the admin immediately to whichever page they were on when the clicked the button. View functions should be in index.php.

function view_myModule_live() 
{
	global $_conf;
	
	jrUser_master_only();
    
	// live/not live switch

	if ($_conf['myModule_live'] == 'off') {
		$onoff = 'on';
		jrCore_set_form_notice('success', 'Your setting is now on');
	} else {
		$onoff = 'off';
		jrCore_set_form_notice('success', 'Your setting is now off');
	}
	$_field = array(
		'name'     => "live",
		'type'     => 'hidden',
		'validate' => 'onoff',
		'value'    => $onoff
	);
	jrCore_update_setting('myModule',$_field);
	
	jrCore_form_result();
}

Note the easy use of jrCore_set_form_notice() and jrCore_form_result() to inform the admin that the action has been performed.
You can now call that myModule_live_button function using myModule_live_button(); in your php code. Here we are placing the button prominently in the module control panel banner.
```
    jrCore_page_banner('my module control panel',myModule_live_button());
```
Or to use that in a table cell, something like this would do the trick:
```
    $dat[3]['title'] = myModule_live_button();
```
And that is all that's needed - a button, and a view function to perform the action.

There are a couple of other things we might want to do though.

A Setting in Module Config

Generally you would have a checkbox "enabled" field in your module config to control this setting. It isn’t difficult, so lets complete things off by adding one of those as well. This would go in the myModule_config() function in config.php:

    // live/not live

    $_tmp = array(
        'name'     => 'live',
        'default'  => 'off',
        'type'     => 'checkbox',
        'validate' => 'onoff',
        'required' => 'on',
        'label'    => 'go live',
        'help'     => 'switches the setting on and off'
    );
    jrCore_register_setting('myModule',$_tmp);

Note: We set the default to "off" - the default will be set when the module is installed. We don't need this setting to be in the config, the update_setting function in the listener will create the setting if it does not already exist.

A Template Button

If you wanted to do the switching from within a smarty template, you’d need another function - the smarty function. It is a very simple example, all it does is to get our button html from the myModule_live_button php function. Note that smarty functions should be in include.php, not index.php.

function smarty_function_myModule_onoff_button($params,$smarty)
{
    global $_mods, $_conf;

    // Check that it is admin, check module and check setting exists

    if (!jrUser_is_master() || !jrCore_module_is_active('myModule') || !isset($_conf['myModule_live'])) {
        return '';
    }

    $out = myModule_live_button();
    
    // standard smarty assign

    if (isset($params['assign']) && $params['assign'] != '') {
        $smarty->assign($params['assign'],$out);
        return '';
    }
    return $out;
}

You can then call that button using the smarty template function:
```
{myModule_onoff_button}
```
Why Do This?

It's a good question, why would you want an on/off switch for a module setting in a template or in a module’s banner? Well you rarely would, but you might, perhaps a convenience switch to toggle a setting whilst you are working on your templates. The on/off setting has just been an example to explain using views to perform actions. The ujSignup module used similar code to provide a prominent live/offline switch for the signup system - when the setting is "off" the jrUser signup forms are in use, when the setting is "on" ujSignup overrides the default system and displays its own signup forms instead.

Code

How to use a modal in a template

How to use module views to perform actions

Table of Contents:

The Button Function

The View Function

A Setting in Module Config

A Template Button

Why Do This?

Tags