Theme pages
Understanding the different HTML pages which Enstore needs to run properly is probably the best way to start customizing themes. In this article we will go over all the standard pages which you will find in all the default themes and what happens on each page. In this article you will also find helpful code examples and snippets which you can use for your own theme.
The Base page Back to top
Where can I see the Base page?
The Base page cannot be requested directly. As you will see when you read on, you'll view the base page through other pages like the browse and item page.
Blocks
We're going to start with explaining the base.html page, because it functions as a foundation for most (if not all) other pages. The base page should contain all the common elements of your store, like the cart, menus and logo. On the base page you can define blocks that child templates can override. The best way to explain this is with an example. For instance, take a look at this very simple example of a base.html:
<body>
<h1>My Great Theme</h1>
<p>Welcome to my store</p>
[% block main %]
[% endblock %]
</body>
Now, you can make the item and browse page extend on the base page. They will inherit everything from the base page. You can overwrite the main block, thus inserting the content from the browse or item page. This is an example of a browse page:
[% extends "base.html" %]
[% block main %]
<p>This is an example text. This is an example text.</p>
[% endblock %]
What we're basically saying here is, take base.html and overwrite block main. Everything between the block tags will be inserted on the place where block main tags were written on base.html. If we view browse.html in the browser it will look like this:
You can find a lot more on blocks and template inheritance in the Django documentation.
What to put on the Base page
The base.html page provides a base for all your other pages, it provides a place to place your commonly used elements like the main menu and the footer. Having one place to put all the generic elements on prevents you from doing things over and over again. Following are elements which you should put in the base.html.
The store's logo and name
In the admin interface you can set a store logo. You can put the following code in your base.html which will show the logo.
[% if settings.logo %]
<img src="[[ settings.logo|imagelink ]]" alt="Logo">
[% else %]
[[ settings.name ]]
[% endif %]
Because the logo is uploaded via the admin, the logo is stored in the store's settings. That's why we need to use the imagelink filter on the settings.logo variable. Now, you can also choose to not use that logo, for example if you're designing a theme for one specific company. You can put the logo image in the assets folder en link to it from base.html like so:
<img src="[[ "mystorelogo.png"|asset ]]">
The cart
We recommend placing the cart in the base.html as well. You can find more information about the cart here. You can include your cart in your theme like so:
[% include "cart.html" %]
The Main Menu
How to loop through the main menu items set in the admin.
The Product Label Menu
The product tag menu displays a list of tags, with which you can search for products. The menu is configured in the admin and can have two levels, menus and submenus. The settings.menu variable is a list through which we can loop:
[% for topmenu in settings.menu %]
<a href="[[ settings.url ]]/browse/[[ topmenu.tags|join:"," ]]/1">[[ topmenu.title ]]</a><br>
[% for submenu in topmenu.submenus %]
<a href="[[ settings.url ]]/browse/[[ submenu.tags|join:"," ]]/1">[[ submenu.title ]]</a><br>
[% endfor %]
[% endfor %]
The Footer
On the bottom of the page, many people will expect a footer holding some additional information. The footer can be set in the admin and shown in the theme with the following code:
[% if settings.templateContent.footer %]
[[ settings.templateContent.footer|textile ]]
[% endif %]
The Browse page Back to top
The browse page is the page where Enstore can list all the requested products. Upon requesting the browse page Enstore retrieves a list of products from the database and returns those to the browse page.
The contents of the product list depends on the parameters you send along with the request. These parameters can be tags, sort method, search terms or a combination of the previous.
If you don't request anything special, just the page, Enstore will retrieve you a list of product sorted alphabetically limited by the page size.
Requesting the Browse page:
[[ settings.url ]]/browse
To select a specific page, you can append the page number after /browse/ if not set, Enstore automatically goes to the first page:
[[ settings.url ]]/browse/4
Labels
You can display products with specific labels like so:
[[ settings.url ]]/browse/[tag-1],[tag-2]/
Sorting
You can sort on the following parameters:
[[ settings.url ]]/browse/1?sort=name <!-- sorting on product name -->
[[ settings.url ]]/browse/1?sort=brand <!-- sorting on brand -->
[[ settings.url ]]/browse/1?sort=price <!-- sorting on price -->
Products on the Browse page
Enstore finds all the products matching your query and puts them in a list. You can display this list by putting this in your browse.html:
[[ products ]] <!-- This is a list of products -->
Doing this, your browser will just display a big blob of product information and you probably don't want that. So try this:
[[ products.0 ]] <!-- Only display the first product in the list -->
Still a blob of information, but this is all about the first product in the list. Now try this:
[[ products.0.name ]] <!-- Show the name of the first product in the list called products -->
Success, now we've got something useful. But there are many more products in the list, and we don't want to rewrite this code all the time, especially because we never know how much products there are.
That's why we use the FOR tag to list all the products. The FOR tag lets you loop through all the items in a list and do something for every item in the list.
[% for product in products %] <!-- products here is the same as [[ products ]] -->
[[ product.name ]] <!-- print this product's name -->
[% endfor %] <!-- Close the forloop when it's done -->
A little more extensive example:
[% for product in products %]
[[ product.brand ]]
[[ product.name ]]
<span class="currency">[[ product.price ]]</span>
<img src="[[ product.images.0.url|imagelink ]]">
[% endfor %]
The Item page Back to top
The item page displays one single product and all its specifics. Upon requesting the item page you will have to provide a product for the page to find.
There is only one good way to make a request for the item page. It looks like this:
[[ settings.url ]]/item/[product-slug]
Enstore will take this address and load the item page. It uses the product slug to retrieve all information for the corresponding product. When your page is ready, you can access all this information through the [[ product ]] variable.
In very few situations you don't know the product slug, usually when working with complicated JavaScript. In those cases it benefits to work with a product's UUID. With it you can request an item page like so:
[[ settings.url ]]/item/[product-uuid]
Although this approach works fine, it's against best practices. Mainly because search engines, like Google, can't index the UUIDs and thus your products are not findable using search engines.
A product on the Item page
The purpose of the Item page is to show product details and images. All product information is accessible through the following dictionary.
[[ product ]]
Example:
<h1>[[ product.name ]]</h1>
<h5>[[ product.brand ]]</h5>
<p class="currency">[[ product.price ]]</p>
<p>[[ product.description ]]</p>
The code above will display the name, brand, price and description of the product. The currency class makes sure the price is formatted in the right currency with the right annotation. A product has many more properties, you can find a list of all possible properties here.
The Welcome page Back to top
The Welcome page is an optional page which can be set in the admin. It allows for an welcome text, a tag menu and a selection of featured products.
Requesting the Welcome page
You can request the welcome page using the following url:
[[ settings.url ]]/page/welcome
Featured products
Some stores want a selection of their top products featured on the welcome page. You can achieve this with the following snippet.
[% get_products_by_tag as featured_products using "new" "3" %]
What this does, is get list called featured_products from Enstore. Enstore populates this list with all products which are tagged with "new" and limits the results by 3. Obviously "new" can be any other tag and you can retrieve as many products as you want.
Tags
You can also get a list of tags by using the following tag:
[% get_product_tags as tags %]
The Page page Back to top
In the admin it's possible to set up generic pages. People can use these generic pages to display custom content. For example a terms and conditions or a contact page. Every custom page is rendered using the page.html, the content of the page is passed as a variable.
Requesting a page
You can request a page using the following url:
[[ settings.url ]]/page/[page-handle]
Content
To display the text set in the admin you can use the following variable:
[[ content.main|textile ]]
The Textile filter enables people to use Textile to markup their text.