How to keep your CMS blocks organized (and not go insane)


Head on over to Magento dashboard in your store and take a look at CMS blocks. How many CMS blocks have you got? Can you tell which of the blocks are being used on site and which are currently not active or can be safely removed? Can you pick a random CMS block and instantly know what it is and where to find it on site? In this article we’re going to cover a powerful way of organizing, searching and filtering CMS blocks by simply naming them in a specific way. And the best part is that it works out of the box in vanilla Magento without any extensions.

CMS blocks are very useful part of Magento. But there is a chance that, over time, you could have dozens (or even hundreds) of various CMS blocks on your Magento store. Those CMS blocks can be named by different people with different mindsets who use different naming conventions and terminology which, in different cases, can cause confusion and lot of time being lost on finding the block you’re looking for.

Currently, Magento admin dashboard doesn’t provide any effective way of organizing them besides some basic search and filter options. But we can make most of these options and come up with a simple, but powerful way of organizing and keeping track of the CMS blocks that works in vanilla Magento and doesn’t depend on extensions.

Simplest and most obvious solution can be found in naming the blocks in a structured way that makes sense to developers and merchants as well.

Rules, Goals and Basic Structure

Let us establish some rules and goals for our naming structure. Suggested naming convention for Magento CMS block titles must meet the following requirements (in no particular order):

  • It must be universal and applicable for all CMS blocks
  • Each block has to have a unique title
  • Users must be able to filter the blocks effectively and always find what they’re looking for without resorting to blind guessing or the other timewasting methods
  • It must work on vanilla Magento (CE or EE) and it must not dependent on any extension
  • Users should immediately get an idea what is the block’s position and purpose

Taking inspiration from various popular naming conventions and following the requirements, I have come up with the following naming structure for CMS block titles.

[TAG] Website Name – Store View – Template Reference – Layout Position – Component Name – Component Variation

Underlined components represent required parameters when naming a CMS block, rest of the parameters are optional.

Please note that you may use any format that you like and feel like it better fits your project. The presented structure is just a proposed naming structure that made most sense to me at the time.

Before we move onto examining each part of naming structure separately, here is an example of CMS block title following the naming rule and using only the required (underlined) parts:

Global – Footer – Social Media Links

Taking a Closer Look at Each Component

[TAG] (optional)

It can be used to tag specific blocks for a specific reason. Tags should be used as a temporary part of a name until requested action has taken place or the tag becomes outdated after new code deployment.


Value Description
[no-value] CMS block isn’t tagged
DELETE Marked for deletion and waiting for the final approval.
EDIT Requested an edit (content, code or design).
BUG-ticket number This CMS block contains an issue or a bug detailed in a ticket or a task defined in the ticket number which is optional.
OUTDATED-id Paired with the id of a block with a tag [NEW], it marks new CMS block which has been replaced with the newer version of the CMS block (with major changes) in recent deployment, but has not been deleted in case of code revert. It can be deleted after the deployment has been verified.
NEW-id Paired with the id of a block with a [OUTDATED] tag, it marks the new version of the CMS blocks that will replace the outdated one when the new code has been deployed to the site.


Website Name (optional)

Refers to the website name in Magento structure where the CMS block can be found.


Value Description
[no-value] Only one Website
multi Block can be found in multiple websites
[Store Name] Block can be found only in a specific website


Store View Name (optional)

Refers to the store view in Magento structure where the CMS block can be found. It can also refer to the i18n internalization to mark identical blocks in different languages.


Value Description
[no-value] Website doesn’t have multiple store views
multi Block can be found in multiple store views (Multilanguage)
en English language
de German language


Template Reference (required)

Refers to the page name.


Value Description
Global Global scope, component appears on all pages
Multi Component appears or 2 or more pages, but not all pages
Category Page Magento Category Page
Product Page Magento Product Page
Homepage CMS Homepage CMS Page
About Us CMS About Us CMS Page


Layout Position (required)

Position in the Magento page layout.


Value Description
Multi Component appears on multiple containers on a page
Content Main contents, main container
Sidebar Left Left sidebar container
Sidebar Right Right sidebar container
Header Website header
Footer Website footer


Component name (required)

Custom name for the CMS block that describes CMS block’s role.


Component Name Value
Sale Banner
Size Guide
Category Description


Component variation (required only under certain condition)

