Magento 2: Adding A New Admin Page

Magento 2 Logo

In this post, we will look at adding a basic page and template to the Magento admin system. It is recommended that you have read and completed Creating a Magento 2 Module & Adding A New Admin Menu Item before moving on to this topic.

New admin pages will typically require the following items, a custom router to tell Magento how to access the modules page, a controller to handle the action, a layout view that instructs Magento on how the page should be constructed, and either a phtml template or the elements for a UI component.

In this example, we will be using a basic phtml template to display some simple text.

Adding A Router

You can register both front-end and adminhtml routers within Magento for custom page routes. Taking from the example in Adding A New Admin Menu Item we will create an admin router to handle the path https://magento.address/admin/examples/examples/posts/

First we need to create the routes.xml file under app/code/Examples/FirstModule/etc/adminhtml/routes.xml

Once you have created the file add the following code to it:

<?xml version="1.0"?>
<config xmlns:xsi="" xsi:noNamespaceSchemaLocation="urn:magento:framework:App/etc/routes.xsd">
    <router id="admin">
        <route id="examples" frontName="examples">
            <module name="Examples_FirstModule"/>

The above specifies the following the frontName attribute is the first part of the path [examples]

Add A Controller

Next, we add the controller folder and the PHP page handler file.

The controller folder will specify the second part of our URL path, in this case, Examples

Go ahead and create the directory app/code/Examples/FirstModule/Controller/Examples/

So now we have the frontName attribute from the router and the controller folder which gives us the path Examples/Examples

Now we need to add the page handler, go ahead and create the class Posts.php in the directory we just created above


Now add the following code to it:


namespace Examples\FirstModule\Controller\Adminhtml\Examples;

class Posts extends \Magento\Backend\App\Action implements \Magento\Framework\App\Action\HttpGetActionInterface
     * Authorization level of a basic admin session
     * @see _isAllowed()
    const ADMIN_RESOURCE = 'Examples_FirstModule::first_module';

     * The admin menu item
    const ADMIN_MENU = 'Examples_FirstModule::level_zero';

     * @var \Magento\Framework\View\Result\PageFactory
    protected $resultPageFactory;

     * Index constructor.
     * @param \Magento\Backend\App\Action\Context $context
     * @param \Magento\Framework\View\Result\PageFactory $resultPageFactory
    public function __construct(
        \Magento\Backend\App\Action\Context     $context,
        \Magento\Framework\View\Result\PageFactory $resultPageFactory
    ) {
        $this->resultPageFactory = $resultPageFactory;

     * @return \Magento\Framework\View\Result\Page
     * @throws \Magento\Framework\Exception\LocalizedException
    public function execute()
        /** @var \Magento\Backend\Model\View\Result\Page $resultPage */
        $resultPage = $this->resultPageFactory->create();
        $resultPage->getConfig()->getTitle()->prepend(__('Examples_FirstModule Posts'));
        return $resultPage;

We now have our router and controller structure in place.

Add Layout Instructions

Now we are going to tell Magento how this page should be displayed.

Create the following directory and file within the module:


Notice how the filename matches our URL path examples/examples/posts, this is how Magento identifies which template file to load when processing the request.

Add the following code to the new template file:

<?xml version="1.0"?>
<page xmlns:xsi="" xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">
    <update handle="styles"/>
        <referenceContainer name="content">
            <block class="Magento\Backend\Block\Template" template="Examples_FirstModule::posts.phtml"/>

The above tells Magento that the main content div should use the standard template block class and a template file called posts.phtml, we will add the template file next.

Add Template File

The template file handles the display logic and is typically a combination of both HTML and PHP, the block defined in the template file is also injected into the template for use. However, in this example, we will just simply be displaying some text on the page. For a more complex template example see the CRUD operations post.

Now create the following directory and file


Add the following code to it:

<h2>Examples_FirstModule post content template</h2>
<p>Congratulations if you are seeing this you have successfully implemented your page and template.</p>

Notify Magento

Finally with the above in place we need to notify Magento of the changes, run the following CLI command and flush the cache

bin/magento c:f

If successful you should be able to use the Examples menu to navigate to the posts page which will be rendered like the below image

New Admin Page Result

What’s Next?

Leave a Reply

Your email address will not be published. Required fields are marked *