phpClick Home Credits Demo Documentation Download FAQ Documentation > Guide to creating new components

Guide to creating new components

Disclaimer: This is just a first high-level draft and needs a lot of refinement to describe the details...

Overview

phpClick works with the concepts of components. Components are self-contained units of HTML and PHP code that the end-user can position on a page. Examples for components already built into phpClick are "htmlText", "image", "button", "inputText". We are already planning to offer many more components such as the obviously missing "radioButton", "checkBox" etc. but also more advanced ones such as "dynamicText", "dataTable", "navigation". However, if you have an idea for a custom component and want it in phpClick, you can do it by yourself by following the process described below.

Each component is represented by a number of files underneath a folder with the components name in the main folder "components". For example, the component "image" consists of the following files:

• components/image/ComponentImage.inc.php (required file)
  This file contains the PHP code that implements the component's behavior. It is implemented as a class with the name "Component<Component-folder-name>", in this case: "ComponentImage"
  
• components/image/icon.png (required file)
  The icon associated with the component. It is shown in the toolbox view
  
• components/image/name.html (required file)
  The user-friendly name of the component. In this case: "Image". The name is displayed in the toolbox view next to the icon.
  
• components/image/actions/deleteImage.inc.php
  An include file that implements a particular action for the image component. In this case it allows users to delete already uploaded images. This file is included by the controller script /do.php which handles all the user input and refreshes individual frames as necessary.

The central part of a component is the class that implements its behavior. Each component inherits from the class "Component" (/includes/Component.inc.php). Each components needs to implement the interface "ComponentInterface" (/includes/ComponentInterface.inc.php) which requires the following methods:

• getType() - Specify the type of the component as text, e.g. inpuText, image
• printPropertiesUi() - Specify the interface for getting the components properties.
• handlePropertiesUi() - Specify how to handle the property values entered by the user. This information can be stored in an xml file whose XMLNode object is a member of the base "Component" class and is ready to use in any derived classes.
• getComponentCode() - Specify what php code phpClick will put in the page to render this component. Any special input validation or preprocessing code can also be provided.

Click on the method names above to see a description of their function.

Step-by-Step from 10,000 feet :)

To create a new component you should take the following steps:

1. come up with a concise component name (no spaces or funny characters), e.g. "colorPicker"
2. create a folder underneath /components/ with the name of your component, e.g. "/components/colorPicker/"
3. find one of the already existing components that is closest to what you want to do and copy its class file into the newly created folder; rename it to match your components name, e.g. "/components/colorPicker/componentColorPicker.inc.php
4. copy an appropriate image file with the name "icon.png" into the folder
5. create a file with the name "name.html" which contains nothing but the user-friendly name of your component, e.g. "Color Picker Tool"
6. edit at least the four methods/functions described above to implement the behavior of your component (This sounds quite easy but may be non-trivial depending on the complexity of your component. I strongly recommend you look at the existing components to get an idea how things work)
7. modify "/components/factory.inc.php" and "/components/index.xml" to register your component with phpClick
8. Test you component and send us your code... :)
   

http://phpclick.sourceforge.net/ Last modified: October 7, 2004 You are visitor number 1 since Nov. 25, 2009.

web hosting kindly provided by