Variation for the existing CMS block. Required if the CMS block is a different version or an iteration of an existing block.


Component Name Value Component Variation Values Description
Component Name [no-value] or Regular No variation, base component
Sale Banner Summer, Holiday, Black Friday Various sale banners
Size Guide Shoes, Shirts, Pants Size Guide for various clothing
Category Description Accessories, Bags, Belts Category page CMS blocks

For the block identifiers, we have to take a different, but simpler approach in naming them. We don’t want to use the same naming format for block identifiers as for the block title, since the idea of the identifier that it doesn’t change to avoid completely refactor the code. I would suggest using the following format for the identifiers to keep up with the structured name format:


Proof of Concept and Examples

Using the presented naming format, let’s convert some block titles for some default Magento 1 CMS Blocks!

Default Magento 1 block title New block title
Footer Links Company Global – Footer – Company Links
Footer Links SM Global – Footer – Social Media Links
Category Landing Page Home Category Page – Content – Home
Category Landing Page Main Block Category Page – Content – Main Block
Cookie Restriction Notice Global – Header – Cookie Restriction Notice


New block title New Block Identifier
Global – Footer – Company Links company_links-regular
Global – Footer – Social Media Links social_media_links-regular
Category Page – Content – Home home-regular
Category Page – Content – Main Block main_block-regular
Global – Header – Cookie Restriction Notice cookie_restriction_notice-regular

That looks way better, doesn’t it? Look at all that info that you could get just looking at the CMS block title! We immediately know which store the block’s location on a website, it’s position on a page, content and role just by simply looking at the block title. Now, isn’t that awesome? But true power and purpose of this naming structure is in filtering the blocks.

Filtering CMS blocks by Block Title

Now that we created new naming format for our CMS blocks and gave them more meaningful titles, let’s see how this naming convention fares when searching for a specific block or a specific group of blocks.

It’s important to note the differences in Searching by Block Title in Magento 1 and Magento 2. Whereas Magento 1 is really strict in regards to search words where you have to type exact part of block title, in Magento 2 we have a more lenient search where every word separated by the empty space or every set of words in quote marks separated by the empty space would be searched.

For testing purposes, I have created 20 empty CMS blocks in Magento 1 and Magento 2 (shown in the images) and I gave them random block titles I could think of following the suggested naming format and I gave them their respective block identifiers following the suggested naming format.


Example – Scenario 1

Routine inspection for tagged CMS blocks (listing all tagged CMS blocks – bugs, delete requests, edit requests, etc.)

Even though there isn’t a keyword that applies for all CMS blocks which are, we cannot filter all the tagged blocks by searching (even though we can search for an individual tag like “[DELETE]”, for example). Instead of searching for each individual tag, we can make the tagged blocks appear on top of the list by sorting the CMS block title in an ascending order to make the tagged blocks appear first in the CMS block listing.


Example – Scenario 2

Listing all CMS blocks that may appear on a specific page (Product page, for example)

Let’s assume that we’re looking for a block that we saw on the Product Page. Sounds simple enough. We just type in “Product Page”, right?


But what if the block is “Global” or “Multi”? We should search for the block using page-specific parameters and widen the search to “Multi” or “Global” blocks if we don’t find it using page-specific parameters. We can also combine this search with info about layout position “Content” or “Sidebar Left” for example, to get better results while filtering. All this could be done using vanilla Magento filtering feature available in CMS Block Admin page. We can also use improved filtering in Magento 2 to get all results in one search.


And finally we end up with results we’re looking for. This way we get a list of all possible blocks that appear on a Product Page (excluding blocks marked with “Multi” which may or may not appear on the Product Page).

Same approach applies when searching the CMS blocks for the CMS block in the specific store, in the specific store view (language) and in the specific section in a page layout.

Example – Scenario 3

Listing all CMS blocks with specific variation (listing all holiday CMS blocks, for example).

It is important to also have rule when naming CMS block variations to allow easier filtering. In this case, if we have included a variation name “Holiday” in all of the CMS block holiday variations, we would simply have to search the CMS blocks by the keyword “Holiday” to display only the holiday CMS blocks.

Example – Scenario 4

Deploying a revamped page element (footer, for example) with updated CMS block (social media links, for example).

