Aldryn News & Blog¶

Overview¶

Aldryn News & Blog is an Aldryn-compatible news and weblog application for django CMS.

Get started ¶

Get started - installation and basic configuration

How to ¶

Publishing news and weblog articles with News & Blog

Features¶

guaranteed support and development - Aldryn News & Blog is a key application in the django CMS/Aldryn ecosystem, and is backed by commercial support
one-click installation on the Aldryn platform
multi-lingual by default
supports advanced frontend frameworks through its compatibility with Aldryn Boilerplates

Release Notes¶

This document refers to version 2.1.1.

See the changelog for details of updates.

Upgrading contains some information on how to upgrade from earlier versions.

Documentation¶

Installation and set-up¶

You can install Aldryn News & Blog either on Aldryn or by hand into your own project.

Aldryn Platform Users¶

To install the addon on Aldryn, all you need to do is follow this installation link on the Aldryn Marketplace and follow the instructions.

Manually you can:

Choose a site you want to install the add-on to from the dashboard.
Go to Apps > Install App
Click Install next to the News & Blog app.
Redeploy the site.

Manual Installation¶

Requirements¶

This project requires django CMS 3.0.12 or later.

Install the package using pip¶

If you’re installing into an existing django CMS project, you can run either:

pip install aldryn-newsblog

or:

pip install -e git+https://github.com/aldryn/aldryn-newsblog.git#egg=aldryn-newsblog

If you need to start a new project, we recommend that first you use the instructions in the official django CMS documentation, which will get you started in less than five minutes.

Once you have created a django CMS project, you can install Aldryn News & Blog in it.

settings.py¶

In your project’s settings.py make sure you have all of:

# you will probably need to add these
'aldryn_apphooks_config',
'aldryn_categories',
'aldryn_common',
'aldryn_newsblog',
'aldryn_people',
'aldryn_translation_tools',
'parler',
'sortedm2m',
'taggit',

# you'll almost certainly have these installed already
'djangocms_text_ckeditor',
'easy_thumbnails',
'filer',

listed in INSTALLED_APPS, after 'cms'.

Additional Configuration¶

Aldryn Boilerplate support¶

Aldryn News & Blog supports Aldryn Boilerplates, and has a set of templates that work with the Bootstrap 3 boilerplate.

Boilerplates provide a convenient way to build optional support for advanced frontend frameworks into Django applications. If the project in which the application is deployed uses a Boilerplate supported by the application, the application will take advantage of it automatically, and integrate seamlessly into the site’s frontend.

If not, the application will fall back gracefully to more basic templates, or the developer can readily add the appropriate Boilerplate support for the application.

If your site uses a boilerplate, you’ll need to make some changes to your settings.py:

add aldryn_boilerplates to INSTALLED_APPS
set ALDRYN_BOILERPLATE_NAME - for example: ALDRYN_BOILERPLATE_NAME = 'bootstrap3'

Django Filer¶

Aldryn News & Blog requires the use of the “subject location” processor from Django Filer for Easy Thumbnails. This requires setting the THUMBNAIL_PROCESSORS tuple in your project’s settings to:

omit the default processor scale_and_crop
include the scale_and_crop_with_subject_location processor

For example:

THUMBNAIL_PROCESSORS = (
    'easy_thumbnails.processors.colorspace',
    'easy_thumbnails.processors.autocrop',
    # 'easy_thumbnails.processors.scale_and_crop',
    'filer.thumbnail_processors.scale_and_crop_with_subject_location',
    'easy_thumbnails.processors.filters',
    'easy_thumbnails.processors.background',
)

For more information on this optional processor, see the documentation for Django Filer.

Database migrations¶

Aldryn News & Blog includes new models that require database migrations. Run python manage.py syncdb if you have not already done so, followed by python manage.py migrate to prepare the database for the new applications.

Note

Aldryn News & Blog supports both South and Django migrations.

django CMS set-up¶

In order to use Aldryn News & Blog, your django CMS project needs to have at least one page set up with an Aldryn News & Blog apphook.

To do this:

Create a django CMS page in the normal way.
In Advanced settings... > Application settings, select NewsBlog.

You’re now ready to begin using Aldryn News & Blog in earnest - see Creating Aldryn News & Blog content for the next steps.

How-to¶

Creating Aldryn News & Blog content¶

Before using Aldryn News & Blog, you need to set up your django CMS project appropriately (in short, making sure that you have a page with a News & Blog apphook - this only takes a moment).

This page is where your articles will be listed (see Multiple news/weblog sections for multiple lists of articles).

