Implementing a Centralized Help Registry for a Package

This requires concrete5 7.4 or greater.

Sometimes it's handy to store all the help for a particular application in one spot – for example, if you have one person tasked with managing the help for multiple block types and Dashboard pages. In this case, you'll want to create a Help Service Provider your Package, and access the various help message registries from within this service provider

Package-Based

Note: in this guide we will be adding a service provider to a package, and registering help from within one particular area of a package. This assumes you are familiar with how to build a concrete5 Package

Overview

Let's say our package has the directory name "acme_widgets". That means we're going to have a controller with the namespace \Concrete\Package\AcmeWidgets, with the file in packages/acme_widgets/controller.php.

First, we'll enable advanced autoloading by adding this protected variable to our package controller (\Concrete\Package\AcmeWidgets\Controller):

protected $pkgAutoloaderMapCoreExtensions = true;

This automatically maps anything within the \Concrete\Package namespace (that doesn't automatically fall into it already, like blocks, controllers, etc…) to src/Concrete. We're going to create a package named \Concrete\Package\AcmeWidgets\Help\HelpServiceProvider. So that means we need to create an empty file in packages/acme_widgets/src/Concrete/Help/HelpServiceProvider.php

<?php
namespace Concrete\Package\Calendar\Help;
use Concrete\Core\Foundation\Service\Provider;

class HelpServiceProvider extends Provider
{

}

This class is incomplete. Any class that extends the core \Concrete\Core\Foundation\Service\Provider must implement a register() method, in which the class registers all the various classes it uses. We're actually not going to bind any classes to the class container – instead we're going to use this register() method to declare all our various help messages.

<?php
namespace Concrete\Package\Calendar\Help;
use Concrete\Core\Foundation\Service\Provider;

class HelpServiceProvider extends Provider
{
    public function register()
    {
    }
}

But for now we'll keep it blank. Now, we need to tell our package about our new service provider. The Package on_start() method is the perfect place for this, as it gets run early in the concrete5 startup routine by any packages that are installed.

public function on_start()
{
    $app = Core::make('app');
    $provider = new \Concrete\Package\Calendar\Help\HelpServiceProvider($app);
    $provider->register();
}

This isn't as complex as it appears. The first line simply gets the current concrete5 application object from the class container. We need that because it's required by the \Concrete\Core\Foundation\Service\Provider class. We pass that in to our help service provider, and we run the register() method.

Of course, our register() method doesn't do anything yet, so let's set up some centralized help definitions from within it.

public function register()
{
    $this->app['help/block_type']->registerMessageString('plain_text_box', 'Plain Text Box Help');
    $this->app['help/block_type']->registerMessageString('dummy_block', 'Other help text.');
    $this->app['help/dashboard']->registerMessageString('/dashboard/acme\_widgets/add',
        t('Add a Widget.')
    );
}

This should be pretty self-explanatory: the first two lines are us using the Block Type Help Manager to register a message string against the block type with the handle plain_text_box and the handle dummy_block, respectively. Next, we use the Dashboard Help Manager to register help against the page with the path /dashboard/acme_widgets/add/.

That's it! Just stack up all the help definitions you'd like in this list and you'll be able to control the help from one spot in your package.

Loading Conversation