- About Pinax
- Important Links
- Overview
- Documentation
- Change Log
- Contribute
- Code of Conduct
- Connect with Pinax
- License
Pinax is an open-source platform built on the Django Web Framework. It is an ecosystem of reusable Django apps, themes, and starter project templates. This collection can be found at http://pinaxproject.com.
Where you can find what you need:
- Releases: published to PyPI or tagged in app repos in the Pinax GitHub organization
- Global documentation: Pinax documentation website
- App specific documentation: app repos in the Pinax GitHub organization
- Support information: SUPPORT.md file in the Pinax default community health file repo
- Contributing information: CONTRIBUTING.md file in the Pinax default community health file repo
- Current and historical release docs: Pinax Wiki
pinax-calendars
, formerly named kairios
provides utilities for publishing events as a calendar.
At the moment, it just provides a visual calendar (both large and small) showing which days have events and optionally linking to a day detail page.
There is a demo project that you can clone and run to see pinax-calendars in action.
Django / Python | 3.6 | 3.7 | 3.8 |
---|---|---|---|
2.2 | * | * | * |
3.0 | * | * | * |
To install pinax-calendars:
$ pip install pinax-calendars
Add pinax.calendars
to your INSTALLED_APPS
setting:
INSTALLED_APPS = [
# other apps
"pinax.calendars",
]
Using pinax-calendars
is a combination of setting up a view that can
paginate through months, adapting a queryset of date-based data, and using a
template tag.
The end result is to render a month-based view of all your events.
Example:
{% load pinax_calendars_tags %}
{% calendar events %}
where events
implements the following protocol:
Returns a link to the page for the given day or None.
has_event
is a boolean telling this method whether
there is an event on the day or not so you can choose whether a day
without an event should link or not.
Returns a link to the page for the given month or None.
Returns a dictionary mapping day number to a list of events on that day.
Note that all methods take additional keyword arguments used for calculating the return value.
There are two mixins to make it easier to write monthly (pinax.calendars.mixins.MonthlyMixin
)
and daily (pinax.calendars.mixins.DailyMixin
) views.
The MonthlyMixin
will add month_kwarg_name
and year_kwarg_name
properties
to the view and default to "month"
and "year"
respectively. These should be set
to match the url pattern for the view.
During the dispatch()
phase of the view lifecycle, these parameters will be
fetched and if they are present, will be coalesced into a datetime.date
object
passing 1
for the day
attribute. If month
or year
are not found in the
url, then timezone.now().date()
will be used. Either one of these options
will set the date
property of the view. This is done so you can provide a
default view that doesn't have the year and month in the url without having
to redirect.
This date
property can then be used in your view to pass to the template
context as the {% calendars %}
template tag will need the date you are
viewing.
The DailyMixin
will add month_kwarg_name
, year_kwarg_name
, and day_kwargs_name
properties to the view and default to "month"
, "year"
, "day"
respectively.
These should be set to match the url pattern for the view.
During the dispatch()
phase of the view lifecycle, these parameters will be
fetched and coalesced into a datetime.date
object which gets set to
self.date
on the view.
This date
property can then be used in your view to pass to the template
context as well as filter your event queryset for just that date.
We use a basic adapter pattern to provide the calendar
tag with some things
it needs. There is a base adapter provided in pinax.calendars.adapters.EventAdapter
but is designed in a way to override parts of it as needed for your use case.
The adapter is providing three functions:
- computing a daily url, used to link to a daily detail view
- computing a monthly url, used for monthly pagination
- structuring event queryset data in a way that can be iterated over in the template include.
All three methods receive extra kwargs
that are passed directly from the
template tag in case you need to do something custom in your site's integration
of pinax-calendars
.
By default, EventAdapter.day_url_name
is set to "daily"
and reverse()
uses
year
, month
, and day
arguments to construct the url. This is done in the
EventAdapter.day_url
method which also receives a has_event
parameter. The
default implementation of day_url()
will only return a URL if has_event
is
True
.
By default, EventAdapter.month_url_name
is set to "monthly"
and reverse()
uses year
, and month
arguments to construct the url. This is done in the
EventAdapter.month_url
method.
The EventAdapter.events_by_day
method takes year
and month
arguments. By
default, it will construct filter arguments based on the EventAdapter.date_field_name
property, which defaults to "date"
, to filter the self.queryset
by year
and month
(e.g. date__year=year, date__month=month
).
It will then collect events into date buckets and return a dictionary of lists.
The template tag is pretty simple. It expects an adapted queryset along with
the date representing the month that you are wanting to display. If no date is
supplied, then it will assume that you mean the current month. You can also
optionally supply a timezone in which case timezone.now
will be localized to
that timezone for the purposes of displaying the current month.
Example:
{% load pinax_calendars_tags %}
{% block body %}
{% calendar events %}
{% endblock %}
Default templates are provided by the pinax-templates
app in the
calendars
section of that project.
Reference pinax-templates installation instructions to include these templates in your project.
View live pinax-templates
examples and source at Pinax Templates!
Override the default pinax-templates
templates by copying them into your project
subdirectory pinax/calendars/
on the template path and modifying as needed.
For example if your project doesn't use Bootstrap, copy the desired templates
then remove Bootstrap and Font Awesome class names from your copies.
Remove class references like class="btn btn-success"
and class="icon icon-pencil"
as well as
bootstrap
from the {% load i18n bootstrap %}
statement.
Since bootstrap
template tags and filters are no longer loaded, you'll also need to update
{{ form|bootstrap }}
to {{ form }}
since the "bootstrap" filter is no longer available.
Rendered by the {% calendar %}
template tag. The template uses semantic
markup to make styling easy and relatively free of framework bias.
The entire block is wrapped in a div.calendar
, there is a header with some
nav, followed by a table (table.calendar-table
for which there is a bit of
bootstrap style included below).
div.calendar
div.calendar-heading
h3.calendar-title
div.calendar-nav
a[href=prev]
span.calendar-date
a[href=next]
div.calendar-body
table.calendar-table
tr
td.day.noday
- or -
td.day.[day-has-events|day-no-events]
a.day-number
- or -
span.day-number
div.day-event-list
div.day-event
If you use pinax-templates calendar.html
template, you can add
this bit of SCSS to your project (if you are building upon Bootstrap)
to render a full width monthly calendar with responsive squares for each day:
.calendar-table {
@extend table;
td {
width: 14.2vw;
height: 14.2vmin;
}
}
- Drop Django 1.11, 2.0, and 2.1, and Python 2,7, 3.4, and 3.5 support
- Add Django 2.2 and 3.0, and Python 3.6, 3.7, and 3.8 support
- Update packaging configs
- Direct users to community resources
- Remove local template in favor of pinax-templates
- fix
reverse
import - add tests
- Update requirements, add django>=1.11
- Update sorting config
- Update documentation
- Remove doc build
- fix setup.py LONG_DESCRIPTION for PyPi
- Add Django 2.0 compatibility testing
- Drop Django 1.8, 1.9, 1.10 and Python 3.3 support
- Convert CI and coverage to CircleCi and CodeCov
- Add PyPi-compatible long description
- Move documentation to README.md
- Added timezone support for calendar PR #5
- Added docs
- Added
adapters.py
andmixins.py
- Donated to Pinax from Eldarion
- Renamed from
kairios
topinax-calendars
Contributing information can be found in the Pinax community health file repo.
In order to foster a kind, inclusive, and harassment-free community, the Pinax Project has a Code of Conduct. We ask you to treat everyone as a smart human programmer that shares an interest in Python, Django, and Pinax with you.
For updates and news regarding the Pinax Project, please follow us on Twitter @pinaxproject and check out our Pinax Project blog.
Copyright (c) 2012-present James Tauber and contributors under the MIT license.