README.md

# CMS HighlightedContent

This app is a base application to build HighlightedContents with django CMS.

Users with permissions will be able to add HighlightedContent Plugins in placeholders and add items to
those highlighted_contents.
Each item is a related instance of whatever model you allow. You can have a highlighted_content with a
item which is a `News` instance, then a item which is a `Page` instance, then a item which is a
`MagicPony` instance etc.


## How to use it

### 0. Configuration

Add `cms_highlighted_content` in `INSTALLED_APPS` and configure models which can be used as "item":

```python
# settings.py


INSTALLED_APPS = [
    # ...
    'cms_highlighted_content',
]

CMS_HIGHLIGHTED_CONTENT_ITEMS_MODELS = (
    # format: ('app_name', ('SomeModel', 'AnOther', )),
    ('news', ('News', ),),
    ('feparchives', ('Project', 'Event', 'News')),
)
```

### 1. Models

In your HighlightedContentItem, you **MUST** define the highlighted_content ForeignKey.

```python
# models.py

from cms_highlighted_content.models import HighlightedContentPluginBase, HighlightedContentItemBase

class HighlightedContentPlugin(HighlightedContentPluginBase):
    pass


class HighlightedContentItem(HighlightedContentItemBase):
    highlighted_content = models.ForeignKey(HighlightedContentPlugin, related_name='items')
```

Make your migration and apply it.

### 2. CMS plugin

```python
# cms_plugins.py

from cms_highlighted_content.cms_plugins import HighlightedContentPluginBase
from .models import HighlightedContentPlugin as HighlightedContentPluginModel


class HighlightedContentPlugin(HighlightedContentPluginBase):
    model = HighlightedContentPluginModel


plugin_pool.register_plugin(HighlightedContentPlugin)
```

### 4. Templates

Slides can be from multiple models (configured in `CMS_HIGHLIGHTED_CONTENT_ITEMS_MODELS`). You must create
at least a general template (`highlighted_content/highlighted_content_item.html`) which can manage all available
models.

You can also create a template for each app (in this exemple, it would be
`news/highlighted_content_item.html`, `filer/highlighted_content_item.html` and `feparchives/highlighted_content_item.html`).

You can also create a template for earch model:

* `news/news/highlighted_content_item.html`
* `feparchives/dossier/highlighted_content_item.html`
* `feparchives/chronicle/highlighted_content_item.html`
* `feparchives/note/highlighted_content_item.html`
* `feparchives/conference/highlighted_content_item.html`

Logic is the same as in django-admin: we check first if a model template exists, then we check for
an app template, then we fallback for a general template.

```
{# news/highlighted_content_item.html #}
{% load i18n %}

{% if item.content_type.model == 'image' %}
    <img class="background" src="{{ object.url }}" alt="" />
    {% if object.default_alt_text %}
        <h2>{{ object.default_alt_text }}</h2>
    {% elif object.default_caption %}
        <h2>{{ object.default_caption }}</h2>
    {% endif %}
{% else %}
    {% with illustration=object.highlighted_content_illustration|default:object.illustration %}
        {% if illustration %}
            <img class="background" src="{{ illustration.url }}" alt="" />
        {% endif %}
    {% endwith %}

    <h2><a href="{{ object.get_absolute_url }}">{{ object }}</a></h2>

    {% if object.summary %}
        <div>
            {{ object.summary|truncatewords_html:20 }}
            <p class="readmore-link">
                <a href="{{ object.get_absolute_url }}">{% trans "Read more" %}&nbsp;&gt;</a>
            </p>
        </div>
    {% endif %}
{% endif %}
```