Posting in the Magento forums has been disabled pending the implementation of a new and improved forum solution which should better serve the community.

For new questions please post at magento.stackexchange.com, the community-run support site for the Magento community. We will be providing updates on the new forum solution soon. For questions or concerns please email community@magento.com.

Magento Forum

How do I set the content of the home page? 
 
Jason J
Sr. Member
 
Total Posts:  79
Joined:  2008-05-29
 

I have installed the ‘blank’ theme to work with on a shop I’m putting together. I have just about worked out which templates do what and what I need to change to get the layout that I want. But one thing - probably a really simple thing - I just cannot fix, is the content of the home page.

The ‘classic’ theme contains various blocks and adverts, and listings on the home page. All the blank theme is showing me, apart from the right-hand column, is the text “Home Page” (content of the CMS home page).

How do I get it to look more like the classic theme home page? For example, how would I get a selection of products, the latest products or top-sellers onto that page?

Do I need to mess with the templates? Do I embed some codes into the CMS page content? Is there an admin screen I have not yet found which lets me add functional blocks to the layout of that home page?

Sorry if this seems obvious to others, but I just don’t know where to start. I don’t know what that missing piece of the jigsaw is.

Thanks,

-- Jason

 
Magento Community Magento Community
Magento Community
Magento Community
 
Jason J
Sr. Member
 
Total Posts:  79
Joined:  2008-05-29
 

Just to add, I have spent weeks looking at the templating system used by Magento, and still just don’t get it. I am used to working with templating systems that construct pages from lots of parts, and blocks and group them together etc. but I seem to be missing something completely here - all the documentation I have found is fairly abstract, e.g. “Magento puts everything together for the column”, but then fails to explain how it goes about doing that.

I can’t even work out how to get rid of the picture of the dog in the left column. I’ve found the template that displays the dog, but it gets passed its image names and URLs from something else, but what, I don’t know. And how does it end up in the left column and not somewhere else? Help! I am tearing my hear out! What exactly is it that I am just not able to see? Is there some magical guide that I have not yet found?

Sorry - I would love to stick to a single specific question, but I don’t understand enough of this system to be able to ask the right questions.

-- Jason

 
Magento Community Magento Community
Magento Community
Magento Community
 
Kara Heinrichs
Guru
 
Avatar
Total Posts:  482
Joined:  2008-01-17
aa, mi, us
 

The layout (xml) files will be your frien-emy here.  I don’t have a really clean way to describe the Magento templating system either (you do get used to it).  But essentially the template (phtml) files control what gets shown, but the xml files control what gets invoked and where. So whether those template files are ever even called is set in the xml files.

For example, page.xml defines the default blocks and templates that will be invoked throughout the website.  catalog.xml defines which additional blocks apply to the catalog pages (as Magento classifies them--this is the real tricky part).  customer.xml defines which additional blocks apply to the account section (why isn’t it called account.xml then? Nobody knows...) And so on.

The dog you hate so much is set to be called in catalog.xml.  The hunk of xml that defines and calls it is shown below.  Delete or comment that out to ditch the dog.

<default>
<
reference name="left">
   <
block type="core/template" name="left.permanent.callout" template="callouts/left_col.phtml">
      <
action method="setImgSrc"><src>images/media/col_left_callout.jpg</src></action>
      <