Before any code deployment, we need to move our updated CMS block for footer social media links and give it a tag [NEW-id] with the id of the original social media links block. After the code deployment and after verifying the deployment success, we need to update the original social media links block title with tag [OUTDATED-id] with the id of the new block. After a few days and if code revert isn’t needed and the block isn’t going to be used anymore, it is safe to either give it a [DELETE] tag or delete it.

Answers to Some Questions That You Might Have

Come on, is it even possible to have that many CMS blocks in your project?

Yes! From personal experience, I worked on projects who had the number of CMS blocks ranging from few dozen CMS blocks on a smaller project, to about a hundred blocks on a regular project and finally, to more than a thousand CMS blocks on a long-term large-scale project.

Why have “Global” and “Multi” values for Template Reference? What is the point?

“Global” refers to the elements that are defined as default in the Magento layout and they aren’t removed for any page/s on the site. “Multi” refers to the elements that are defined as default in the Magento layout, but which are removed from at least one page in the Magento layout.

Practical example would be removing excessive (and distracting) header elements only on checkout page to make sure customer is completely focused on the checkout form. In that case, you would need to use “Multi” in the removed CMS block’s name.

Why not just get an extension that fixes this issue?

Why not, indeed. Go for it. This is conceived as a free alternative that works out of the box and uses vanilla Magento features. All it takes is coordination and established rule between people who create and manage CMS blocks.

Editing that many block titles can become tedious when refactoring!

Magento 2 allows making quick changes to the CMS blocks (like changing a block title) right from the CMS block listing. Even though this method requires opening the CMS block in Magento 1 which is an extra step in comparison to Magento 2, the benefits greatly outweigh those occasional inconveniences.


I have an idea for a better naming structure!

Let me know in the comments. I am curious what other developers will come up with and how they organize and prioritize CMS block info.


Working with CMS blocks can be a messy job and organizing them can be even messier. It is astounding how much better we can manage CMS blocks simply by establishing naming rules. I hope that you found this method of naming CMS blocks useful and that it will help you in your projects. I am also hoping that this is just a temporary solution and that folks over at Magento will come up with a better way of organizing and keeping track of CMS blocks and CMS pages.

What do you think about this idea? Can you see yourself using an established naming rules for CMS blocks in your current or future projects? Or you have a better suggestion for the naming rules? I am curious to know your thoughts, opinions and ideas, so feel free to leave me a comment below.

About Adrian Bece

Frontend Developer

Frontend Developer who is not only fluent in numerous programming languages, he also plays electrical guitar and is avidly interested in hard rock music.

Read more posts by Adrian / Visit Adrian's profile


  1. how to add custom cart in product detail page right when add product to cart it should show right side only in cart block so please help me

  2. Awesome post! so helpful

    for the id’s, when you use the convention: component_name-component_variation

    do you encounter any situations with overlap? perhaps if a shipping banner is on a product page and homepage, but each one has different content. how would you handle that scenario?

    Homepage CMS – Sidebar – Shipping Banner
    Product Page – Sidebar – Shipping Banner


    1. Hello KJ,
      thank you for your comment. I am glad that you have found my article useful.

      Regarding the shipping banner question, as you said it yourself – the banner is in 2 different places and has different content, but they are both banners and related to shipping. Your suggested name reflects only the position and main type:

      Homepage CMS – Sidebar – Shipping Banner
      Product Page – Sidebar – Shipping Banner

      To avoid overlapping and to have more complete information about your CMS blocks, you need to add a “variation” at the end. Please view the “Component variation” section of the article for more info, but basically, “variation” reflects the slight differences in content or style of the CMS blocks, so in your case the name would be, for example:

      Homepage CMS – Sidebar – Shipping Banner – Regular Promo
      Product Page – Sidebar – Shipping Banner – Special Promo

      and their respective id-s:


      Let me know if this has been helpful or if you need more info.

      Adrian Bece

    1. Hi Peter,

      thanks for the comment. This only goes to show that the Magento community obviously has a lot of ideas for improving CMS blocks. It would be nice to see them revamped in future versions of Magento.

      Adrian Bece

Leave a Reply

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

You may use these HTML tags and attributes: <a href="" title=""> <blockquote cite=""> <code> <del datetime=""> <em> <s> <strike> <strong>. You may use following syntax for source code: <pre><code>$current = "Inchoo";</code></pre>.