Development Guide

Forms and Object Data

This is deprecated use the Input/Form classes of the Kitchensink instead.

If you handle forms or input fields with the ILIAS property forms, as explained below, you need to ensure the following rules:
 
Storing form data into an object via set() method:
 
$obj->set...(ilUtil::stripSlashes($_POST["..."])) // this strips slashes added by magic_quotes
 
Insert object data into form input fields:
 
$tpl->setVariable("PH", ilUtil::prepareFormOutput($obj->get...()));
 
Insert data coming from a form into form input fields:
 
$tpl->setVariable("PH", ilUtil::prepareFormOutput($_POST["..."], true));
 
These things are done automatically, if you use the property form classes.

Property Forms

To create property forms an extra class is available at Services/Form/classes/class.ilPropertyFormGUI.php. This class brings the following features:

  • Support for text input, text areas (incl. RTE), checkboxes, radio groups (incl. nested subitems), date/time input, file input, select lists.

  • Input validation (currently only required fields)

Example 1

This example creates a simple form with one text input field.

include_once("./Services/Form/classes/class.ilPropertyFormGUI.php");
$form = new ilPropertyFormGUI();
$form->setFormAction($ilCtrl->getFormAction($this));
$form->setTitle($lng->txt("gmaps_settings"));
 
// text input
$text_prop = new ilTextInputGUI($lng->txt("gmaps_api_key"), "api_key");
$text_prop->setInfo($lng->txt("gmaps_api_key_desc"));
$text_prop->setValue($api_key);
$form->addItem($text_prop);
 
$form->addCommandButton("saveGoogleMaps", $lng->txt("save"));
$form->addCommandButton("view", $lng->txt("cancel"));
$tpl->setContent($form->getHTML());

Example 2

This examples shows how to nest subitems into a radio group. The same works with checkboxes.

include_once("./Services/Form/classes/class.ilPropertyFormGUI.php");
$form = new ilPropertyFormGUI();
$form->setFormAction($ilCtrl->getFormAction($this));
$form->setTitle($lng->txt("gmaps_settings"));
 
// radio group
$radio_prop = new ilRadioGroupInputGUI("Radio Test", "radio_test");
$radio_prop->setInfo("This is the info text of the Radio Test property.");
$op = new ilRadioOption("Option 1", "1", "Infotext for Option 1");
 
	// nest text input in first option
	$text_prop = new ilTextInputGUI("Text Input", "ti2");
	$text_prop->setInfo("This is the info text of subitem 'Text Input' of Option 1.");
	$op->addSubItem($text_prop);
 
$radio_prop->addOption($op);
$op = new ilRadioOption("Option 2", "2", "Infotext for Option 2");
 
	// nest checkbox and two date/time input fields into option 2	
	$cb_prop = new ilCheckboxInputGUI("Checkbox", "cbox2");
	$cb_prop->setValue("1");
	$cb_prop->setChecked(true);
	$op->addSubItem($cb_prop);
 
	$dt_prop = new ilDateTimeInputGUI("Start Date", "datetime5");
	$dt_prop->setDate("2006-12-24");
	$dt_prop->setTime("15:44");
	$dt_prop->setShowTime(true);
	$dt_prop->setInfo("Info text for the start date.");
	$op->addSubItem($dt_prop);
 
	$dt_prop = new ilDateTimeInputGUI("End Date", "datetime6");
	$dt_prop->setDate("2006-12-24");
	$dt_prop->setTime("15:44");
	$dt_prop->setShowTime(true);
	$dt_prop->setInfo("Info text for the end date.");
	$op->addSubItem($dt_prop);
 
$radio_prop->addOption($op);
$radio_prop->setValue("1");
$form->addItem($radio_prop);
 
$form->addCommandButton("save", $lng->txt("save"));
$form->addCommandButton("view", $lng->txt("cancel"));
 
$tpl->setContent($form->getHTML());

