Concrete5

If you're a developer of concrete5 websites or add-ons that run on those websites, you should be ready for version 5.7. In this how-to, I'm going to go through how I got a relatively simple add-on ready for 5.7.

Updates 07-01-2015

Download the completed add-on: email_list_signup.zip

Updates 10-16-2014

Since writing this add-on, packages have changed slightly in 5.7. The controller file now needs to be namespaced. I've updated the code below (see Controller). Thanks to cpillz and exchangecore for pointing this out.

Also, prior to releasing 5.7 but after this how-to was created the IP service class was reworked significantly. This how-to doesn't go about how to use the new class, but I have posted an updated zip file that contains the fixed code so that the new add-on will run.

Background

Don't know anything about concrete5 5.7? Check out this overview..

Don't know anything about the underlying changes coming in 5.7? Check out my post on the subject.

The Add-On

For this tutorial, I wanted a relatively simple add-on that had some dashboard pages and at least one block. I found one here, in community member jordanlev's Email List Signup add-on. Download the add-on to get a sense as to what the code looked like prior to this how-to.

General Code Cleanup

Old Loader Methods

While it's not required, you can remove any calls to Loader::model() and Loader::library from within your add-ons. These methods no longer do anything. Your classes should load automatically, provided your code follows the concrete5 modified PSR-4 standard.

Get Current Page

Anywhere your code uses "global $c" to get the current concrete5 page object is not likely to work any longer. Instead, use this code to retrieve the current Page from most contexts:

$c = Page::getCurrentPage();

The Controller

Namespacing and Class Renaming

We're going to need to namespace the controller – and then make sure that any classes we're using inside the controller are declared at the top in the global, non-namespaced scope:

namespace Concrete\Package\EmailListSignup;
use Package;
use BlockType;
use SinglePage;
use Loader;
class Controller extends Package

Email List Signup Block

Namespacing and Class Renaming

This add-on contains one block, the email_list_signup block. You don't have to restructure this block at all, or rename any files in it. You do, however, have to add some namespacing and "use" directives to the top of the block controller file. Here's how the block controller looked originally:

<?php defined('C5_EXECUTE') or die(_("Access Denied."));
class EmailListSignupBlockController extends BlockController {

And here's how it looks now:

<?php  
namespace Concrete\Package\EmailListSignup\Block\EmailListSignup;
use \Concrete\Core\Block\BlockController;
use UserInfo;
use Loader;
use \Concrete\Package\EmailListSignup\Models\EmailListSignup as EmailListSignup;
use Config;
use Page;
use View;
class Controller extends BlockController {

Hopefully what's happening here is pretty obvious. All the class files within this add-on will generally have to be namespaced within the Concrete\Package\EmailListSignup namespace. The block controller has to be within the Concrete\Package\EmailListSignup\Block\EmailListSignup namespace.

After that, it's a simple matter of ensuring that all classes referenced within the file are declared at the top, since none of the classes exist within the same namespace.

Finally, we name the class "Controller."

On Page View Event

The on_page_view() method in concrete5 block controllers used to fire every time a block of that type was included on a page. This let blocks include assets in headers. This method was separated from the general view() method of the block controller, because it had to fire earlier in the dispatcher flow than view() used to, in order to inject assets into the header of the page.

This is no longer a requirement. You can add assets to the header and footer of a page in the view() method. Consequently, while on_page_view() will work for some things still, it is deprecated. It wasn't working for what Jordan had wanted it to do, so I moved his code into the view() method.

Email List Signup Model

The EmailListSignup model found in the models directory is a simple database access class that extends the now deprecated Model class in concrete5. We have removed ADODB, but kept a polyfill around for legacy purposes. Here's what the EmailListSignup model used to look like:

<?php defined('C5_EXECUTE') or die(_("Access Denied."));
class EmailListSignup extends Model {

Here's what it looks like now:

<?php  
namespace Concrete\Package\EmailListSignup\Models;
use \Concrete\Core\Legacy\Model;
use Loader;
class EmailListSignup extends Model {

Our legacy Model class works as a drop-in for the old ADODB ActiveRecord model.

Dashboard

Controller Reorganization

Our new autoloading standard has some different directory naming requirements. The add-on used to be structured in this way:

controllers
|- dashboard
   |- reports
      |- email_list_signups.php

Now, since controllers and views don't require pages to operate, we need another level to separate page-less controllers from those that are page controllers. Here is how the add-on's controllers directory is now structured.

controllers
|- single_page
   |- dashboard
      |- reports
         |- email_list_signups.php

Namespacing

Finally, we need to namespace the Email List Signup dashboard page controller. This is our old controller:

<?php defined('C5_EXECUTE') or die(_("Access Denied."));
class DashboardReportsEmailListSignupsController extends Controller {

This is new page controller:

<?php 
namespace Concrete\Package\EmailListSignup\Controller\SinglePage\Dashboard\Reports;
use \Concrete\Core\Page\Controller\DashboardPageController;
use Loader;
use \Concrete\Package\EmailListSignup\Models\EmailListSignup;

class EmailListSignups extends DashboardPageController {

In general, this should be similar to the namespacing of the Block controller above.

That's It!

That should get us an add-on that works and installs! While this gets you an add-on that works and installs, it's not the most beautiful add-on in the world. Part two of this how-to will cover how we can make our add-on look nicer in the world of 5.7, both on the front-end and in the dashboard.