There are various different ways to create a new article:

From the django CMS toolbar, select Create then New news/blog article. This opens the django CMS content wizard, providing a quick way to add new content.
If you’re on a page with a News & Blog apphook, select News & Blog > Add new article... from the django CMS toolbar.
Add a new article in the Django Admin, in the Aldryn News & Blog section.

Fields¶

Most of the fields for an article are self-explanatory, and they behave in logical ways. For example, setting the Publishing date in the future will publish the item automatically at that date/time.

Note that items will not be published until the Is published option has been explicitly set (and the Publishing date has been reached).

A Featured item will be given prominence in lists, such as on the home page of the news section.

Meta Options¶

Advanced settings¶

Tags are a set of optional free labels. Note that Tags, unlike most other fields, are not language-aware (i.e. the same set of tags is available across all languages). See the Taggit documentation for more.

Categories offer a more formal taxonomy, managed by the Aldryn Categories application.

Application configuration allows you to select which list (if you have multiple Application Configurations) of news/weblog articles the article will be associated with.

Main content¶

Unless you used the Content creation wizard (the Create button) your new article will not have any content other than the Lead-in.

The main content in an article is maintained in its Newsblog Article Content placeholder.

To add content:

Select your (empty) article, for example from the News & Blog home page on your site.
By default, you will be in Content mode. Select Structure from the django CMS Toolbar.
Hit the + button to add a plugin to the Newsblog Article Content placeholder.
Typically, this will be a Text plugin; add some text and Save.

When you switch back to Content mode, you’ll see your full article.

Shared content¶

If you’re using one of the default templates, you’ll find that your article also contains another placeholder, called Newsblog Social. This is a Static placeholder - it’s shared between all templates that contain it; in other words, between all News & Blog articles. If you add or change plugins in that placeholder, all your Aldryn News & Blog articles will display them.

In this template, it’s intended to be a convenient way for you to add social media links and buttons to all your News & Blog articles.

See Section-specific shared content for more fine-grained control over content that’s shared across articles.

Using plugins¶

Aldryn News & Blog comes with a set of useful plugins. They are mostly self-explanatory.

Where to use plugins¶

Though you can add any of these plugins to any placeholder or static placeholder, some really make only sense in particular contexts (and some will simply do nothing at all in a context where they don’t make sense).

For example, the Related articles plugin only makes sense when attached to an article. Dropped into a django CMS page for example, it will do nothing.

On the other hand, it would be possible but probably not very desirable to have a list of Recent articles appear in the template of an article.

List of plugins¶

Most of the plugins produce output specific to a particular apphook configuration. In these the Application configuration is a required field.

In alphabetical order:

Archive¶

Archive creates a list of dates representing published articles.

Selecting a date takes you a sub-page in the archive, with a paginated list of articles for that date.

Article search¶

Article search provides a search field. The search mechanism will search through article Titles and Lead-in fields, but not other content.

Authors¶

Authors creates a list of authors who have published articles.

Selecting an author takes you a sub-page in the archive, with a paginated list of articles for that author.

Categories¶

Categories creates a list of categories articles have been placed in.

Selecting a category takes you a sub-page in the archive, with a paginated list of articles for that category.

Featured articles¶

Featured articles creates a list of articles that have been marked as Featured. Their display can be styled with CSS to achieve the effect you require - see Customising news output for an example.

Latest articles¶

Latest articles creates a list of the most recent articles.

Tags¶

Tags displays a list of tags associated with articles.

Multiple news/weblog sections¶

Your project can host multiple independent news/weblog sections, each with their own items. For example, a company website might have a news section for publishing press releases, and a weblog for publishing more informal articles.

To do this, you need to create a django CMS page for each news/weblog section, and add an apphook for Aldryn News & Blog to each of them. You will also need to create a separate apphook configuration for each of them - apphook configurations cannot be shared between apphook instances.

Creating a new News & Blog section¶

The quickest way to do this is:

Create the new page.
In its Advanced settings, choose Newsblog in the Application field. A new field, Application configurations, will appear immediately below it.
Add a new application configuration, by selecting the + icon.

Fields¶

Instance namespace - a unique (and slug-like) name for this configuration. Note that this cannot be subsequently changed.

Application title - A human-readable name for the configuration, that helps explain its purpose to the users of the system. For example, if this news section will publish press releases, call it Press releases. The name will be reflected in the django CMS toolbar when you’re on that page.

Permalink type - the format of canonical URLs for articles in this section.

