Template Tags

Introduction

Sometimes within the Donation Store UI, there is some functionality that cannot be expressed through HTML alone and by expressing the functionality in the view just doesn't make sense. For this, Donation Store offers template tags. These template tags can be called within a Donation Store template. They are linked to a backend Python function that executes some sort of functionality. Most of the time, these tags return some sort of value that you can then use in the template.

In Donation Store, template tags look like this

{% is_logged_in webstore as logged_in %}

This doc will cover all of the built in template tags that Donation Store offers, how you can use them and what they return. Note that you can make your own custom template tags but that is described in this doc.

is_logged_in

This tag is intended to check if a given user is logged in. It takes the current webstore object and returns True or False based on whether the user is logged in or not. The result is stored in the logged_in variable. For example

{% is_logged_in webstore as logged_in %}
{% if logged_in %}
	User is logged in!
{% else %}
	The user is not logged in
{% endif %}

get_user

This tag is used to get the current user who is logged in. It takes the current webstore object and returns a dictionary with the user's username and their UUID. It is advised that this is only used while you are sure the user is logged in as specified above with the is_logged_in tag. For example

{% get_user webstore as logged_in_user %}
{{ logged_in_user.username }}
{{ logged_in_user.uuid }}

get_cart_contents

This tag is used to get the contents of the cart if it exists. If there is no items in the cart then it will return None. If there are items, it will return a list of items witch the quantity of each and the package object. The items can be iterated over like below

{% get_cart_contents webstore as cart %}
{% for item in cart %}
    {{ item.quantity }}
    {{ item.package.name }}
{% endfor %}

Note that the deductions using coupons or sales are done at the checkout to allow for this to be verified on the server side.

If you want to see what values you can access on the package object check out the Variables Doc where it lists each field and its description

check_for_sale

The purpose of this tag is to check if a given package is eligible to be on sale based on what is set on the control panel. It takes the package ID of the package it is checking and the current webstore id. Depending on whether or not there is a sale it will return different values.

It will return a sale dictionary that has the is_on_sale boolean set to True or False. If its true, it will return the original_price and sale_price values in the dictionary too. If the package is on sale, but the package is set with "Allow customer to change price", it will return True for is_on_sale, but it will also return a True value for allow_customer_to_change_price. If this is present and is set to True, you shouldn't render a price, but instead the translation of the user is allowed to choose how much they want to pay. For example

{% check_for_sale package.id webstore.id as package_on_sale %}
{% if package_on_sale.is_on_sale %}
	{% if 'allow_customer_to_change_price' in package_on_sale %}
		You decide how much to pay.
	{% else %}
		{{ package_on_sale.original_price }}
		{{ package_on_sale.sale_price }}
	{% endif %}
{% else %}
	{{ package.price }}
{% endif %}

get_add_to_cart_buttons

The purpose of this tag is to check to see if a particular customer is allowed to buy a particular package. You should use this tag to construct the button that is displayed when the customer tries to purchase a package.

The tag returns a dictionary with different values in it. If a customer is allowed to purchase a package, the value of is_allowed_to_purchase will be True, if they aren't it will be False. You should display disabled or enabled buttons based on this.

The "Buy" or "Subscribe" button text should be derived by you when checking what kind of package it is.

This tag returns a reason why the user cannot buy a certain package. It's up to you to decide how that is displayed, but by default, it is displayed as a Tooltip. If the customer is allowed to purchase a package and is_allowed_to_purchase is True, then a reason will be returned, in the reason field.

It takes the language package_payments package and webstore object, all accessible from the store front. For example

{% get_add_to_cart_buttons language package_payments package webstore as cart_button %}
{% if cart_button.is_allowed_to_purchase %}
	{% if package.purchase_type == 'O' %}
	<input type="submit" name="add_to_cart" class="btn btn-primary" value="{{ language.translations.add_to_cart }}">
  {% elif package.purchase_type == 'S' %}
  <input type="submit" name="add_to_cart" class="btn btn-primary" value="{{ language.translations.add_to_cart }}">
	{% endif %}
{% else %}
	<span class="d-inline-block" tabindex="0" data-toggle="tooltip" title="{{ cart_button.reason }}">
	{% if package.purchase_type == 'O' %}
		<input type="submit" name="add_to_cart" class="btn btn-primary" value="{{ language.translations.add_to_cart }}">
	{% elif package.purchase_type == 'S' %}
		<input type="submit" name="add_to_cart" class="btn btn-primary" value="{{ language.translations.add_to_cart }}">
	{% endif %}
	</span>
{% endif %}

get_gateway_offset

This tag is used to return the offset for a given gateway if it is set. This one is pretty simple, it takes the gateway and the cart total and just returns a price which then should be passed into the get_price_using_currency tag (explained below), to get the amount in the set or chosen currency. For example

{% get_gateway_offset paypal_gateway request.session.cart_total as offset %}
{% get_price_using_currency offset webstore %}

get_price_using_currency

Prices throughout the store should use this tag as it takes a given price in the base currency and returns it in the selected currency. For example if a package was €10 and the webstore currency is EUR and the user is viewing the store in that currency, it would display 10 EUR. If the user picks USD, then the 10 would be converted to USD using the above tag and it would return 10.88 USD (or whatever the exchange rate is at the time). It does this dynamically based on the currently selected currency. It takes the price your displaying and the webstore as objects. For example

{% get_price_using_currency package.price webstore %}