concrete5 doesn't force developers into the concept of models. Instead, it's recommended that classes which deal primarily with one database table be separated into their own files, and stored in the models/ directory. Even Block Types, which allow developers to specify their block's database table and automatically save POST data against its schema, the ActiveRecord portion can be overridden in the Block Type's controller and ignored.
Pages in concrete5 do have controllers, however. These are simply scripts which are automatically loaded when the page is rendered, and which may contain methods that are automatically run in certain situations.
Controllers for single pages simply go directly in the controllers/ directory at the same level as their single page counterpart. For example, if you have a single page at /dashboard/widgets/search/, you'd create a controller page at controllers/dashboard/widgets/search.php. You could also create this page at controllers/dashboard/widgets/search/controller.php.
Single page controllers should be named PathToMyPageController and extends the Controller class. In the example above, the controller would be named DashboardWidgetsSearchController.
Page types can also have controllers. These controllers will be automatically accessed whenever a page of a certain type is rendered. These controllers must live at controllers/page_types/page_type_handle.php (e.g. the "full" page type could have a controller at controllers/page_types/full.php).
Page type controllers should be named HandlePageTypeController and extends the Controller class. In the example above, the controller would be named FullPageTypeController.
Running controller methods automatically
Controllers allow developers the ability to split certain bits of page functionality into different functions, and automatically run those functions at different points, based on a URL to a given page. Consider this function, when run from a page template:
When the link that action() generates is followed, the current page will be re-rendered, but the controller method action_activate_widget() will be run. The URL generated will look like
http://www.mysite.com/path/to/my/page/-/activate_widget/ - < concrete5.4
http://www.mysite.com/path/to/my/page/activate_widget/ - >= concrete5.4
Note: as of concrete 5.4, the dash separator no longer exists within URLs. This imposes a slight performance penalty, so if you don't mind the dash you can reinstate it by adding define("ENABLE_LEGACY_CONTROLLER_URLS", true) to your config/site.php
Automatic Controller Methods
If they exist, certain methods within page controllers are run automatically
This is run whenever a page is viewed, and another controller method isn't being explicitly called.
This is run when the page controller is started. This is preferable than defining logic in __construct()
This is run when the page controller is just about to exit, and begin rendering the view layer.
Other useful Controller Methods
Adds an item that will be output within a page's header.
$var = $this->post('string');
Searches the $_POST array for a variable named 'string' and returns it.
Makes the value $value available within the associated View under the name $key. For example, within the controller, enter this code:
$this->set('catName', 'Mittens'); //And within the view, you can enter My cat's name is !
Any viewable template in concrete5 is executed in the View context. Block add, edit and view templates are executed within the BlockView context. Single page templates and page type templates are executed within the View context.
The following methods are available within these templates:
$path = $this->getStyleSheet($stylesheet)
Returns a stylesheet found in the active theme's directory - but FIRST passes it through the tools CSS handler in order to make certain style attributes found inside editable.
$themeHandle = $this->getThemeHandle()
Returns the handle of the currently active theme.
$path = $this->getViewPath()
Returns the path used to access this view.
$this->inc($file, $args = array())
Includes file from the current theme path. Similar to php's include(). Files included with this function will have all variables set using $this->controller->set() in their local scope, As well as access to all that controller's helper objects.
$this->url($path, $task, $arguments)
A utility function that is used inside a view to setup urls w/tasks and parameters. Accepts a variable number of arguments, which will all be passed to the URL function.
This will generate the following URL:
When, when clicked, will look into the DashboardWidgetsController class for the add_widget($arg1, $arg2, $arg3) function.
Just like url(), but it will pass the current page path into the function.
$r = $this->section($url)
Checks the current view to see if you're in that page's "section" (top level)
$items = $this->getHeaderItems()
Returns a list of all header items defined so far.