Non-permalink-handling - For convenience, the system can optionally resolve URLs that are not in the canonical format. For example, if the canonical URL is 2016/11/27/man-bites-dog, the URL man-bites-dog can redirect to it. This behaviour is the default, but optional.

Prefix for template directories - If you’d like this news section to use custom templates, create a set in a new directory. So for example, instead of using the default aldryn_newsblog/article_list.html, it will look for aldryn_newsblog/custom-directory/article_list.html.

Include in search index - see Per-apphook indexing.

Other fields are self-explanatory.

Apphook configurations can also be created and edited in other ways:

from the Django Admin, in Aldryn News & Blog > Application configuration
from the option Configure addon... in the apphook’s menu in the django CMS toolbar

Access to application configuration¶

Typically, you will not provide most content editors of your site with admin permissions to manage apphooks - this should be reserved for site managers.

Creating content in a specific News & Blog section¶

Articles¶

The section that a particular article is attached to is set in its Application Configuration field, in its Advanced settings. This can be changed once an article has been created, thus moving it from one section of a site to another.

Section-specific shared content¶

In Shared content, we noted that you can use Static placeholders in your article templates article_detail.html, so that all articles can incorporate some boilerplate content (a typical example would be a list of social media links):

{% static_placeholder "newsblog_social" %}

Sometimes this is all you need, but if you are maintaining multiple News & Blog sections, you might not want site-wide shared content of this kind, but only section-specific shared content. For example, you might require one set of social media links for news pages aimed at your customers and another for pages aimed at your investors.

In this case, you will need to override the default templates, which you can do at project level. You can remove the default {% static_placeholder %} altogether if you wish, or you can simply add new apphook-configuration-aware placeholder template tags where you need them. For example:

{% render_placeholder view.config.placeholder_detail_bottom %}

Unlike static placeholder template tags, which can be added arbitrarily to your templates as you need them, these are standard PlaceholderFields, defined in the NewsBlogConfig model.

Several are defined there ready for you to use if you need them, and you advised to use them rather than amend that model to add your own (which will require forking the News & Blog code-base, and creating your own migrations for them.)

Customising news output¶

By default, a News & Blog page will simply list items, using the article_list.html template, while an article will use the article_detail page.

At its most basic, all the article_list.html template does is extend a base template and add the article list. Similarly, the article_detail will extend a base template.

It’s easy to override these templates to add your own components to your News & Blog pages. If you add static placeholders to the templates, then you will be able to add arbitrary plugins to it; these will then appear on all the News & Blog pages that use those templates.

Customising a news section page¶

The simplest news section page (the django CMS page that has a News & Blog apphook attached to it) is a list of articles.

The optional Aldryn Bootstrap Boilerplate templates, which will be used if you are using the Aldryn Boilerplate Bootstrap 3 components - see Aldryn Boilerplate support - offer something more sophisticated.

In that case, the article list template will extend a more complex template, that implements some static placeholders.

It makes possible the layout represented here, which was taken from the Divio website. It’s worth describing how it’s implemented, to show some of the possibilities.

The page has a static_placeholder newsblog_feature. Into this are placed:

a heading, Featured articles
a Featured articles plugin, set to display the latest three articles on which the “featured” flag has been set
a heading, Recent articles

Below the newsblog_feature static placeholder, the article_list.html template simply lists the articles (4).

On the right are the items from the newsblog_sidebar. These are:

a Categories plugin, that lists the different categories of article that have been published
an Authors plugin, that lists different authors of published articles

See Using plugins for more details of the different plugins available.

Customising News & Blog article templates¶

Articles can be similarly customised. For example you might add a Related articles plugin to the static placeholder of your articles, so that each article will display a list of related articles.

Section-specific content¶

If you have multiple news sections, you can also have Section-specific shared content, by using apphook-configuration-aware placeholder template tags as described in Section-specific shared content.

Search functionality¶

Default search functionality¶

By default, the Article search plugin searches through articles’ Title and Lead-in fields. To have it search through the main content of articles, you need to add a setting:

ALDRYN_NEWSBLOG_UPDATE_SEARCH_DATA_ON_SAVE = True

When this is enabled, when articles and plugins are saved they will render their content and save it to the database. This rendered content will be added to the search corpus.

Rebuilding the search corpus¶

Enabling ALDRYN_NEWSBLOG_UPDATE_SEARCH_DATA_ON_SAVE will not automatically add the rendered content of previously-saved articles.

To have them added, you will need to run a management command, rebuild_article_search_data - i.e.

python manage.py rebuild_article_search_data

