Like Playing with Building Bricks: Page Components

Summary

Editable content of a page is managed by inserting and editing page components
It’s like playing with building bricks, first select the area to be edited, than insert and combine components

Creating new Page Components

Config → Pages → Components → Create new component creates a new Page Component.

Following class scaffold is created for you:

<?php
/**
 * Name of your component
 *
 * @package phenotype
 * @subpackage application
 */
class PhenotypeComponent_1 extends PhenotypeComponent
{
  public $com_id = 1;
 
  public $name = "New component"; // is shown as label in the editing area
 
  public function setDefaultProperties()
  {
    $this->set("_revision",1);
  }
 
  public function initForm($context)
  {
     // Customize input form with form_xy-methods 
    $this->form_textfield("Headline","headline",300);
  }
 
  public function render($context)
  {
    // Example:
 
    // Initialize template access (=>$mySmarty)  
    eval ($this->initRendering());
 
    $mySmarty->assign("headline",$this->getH("headline"));
    $html = $mySmarty->fetch($TPL_1);
 
    return $html;
  }
 
}

Customize your page component

To customize a page component you may adapat three stages of the component:

Editing
Update (i.e. processing user input)
Rendering

The code scaffold provided you methods for two of the three mentioned stages:

→edit($context)
→render($context)

Customize Editing

Within the edit-method you can use →form_xy methods of your component to build up the desired input fields. You may also use echo to output html and build forms directly.

Let’s demonstrate the most relevant form_methods, starting with form_textfield as included in the code scaffold:

Text

→form_textfield($title, $property, $width)

→form_textarea($title, $property, $width, $rows)

→form_richtext($title, $property, $width, $rows, $filter = 1)

Assets (Images and Documents)

Selecting Assets:

→form_document_selector($title, $property, $folder=””, $changefolder = true, $infoline = true, $type_filter = ””,$grp_id)

→form_image_selector($title, $property, $folder=””, $changefolder = true, $x = 0, $y = 0,$grp_id=0,$_options=Array())

Uploading Assets (for user without mediabase access):

→form_imageupload($title,$property,$path=“_upload”,$grp_id=2)

Selections

Selecting a value out of an arbitrary selection:

→form_selectbox($title, $property, $_options, $addzerodots=true)

Selecting a content object record:

→form_content_selectbox($title, $property, $con_id, $addzerodots=true, $statuscheck=true,$sql_where=””)

Special Form Elements

→form_html($title, $property, $width, $rows)

→form_enumeration($title, $property, $start = 3, $max=99)

See API Doc for all available form_xy methods.

Usally you don’t have to customize the page component update stage. All form_xy-methods called within the method initForm are finalized on update. Press the debug button after an update to see how the properties of your page component got set:

Anyway, you might overwrite the →update()-method to insert your own processing.

Customize Rendering

Finally you must implement →render(), otherwise your component stays invisible.

Use →get(), getI(), getH(), getHBR() (or any other Phenotype Getter) to access the properties of your component and simply echo them out.

Let’s take a look at the source code of the enumeration component:

<?php
/**
 * Enumeration
 * 
 * @package phenotype
 * @subpackage application
 */ 
class PhenotypeComponent_1103 extends PhenotypeComponent
{
	public $com_id= 1103;
	public $name = "Enumeration";
 
	public function setDefaultProperties()
	{
		$this->set("_revision",1);
		$this->set("enum_count",3);
	}
 
	public function initForm($context)
	{
		// Customize input form with form_xy-methods
		$this->form_textfield("Headline","headline",300);
		$this->form_enumeration("","enum");
	}
 
	public function setFullSearch()
	{
		$s="";
		for ($i=1;$i<=$this->get("text_count");$i++)
		{
			$s .= $this->get("text_item".$i) . "|";
		}
		return ($s);
	}
 
	public function render($context)
	{
		$html ='';
		if ($this->get("headline")!="")
		{
			$html .='<h1>'.$this->getH("headline").'</h1>';
		}
 
 
		$html .= '<ul>';
		for ($i=1;$i<=$this->getI("enum_count");$i++)
		{
			$text = $this->getH("enum_item".$i);
			if ($text !="")
			{
				$html .= '<li>'.$text.'</li>';
			}
		}
		$html .='</ul>';
		return $html;
	}
}

Advanced techniques

function setDefaultProperties()

As shown in above example there are two other methods to be mentioned. If you want to set some default values, implement the method →setDefaultProperties() using $this→set($property, $value).

function setFullSearch()

If you want the content of your component to be added to the fulltext index of your page, implement the method setFullSearch()

Component templates

Every page component can have it’s own (smarty) templates. For usage of templates within Penotype components read the section "Using Smarty Templates" for Dynamic Pages. When it comes to template handling, there’s no difference between includes, page components and content objects.

Component context

Page component methods are called with a $context parameter. Within a layout it’s possible to define that context as a number between 1 and 9 for the editable area of a page.
So you may implement context dependent components, e.g. a component uses different rendering templates wether it’s used in the main content of a page or in a content related column.

Component Groups

Components are combined in groups. The reason is to offer your editors only reasonable component selections, when you have developed a lot of them. To edit a component group click Config → Pages → Componentgroups → Your Group. After that you may want to assign this new group to your layout: Admin → Layout → Your Layout → Placeholder.

By the way, it is a typical beginners error to forget to assign a new component to a component group and wonder, why it’s not possible to use the new component!