MarkupDynamicSelects API

There are 5 MarkupDynamicSelects methods that you will interact with in your template file in order to successfully output a Dynamic Selects. Please note that you can output as many Dynamic Selects as you wish in any one template file. The 5 methods are introduced below.

processAjax()

This method takes one non-optional argument $input. As the name suggests, it processes ajax-calls for data to populate a dependent select. $input here is a ProcessWire input.

processAjax($input);

renderDynamicSelectsStyles()

This method accepts no arguments. It is optional to use. It simply renders some basic CSS to style your Dynamic Selects.

renderConfigs()

The method outputs two Javascript configuration values needed by the module. The method accepts one optional argument, $options, which is an array containing two options as shown below:

The default options are:

// default options
$defaultOptions = array(
		// by default we post ajax calls to the current page
		'ajaxURL' => './',
		// error message to be returned if data not returned by server
		'fetchError' => $this->_('Dynamic Selects: There was an error fetching data'),
);

You can override any of the two default options by passing your own array to the method, for instance:

// custom options
$options = array(
		// custom ajax-handler page
		'ajaxURL' => '/products/electronics/',
		// custom error message
		'fetchError' => ('Dropdowns: We encountered an error and could not fetching results'),
);

echo renderConfigs($options);

renderDynamicSelectsScripts()

This method is at the heart of Dynamic Selects. It outputs the Javascript necessary to make the Dynamic Selects work. It is repsonsible for fetching and displaying data as well as building and accessing the Dynamic Selects local cache (if caching is in use). It takes no arguments.

render()

This method is responsible for rendering Dynamic Selects on the page. It is the gateway to the Dynamic Selects created in ProcessDynamicSelects. The method accepts two arguments, the first of which is not optional.

render($dynamicSelects, $debug=false);

The first argument $dynamicSelects tells the method what Dynamic Selects built and configured using ProcessDynamicSelects to display. Please note that depending your settings, a given user (e.g. 'guest') might not be able to view the Dynamic Selects. The value of the first argument can either be a:

Page: A Page Object of the Dynamic Selects.
ID: The (integer) ID of the Dynamic Selects page.
Title: The title of the Dynamic Selects page.
Name: The name of the Dynamic Selects page.
Array: The settings of the Dynamic Selects. These are saved in ds_settings as a JSON string.

The second argument is boolean. The default is false. If set to true, it will, in addition to rendering the Dynamic Selects, dynamically render an ordered list showing the returned results and their respective IDs for the currently triggered dependent select. This is used for debugging purposes only and is not useful for production. More details about debugging can be found in this topic.

A complete template file example is shown below. Please see the inline comments.

<?php

	// call the module
	$ds = $modules->get('MarkupDynamicSelects');

	// if we got an ajax request deal with it before page is rendered
	if ($config->ajax) {
		$dataJSON = $ds->processAjax($input);
		echo $dataJSON;
		exit;
	}

?>
<!DOCTYPE html>
<html lang="en">
	<head>
		<meta http-equiv="content-type" content="text/html; charset=utf-8" />
		<title><?php echo $page->title; ?></title>
		<!-- Include font awesome (needed for spinner) BUT you can also use your own or none if you wish -->
		<link href="https://maxcdn.bootstrapcdn.com/font-awesome/4.6.3/css/font-awesome.min.css" rel="stylesheet" integrity="sha384-T8Gy5hrqNKT+hzMclPo118YTQO6cYprQmhrYwIiQ/3axmI1hQomh7Ud2hPOy8SP1" crossorigin="anonymous">
		<!-- echo this modules CSS styles. This is optional; you are free to use your own CSS styles -->
		<?php echo $ds->renderDynamicSelectsStyles(); ?>
		<link rel="stylesheet" type="text/css" href="<?php echo $config->urls->templates?>styles/main.css" />		

		<!-- JAVASCRIPT-->
		<!-- Include the usual suspect. We need jQuery for the module to work -->
		<script src="//ajax.googleapis.com/ajax/libs/jquery/2.2.0/jquery.min.js"></script>

		<!-- Output the dynamic selects Javascript configurations before the page is fully rendered -->
		<!-- if using a different page to handle ajax calls -->
		<!-- <script type="text/javascript">var config = <?php #echo $ds->renderConfigs(array('ajaxURL' => '/colors/')); ?>;</script> -->
		<!-- if using the same page to handle ajax calls -->
		<script type="text/javascript">var config = <?php echo $ds->renderConfigs(); ?>;</script>

		<!-- Output the script needed to make dynamic selects work. We could also output this just before we close </body> -->    
		<?php echo $ds->renderDynamicSelectsScripts(); ?>
	</head>
	<body>
	<div id="content">
		<h1><?php echo $page->title; ?></h1>
		<?php

		// output the render() method

		/** 
			Various methods to pass first argument $dynamicSelects
			@note: we only need to use one of the below
		**/

		#1. pass  as a page
		$myDynamicSelectsPage = $pages->get(1234);
		echo $ds->render($myDynamicSelectsPage);

		#2. pass  as an ID		
		echo $ds->render(1795);

		#3. pass  as title
		echo $ds->render('Entertainment');

		#4. pass  as name
		echo $ds->render('high-quality-products');

		#5. pass  as an array	
		$myDynamicSelectsPage = $pages->get(1234);
		// grab the Dynamic Selects settings from the field 'ds_settings'
		$settingsJSON = $myDynamicSelectsPage->ds_settings;
		// convert the JSON string to an array. Here we assume the JSON string is not empty
		$settingsArray = json_decode($settingsJSON, true);
		echo $ds->render($settingsArray);

		?>
		</div>
	</body>
</html>

« Creating and Setting Up Frontend Dynamic Selects

Frontend Example 1: Continents, Countries and Cities »