The command optionally takes --language or the short-hand -l to specify the translations to process, for example:

python manage.py rebuild_article_search_data -l en de

If this option is not provided, all languages will be processed.

Aldryn Search and Haystack¶

Aldryn News & Blog supports Aldryn Search and Django Haystack.

If you have Aldryn Search and Haystack installed and configured in your project, News & Blog’s content can also be rendered searchable. To enable this, add:

ALDRYN_NEWSBLOG_SEARCH = True

in your settings. Note that if your search infrastructure is not configured, this setting will have no effect.

Per-apphook indexing¶

If you have configured your system for Aldryn Search and Haystack support and have enabled it for Aldryn News & Blog, you can control it on a per-apphook basis. That is, you can turn it on or off for the articles belonging to a particular apphook, using the Include in search index? setting of the apphook configuration.

This doesn’t affect the default search mechanism - only the Haystack-based search.

Development & community¶

Aldryn News & Blog is an open-source project.

You don’t need to be an expert developer to make a valuable contribution - all you need is a little knowledge, and a willingness to follow the contribution guidelines.

Divio AG¶

Aldryn News & Blog is developed by Divio AG and released under a BSD licence.

Aldryn News & Blog is compatible with Divio’s Aldryn cloud-based django CMS hosting platform, and therefore with any standard django CMS installation. The additional requirements of an Aldryn application do not preclude its use with any other django CMS deployment.

Divio is committed to Aldryn News & Blog as a high-quality application that helps set standards for others in the Aldryn/django CMS ecosystem, and as a healthy open source project.

Divio maintains overall control of the Aldryn News & Blog repository.

Standards & policies¶

Aldryn News & Blog is a django CMS application, and shares much of django CMS’s standards and policies.

These include:

guidelines and policies for contributing to the project, including standards for code and documentation
standards for managing the project’s development
a code of conduct for community activity

Please familiarise yourself with this documentation if you’d like to contribute to Aldryn News & Blog.

Running tests¶

Aldryn News & Blog uses django CMS Helper to run its test suite.

Backend Tests¶

To run the tests, in the aldryn-newsblog directory:

virtualenv env  # create a virtual environment
source env/bin/activate  # activate it
python setup.py install  # install the package requirements
pip install -r test_requirements/django-1.7.txt  # install the test requirements
python test_settings.py  # run the tests

You can run the tests against a different version of Django by using the appropriate value in django-x.x.txt when installing the test requirements.

Frontend Tests¶

Follow the instructions in the aldryn-boilerplate-bootstrap3 documentation and setup the environment through the Backend Tests section.

Instead of using python test_settings.py described above, you need to excecute python test_settings.py server to get a running local server. You can open the development server locally through http://127.0.0.1:8000/. The database is added within the root of this project local.sqlite. You might want to delete the database from time to time to start with a fresh installation. Don’t forget to restart the server if you do so.

Documentation¶

You can run the documentation locally for testing:

navigate to the documentation cd /docs
run make install to install requirements
run make run to run the server

Now you can open http://localhost:8000 on your favourite browser and start changing the rst files within docs/.

Upgrading¶

The changelog is maintained and updated within the repository.

Aldryn News & Blog¶

Overview¶

Get started¶

How to¶

Features¶

Release Notes¶

Documentation¶

Installation and set-up¶

Aldryn Platform Users¶

Manual Installation¶

Requirements¶

Install the package using pip¶

settings.py¶

Additional Configuration¶

Aldryn Boilerplate support¶

Django Filer¶

Database migrations¶

django CMS set-up¶

How-to¶

Creating Aldryn News & Blog content¶

Fields¶

Meta Options¶

Advanced settings¶

Main content¶

Shared content¶

Using plugins¶

Where to use plugins¶

List of plugins¶

Archive¶

Article search¶

Authors¶

Categories¶

Featured articles¶

Latest articles¶

Related articles¶

Tags¶

Multiple news/weblog sections¶

Creating a new News & Blog section¶

Fields¶

Access to application configuration¶

Creating content in a specific News & Blog section¶

Articles¶

Section-specific shared content¶

Customising news output¶

Customising a news section page¶

Customising News & Blog article templates¶

Section-specific content¶

Search functionality¶

Default search functionality¶

Rebuilding the search corpus¶

Aldryn Search and Haystack¶

Per-apphook indexing¶

Development & community¶

Divio AG¶

Standards & policies¶

Running tests¶

Backend Tests¶

Frontend Tests¶

Documentation¶

Upgrading¶

Get started ¶

How to ¶