Modules

Introduction

Modules are small pieces of independent functionality that can be placed throughout your webstore. Donation Store comes with some default Modules that can be used by you throughout your store. This guide explains how they work, specifically when it comes to using them when making custom themes and templates.

How Modules Work

All Donation Store modules have some common fields. These include the header, the on home page status and the template URL. Each is described below:

• Header - This is the small bit of customisable text that you can enter on the Control Panel that is intended to describe the module.

• Homepage Status - Modules can be placed inside Pages, or more commonly within the Home Page, Login Page etc. (where applicable). If this is enabled, the module will not only be shown on the Page's you choose but also on the homepage and login page etc.

• Template URL - Each module has a relevant template which is how the module looks. While the backend code is provided for you, you have customisability over the front end/how it looks. This template URL is relative to the current active template. For example, if you have the "default" theme enabled, then you will find the module templates in:

  templates/default/modules
  

  The template URL for a given module is relative to the current template. For example, a Gift Card Balance module would have a template URL of:

  gift-card.html
  

  When you have the default theme enabled, Donation Store will prepend the path to the template dynamically. This means that if you created a new template and switched to that, the path would change from:

  templates/default/modules/gift-card.html
  

  to something like this:

  templates/other-template/modules/gift-card.html
  

How Modules are Rendered

If the module is a "homepage" module, every time a page is loaded that is considered a "homepage", Donation Store will get the full list of active modules from the database and render them in that section. If you look at one of the template files, this looks like the following:

{% for module in modules %}
	{% include module.template %}
{% endfor %}

You don't need to edit this as it will do all of the rendering for you. If you want to render the "homepage" modules on a page that isn't already included, you can place the above code into it and Donation Store will render them as normal.

The Template

As stated above, each module has it's relevant template. The template can have any structure (and can use any style) you'd like, however, the default template will give you an example of how it works.

Each template is linked to a backend function in the Donation Store code. These functions provide the actual functionality of a module and will return a module object that can then be used by you throughout the code. The module object that is returned is slightly different for each module, so this document goes into detail about each, but here is a generic example:

{% top_customer_module as top_customer %}
<div class="top-customer">
	<p>{{ top_customer.username }}</p>
	<p>
		{{ top_customer.period }}
		{% if top_customer.amount %}
		{{ top_customer.amonut }}
	</p>
</div>

As you can see, you have access to some of the data on the module once it has been returned.

Note about Forms

Some modules may contain HTML form elements. These are used to send requests to the Donation Store backend for some sort of information, for example, to check the balance of a gift card. To prevent Cross Site Scripting attacks, a token is generate for each form request that is then checked on the backend to make sure that the request was legitimate and came from where Donation Store was expecting. That's why you may see this tag:

{% csrf_token %}

Inside a form, just before the end. This is essential for forms and it won't work without it.

The next doc explains each module individually. Click here to View the Modules Doc