h1. django-adzone Documentation

© Copyright 2013 Andre Engelbrecht. All Rights Reserved.

h2. License

Please see the LICENCE file for information on the License.

h2. Disclaimer

Please take note: django-adzone has just gone through a major update. If you have been using the previous version of django-adzone, then you should not upgrade since you are highly likely to break something. You have been warned :)

0.2b is a alpha release. Please test and report any bugs that you may find.

h2. Release Notes

• Many thanks to, Rafael for adding internationalization and pt_BR translation!
• AdBase model is no longer abstract.
• Added a manager to the AdBase class which can be used to return specific ads
• AdBase child models (ie. textad and bannerad) no longer needs a get_absolute_url method
• Removed the FlashAd model. This will be used in a example on how to create your own ad types (coming soon)
• The url to view a ad is now a named url pattern, so reverse lookups can be used.
• The zone_ad template tag is now a inclusion_tag

h2. Concept behind adzone

The concept behind adzone is quite simple. You have certain areas on your website reserved for adverts. The size and nature of the ads may differ for each of these areas. Adzone allows exactly this kind of functionality, by choosing which adds belong to certain zones.

Ads are grouped according to 2 criteria

h3. 1.The Category

The ad category explains the nature or subject matter for the advert. This can help to specify in which pages of your site you want a specific group of ads to appear. For example, you have a bunch of ads related to your blog, so you add them to your Blog category.

h3. 2.The Zone

Zone specifies what area on the current page the ad belongs to. If you are displaying a ad on your blog you might have 2 zones, one for content, and one for the right column.

These two grouping criteria provides enough flexability to control what ads will display where. All you need to do is to use the adzone template tags, to specify categories and zones in your templates.

h2. Note on Adblock plugins for browsers.

If you have any adblock plugins installed in your browser, it may be best to either disable them or add your site admin to the whitelist. If you dont, there is a risk that certain fields may not show up when you want to edit anything.

h2. Installing

Installation instructions may vary depending on your environment. To install system wide however, just run:

@python setup.py install@

h2. How to use

h3. Getting Started

1. Add @adzone@ to your installed apps.
2. To make sure that the user IP is recorded on the impressions, add the following to your TEMPLATE_CONTEXT_PROCESSORS: @'adzone.context_processors.get_source_ip'@ (this is not a requirement for the app to work in general)
3. Add the adzone urls to your project urls: @(r'^adzone/', include('adzone.urls')),@
4. Remember to run syncdb again :)

h3. Using the built-in template tag to display an ad

To show a specific ad in a template, you can use the built-in template tag. Lets say you have the following Ad Category and Zone set up in your database (via Admin): ad category title: 'General' ad category slug : 'general' ad zone title: 'Content' ad zone slug: 'content'

Now, in your template, you first want to load the tag library: @{% load adzone_tags %}@

Averts are loaded through the use of two tags:

@{% random_zone_ad 'sidebar' %}@ - Loads a random advert for the sidebar zone

@{% random_category_ad 'sidebar' 'general' %}@ - Loads a random advert from the "general" category, for the sidebar zone.