How to create your first module

As the first article, it is perfectly natural to start with some Magento basics. We are a development company after all, so after a lot of though, we decided to start with up to date tutorial of how to create a new module. In the time of writing that, the current Magento version is 1.8.1, but we will try to update it when the long expected version 2 comes.

Prerequisites:
Installed Magento, either on local machine or on a development server.

Fundamentals:
Magento is devided into folders. For our purposes of creating a simple module, our folder of interestest is /app

Lets start with briefly explaining what are the folders inside.

/code – here is the code of all modules. This is divided into /core, /community, /local. Normally /core folder (app/code/core) is reserved for the core Magento modules and it shouldn’t be tampered with (you will loose all changes on update). /community folder is for modules from third party companies. /local – this is the folder you are interested in. In the local folder are all of the local developed modules. Unfortunately, not all companies are keeping that conventions and they are saving their modules in the local folder.

/design – as name suggest here is the whole design of the site. Both for the frontend part and from the admin interface.

/etc – here are the module definitions and the data base connection settings. You should be really careful with permissions of that folder.

/locale – here are all locales for the different languages and the email templates for the specific language.

Now, back to the module creation, lets start with the structure of the module.

- app
- code
- local
- NameSpace
- CompanyName
- etc
- modules
- NameSpace_CompanyName.xml

There are two parts here. NameSpace and CompanyName, both in the module definition and as local folders. The idea of NameSpaces is to “group” more than one modules inside a folder. Most of the companies use that namespace as CompanyName. So for our testing purposes we will use Buzzjective as namespace and First as module name.

Here you should note a couple of things. All blank spaces are replaced with a capital letter of the second word. This is a part of the best practices. The module we are creating is in 2 folders inside /app – code and etc. The purpose of that is 1. Define the module 2. Execute the module files. If you read carefully so far, you will know that the module is defined in app/etc/modules and the modules files are in app/code/local.

So lets start our actual work by creating the definition file. Go to the app/etc/modules/ and create a file named Buzzjective_First.xml and put the following contents.


<?xml version="1.0" encoding="UTF-8"?>

<config>

<modules>

<Buzzjective_First>

<active>true</active>

<codePool>local</codePool>

</Buzzjective_First >

</modules>

</config>

Most of the times the only differences here are the words “Buzzjective_First” and the codePool. As I previously explained you, there are 3 folders with modules code – core, community and local. It is easy to guess that we need to use <codePool>local</codePool> for our testing purposes. “Buzzjective_First” is basically telling the system to go inside app/code/local/Buzzjective/First and look for a code there. <active>true</active> is only activating the module – it can take true and false as arguments.

Now the module is defined and we can go and create the folders we just defined. Go to app/code/local (it should be empty or missing with the initial installation) and create folder “Buzzjective” and inside that folder create folder named “First”.

Now lets take a look at the module’s actual structure:

/etc – this is the only required folder of a module. All configuration files of the module should be placed there (just like the Magento configuration file is placed inside app). The only required file of a module is config.xml

/Block – This folder is used for the View classes (Magento is using MVC architecture – Model-View-Controller). //TODO Magento MVC article

/Model – This folder is used for the Model classes – generally models are used for data interactions – in/out connection to the database.

/controllers – This folder contains the controller classes. Controllers are used for the business logic of the module.

/Helper – This folder is used for saving utility files that can be called from everywhere.

/sql – This is the folder that is used for database interaction when the module is installed or updated (create new table, add new attribute .. so on)

As I already mentioned the only required file is /etc/config.xml, so go ahead and create it with the following contents:

</pre>
<? xml version="1.0" encoding="UTF-8" ?>

<config>

<modules>

<!--

This must exactly match the namespace and module's folder

names, with directory separators replaced by underscores

-->

<Buzzjective_First>

<!-- The version of our module, starting at 0.0.1 -->

<version>0.0.1</version>

</ Buzzjective_First >

</modules>

</config>

This is similar to the module definition file, but here are defined the actual configuration of the module. In the example I am making it is the version – 0.0.1

Now when you save that file, you can go to the Magento backend and clear your cache.

When you do that go to System > Configuration > Advanced > Advanced and go to “Disabled Module Output” and you will see your first module “Buzzjective_Local” enabled.