New Component

From Cloudrexx Development Wiki
Jump to: navigation, search

This article is currently under construction and describes approaches that might not be implemented yet

This article describes how to create a new Contrexx component in Contrexx 3.1 and newer. For older versions of Contrexx, please refer to New_Module!


For a quick start, jump to Start. You should know the following things about Contrexx components before you start:


Components are self-contained parts of Contrexx. A Component can be added or removed, without affecting other Components. Components can have dependencies to other Components (for Example: a lot of different Components need the ContentManager to be present).

So when creating a Component, all your code must be located within one single directory. If you change any line of code outside of your Component's folder, you're probably doing something wrong...


New components use the following directory structure:

Folder Usage Deployment
Controller Controller classes x
Data Data for the component -
Data.sql Contains base data for this component -
OldStructureWithTestData.sql Contains old structure with some data for testing -
Migration.sql Migrates OldStructureWithTestData.sql -
Dev Development scripts -
Doc ERD, PDFs, etc. -
Model Model classes and definitions x
Entity Model entity classes x
Event Event listener classes x
Repository Model repository classes x
Yaml Model YAML definitions x
Testing Testing scripts and classes -
UnitTest UnitTests -
View View files x
Media Images, PDFs, etc. x
Script JavaScript x
Style CSS x
Templates Template files x
Frontend Template files for frontend mode x
Backend Template files for backend mode x
Command Template files for command mode x
Generic Template files used in more than one mode x
lang Language files x
en English language files x
frontend.php English frontend mode language file x
backend.php English backend mode language file x
... Other languages x Component description. (Filename is case insensitive). -

All of these folders are optional, is mandatory. The structure can be extended according to your needs, but do not add any folders to any level specified here. If you add a folder, write its name in singular CamelCase (see Naming conventions). All folders with sub-folders should not directly contain files (you may break this rule in folders you create yourself, but you shouldn't).


All files are named in CamelCase too and do not contain the Component's name (again see Naming conventions).

Component types

Here's a simple graphic showing whether your code will be part of lib, core, core_modules or modules:


If you are creating/adding a library, simply create the folder /lib/{name_of_your_lib} and start developing your lib. You may skip the following steps!


Before you start coding, think of what your component will do, what it needs and what it consists of. Draw a Class Diagram and/or an ERD.


To successfully develop something for Contrexx you will need the following:

  • A Contrexx Installation (The easiest is to have a working installation on your local machine. For Windows use XAMPP, on Unix-based systems install Apache, Mysql and maybe also PHPmyAdmin)
  • The Contrexx Workbench. For more info about how to install and use the Contrexx Workbench see Contrexx Workbench


Now you can start creating your component. The following command will create a module in the customizing folder for you:

./cx workbench create module {name} customized

This creates the directories to use, adds some sample files and activates the component in your local installation.

For more info about the create command, see the Workbench documentation (or try ./cx workbench help create)


Now you can start writing your yaml files. If you don't need the database, you may skip this step.

  1. Write your .yml files. The format for the .yml files is defined by doctrine, please refer to the current doctrine documentation for more info
    • There are certain tools that might help you. The best we found so far is It allows you to draw your model easily and you can import existing YAML files.
  2. Generate entities, repositories and database changes. This is done by executing workbench.bat db update

For naming conventions of database tables see article Naming conventions of database tables.


Workbench's create command also added two controllers to your Component: A FrontendController and a BackendController. They do most of work that is needed for almost every Component for you. Both of them contain a parsePage() method with a bit of code to start with.

Backend sub navigation

The BackendController also has a method named getCommands(). You may return a one or two dimensional array of strings. There is an empty entry that will be rendered as Default. This will automatically generate a sub navigation. For example:

    'users' => array(
    'dispatch' => array(

This would generate a navigation matching the one of the e-mail marketing module. For every level, a default is added, so the first entry can be omitted. If you only need one navigation point, you may return an empty array (default). The backend controller then searches for language variables of the following scheme: TXT_{COMPONENT_TYPE}_{COMPONENT_NAME}_ACT_{1ST_LEVEL}(_{2ND_LEVEL}). For the added default, DEFAULT is used for 1st and 2nd level.


The method parsePage() gets a Sigma template as parameter. In frontend, that template consists of the content of the resolved page. In backend, a template file ({your_component_directory}/View/Template) named like the current command (see getCommands()) or Default.html is loaded.

Here you have access to your Component's name and type using $this->getName() resp. $this->getType() and to the Cx object.

JavaScript and CSS

Workbench's create command added a Front- and Backend.js and a Front- and Backend.css. Those are automatically loaded if they exist.

Write own ComponentController

By default, the \Cx\Core\Core\Model\Entity\SystemComponentController class is used as main controller for your Component. If you want to add additional Controllers (in addition to Front- and BackendController), or if you need hook scripts or JsonData, you have to write your own ComponentController. In order to do so, create the file {your_component_directory}/Controller/ComponentController.class.php containing the class ComponentController which extends \Cx\Core\Core\Model\Entity\SystemComponentController. You may then start overwriting some of the following methods (see the method descriptions in SystemComponentController class for more info):

Stage 2

 * preInit()
 * preComponentLoad()
 * getControllerClasses()
 * getControllersAccessableByJson()
 * registerEvents()
 * registerEventListeners()
 * postComponentLoad()
 * postInit()

Stage 3: Frontend- and backend-mode

 * preResolve()
 * resolve()
 * postResolve()
 * adjustRequest()
 * preContentLoad()
 * preContentParse()
 * load()
 * postContentParse()
 * postContentLoad()
 * preFinalize()
 * postFinalize()

Stage 3: Command-mode

 * getCommandsForCommandMode()
 * hasAccessToExecuteCommand()
 * getCommandDescription()
 * executeCommand()

See Component Hooks for a detailed explanation of the core system hooks.


The view is generated using PEAR Sigma templates (as in previous versions of Contrexx). As stated in section "Controller", backend templates are located in {your_component_folder}/View/Template. Frontend templates are loaded from page content.