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!

Introduction

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

Components

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...

Folders

New components use the following directory structure:

  • Controller
  • Data
  • Dev
  • Doc
  • Model
    • Entity
    • Event
    • Repository
    • Yaml
  • Testing
  • View
    • Media
    • Script
    • Style
    • Template
  • lang

All of these folders are optional. 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).

Files

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:

CoreModule.svg

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!

Planning

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.

Prerequisites

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

Start!

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)

Model

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 http://www.skipper18.com/. 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.

Controller

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:

array(
    '',
    'lists',
    'users' => array(
        '',
        'edit',
        'import',
    ),
    'news',
    'dispatch' => array(
        '',
        'templates',
        'interface',
        'confightml',
        'activatemail',
        'confirmmail',
        'notificationmail',
        'system',
    ),
)

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.

Content

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.

View

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.