File: user_guide.txt

Result Class User Guide


Jesse Estevez


WARNING:  This is my first class released to the public and I am aware that the documentation is pretty bad.

So, PLEASE send any questions to me.  I have released this class and will support and improve it if anyone is interested.

jestevez@travel-italy.com



(1)  Always create an instance by passing a valid db result id.

Like this...

$foo = new result ( $result_id );




(2)  After you create an instance you must set rules (or nothing happens).

(3)  set_result_rule() takes one argument, an array.  Here are all the possible keys for this array...

'name'		=> STRING, REQUIRED the name of your rule
'min' 		=> INTEGER, REQUIRED a result set must have at least this many rows for this rule to apply.
'max' 		=> INTEGER, REQUIRED a result set must have at most this many rows for this rule to apply.
'offset'	=> $offset  Leave this alone!  It is used to scroll through results
'limit'		=> INTEGER the maximum number of results to show on one page
'scroll_args' 	=> ARRAY an array of strings which will be evaluated as globals and appended to 'next' and 'prev' links.
'template'	=> STRING template to use (should _not_ include ".tpl"
'format' 	=> ARRAY the elements of a template you want to use, in the correct order.  If a template element expects result data, its key should be 'data'.
'arguments'	=> ASSOC ARRAY an array of name value pairs passed to each template element.


A rule is set with set_result_rule ( $rule ), like this...

$foo->set_result_rule
	(
	array
		(
		'name' => 'Rule Yellow',
		'min' => 2,
		'max' => 6,
		'redirect' => 'www.yellow.com'
		)
	);
	
Here is a rule that is conditional...

$foo->set_result_rule
	(
	array
		(
		'name' => 'Rule Yellow',
		'test' => $some_variable
		'min' => 2,
		'max' => 6,
		'redirect' => 'www.yellow.com'
		)
	);
	
In the above example, if $some_variable is true and the database returns 2-6 rows, the user will be redirected to yellow.com


Here is another example (not conditional)...

$foo->set_result_rule
	(
	array
		(
		'name' => 'Rule Blue',
		'template' => 'blue',
		'min' => 7,
		'max' => 10,
		'template' => 'blue_edit',
		'format' => array ( 'template_edit_instructions', 'data'=>'edit_form', 'submit_button' )
		)
	);
	
In the above example, if the database returns one row, the template 'blue' will used and, according to the format, 
the following functions on the template will be used...
blue_template_edit_instructions()
blue_edit_form()	<- this will execute 7 to 10 times, each time with a new row of data.
blue_submit_button()

(4)  How to "page" or "scroll" through results.

$foo->set_result_rule
	(
	array
		(
		'name' => 'Rule Blue',
		'template' => 'blue',
		'min' => 7,
		'max' => 100,
		'template' => 'blue_edit',
		'format' => array ( 'template_edit_instructions', 'data'=>'edit_form', 'submit_button' ),
		'offset'=> $offset,
		'limit' => 5
		)
	);
	
Just like the last example in (3), only now no more than 5 results will be shown at once and you will get pretty next and prev links.

Important note:  it is too dangerous to pass arounda  query from page to page.  Instead, you should use scroll_args, which is an array of strings which are variable names that exist at the global scope.  These will snagged and added to arguments to the urls for the next and prev links.