# Introduction to Dukaan Themes
Dukaan themes are a collection of templates, stylesheets, and scripts that determine the look and feel of your online store. They are built using a combination of HTML, CSS, JavaScript, and the Nunjucks templating language. Customizing your theme allows you to create a unique shopping experience tailored to your brand and audience.
## π If you're not a coder
We recommend that you learn about the basics of HTML, CSS, JS (can also skip this if you're really good at Googling :wink:) and then start with the tutorial from the [next chapter](/building-your-own-custom-theme).
## π§βπ» If you're a coder
Brush up on your HTML, CSS & JS skills and top it with some Nunjucks. If you're not aware of Nunjucks worry not we have covered the basics of it here in the [Nunjucks chapter](/nunjucks-templating-language).
## π οΈ Cut the fluff and just show me how to deploy
You can directly learn about deploying your changes [from this chapter](/making-your-first-edit).
# Building your own custom theme
Before you start building your custom theme, you must have a Dukaan account.
Sign up for a free Dukaan account to access theme development resources (You can create your dukaan account [here](https://web.mydukaan.io/))\
\
Once your account is created we're all set get tinkering.
To make your custom theme you'll get HTML, CSS & JS files with the bare minimum amount of code which is required and you can build on top of that.
# Getting the basics right
* Login to your Dukaan account here - [web.mydukaan.io](https://web.mydukaan.io/)
* Then click on the "**Appearance"** section on the left hand navigation pane\
* In the Appearance tab you will have a list of all themes.
* The first theme card is the theme which is currently applied on your store, click on "**Customize"** button
* Here, click on "**Code editor"** button to build your magic\
# Making your first edit
Before we dive deep into folder structure, customizing components, functions and all, let's just try to make a simple change to see how it looks like.
This is how the **"Code Editor"** page looks like. Please ensure you are on this page before we proceed further.\
### βοΈ Objective - To add the text "My custom theme" to the top of the page
1. In the left hand side, click on the file "layout.html"\
\
This is how it would look like
2. Now in the layout.html file, just inside the `` tag, below it add the code `
My custom theme
`\
3. Once you have added the text, click on "**Save & Preview store"** button
4. Now your changes would be deployed to a preview site which is different from your main store website
5. Your preview store link would be `.sh/` \
(Note - It's not yet deployed to your original store link, which is `mydukaan.io/`)
6. The mobile preview is visible within the code editor itself.
7. If you can see, the text "My custom theme" is now visible on both mobile screen as well as desktop site. Awesome, you just edited your theme!
8. We can also make the text bold by changing the HTML to this. \
`
My custom theme
`\
Similarly, you can continue playing around with
# Theme folder structure
A Dukaan theme primarily consists of three types of files:
1. HTML (.html)
2. CSS (.css)
3. Javascript (.js)
When you open the code editor, you can view the folder structure of a theme, which is organized as follows:
```
public/
β
βββ css/
βββ dist/ (ignore this folder for now, you won't need to change any files here)
βββ js/
βββ index.html
βββ layout.html (root HTML file, also known as the parent HTML file)
βββ product.html (contains code for the products page; it inherits layout.html)
βββ search.html (contains code for the search page; it inherits layout.html)
βββ category.html (contains code for the category products page; it inherits layout.html)
βββ categories.html (contains code for the categories page; it inherits layout.html)
βββ subcategories.html (contains code for the subcategories page; it inherits layout.html)
βββ coupon.html (contains code for the coupons page; it inherits layout.html)
βββ advance-category-templates.html
βββ product-variant-templates.html
```
`layout.html` serves as the main parent file and is considered the root HTML file. All other files can be thought of as child files. The `layout.html` file is the base template that contains the common structure and elements for your website. You can use blocks in this file, which can then be customized in child templates.
For each specific page, there is a separate HTML file that extends the `layout.html` file. For example:
* For the products page, there is a `products.html` file.
* For the categories page, there is a `categories.html` file.
* Similarly, there are separate files for other pages like search, category products, subcategories, and coupons.
By organizing the theme in this manner, you can maintain a clean and modular code structure, making it easier to develop, customize, and maintain your website.
## π€ How is it different from frameworks like React?
In the Dukaan theme, files are organized based on pages rather than components, which is different from a component-based framework like React. In React, each component is usually defined in a separate file, allowing for reusability and a modular structure. However, in the Dukaan theme structure, **one file corresponds to one page.**
This means that the `products.html` file contains the entire code for the products page, the `categories.html` file contains the entire code for the categories page, and so on. This approach is more focused on organizing the code based on pages, rather than breaking down the code into smaller, reusable components.
Despite this page-based organization, templates can still be reused across multiple pages by using the `layout.html` file. This file serves as the base template for the entire website and contains the common structure and elements that are shared across different pages. By defining reusable templates in the `layout.html` file, you can ensure that these templates only need to be defined once and can be extended or customized by the child pages (e.g., `products.html`, `categories.html`, etc.) as needed.
In summary, while the Dukaan theme does not follow a component-based structure like React, it still allows for template reusability and modularity by utilizing the `layout.html` file as the base template for all pages.
# How does it all work?
As discussed previously, we use html files for different pages, products page has its own html file, similarly for categories page and so on.\
But how are all these pages related and linked to each other? The answer to that is a templating engine. \
We could also put all the .html into a single file layout.html but that would a horibble mess of code and a big huge difficult to read file and if you add dynamic content to it, god bless you and your coders! Hence we split it into different files for easier maintenance and understanding.\
\
However with this code could be duplicated across these files and a lot of other issues can arise.\
Hence to keep things organized, reduce repitition of code, and handle dynamic content we use a templating engine to simplify the things. \
\
Dukaan theme uses Nunjucks templating engine, we have explained about it in the [next chapter](/nunjucks-templating-language).
## π€ How to know which file to change?
Let's understand with an example.\
Imagine the layout.html file is like the menu template for a restaurant. It defines the overall design, font, and color scheme of the menu. This template is used by all the different sections of the menu, such as appetizers, main courses, and desserts.
Now, think of the product.html file as the dessert section of the menu. It follows the same menu template (layout.html) but has its unique dessert items and descriptions listed.
In this case, Nunjucks acts like a menu designer who uses the menu template (layout.html) to create the overall look of the menu and then adds the specific items and descriptions for each section, like the desserts in the product.html file.
To customize the restaurant menu, you have two options:
1. If you want to change the overall design, font, or color scheme of the entire menu, you can edit the layout.html file (the menu template). This will affect all sections of the menu that use this template.
2. If you only want to change something specific to the dessert section, like adding a new dessert item or updating its description, you can edit the product.html file. This will only affect the dessert section and leave the rest of the menu untouched.
So, if you wanted to make the product title text bold, you have to goto the products.html page and then find the variable which contains the product title and update its css to bold.
\
# Nunjucks Templating Language
We will cover the very basics of Nunjucks that you would require while building a theme.\
You can view the complete official docs of Nunjucks here -.
### 1. Variables
Variables are like containers that store information. In Nunjucks, you can use double curly braces `{{ }}` to display the content of a variable.
For example
```django
Add to bag, one {{ product_name }}!
```
This will display: `Add to bag, one Cookie!`
### 2. Operators
Operators are symbols that help perform operations on variables, like simple math or comparisons.
For example
```django
Total cart cost: {{ price + tax }}
```
This will display: `Total cart cost: 12`
### 3. Loops
Loops are a way to repeat actions or display a list of items. In Nunjucks, you can use the `for` loop to go through a list and perform an action for each item.
For example:
```django
{% for product in products %}
{{ product }}
{% endfor %}
```
This will display:
```
Bag
Pen
Paper
```
### 4. Conditional statements
Conditional statements, like `if`, `elif`, and `else`, allow you to perform different actions based on certain conditions.
For example:
You can display a message depending on whether a user is logged in or not:
```django
{% if user_is_logged_in %}
Welcome, {{ username }}!
{% else %}
Please log in.
{% endif %}
```
This will display:
`Welcome, Kaushik`
### 5. Template Inheritance
Template inheritance in Nunjucks helps you create a consistent structure for your website by allowing you to reuse a base template and customize specific parts for different pages. It's like having a blueprint that you can use to build various rooms in a house (If you remember the Menu example we explained in the previous chapter).\
\
Let's understand with a simple example.
1. Base Template - layout.html\
It that has the common structure and elements for your website. Use the `{% block %}` tag to mark areas that can be customized in child templates.
```html
{% block title %}
Default Title
{% endblock %}
{% block header %}
Header
{% endblock %}
{% block content %}
{% endblock %}
```
2. Child Template - product-details.html\
Create a child template (e.g., `product-details.html`) that extends the base template using the `{% extends %}` tag. Then, use the `{% block %}` tag again to override and customize the content in specific areas.
```html
{% extends "base.html" %}
{% block title %}
Product Details - My E-commerce Website
{% endblock %}
{% block header %}
{% endblock %}
{% block content %}
Product Name
Product description goes here. This product is perfect for those who are looking for a high-quality, stylish, and durable item.
{% endblock %}
```
### 6. Include
Include allows you to insert reusable components or partial templates into your main templates. It's like using puzzle pieces to build a complete picture. This feature helps you maintain a consistent structure across your website and avoid repeating code.\
\
Here's an example.
Header & footer usually have same content across pages, say product details page, homepage and checkout page. So, it doesn't make sense to duplicate them everywhere, instead we can just define them in 1 file and then use that across all the pages.\
\
Let's create 2 files, header.html & footer.html
```html
```
```html
```
Now you can just use these files across all your pages. Let's see how.
```html
{% extends "layout.html" %}
{% block header %}
{% include "header.html" %}
{% endblock %}
{% block content %}
{% endblock %}
{% block footer %}
{% include "footer.html" %}
{% endblock %}
```
Similarly we can also use it in about.html
```html
{% extends "layout.html" %}
{% block title %}
About Us - My Website
{% endblock %}
{% block header %}
{% include "header.html" %}
{% endblock %}
{% block content %}
About Us
Welcome to our website! We are a company dedicated to providing the best
products and services to our customers. Our team is passionate about
innovation, and we work hard to ensure that we exceed your expectations.
Our Mission
Our mission is to deliver top-quality products and services that make a
positive impact on people's lives. We strive to achieve this goal by
constantly improving our processes, staying up-to-date with industry trends,
and listening to our customers' feedback.
{% endblock %}
{% block footer %}
{% include "footer.html" %}
{% endblock %}
```
### 7. Filters
These are used to modify the output of variables or expressions before they are displayed. Think of them as tools that can tweak or transform data into the desired format. Filters are applied using the pipe symbol `|`. It can be used in the following way.
To convert a text to uppercase we can write this
```
{{ pageTitle | upper }}
```
This will display `WELCOME`
### 8. Comments
Comments are used to add notes or explanations to your code that will be ignored by the template engine and will not be displayed on the rendered page.
You can add a comment in Nunjucks by using `{# ... #}`. Any text within the opening and closing braces will be treated as a comment and ignored by the engine.
For example, in the code below, line 2 is a comment. Note how it starts and ends with a #.
{% code lineNumbers="true" %}
```html
```
{% endcode %}
### Conclusion
With this our introduction to Nunjucks is complete and you're all set π, this sums up the bare minimum Nunjucks needed for editing a Dukaan theme.\
If you want to delve deep into the official documentation [here](https://mozilla.github.io/nunjucks/)[ is the link.](https://mozilla.github.io/nunjucks/)
# Basic code editing
We shall now move into learning how to make edits into our theme to change the structure, looks and functionality.
### βοΈ Objective - To show list of categories in a carousel in layout.html page
We will divide it into 4 parts
1. [Adding the HTML](/basic-code-editing/adding-the-html) for the product card to display (If we were building a house, this step would be building the structure of the house using cement, wood, bricks)
2. [Adding the CSS](/basic-code-editing/adding-the-css) i.e. color, shadow and other visual elements to make it look appealing (painting the building, adding flooring, furniture, etc.)
3. [Adding the Javascript](/basic-code-editing/adding-the-javascript) i.e. functionality to the product card, like, what happens when someone clicks on a product, or hovers on it (Adding fans, lights, electric wiring, etc)
4. [Adding Nunjucks](/basic-code-editing/adding-nunjucks) for fetching real data and using it to display the products (Inviting people to live in the house)
# Adding the HTML
### βοΈ Objective - To display categories in homepage
Open the layout.html file
This is how a bare minimum layout.html file would look like, it has some code which is required for a theme to function properly, avoid removing any of this code.
```html
{% include './../../dukaan/common/theme-fonts.html' %}
{{ 'splide.min.css' | css | static }}
{{ 'layout.css' | css | static }}
{{ 'styles.css' | css | static }}
{% include './../../dukaan/common/seo_tags/commonSeoTags.html' %}
{% include './../../dukaan/common/theme-colors.html' %}
{% block head %}
{% endblock head %}
{{ 'head' | DukaanBlocks }}
{% include './../../dukaan/common/spinner-loader.html' %}
{% include './../../dukaan/common/hellobar.html' %}
{% block content %}
{% endblock content %}
{% include '../../dukaan/common/bxgy-sticky-footer.html' %}
{% include '../../dukaan/common/store-open-sticky.html' %}
{% block postfooter %}
{% endblock postfooter %}
{{ 'footer' | DukaanBlocks }}
{% include './product-variant-templates.html' %}
{{ 'variant-utils.js' | js | static }}
{{ 'dukaan-utils.js' | js | static }}
{{ 'layout.js' | js | static }}
{{ 'dukaan-coupons.js' | js | static({ defer: true }) }}
{{ 'dukaan-offers.js' | js | static({ defer: true }) }}
{{ 'axios.min.js' | js | static({ defer: true }) }}
{{ 'splide.min.js' | js | static }}
{{ 'common-components.css' | css | static }}
{% include './../../dukaan/common/auth.html' %}
{% include '../../dukaan/common/multilanguage.html' %}
{% include './../../dukaan/common/common-scripts.html' %}
{% include '../../dukaan/common/snackbar.html' %}
{% block script %}
{% endblock script %}
```
If we check now, our site would be completely blank. Now, we will try to display a dummy category.
We will display a category image and category name, go ahead and paste this code inside the body tag.
```html
```
This code snippet creates a simple HTML structure to display a category card within a container. The category card includes an image and the category name, for now we have hardcoded a dummy image and category name, both wrapped within a hyperlink element for navigation purposes.
\
If you save & preview the changes, you'd see something like this
Let's try to add some more dummy categories, the updated code would be
```html
```
This is how our site looks now
Now that we can display dummy data with HTML its time to flare up the tags by spicing it up with some CSS in the next chapter.
For reference - The contents of layout.html file after the above changes
```html
{% include './../../dukaan/common/theme-fonts.html' %}
{{ 'splide.min.css' | css | static }}
{{ 'layout.css' | css | static }}
{{ 'styles.css' | css | static }}
{% include './../../dukaan/common/seo_tags/commonSeoTags.html' %}
{% include './../../dukaan/common/theme-colors.html' %}
{% block head %}
{% endblock head %}
{{ 'head' | DukaanBlocks }}
{% include './../../dukaan/common/spinner-loader.html' %}
{% include './../../dukaan/common/hellobar.html' %}
{% block content %}
{% endblock content %}
{% include '../../dukaan/common/bxgy-sticky-footer.html' %}
{% include '../../dukaan/common/store-open-sticky.html' %}
{% block postfooter %}
{% endblock postfooter %}
{{ 'footer' | DukaanBlocks }}
{% include './product-variant-templates.html' %}
{{ 'variant-utils.js' | js | static }}
{{ 'dukaan-utils.js' | js | static }}
{{ 'layout.js' | js | static }}
{{ 'dukaan-coupons.js' | js | static({ defer: true }) }}
{{ 'dukaan-offers.js' | js | static({ defer: true }) }}
{{ 'axios.min.js' | js | static({ defer: true }) }}
{{ 'splide.min.js' | js | static }}
{{ 'common-components.css' | css | static }}
{% include './../../dukaan/common/auth.html' %}
{% include '../../dukaan/common/multilanguage.html' %}
{% include './../../dukaan/common/common-scripts.html' %}
{% include '../../dukaan/common/snackbar.html' %}
{% block script %}
{% endblock script %}
```
# Adding the CSS
### βοΈ Objective - To add design to the category divs
Open the layout.css file, you would be seeing some existing code in it, for now you can ignore it.
Let's add the following css to the end of layout.css file
```css
/* layout.css */
/* ... other existing styles ... */
.container {
display: flex;
overflow-x: auto;
width: 100%;
padding: 1rem;
}
.category-card {
flex: 0 0 auto;
width: 200px;
margin-right: 1rem;
text-align: center;
background-color: #fff;
box-shadow: 0 2px 5px rgba(0, 0, 0, 0.1);
border-radius: 5px;
overflow: hidden;
}
.category-link {
text-decoration: none;
color: inherit;
}
.category-image-wrapper {
width: 100%;
height: 0;
padding-bottom: 100%;
position: relative;
}
.category-image {
position: absolute;
top: 0;
left: 0;
width: 100%;
height: 100%;
object-fit: cover;
}
.category-name {
padding: 1rem;
font-size: 1.1rem;
font-weight: bold;
}
/* Media queries for responsiveness */
@media (min-width: 480px) {
.category-card {
width: calc(50% - 1rem);
}
}
@media (min-width: 768px) {
.category-card {
width: calc(33.333% - 1rem);
}
}
@media (min-width: 992px) {
.category-card {
width: calc(25% - 1rem);
}
}
@media (min-width: 1200px) {
.category-card {
width: 200px;
}
}
```
This CSS code snippet provides styling for the category card HTML structure. The main container is a flex container with horizontal scrolling enabled. Each category card has a fixed width, a margin to its right, and some basic styling such as a background color, box-shadow, and border-radius.
{% hint style="info" %}
Don't remove classnames which start with "dkn-" because they are used by internal functions.
{% endhint %}
The category link has its text decoration removed and inherits the color from the parent. The category image wrapper has a square aspect ratio and uses the padding-bottom trick to achieve this. The image is positioned absolutely within the wrapper and covers the entire space, maintaining its aspect ratio.
Lastly, the category name has some padding, font size, and font weight adjustments to make it stand out more.
Wohoo! It looks beautiful now, with our CEO Leo lighting up the page with his cuteness.\
\
After you've added this, its time to add some functionality to our cards, what if a user clicks on the category card? We could take it to category page, display a message or just shower confetti!
\
We'll figure it out in the next chapter
# Adding the Javascript
### βοΈ Objective - When user clicks on category card, it should show the category name in a popup
Open the file layout.js and add the following code to it
```javascript
/* layout.js */
document.querySelectorAll('.category-link').forEach(link => {
link.addEventListener('click', event => {
event.preventDefault();
const categoryName = event.currentTarget.querySelector('.category-name').textContent;
alert(`You clicked on ${categoryName}`);
});
});
```
This JavaScript code adds a click event listener to each `.category-link` element. When a user clicks on a category card, a popup appears with a message displaying the category name.\
\
Go ahead and deploy this change and see your action happening live on the preview site.
Once successfully deployed it would look something like above when a category card is clicked.\
\
Up next, its time to bundle up everything and show some real data using Nunjucks.
# Adding Nunjucks
### βοΈ Objective - To integrate dukaan categories data with the category cards we have created so far
Let's go back to our layout.html file, earlier it was just hardcoded categories, we will now display real categories from our store using Nunjucks.\
\
The categories data of our store comes from a variable called `DUKAAN_CATEGORY_LIST`. It's a list of categories, for now we just need the category name and category image.\
You can find a sample data of it and all other available variable list [here](/dukaan-data).
```html
{% include './../../dukaan/common/theme-fonts.html' %}
{{ 'splide.min.css' | css | static }}
{{ 'layout.css' | css | static }}
{{ 'styles.css' | css | static }}
{% include './../../dukaan/common/seo_tags/commonSeoTags.html' %}
{% include './../../dukaan/common/theme-colors.html' %}
{% block head %}
{% endblock head %}
{{ 'head' | DukaanBlocks }}
{% include './../../dukaan/common/spinner-loader.html' %}
{% include './../../dukaan/common/hellobar.html' %}
{% block content %}
{% endblock content %}
{% include '../../dukaan/common/bxgy-sticky-footer.html' %}
{% include '../../dukaan/common/store-open-sticky.html' %}
{% block postfooter %}
{% endblock postfooter %}
{{ 'footer' | DukaanBlocks }}
{% include './product-variant-templates.html' %}
{{ 'variant-utils.js' | js | static }}
{{ 'dukaan-utils.js' | js | static }}
{{ 'layout.js' | js | static }}
{{ 'dukaan-coupons.js' | js | static({ defer: true }) }}
{{ 'dukaan-offers.js' | js | static({ defer: true }) }}
{{ 'axios.min.js' | js | static({ defer: true }) }}
{{ 'splide.min.js' | js | static }}
{{ 'common-components.css' | css | static }}
{% include './../../dukaan/common/auth.html' %}
{% include '../../dukaan/common/multilanguage.html' %}
{% include './../../dukaan/common/common-scripts.html' %}
{% include '../../dukaan/common/snackbar.html' %}
{% block script %}
{% endblock script %}
```
In this Nunjucks template, we use a `for` loop to iterate over the `DUKAAN_CATEGORY_LIST` variable and create a category card for each item. We use the `{{ }}` syntax to insert the category name and image URL from the data.\
\
You can deploy the change, you can now see your store category data visible in the homepage.
\
π Awesome, you just displayed your store categories in your own custom theme. You can do more changes as per your requirement, to read more about the data which Dukaan makes accessible using Nunjucks read about [Dukaan Data](/dukaan-data).
# Customising Dukaan Templates
### π€ How to customise custom HTML Tag content
Say, you want to customise `` tag content, then you need to edit the content present inside the HTML tag `` having its corresponding Template id.
Similarly for other HTML tags, the tag name would be the template id.
### Add to bag button
1. ``
This button is used in Product Details page & Variants Modal
Template id - `add-to-bag-button-without-variant`
2. ``
This button is used in Product Card
Template id - `add-to-bag-button-with-variant`
3. ``
This button is used in Product Details page & Variants Modal
Template id - `buy-now-button-template`
If you want to customise the styles of Out of stock button please add/modify template having the id - `out-of-stock-button`
### Product cards
Depending on your theme you can find your product card template. The template ids used in different themes are
1. `product-card-template`
2. `similar-product-card`
3. `dkn-product-card-template`
4. `advance-filter__product-card`
Now you can customise the structure and styles according to your usecase.
{% hint style="info" %}
Don't remove classnames which start with "dkn-" because they are used by internal functions.
{% endhint %}
### Category cards
To customise the category card look for the template having the id `categories-card-template.`
{% hint style="info" %}
Don't remove classnames "category-image" and "category-name".
{% endhint %}
### Variant Pills
The template ids for customising variant pills are :
`"dkn-size-variant-item-template"`- To customise text type variants.
`"dkn-color-variant-item-template"`- To customise color type variants.
### Variant Modal
To customise the structure of variant modals look for the template id `product-variant-selection-modal`
{% hint style="info" %}
Don't remove classnames which start with "product-".
{% endhint %}
# Dukaan Data
You can access your store data using these keys on server side with Nunjucks by simply mentioning the variable name. Example - `{{DUKAAN_STORE.link}}`
This data is available on client side in the window object in a key called Dukaan Data. For example `window.DukaanData.DUKAAN_STORE`
### Variables
`DUKAAN_STORE - Store related information like store id, store link, etc.`
`DUKAAN_CATEGORY_LIST - List of active categories`
`DUKAAN_CATALOG - This is list of Dukaan Categories with their products and other data`
`STORE_MENU - Navigation menu related data`
Sample data
```json
[
{
"id": 269676,
"position": 0,
"label": "Why to buy from us ?",
"url": null,
"content_type": "storepage",
"content_object": {
"id": 7697,
"slug": "why-to-buy-from-us",
"image": ""
},
"name": "Why to buy from us ?",
"child": []
},
{
"id": 269677,
"position": 0,
"label": "Harry Potter & The Philosopher's Stone",
"url": null,
"content_type": "product",
"content_object": {
"id": 38266106,
"slug": "harry-potter-the-philosopher-s-stone-1",
"image": "https://api.mydukaan.io/static/images/category-def.jpg"
},
"name": "Harry Potter & The Philosopher's Stone",
"child": [
{
"id": 269678,
"position": 0,
"label": "TEST PRODUCT",
"url": null,
"content_type": "product",
"parent_id": 269677,
"content_object": {
"id": 38506255,
"slug": "test-product",
"image": "https://api.mydukaan.io/static/images/category-def.jpg"
},
"name": "pl",
"child": []
}
]
},
{
"id": 269679,
"position": 0,
"label": "Harry Potter & The Philosopher's Stone",
"url": null,
"content_type": "product",
"content_object": {
"id": 38266105,
"slug": "harry-potter-the-philosopher-s-stone",
"image": "https://api.mydukaan.io/static/images/category-def.jpg"
},
"name": "Harry Potter & The Philosopher's Stone",
"child": []
}
]
```
`DUKAAN_THEME_DATA - Theme related data like active theme, font, primary and secondary colors & theme sections`
Sample data
```json
{
"store": 101561150,
"payment_done": null,
"meta": {
"colors": {
"primary": "#146eb4",
"secondary": "#ee741f"
},
"header": {
"showStoreImageOnly": false
},
"favicon": {
"faviconUrl": "https://mydukaan.io/favicon.png"
},
"advanced": {
"product": {
"showAddToBagOnProductCard": true
}
}
},
"store_theme_data": {
"id": 2270035,
"twitterUrl": "",
"instagramUrl": "",
"facebookUrl": "",
"linkedinUrl": "",
"youtubeUrl": "",
"pinterestUrl": "",
"cxSupport": "+91-9040826685",
"deliveryHappensWithIn": "3-5 days"
}
}
```
`DUKAAN_BANNERS - This is a list of top banners and their related data`
Sample data
```json
[
{
"id": 73413,
"uuid": "85af7d36-904b-4eaf-8e0d-595bcf8b85cd",
"is_active": true,
"image": "https://dukaan-core-file-service.s3.ap-southeast-1.amazonaws.com/upload_file_service/ebaca373-2ed1-4c4e-8309-e1ca69dd7beb/image.png",
"url": null,
"position": 0,
"store": "31d9141e-acc5-4bbe-ad6a-ea6ef13dccf9"
},
{
"id": 25496,
"uuid": "3e00dd26-1ea0-460b-bbd9-5ae7dbe86cb3",
"is_active": true,
"image": "https://dukaan-us.s3.amazonaws.com/5540936/5b45f4f7-f9f4-4358-9674-c97bed40d23b/image-86e59caa-9859-4898-94d2-d3fba32b8c79.png",
"url": null,
"position": 1,
"store": "31d9141e-acc5-4bbe-ad6a-ea6ef13dccf9"
}
]
```
Only the essential variables are mentioned above, you can view the other variables by running `console.log(window.DukaanData)`in your browser console.
# Advance code editing
### β Alert - This is a section for pro wizards only π§
We have listed some of the complex customisations which are required by some customers in this section.
# Customising core functionality
Say you want to customise what happens after a user clicks on "Add to bag" button, we allow you to perform your own action using a function. This function has a pre-defined name as declared by our developers and all you need to do is use that function and define what it should do.
## βοΈ Objective - Display success message after Add to bag button is clicked
The name of the function which needs to be defined in order for an action to be performed after Add to bag event is called **`afterAddToBagCall`**
The function accepts 2 parameters **`productUUID`** and **`skuUUID`**
So, let's define the function
```javascript
window.afterAddToBagCall = (productUUID, skuUUID) => {
alert(`Add to bag button clicked`);
}
```
Let's add the above code snippet to our layout.js file. Once added, click on **Save & preview store** button.
On clicking the Add to bag (in this case Place in bag since we changed the text) button, we get a popup.
Once you click on OK the message disappears and your product is added to cart, as seen in the picture below.
This is how you can customise this function to do changes as per your requirement.
You can view list of all such custom [Dukaan Functions here](/dukaan-functions).
# Dukaan Functions
## 1. After add to bag event
```javascript
window.afterAddToBagCall = (productUUID, skuUUID) => {
alert(`Add to bag button clicked`);
}
```
## 2. Product card renderer
It renders the product card
mountElement is the element inside which the card is to be rendered. Mount element is the element which is targeted and inside which the current product card is to be appended.
```javascript
productCardRenderer(mountElement, product, {
additionalRenderer: nameOfYourFunction
});
```
## 3. Category card renderer
It renders the category card
mountElement is the element inside which the card is to be rendered. It is the element which is targeted and inside which the current category card is to be appended.
```javascript
categoryCardRenderer(mountElement, category, {
additionalRenderer: nameOfYourFunction
});
```
# Integrating Dukaan Plugins
Active plugin list can be access from window object
`window.ACTIVE_APPS_LIST` - It gives an object containing data about the status of plugins, its an object of key value pairs where the key is the plugin name and the value is boolean value representing the status.
### Sample data
```json
{
"REVIEWS_AND_RATINGS": true,
"COUNTDOWNTIMER": false,
"WISHLIST": false,
"STORE_LOCATOR": false
}
```
We will learn about how to integrate these plugins in your theme in the following chapters.
# Wishlist plugin
You can see the **Wishlist plugin** at work here, beside the Add to bag button there is a heart shape button which helps wishlist a product.
> If you're unaware of what **wishlist** does, it allows users to save products that they're interested in for future purchase or reference. It acts as a personal shopping list and helps users keep track of items they might want to buy later, without having to search for them again.
### π€ How to use ?
#### 1. Implementing the appearance & functionality of the wishlist button
Open the layout.html file and define the template and mention its id attribute such that it can be used wherever you want to place the wishlist template. In this case we are using the id **`"heart-wishlist-button-template"`**
```html
```
#### 2. Importing the wishlist template wherever required
Now you can use it directly wherever you need the wishlist button, for example we need it in the product card listing.
So, all you need to do is use the custom tag **`wishlist-button-load-point`**
Define this tag and in the attribute **`data-template-id`**mention the id you used for template, in our case it was **`"heart-wishlist-button-template"`** inside the tag you can define the UI element for the button as a default, else whatever has been defined inside the template shall be rendered.
```html
```
{% hint style="info" %}
Please note that you need to install the **Wishlist plugin** on the seller side for the changes to reflect on the store front.
{% endhint %}
# Countdown timer plugin
An active countdown timer looks like this in the product details page.
> A countdown timer displays a visual countdown to a specific date and time, usually the end of a sale or promotion. This creates a sense of urgency for potential buyers and encourages them to take action before the timer runs out. The countdown timer can help increase conversions, drive sales, and create a sense of excitement for customers.
### π€ How to use ?
{% code overflow="wrap" %}
```html
```
{% endcode %}
# Product scarcity plugin
The product scarcity plugin draws customers' attention and creates a sense of urgency to initiate an order. It places a statement signifying βlow stock alertβ or βlimited availabilityβ below your productβs listing.
This is how the plugin looks like in the product page
Hurry 10 order left
# Testing and Deploying Your Theme
For every change you make in the code editor, there are 2 steps involved.
1. Previewing how your change would look like & testing it.
2. Deploying the changes to your site
## π Previewing your changes
1. Once you make your changes in the code editor click on the **"Save & preview"** button on the top right corner of the code editor
This deploys your changes to an **intermediate url which is not your actual site**, i.e. your customers won't be able to see the changes, so its a perfect place to experiment
The intermediate url ends with a domain **".sh"** instead of the original Dukaan domain **".io"**\
So, if your store url was **"general-store",** \
It's preview url would be - **"mydukaan.sh/general-store"** \
whereas the original store link would be - **"mydukaan.io/general-store"**
On successful deployment you'd see a message something like this
Your changes would be visible in your preview url, and you can do all the testing you want here before you make the changes live for your customers.
Mobile screen preview is directly visible from the code editor itself, its on the right side of the code editor
{% hint style="info" %}
Note - You can deploy to your preview url as many times as you want, so feel free to experiment your ideas.
{% endhint %}
## π Deploying your changes
Now when you're sure that your customers must see the changes you've made you can deploy it with a single click by simply clicking on the **"Publish"** button
This makes all your changes live for your customers instantly on your original store url.
# Code Snippets
We have compiled some of the most commonly asked for customisation requests from our customers and listed it here for you.
# Changing text of Add to bag button
Say you want to update the text of **"Add to bag"** button to **"Place in bag"**.\
To replace this you need to go to the file that contains the text "Add to bag" and replace it with the new text.\
\
You can find the text in the file layout.html.\
In the file search for the text "Add to bag" and you'd find this code
Line number 291 has Nunjucks code `DUKAAN_LANGUAGE.ADD_TO_BAG`\
It basically fetches the text equivalent for "Add to bag" from the variable DUKAAN\_LANGUAGE which contains a list of all texts as per the store language set.
So, you can replace it directly with your text "Place in bag", and this is how the updated code would look like.
{% hint style="info" %}
You need to replace the text for all occurrences of "Add to bag" button in the layout.html file since this button is used in multiple places, make sure you don't miss out on any else you'll see the "Add to bag" text in some places and "Place in bag" button in the remaining.
{% endhint %}
Deploy the change to see it live on your preview and main store.
## Alternative using Javascript (Not recommended)
You can use query selectors to target the Add to Bag button and replace its text.\
Place this code snippet in the layout.js file and then deploy to see the changes live.
```javascript
const buttons = document.querySelectorAll('.without-cart-add-to-bag-button');
buttons.forEach(button => {
button.textContent = 'Place in bag';
});
```
# Adding shadow to product cards
You can make the product cards more fancy by adding some shadow to it so that it highlights and looks funky.
```css
.card {
border-radius: 10px;
box-shadow: 0px 5px 20px rgba(0, 0, 0, 0.5);
padding: 20px;
background-color: #F7F7F7;
transition: all 0.3s ease-in-out;
}
.card:hover {
transform: translateY(-5px);
box-shadow: 0px 15px 30px rgba(0, 0, 0, 0.3);
background-color: #FFC107;
}
```
The above CSS makes the card with rounded edges, a shadow effect, and a light grey background. When you hover over the card, it will move up slightly, the shadow effect will get stronger, and the background color will change to a yellowish color.
Add this CSS to the layout.css file and deploy the changes.
This is how the card looked previously
This is how it looks after adding the CSS, where the middle card is hovered upon.
# Adding auto-scrolling text in homepage
We will try to add a non-stop horizontal scrolling banner containing a brand name on the top of our store.
Open the layout.html page and the following HTML code to it just inside the body tag or anywhere as per your requirement
```html
```
After this, open the layout.css file and add the following CSS to the file.
```css
.scroll {
position: relative;
width: 100vw;
height: 15%;
background-color: #252525;
overflow: hidden;
z-index: 1;
margin: 0;
padding: 0;
}
.m-scroll {
overflow: hidden;
height: 100%;
white-space: nowrap;
animation: scrollText 10s infinite linear;
margin: 0;
font-size: 0;
display: inline-block;
}
span {
font-size: 50px;
display: inline-block;
min-width: 100vw;
margin: 0;
padding: 0;
color: white;
}
@keyframes scrollText {
from {
transform: translateX(0%);
}
to {
transform: translateX(-50%);
}
}
```
Once you're done, you can deploy the changes and wait for them to reflect on your store page. This is how it would look like