action method="setImgAlt" translate="alt" module="catalog"><alt>Our customer service is available 24/7. Call us at (555555-0123.</alt></action>
      <
action method="setLinkUrl"><url>checkout/cart</url></action>
   </
block>
</
reference>
...
</default>

It kind of goes on like that.  But if you open up and look at the xml files, you’ll begin to see block names you recognize and this is where you turn them on or off or move them around to show up left instead of right and vice versa. 

Don’t know if that helps or not, but I think based on what you’ve said that that’’s your next step--familiarizing yourself with the layout files.  Luck,
--k.

 
Magento Community Magento Community
Magento Community
Magento Community
 
Jason J
Sr. Member
 
Total Posts:  79
Joined:  2008-05-29
 

Thanks kara - that does help a lot. Just knowing that everyone else finds certain things tricky helps me to plod on - when I know I’m not missing something obvious staring me in the face, then I know I’m not wasting my time going through all the minor details.

So, from what you say, the concepts seem to be:

* phtml files contain HTML and some PHP. They define what things look like, but not when they will or will not be displayed. I assume they contain some logic such as loops for generating tables (but I need to find some examples of that).

* xml files define what is displayed and when. Magento is split up into many sections and those sections define which of the XML files are loaded up to be processed. Trying to work out what the sections are and what they are called is tricky, because they don’t appear to be listed or described in one place.

* There are blocks of functionality (that have their associated templates). These are invoked through the XML files, with parameters passed in through XML tags. Again, there is no single list of these blocks with documentation on their parameters. Unlike most CMSs, the block structure is defined through these XML files that are edited directly, and not through admin screens. I guess this is one thing that makes it more difficult to set up, since there is no single admin screen that lists all the available blocks.

How is that for a start? It would be nice if there were a theme that were full of comments describing how it works. I think that would help beginners a lot.

-- Jason

 
Magento Community Magento Community
Magento Community
Magento Community
 
Jason J
Sr. Member
 
Total Posts:  79
Joined:  2008-05-29
 

Specifically on that laptop dog template, I make some changes to it and included my own image and links in there. Now I have seen how to do it, it makes sense - thanks.

So an analysis of that block is:

* The block type is ‘core/template’. That appears to be similar to an ‘include’ in other templating systems - it just pulls in a template without any particular functionality.

* The template is located at “callouts/left_col.phtml” (in the apps/design theme). It could have been anywhere though. Some of the template folders are linked to specific blocks of functionality by their name (I think - “customers” is one you mentioned) but this one “callouts” is just an arbitrary name used by the theme designer.

* The name of the block “left.permanent.callout” - I cannot work out what the significance of that is. Is it, again, an arbitrary name defined by the theme designer? I created a second block with the same name, and both ended up with the same content. I then changed the names to “left.permanent.callout1” and “left.permanent.callout2” and they both took on their own separate content. So my conclusion is that this is a naming scheme left up to the theme developer, and so we should not expect any project documentation on these names.

* The parameter (child tags) - again arbitrary. These are passed in here and referenced from the template. I could add my own tags and reference them. I assume that for other blocks with functionality in them, the parameters will be pre-defined, and some may be mandatory. Again, where these would be documented is a mystery - perhaps in lots of different places. Oh, and the naming convention - ‘action’, ‘method’ - no idea how these relate to ‘parameters’ at all. I guess there is a whole new dialect to learn.

Is that accurate?

-- Jason

 
Magento Community Magento Community
Magento Community
Magento Community
 
Jason J
Sr. Member
 
Total Posts:  79
Joined:  2008-05-29
 

Well, I think it has finally dawned on me why this stuff is so hard. It’s because designing a theme for Magento seems to be a one-way process.

It is one thing to put a page together and decide how it is constructed from its constituent parts. It is another thing altogether trying to work out what the constituent parts are of a theme in order to make changes.

For example, I’m trying to change the links at the bottom of a page; I would like four groups of links. There is no way to look at the footer and determine logically where all the current links are coming from. That’s the problem I am having - I can’t just say “okay, following the rules I now know, I can deduce that these N places are where I would find the source of this block of HTML”.

Instead it seems to be a case of trial-and-error poke this or that, display debug messages, display template paths (and try to work out how they get included in the first place too). It’s not the kind of development I am used to. I’m more used to a linear approach: this is what I want to do -> this is where I go to do it. Instead, I know what I want to do, but then I need to search and open every single template and XML file available to try to work out how to do it.

So, am I being unduly unfair on the Magento templating system? If so, are there any tools or techniques that I am overlooking? If not, then what kind of thing would help? Perhaps a map of the blank template as a flow diagram showing dependencies? Maybe just a crib sheet with examples of dependency paths for typical parts of a normal theme? Maybe it is just the wiki that needs fleshing out?

Dunno - I am missing something here, and cannot believe I am the only one. But I don’t know what.

-- Jason

Edit: Just searching Google, and the web is full of statements like “I worked with Magento earlier in the year and it was a nightmare” and “Ugh, I won’t take another one of those projects”. I’m sure it is just something small that can be done to improve that perception.

 
Magento Community Magento Community
Magento Community
Magento Community
 
Jason J
Sr. Member
 
Total Posts:  79
Joined:  2008-05-29
 

I’m probably talking to myself, but here is something that clicked today. The block type often uses underscores in the names. These underscores convert the name into a path in order to locate the code behind a block.

I was looking at stuff like this and wondering where on earth “html_fooer” was defined, so I could see how it worked:

<block type="page/html_footer" name="footer" as="footer" template="page/html/footer.phtml">
                <
block type="page/switch" name="store_switcher" as="store_switcher" template="page/switch/stores.phtml"/>
                <
block type="page/template_links" name="footer_links" as="footer_links" template="page/template/links.phtml"/>
            </
block>

In fact, block “page/html_footer” is actually under Page/Block/Html/Footer.php

Knowing this helps to understand what blocks are available. Looking in the code for these blocks also shows us what templates they use. Some - like the one above - do not predefine a template and so it can be passed in as an attribute. It would be nice to think that *any* of these blocks allow the template to be overridden, but that does not seem to be the case - most set the template as the last action in their constructor (actually, that’s wrong - see below).

e.g .Block type “page/template_links” is controlled from a class at:

app/code/core/Mage/Page/Block/Template/Links.php

Looking in the code, it sets the template to “page/template/links.phtml”, meaning that the template attribute passed in, in the blank theme is redundant (it can be left out completely and the page still works the same). Interestingly, if I set the template attribute to another template, then Magento attempts to use that, so the template attribute *does* somehow override that set within the block class.

Note: these template paths are *arbitrary*. There is no real logic to them apart from what the block developer decided at the time the block was developed. We need documentation that lists what the default templates are for each block and that would help a lot. Also what I am ignoring here is the various template override and fallback schemes used across themes, stores and websites. These can be largely ignored as they “just work”, i.e. they are pretty unobtrusive to the way things work.

So, once you are inside a template (page/template/links..phtml in this case) you have access to the block object as $this. The links class offers getLinks(), addLink() and removeLinkByUrl(), as well as whatever it inherits from its parent class.

One thing to watch out for in these classes, is that they define their own objects internally. So, a list of links would be an array of Varien_Objects. That gives each link a bunch of methods as well as properties that is is worthwhile knowing about. Again, that would be a good one for the documentation.

-- Jason

 
Magento Community Magento Community
Magento Community
Magento Community
 
Kara Heinrichs
Guru
 
Avatar
Total Posts:  482
Joined:  2008-01-17
aa, mi, us
 

Now that you’ve gotten this far, see if these 2 wiki articles help fill in any of the blanks.  They don’t rise to the level of great documentation, but they are a wee bit helpful and will likely make more sense now than when you began.
http://www.magentocommerce.com/wiki/doc/magento-architecture
http://www.magentocommerce.com/wiki/basic_magento_directory_overview

Also, sometimes easier than clicking through the core files you can use the auto-generated docs at:
http://docs.magentocommerce.com/

Again, not great documentation, but sometimes it’s easier to see all the methods in one list.

 
Magento Community Magento Community
Magento Community
Magento Community
 
Jason J
Sr. Member
 
Total Posts:  79
Joined:  2008-05-29
 

I’ll do what I can.

I had come across those architecture diagrams a long time ago (more than a year ago) but strangely didn’t find them again until you just posted those links.

I have kind of got the hang of lots of little bits of theme, but still lack the understanding of how the major bits fit together, for example how one XML layout file gets chosen over another.

-- Jason

 
Magento Community Magento Community
Magento Community
Magento Community
 
Kara Heinrichs
Guru
 
Avatar
Total Posts:  482
Joined:  2008-01-17
aa, mi, us
 

I hear you.  I don’t have the answers either.  I’m just thinking out loud with you here, but one of the reasons I go back to that architecture diagram is that it shows that the controllers are the real itermediaries. They contain the built in knowledge of what module will respond given a finite set of user actions.  I used to try to see all the relationships in the layout files, but they’re not actually there.  Magento is prewired to understand it’s own architecture via the controllers.

Don’t know if it’ll help at all, but early on I drew the attached IA diagrams with the Magento modules/layouts overlaid so I could keep track of what controlled what.  Maybe helpful?  or something you can extend as you lock in your own understanding of how Magento does and doesn’t work.

Image Attachments
magento_layouts.pngmagento_blocks.png
 
Magento Community Magento Community
Magento Community
Magento Community
 
tjonnyc
Sr. Member
 
Total Posts:  111
Joined:  2009-04-07
 

Trying to find the right file among Magento’s 10,000+ files is a pain.
But there’s hope - the “Template Path Hints” function.

Admin -> System -> Configuration -> change “Scope” to “Main Website” -> Advanced -> Developer -> Debug -> turn “Template Path Hints” ON (you may also want to turn on the “Add Block Names To Hints” option).

Reload the front-end, and you’ll see a bunch of overlays showing you exactly which files create which blocks, and what the block names are so you can locate them in the XML catalogs.

Image Attachments
Template_Path_Hints_medium.jpg
 
Magento Community Magento Community
Magento Community
Magento Community
Magento Community
Magento Community
Back to top