Creating a Magento admin page
This tutorial gives instructions for the creation of a module that displays a simple page in the Magento admin.
For the purposes of this tutorial MyCompany is the name of the company associated with a module named ExampleAdminNewPage.
Start by creating the working directory for all the module files.
In your Magento development environment under the
app/code directory, run the following command:
mkdir -p MyCompany/ExampleAdminNewPage
This command creates the
MyCompany company directory and the
ExampleAdminNewPage module directory. The latter will be the root directory for the module we will create.
Initial boilerplate files
These initial boilerplate files are the bare essential files needed for any Magento module.
In the module’s root directory, create the file
composer.json. This file gives composer the ability to install this module and its dependencies.
For more information see:
In the module’s root directory, create the file
registration.php. This file registers the module
MyCompany_ExampleAdminNewPage with Magento.
For more information see: registering your component.
In the module’s root directory, create a new directory called
etc. Under that directory, create the file
module.xml. This file specifies the name and setup version of this module.
For more information see: naming your component.
Routing and navigation
Before we can view the module’s page, we need a way to navigate to it. These files create a link to the page in the left navigation and tells Magento how to resolve requests for that page.
For more information on this topic, see: routing.
Under the created
etc directory, create a new directory called
adminhtml. Under that directory, create the file
menu.xml. This XML file adds new menu items to the Magento admin.
menu.xml file provided below adds two items in the Content section of the left navigation:
- A new separate section with the title Greetings under Content.
- A link with the label Hello World that leads to a page request for
exampleadminnewpage/helloworld/indexunderneath that new section.
The following parts make up the generated page request link to the Hello World page:
exampleadminnewpage- This is the
frontName. Because its purpose is to help route requests to the correct module, we give it the same name as the module, but this is not required.
helloworld- This specifies the name of the controller to use.
index- In the XML file, since the action for the controller is not specified, Magento uses the default value
etc/adminhtml create the file
routes.xml. The contents of this XML file tells Magento to route requests that use the
exampleadminnewpage to this module.
Now that we have a link to the Hello World page, we need to create the file needed to handle that request.
In the module’s root directory, run the following command:
mkdir -p Controller/Adminhtml/HelloWorld
Controller/Adminhtml/HelloWorld directory, create the file
Index.php. This file is the class assigned to the default Index action for the
HelloWorld controller. Since the admin area serves this page, the file belongs in the
Adminhtml directory, and the class itself extends
Now that Magento knows how to handle requests for the Hello World page, we need view files that define the look of the page.
Create the necessary directories for the files by running the following commands from the module’s root directory:
mkdir -pm view/adminhtml/layout mkdir -pm view/adminhtml/templates
These files belong in the
view/adminhtml directory because the Magento admin area use these files during page generation.
This file defines the layout and structure of the index page for the HelloWorld controller. It sets the title to “Greetings” and instructs Magento to use the
helloworld.phtml template as the content in a
Magento\Backend\Block\Template block class.
The name of this file uses the following pattern: frontName_controller_action.xml
This template file contains the actual page content for the Hello World page.
Full module directory structure
The module is now complete. Your module’s directory structure under
app/code should look like the following:
MyCompany `-- ExampleAdminNewPage | |-- Controller | |-- Adminhtml | |-- HelloWorld | `-- Index.php |-- etc | |-- adminhtml | | |-- menu.xml | | `-- routes.xml | `-- module.xml |-- view | |-- adminhtml | |-- layout | | `-- exampleadminnewpage_helloworld_index.xml | `-- templates | `-- helloworld.phtml |-- composer.json `-- registration.php
Installing the module
Now that the module is code-complete, run the following commands to install it:
bin/magento module:status- This command shows a list of enabled/disabled modules.
bin/magento module:enable MyCompany_ExampleAdminNewPage- If necessary, run this to enable the disabled module.
bin/magento setup:upgrade- This command will properly register the module with Magento.
bin/magento setup:di:compile- This command compiles classes used in dependency injections.
Once the module installation has completed, the link to the Hello World page should appear in the Greetings section under Content in the left navigation in the admin area. Clicking this link will take you to a page that looks like the one pictured below.