Example 3

This example shows how to use input validation in a create/save/edit/update scenario. Currently only the validation of required fields is supported. You have to call checkInput() one time, before using getInput(). checkInput() validates, and strips slashes/html code out of the POST data.

...
	/**
	* FORM: Create.
	*
	*/
	public function create()
	{
		$this->initForm("create");
		return $this->form_gui->getHtml();
 
	}
 
	/**
	* FORM: Edit form.
	*
	*/
	public function edit()
	{
		$this->initForm("edit");
		$this->getValues();
		return $this->form_gui->getHtml();
 
	}
 
	/**
	* FORM: Save.
	*
	*/
	public function save()
	{
		$this->initForm("create");
		if ($this->form_gui->checkInput())
		{
			$this->external_feed_block = new ilExternalFeedBlock();
			$this->external_feed_block->setTitle($this->form_gui->getInput("block_title"));
			$this->external_feed_block->setFeedUrl($this->form_gui->getInput("block_feed_url"));
			$this->prepareSaveFeedBlock($this->external_feed_block);
			$this->external_feed_block->create();
			...;
		}
		else
		{
			$this->form_gui->setValuesByPost();
			return $this->form_gui->getHtml();
		}
 
	}
 
	/**
	* FORM: Update.
	*
	*/
	public function update()
	{
		$this->initForm("edit");
		if ($this->form_gui->checkInput())
		{
 
			$this->external_feed_block->setTitle($this->form_gui->getInput("block_title"));
			$this->external_feed_block->setFeedUrl($this->form_gui->getInput("block_feed_url"));
			$this->external_feed_block->update();
			...;
		}
		else
		{
			$this->form_gui->setValuesByPost();
			return $this->form_gui->getHtml();
		}
 
	}
 
	/**
	* FORM: Init form.
	*
	* @param	int	$a_mode	Form Edit Mode (IL_FORM_EDIT | IL_FORM_CREATE)
	*/
	public function initForm($a_mode)
	{
		global $lng;
 
		$lng->loadLanguageModule("block");
 
		include_once("Services/Form/classes/class.ilPropertyFormGUI.php");
 
		$this->form_gui = new ilPropertyFormGUI();
 
 
		// Property Title
		$text_input = new ilTextInputGUI($lng->txt("block_feed_block_title"), "block_title");
		$text_input->setInfo("");
		$text_input->setRequired(true);
		$text_input->setMaxLength(200);
		$this->form_gui->addItem($text_input);
 
		// Property FeedUrl
		$text_input = new ilTextInputGUI($lng->txt("block_feed_block_feed_url"), "block_feed_url");
		$text_input->setInfo($lng->txt("block_feed_block_feed_url_info"));
		$text_input->setRequired(true);
		$text_input->setMaxLength(250);
		$this->form_gui->addItem($text_input);
 
 
		// save and cancel commands
		if ($a_mode == "create")
		{
			$this->form_gui->addCommandButton("save", $lng->txt("save"));
			$this->form_gui->addCommandButton("cancelSave", $lng->txt("cancel"));
		}
		else
		{
			$this->form_gui->addCommandButton("update", $lng->txt("save"));
			$this->form_gui->addCommandButton("cancelUpdate", $lng->txt("cancel"));
		}
 
		$this->form_gui->setTitle($lng->txt("block_feed_block_head"));
		$this->form_gui->setFormAction($this->ctrl->getFormAction($this));
 
	}
 
	/**
	* FORM: Get current values from persistent object.
	*
	*/
	public function getValues()
	{
		$values = array();
 
		$values["block_title"] = $this->external_feed_block->getTitle();
		$values["block_feed_url"] = $this->external_feed_block->getFeedUrl();
 
		$this->form_gui->setValuesByArray($values);
 
	}

For the whole API documentation, see http://ildoc.hrz.uni-giessen.de/ildoc/ -> Services/Form.