Add Control Panel Pages To Your Add-On

Automatically Generate Your Sidebar

If you’d like to have your sidebar automatically generated then that’s it! The Sidebar class will scan our ControlPanel/Routes folder for all available Control Panel routes and automatically create respective entries in our sidebar. There’s no need to add the sidebar to your Control Panel page as it will automatically be added when the page is rendered.

Example:

With an add-on folder like this:

amazing_add_on
┣ ControlPanel
┃ ┣ Routes
┃ ┃ ┣ Configurations.php
┃ ┃ ┣ Settings.php
┃ ┃ ┣ Licenses.php
┃ ┃ ┣ Index.php
┃ ┗ Sidebar.php
┗ ...

Would produce a sidebar in the Control Panel like this:

You can take this a step further by adjusting the following properties in your Control Panel routes (ControlPanel/Routes/[route_name].php) to adjust how sidebar items are displayed:

Manually Generate Your Sidebar

We will set the $automatic property in our ControlPanel/Routes/Sidebar.php file to false.

public $automatic = false;

This tells our Sidebar class not to automatically create any sidebars.

From here you can utilize the CP/Sidebar Service in the process() method of our Sidebar class to manually create your sidebar and all related items.

HTML String

If you would just like to output a string of HTML for you control panel page, then you would just do something like the following:

 public function process($id = false)
    {
      $this->addBreadcrumb('index', 'Home');

      $html = "<h2>Welcome to my add-on</h2><p>This is an amazing add-on that does amazing things!"

      $this->setBody($html);

      return $this;
    }

This would produce a page looking like this:

If you would like to make this page more dynamic or include additional functionality, then you need to explore using Views.

Views

When your add-on was created via the CLI a views folder was also created in your add-on’s folder. Inside of this folder a file was also created, views/Index.php. By default this Control Panel page is already using the View service by calling $this->setBody().

$variables = [
    'name' => 'Matt',
    'color' => 'Green'
];

$this->setBody('Index', $variables);

As we can see here, the route file is passing two arguments to $this->setBody():

• Index is the name of the corresponding view to use (references views/Index.php)
• $variables is an array of variables that will be available to the view.

Now let’s look at the view itself, found at views/Index.php.

<?php

echo "<h2>Time to make magic</h2>";

if (isset($name)) {
    echo "<p>Name: " . $name . "</p>";
}

if (isset($color)) {
    echo "<p>Color: " . $color . "</p>";
}

Notice the variables $name and $color correspond to the $variables array passed to the view in the route file.

This renders as such:

Taking this a bit further, we can use the CP\Form service to display panels and forms similar to what is found on many pages in the Control Panel.

Using the CP\Form is highly recommend to speed up your development and to maintain the integrity of the Control Panel design.

We’ll start by using the CP\Form service in a method which will return our $form array. The $form array will then be passed to our View through our $variables array.

private function getForm()
{
  $form = ee('CP/Form');
  $form->asTab();
  $form->asFileUpload();
  $field_group = $form->getGroup('header 1');
  $field_set = $field_group->getFieldSet('first_name');
  $field_set->getField('first_name', 'text')
            ->setDisabled(true)
            ->setValue('Eric');
  
  return $form->toArray();
}

Now, let’s add that to our route file and be sure to pass the array returned from getForm() to our view.

public function process($id = false)
{

  // set the breadcrumb
  $this->addBreadcrumb('index', 'Home');

  // call our getForm() method to get
  // our array
  $form = $this->getForm();

  // store our form in our $variables array
  // to be passed into our view
  $variables = [
    'form'  => $form
  ];

  $this->setBody('Index', $variables);

  return $this;
}

private function getForm()
{
  $form = ee('CP/Form');
  $form->asTab();
  $form->asFileUpload();
  $field_group = $form->getGroup('header 1');
  $field_set = $field_group->getFieldSet('first_name');
  $field_set->getField('first_name', 'text')
            ->setDisabled(true)
            ->setValue('Eric');
  
  return $form->toArray();
}

Since we passed our form to our view in the $variables array, inside of views/Index.php we can now use the View service to render our $form array as the main body of our Control Panel page.

if (isset($form)) {
    echo ee('View')->make('ee:_shared/form')->render($form);
}

Your add-on will now have a Control Panel page with a form as seen in this screenshot:

Finally, make the form submission do something. The form is being submitted to same CP controller, so we can check whether it has been submitted by adding ee('Request')->isPost() check. For the sake of this demo, we’ll skip the database saving part and just display success message on submission.

public function process($id = false)
{
  if (ee('Request')->isPost()) {
    ee('CP/Alert')->makeBanner('amazing_add_on')
      ->asSuccess()
      ->withTitle(lang('success'))
      ->addToBody('Form has been submitted!')
      ->now();
  }

  // set the breadcrumb
  $this->addBreadcrumb('index', 'Home');

  // call our getForm() method to get
  // our array
  $form = $this->getForm();

  // store our form in our $variables array
  // to be passed into our view
  $variables = [
    'form'  => $form
  ];

  $this->setBody('Index', $variables);

  return $this;
}

This is only the beginning of what you can do with forms in the Control Panel. Read more in the docs on the CP\Form service to understand what else is possible.

{ee:u} Learn more about the CP\Form service on ExpressionEngine University.