When you are first starting out Magento can be a bit intimidating, with what seems like a million folders and files it will take some time to get familiar with where things are located. Almost one year later, and many learning experiences under my belt I would like to share with you some of the things I wish I knew starting from day one. As with every new skill you attempt to master you can only get better with time and practice so have a read through this post, set yourself up with a new install of Magento and start coding!
Before I dive in I’ll make a quick note – here at Demac PhpStorm is our editor of choice while working with our Magento projects. If you are head over heals for another editor, switching over may seem crazy but trust me the benefits are worth it.
1. Editing Files
Whether you are a front end or backend developer the one golden rule of Magneto is NEVER EVER EVER edit a core Magento file – that is any file that comes as the base install which include the frontend > base folder and frontend > package > default folder. If you want to – and you will – make changes to these files here is what you must do.
Create a new theme folder:
First, Magento works with a fallback system. This means that you can have multiple working themes and then tell Magento which one to look for when it renders your site. If you are making any type of changes to the base install you will want to set up a new theme and later I will show you how to point Magento to it. To make a new theme create a new folder on the same level as default (which is just inside of the package folder) and give it a new name. This rule also applies to creating a few theme inside of the skin folder. Inside of the new theme folder create a separate folder called layout (for a .xml files) and templates (for .phtml files). There you go, new theme started!
Set up the theme fallback system:
You will only see these new changes being made if the new theme is set up to do so. To set this up log into Magento and head to System > Configuration > Design.
1. Package Tab: If you are working on an Enterprise install this field should say ‘enterprise’
2. Themes Tab: Set translations, templates, skin and layout all to your new themes name. If the default field is left blank Magento will automatically use the base theme as its fallback meaning that if it can’t find a file it needs in your new theme then it goes to the one in the base folder next. This is why we only duplicate each file we need separately instead of the whole theme folder because it is not necessary to have duplicated content with a fallback system in place.
With any type of configuration changes made you will need to flush the cache. Go to System > Cache Management, click the flush Magneto cache button, this will make sure your new changes have been applied. If you are just starting a new build and the site is only on your local computer it is safe to turn the cache off so you do not have to refresh it each time you make a change.
Editing Template Files:
Any file you want to change in the default theme, copy the original file into your new theme folder with the same structure as it originally had and then start making changes. This ensures your changes are upgrade safe because the upgrade will not touch a custom theme. The image below shows how you would duplicate the catalog/product/view.phtml and how you would set up a local.xml file for layout changes.
Editing Layout Files:
If you look in the base themes layout folder you will see many .xml files – one for each module. Unlike with templates where we copy each file to the new theme with layout we just create one file called local.xml and place it in our new themes layout folder. design > frontend > package > new theme > layout > local.xml. More details to come on what we can write inside of it.
Using the translate function:
When you open a .phtml you will see this used a lot
<?php echo $this->__(‘Text Here’)?>
That is a tranlate function and all of the text you write inside of the .phtml files should be written inside of the translate function. Whether you are writing a page title, label, or text in a button it’s best practice to put it inside of the translate function.
What this translate function allows you to do is access language translations stored in a a .cvs file. (app>design>frontend>package>theme>locale>languagecode) Even if you only have a store in one language to start off with it’s best to do it the right way first so if you do decide to add a language in the future you don’t have to go back into your template files and add this code around all of your text. The language code for the folder follows a pattern – example en_CA for English Canada, and fr_FR for French France.
Inside the .csv file you can write “Shopping Cart”,”French Translation of Shopping Cart” as as expected any text that follows exactly what is within the first quote before the comma will be translated to what is after the comma. Spacing and capitalization count and you should start each translation on a new line.
Create and Edit CMS Content:
Magento allows users to create either individual blocks or whole pages that they have access to edit from within their account. These are called CMS Static Blocks and CMS Content blocks. Static blocks are helpful to keep content modular and easy to access. They can be used for promotional banners on a homepage or links in your header/footer. A CMS page can be used for Contact Us, or Shipping Policy where this content can be edited by the user and does not need to be stored in a template file.
Create a CMS block:
1. Create it in the database. Log in to your Magento account and go to CMS > Static Block > Add New Block.
Block Title : user friendly name and easy to identify, can have spaces (e.g. New Block Name)
Identifier: will be set in the local.xml file, should have no spaces and use a consistent naming convention (e.g. new_block_name)
Store View: set to all or only select stores.
Enabled: Turned on or set to Disabled to turn it off.
Content: Add images, text or even add another static block inside of it.
2. Add the new CMS block to our layout and template folders so it knows which page, template and block it is being displayed in.
Inside of the local.xml file you can add a <layout> tag, and then <default> tag if you want this block to appear on every page. Otherwise as I show below we will only add it to the homepage using the <cms_index_index> page handle.
<block type="cms/block" name="new_block_name" alias="new.block.name">
1. Add the handle of the page you are using the block on, in this example its the homepage.
2. Reference the structural block you want the static block to be displayed in, in this case it is the main content area. (link to docs about structural blocks).
3. Create the block with the attributes type, name and alias.
4. Use the action method to tell magento what we are doing with this block.
5. Set the block id – which is is the identifier you set when you create the block.
*CMS pages do not need to be set anywhere, they will appear automatically.
Add Css or Js Files
To add a .css or .js file you would add this in the layout.xml file.
<default> The default handle adds this css file to every page, you only need this once.
<reference name="head"> Referencing the head will add it to the head of the document
<action method="addItem"> addItem is used for css or js files
<type>skin_css</type> Here we specify that its found in the skin folder and whether it is a css or js file
<name>css/styles.css</name> Here we provide the folder and file name. Because we specified skin above it knows to start the file path from the skin folder so you just need to add the remaining path from there.
To add a js file you would do the same as above but <type>skin_js</type> and <name>scripts.js</name>
Searching for a file or folder
Knowing how to search for a file can help save you a lot of time when you’re first starting out and aren’t familiar with the folder structure. Command + Shift + F when you have a folder selected will search that directory for any text you choose. So if you’re looking for a page name or the class of an element this can be helpful. It will return a list of files that its found in an you can go from there.
Magicento is a setting you can enable in PhPStorm that does many helpful things for you. Hitting Shift two times will search for a file name throughout the whole directory. If you want to duplicate a file just press control + M and select ‘copy template’ and then your package and theme and it will copy the file and folder structure for you. This saves time and ensures there are no typos or incorrect folder structure.
Enabling File Path Hints:
System > Configuration > Developer > Select Current Configuration Scope > Debug > Template Path Hints (turn to yes)
You may need to clear cache again if its is enabled and then return to a page and refresh it. You should see something like this. Red lines around your page with tags that tell you which block it is and it’s template. This can help you quickly narrow down which file you need to edit.