Ingredients¶
The following image visualizes the ingredients (that is: the different logical parts/components of django-calingen) and their logical relations.
Visualization of the Ingredients¶
Compilers¶
django-calingen uses compilers to convert the result of the rendering process of a layout into something usable (or - most likely - printable).
Note
The original development idea of django-calingen was to generate TeX-documents of
the calendar inlays and then use a TeX compiler (e.g. pdflatex) to turn
them into PDFs, ready for printing.
However, during development, the focus on TeX was dropped in favour of a more generic approach, allowing layouts to return any text-based result.
Technically, compilers are implementations of the app’s
CompilerProvider interface. They are
resposible for providing a valid HTTP response during the generation process
(see Layout Rendering and Compilation and
CompilerProvider Development for details).
How this response is determined and what the actual response is, is up to the respective compiler implementations, i.e. a compiler could accept a TeX-based layout’s output and run it through an actual TeX compiler, providing the compilation result as an HTTP file download.
Note
Obviously, there is a close connection between layouts and compilers. All
layouts indicate the type of their rendered output with their
layout_type attribute (refer to
LayoutProvider). See
CALINGEN_COMPILER for the
corresponding app-specific configuration option and
Map Layouts to Compilers for
guidance on how to use this setting.
Included Compilers¶
django-calingen provides three example compilers out of the box. They are included
in calingen.contrib.compilers.
- CopyPaste Compiler
This compiler does not actually compile the rendered source.
It will present the rendering result using a given template (
calingen/contrib/compiler_copypaste.html), ready to copy the source, paste it into another piece of software for further processing.This compiler can handle any type of layout and may be used as the project’s default compiler (see the important box here: Map Layouts to Compilers).
- Download Compiler
This compiler does not actually compile the rendered source.
It will provide the rendering result as a file download. It will try to guess the correct file extension by evaluating the layout’s type.
This compiler can handle any type of layout and may be used as the project’s default compiler (see the important box here: Map Layouts to Compilers).
- HtmlOrDownload Compiler
This compiler does not actually compile the rendered source.
It is an extension to the Download Compiler that directly serves the results of the rendering process of layout’s with type
"html"and provides all other rendering results as file downloads, just like the Download Compiler.This compiler can handle any type of layout and may be used as the project’s default compiler (see the important box here: Map Layouts to Compilers).
Integration of Compilers into the Project¶
Compilers are not required to be Django applications. They are dynamically imported while running the generation process of django-calingen, as described here.
This means they must be importable. This is the only requirement regarding compilers.
Note
Compilers will be imported by their full dotted Python path using Django’s
import_string function
(see CompilerView for implementation
details).
Compilers may be provided as source code (i.e. by a GitHub repository) or as an actual installable Python package (i.e. provided using PyPI). If you want to include third party compilers, make sure to follow their specific installation instructions.
Events¶
The actual key feature of django-calingen is the generation of calendar inlays. During that generation process, calendar entries, like birthdays, holidays and appointments are automatically included in the output.
Events are a more abstract representation of the calendar entries, e.g.:
Hint
Your dog’s birthday is February, 3rd 2022.
But obviously you want to include its birthday in every generated calendar, for all years to come (2023, …).
The event is 2022-02-03, Dog's Birthday, but the calendar entries will
be 2022-02-03, Dog's Birthday, 2023-02-03, Dog's Birthday, …
Event Sources¶
Events can originate from two different sources:
- Internal Events
These events are created with django-calingen, using the app’s
Eventmodel.- External Events
These events are provided by plugins, implementing the app’s
EventProviderinterface. See Event Provider for details.
Event Categories¶
django-calingen defines different categories of events in
calingen.constants.EventCategory, namely
Annual Anniversaries
Holidays
Note
This list might be extended, see issue 16.
Internal events, as described above, are required to include one of these pre-defined categories. For external events this is recommended but not enforced.
Event Provider¶
django-calingen provides a plugin interface for the provision of events by plugins.
Technically, event providers are provided as standalone Django applications
that register themselves with django-calingen and are integrated into the general
workflow of the app (see Generate Calendar Inlays),
therefore they may be installed like any other application into the Django
project: just add them to the project’s settings module in
INSTALLED_APPS.
Note
Even more technically: Event providers are implementations of the app’s
plugin mount point EventProvider.
See EventProvider Development for details.
Event providers are selectable by the user in his profile settings.
Included Event Providers¶
django-calingen ships with one event provider out of the box. It is included in
calingen.contrib.providers.
Warning
While this provider is available when django-calingen is installed, it must be
activated manually by including it in INSTALLED_APPS.
- German Holidays
Provides the holidays of the Federal Republic of Germany, split by its federal states.
Note
All federal states are included and will be selectable in the user’s profile.
Layouts¶
django-calingen uses layouts to format the actual calendar inlays. Basically they are sets of templates used to present the app’s data (which is a list of events for a given user).
Technically, layouts are provided as standalone Django applications that
register themselves with django-calingen and are integrated into the
general workflow of the app (see
Generate Calendar Inlays), therefore they may be
installed like any other application into the Django project: just add them to
the project’s settings module in INSTALLED_APPS.
Note
Even more technically: Layouts are implementations of the app’s plugin mount
point LayoutProvider. See
LayoutProvider Development for details.
Layouts are rendered to their respective result. This means, that the
project’s template engine is used to render a layout’s templates to a
string which can be processed further by a compiler (see
Compilers and TEMPLATES).
Included Layouts¶
django-calingen provides three example layouts out of the box. They are
included in calingen.contrib.layouts.
Warning
While these layouts are available when django-calingen is installed,
they must be activated manually by including them in
INSTALLED_APPS.
- Simple Event List
This is just an easy example of a layout, that processes the given list of Event instances (both, user-provided and externally provided) and creates TeX sources for compilation with a TeX compiler (like
pdflatex).The layout does not provide a configuration form, as it does not have any options.
During processing, the Event instances are grouped by their month.
- Year By Week
This slightly more complex example actually creates a list of all days of the year, include Event instances and then creates TeX sources.
There is no configuration form.
It visualizes, how a complete calendar can be generated.
- Lineatur
This layout may be used to generate ruled paper sheets to augment a calendar.
It will generate HTML sources (and might even provide a valid HTTP response in combination with an appropriate compiler).
This layout provides a configuration form.
Plugin API¶
django-calingen does provide in fact three endpoints for plugins to attach to, namely