Getting Started

Introduction

In Donation Store, themes describe how the actual webstore looks to the customer. They have custom CSS or modifications in the CSS to change how they look. Most of the time, the actual HTML code (the template) is mixed in with the theme. The theme docs, will, for the most part, comment on both the CSS and HTML code together as having a separate section for templates doesn't seem right as they are both tightly coupled.

A lot of the time, theme authors will change how the store looks by changing the CSS, but they will also change how the page is structured in order to follow their design.

Creating a New Theme

Donation Store comes with a theme already installed, it's called the "default" theme. It is found in the /templates/store folder. For the purposes of ensuring consistency with updates and to ensure your changes don't get overwritten, you should copy the default directory and make a new folder with your theme's name in the same /templates/store directory.

Change Imports

When you copy the default theme and call it your own name, you may notice that the theme imports files for the footer and header. Because you copied the default template, these will be imported from the default template. This should be changed where appropriate to your new template. Read more about including and extending templates in the Includes and Extends doc.

How to Develop Themes on a Store

You have two options when editing the theme and template files, you can edit them straight from your server (preferably using a test store or one that isn't launched/in maintenance mode), or you can use the Donation Store Marketplace Sandbox.

If you choose to edit the files directly from the server, you will more than likely want to enable auto reloading on the Donation Store service (more on this in the next section below).

Right now the Marketplace is still under development, however it will be ready for beta access very soon. It will allow authors to sell their content related to Donation Store, but it also has the Sandbox, which is an environment setup for theme authors who don't want to purchase Donation Store to either create a theme for sale on the Marketplace or create a theme for their client.

The Sandbox is an in-browser file editor that is linked to a mock/test store that shows a demo store that isn't real but shows all the different states the store can be in so you can create the theme live. This is quicker than editing it live from the main app as the demo store is static, fake data.

Enable Auto Reload

By default, the Gunicorn web server that accepts requests and passes them onto Donation Store needs to be restarted when code changes, whether that be the template or the Python code itself. To avoid having to do this, you can enable reload mode on Gunicorn, which will restart the workers anytime the files changed.

Navigate to

/etc/systemd/system/donationstore-app.service

and add the —reload flag to the ExecStart line. The complete file should look like this:

[Unit]
Description=donationstore daemon
PartOf=donationstore.service
After=donationstore.service

[Service]
User=donationstore
Group=www-data
WorkingDirectory=/home/donationstore/env
ExecStart=/home/donationstore/env/bin/gunicorn DonationStoreV2.wsgi:application --bind [yourIP]:8000 --reload --error-logfile /var/log/donationstore/error.log --access-logfile /var/log/donationstore/access.log

[Install]
WantedBy=donationstore.service

You also need to ensure Debug mode is enabled in the settings.py file in

/home/donationstore/env/DonationStoreV2/settings.py

Debug = True

Please note that this mode is potentially hazardous as it shows internal information about how the application is written and information like server IPs etc. For this reason, this should only be enabled in a testing environment and never in production.

Once you save that file, reload the daemon and restart Donation Store.

systemctl daemon-reload
service donationstore restart

Now when you change any of the template code, your changes will be reflected immediately.

The next step, lets see how we can start customising the template.