Lightnote CMS - web 2.0 content management system

Parameters

Assume you want to add some configuration parameters for your extension: e-mail address for contact form, or how much news per page should be displayed or whatever you want.

Configuration of extension comes in two flavors:

  1. Global configuration - parameters, which are defined once you whether install or re-configurate extension. These parameters are availiable to all instances of extension.
  2. Local configuration - parameters, which user specifies for each instance of extension.

Global and local configurations are defined inside of Extension configuration file (config.xml) within globalConfig and localConfig elements, respectively. globalConfig and localConfig in turn must consist of at least one sub element, named userControls, the configuration of which is identical as of custom content elements.

<?xml version="1.0" encoding="utf-8"?>
<Extension>
   <friendlyName>Sample extension</friendlyName>
   <globalConfig>
       <textbox name="param1" friendlyName="parameter 1"></textbox>
       <textbox name="param2" friendlyName="parameter 2"></textbox>
   </globalConfig>
   <localConfig>
       <textbox name="param1" friendlyName="parameter 1"></textbox>
       <image name="image1" friendlyName="image 1"></image>
   </localConfig>
</Extension>

To obtain configuration parameters from your extension you can use following methods:

  • GetLocalVars() - retrieves associative array with local control's values.
  • GetLocalControls() - retrieves associative array with instances of local control's objects.
  • GetGlobalVars() - retrieves associative array with global control's values.
  • GetGlobalControls() - retrieves associative array with instances of global control's objects.

If you need to get a raw value of control, it is best practice to use GetLocalVars or GetGlobalVars methods, they execute faster and you get what you need with less typing:

$localVars = $this->GetLocalVars();
$param1 = $localControls["param1"];
The advantage of using GetLocalControls() and GetGlobalControls() methods is that you get an associative array of UserControl objects, which have additional convinient methods:
$localControls = $this->GetLocalControls();
$imageSrc = $localControls["myimage"]->GetSrc();

The full API documentation for User Controls you can find here.

"Contact form" example

Let's consider a simple contact form extension having 3 configuration parameters: header, image and an e-mail address of administrator to which contact form will be sent.

Contact form

Assume this extension has been named "contact" and placed under extensions/contact/ folder:

config.xml
<?xml version="1.0" encoding="utf-8"?>
<Extension>
    <friendlyName>Contact form</friendlyName>
    <localConfig>
        <userControls>
            <textbox name="subject" friendlyName="Subject"></textbox>
            <image name="image" friendlyName="Image" maxwidth="200"></image>
        </userControls>
    </localConfig>
    <globalConfig>
        <userControls>
            <textbox name="email" friendlyName="Contact e-mail address"></textbox>			
        </userControls>
    </globalConfig>
</Extension>
contact-form.html
<div class="contact-form">
    <h2>{$element->header}</h2>
    <img src="{$imageSrc}" />
    <form method="post" action="" name="contact-form">
        <label>Your Name:</label> <input type="text" name="name" value="" /><br />
        <label>Your E-Mail:</label> <input type="text" name="email" value="" /><br />
        <label>Message:</label><br /><textarea name="message"></textarea><br />
        <input type="submit" name="send" value="Send" />
    </form>
</div>
class.ext_contact.php
<?php

class Ext_contact extends Extension
{
	function Render($smarty)
	{
		$localVars = $this->GetLocalVars();
		$localControls = $this->GetLocalControls();
		
		if(isset($_POST["contact"]))
		{
			/*
			  ... form validation logic ...			  
			*/ 
			
			$globalVars = $this->GetGlobalVars();
			
			$mailHeader  = "From: " . $_POST["name"];
			$mailHeader .= "<" . $_POST["email"] . ">";
			
			$subject = $localVars["subject"];
			$email = $globalVars["email"];
			$message = $_POST["message"];
			
			mail($email, $subject, $message, $mailHeader);
			return "Contact form has been posted.";
		}
		
		$this->Assign("imageSrc", $localControls["image"]->GetSrc());
		
		$content = $this->Fetch("contact-form.html");
		
		return $content;
	}
}

?>