Skip to content

Commit

Permalink
Merge deb5e5f into 12a2141
Browse files Browse the repository at this point in the history
  • Loading branch information
@yakky
yakky committed Sep 6, 2020
2 parents 12a2141 + deb5e5f commit 500354c
Show file tree
Hide file tree
Showing 3 changed files with 139 additions and 81 deletions.
1 change: 1 addition & 0 deletions changes/541.bugfix
View file
@@ -0,0 +1 @@
Improve setup documentation
19 changes: 16 additions & 3 deletions docs/features/home.rst
View file
Expand Up @@ -4,11 +4,24 @@
Attaching blog to the home page
===============================

If you want to attach the blog to the home page you have to adapt settings a bit otherwise the
"Just slug" permalink will swallow any CMS page you create.
*********************************
Add blog apphook to the home page
*********************************

To avoid this add the following settings to you project:
* Go to the django CMS page admin: http://localhost:8000/admin/cms/page
* Edit the home page
* Go to **Advanced settings** and select Blog from the **Application** selector and create an **Application configuration**;
* Eventually customise the Application instance name;
* Publish the page
* Restart the project instance to properly load blog urls.

*******************
Amend configuration
*******************

Permalinks must be updated to avoid blog urlconf swallowing django CMS page patters.

To avoid this add the following settings to you project:

.. code-block:: python
Expand Down
200 changes: 122 additions & 78 deletions docs/installation.rst
View file
Expand Up @@ -7,106 +7,147 @@ Installation
django CMS blog assumes a **completely setup and working django CMS project**.
See `django CMS installation docs <https://django-cms.readthedocs.io/en/latest/how_to/index.html#set-up>`_ for reference.

Install djangocms-blog:
If you are not familiar with django CMS you are **strongly encouraged** to read django CMS documentation before installing django CMS blog, as setting it up and adding blog content require to use django CMS features which are not described in this documentation.

.. code-block:: python
django CMS docs:

pip install djangocms-blog
- `django CMS tutorial <http://docs.django-cms.org/en/latest/introduction/index.html>`_
- `django CMS user guide <http://docs.django-cms.org/en/latest/user/index.html>`_
- `django CMS videos <https://www.youtube.com/channel/UCafBqF_OeeGDgQVte5eCiJg>`_

Add ``djangocms_blog`` and its dependencies to INSTALLED_APPS:
*********************
Installation steps
*********************

.. code-block:: python
* Install djangocms-blog:

INSTALLED_APPS = [
...
'filer',
'easy_thumbnails',
'aldryn_apphooks_config',
'parler',
'taggit',
'taggit_autosuggest',
'meta',
'sortedm2m',
'djangocms_blog',
...
]
.. code-block:: python
pip install djangocms-blog
Then apply migrations:
* Add ``djangocms_blog`` and its dependencies to INSTALLED_APPS:

.. code-block:: python
.. code-block:: python
python manage.py migrate
INSTALLED_APPS = [
...
'filer',
'easy_thumbnails',
'aldryn_apphooks_config',
'parler',
'taggit',
'taggit_autosuggest',
'meta',
'sortedm2m',
'djangocms_blog',
...
]
If you want to enable haystack support, in addition to the above:
* install djangocms-blog with:
.. note:: The following are minimal defaults to get the blog running; they may not be
suited for your deployment.

.. code-block:: python
* Add the following settings to your project:

pip install djangocms-blog[search]
.. code-block:: python
* add ``aldryn_search`` to ``INSTALLED_APPS``
* configure haystack according to `aldryn-search docs <https://github.com/aldryn/aldryn-search#usage>`_
and `haystack docs <http://django-haystack.readthedocs.io/en/stable/>`_.
* if not using ``aldryn_search``, you can define your own ``search_indexes.py`` by skipping ``aldryn_search`` installation and writing
your index for blog posts by following haystack documentation.
THUMBNAIL_PROCESSORS = (
'easy_thumbnails.processors.colorspace',
'easy_thumbnails.processors.autocrop',
'filer.thumbnail_processors.scale_and_crop_with_subject_location',
'easy_thumbnails.processors.filters',
)
META_SITE_PROTOCOL = 'https' # set 'http' for non ssl enabled websites
META_USE_SITES = True
To enable taggit filtering support in the admin install djangocms-blog with:
* For meta tags support enable the needed types::

.. code-block:: python
META_USE_OG_PROPERTIES=True
META_USE_TWITTER_PROPERTIES=True
META_USE_GOOGLEPLUS_PROPERTIES=True # django-meta 1.x+
META_USE_SCHEMAORG_PROPERTIES=True # django-meta 2.x+

pip install djangocms-blog[taggit]
* Configure parler according to your languages:

*********************
Minimal configuration
*********************
.. code-block:: python
PARLER_LANGUAGES = {
1: (
{'code': 'en',},
{'code': 'it',},
{'code': 'fr',},
),
'default': {
'fallbacks': ['en', 'it', 'fr'],
}
}
The following are minimal defaults to get the blog running; they may not be
suited for your deployment.
.. note:: Since parler 1.6 this can be skipped if the language configuration is the same as ``CMS_LANGUAGES``.

* Add the following settings to your project:
* Add the following to your ``urls.py``:

.. code-block:: python
.. code-block:: python
THUMBNAIL_PROCESSORS = (
'easy_thumbnails.processors.colorspace',
'easy_thumbnails.processors.autocrop',
'filer.thumbnail_processors.scale_and_crop_with_subject_location',
'easy_thumbnails.processors.filters',
)
META_SITE_PROTOCOL = 'https' # set 'http' for non ssl enabled websites
META_USE_SITES = True
url(r'^taggit_autosuggest/', include('taggit_autosuggest.urls')),
* For meta tags support enable the needed types::
* Apply the migrations:

META_USE_OG_PROPERTIES=True
META_USE_TWITTER_PROPERTIES=True
META_USE_GOOGLEPLUS_PROPERTIES=True # django-meta 1.x+
META_USE_SCHEMAORG_PROPERTIES=True # django-meta 2.x+

* Configure parler according to your languages:
***********************
Modify templates
***********************

.. code-block:: python
For standard djangocms-blog templates to work to must ensure a ``content`` block is available in the django CMS template
used by the page djangocms-blog is attached to.

PARLER_LANGUAGES = {
1: (
{'code': 'en',},
{'code': 'it',},
{'code': 'fr',},
),
'default': {
'fallbacks': ['en', 'it', 'fr'],
}
}
For example, in case the page use the ``base.html`` template, you must ensure that something like the following is
in the template:

.. note:: Since parler 1.6 this can be skipped if the language configuration is the same as ``CMS_LANGUAGES``.
.. code-block:: html+django
:name: base.html

* Add the following to your ``urls.py``:
...
{% block content %}
{% placeholder "page_content" %}
{% endblock content %}
...

.. code-block:: python
Alternative you can override then ``djangocms_blog/base.html`` and extend a different block

url(r'^taggit_autosuggest/', include('taggit_autosuggest.urls')),

.. code-block:: html+django
:name: djangocms_blog/base.html

...
{% block my_block %}
<div class="app app-blog">
{% block content_blog %}{% endblock %}
</div>
{% endblock my_block %}
...


***********************
Enable haystack support
***********************

If you want to enable haystack support:

* install djangocms-blog with:

.. code-block:: python
pip install djangocms-blog[search]
* add ``aldryn_search`` to ``INSTALLED_APPS``
* configure haystack according to `aldryn-search docs <https://github.com/aldryn/aldryn-search#usage>`_
and `haystack docs <http://django-haystack.readthedocs.io/en/stable/>`_.
* if not using ``aldryn_search``, you can define your own ``search_indexes.py`` by skipping ``aldryn_search`` installation and writing
your index for blog posts by following haystack documentation.

*************************
Attach the blog to a page
*************************

* To start your blog you need to use `AppHooks from django CMS <http://docs.django-cms.org/en/latest/how_to/apphooks.html>`_
to add the blog to a django CMS page; this step is not required when using
Expand All @@ -119,6 +160,8 @@ suited for your deployment.
* Publish the page
* Restart the project instance to properly load blog urls.

Check the :ref:`blog-home-page` section to attach the blog on the website home page.

.. warning:: After adding the apphook to the page you **cannot** change the **Instance Namespace**
field for the defined **AppHokConfig**; if you want to change it, create a new one
with the correct namespace, go in the CMS page **Advanced settings** and switch to the
Expand All @@ -137,20 +180,21 @@ suited for your deployment.
.. _external_applications:

***********************************
External applications configuration
Further configuration
***********************************

Dependency applications may need configuration to work properly.
As django CMS heavily relies on external applications to provide its features, you may also want to check the documentation of external packages.


Please, refer to each application documentation on details.

* django-cms: http://django-cms.readthedocs.io/en/release-3.4.x/how_to/install.html
* django-filer: https://django-filer.readthedocs.io
* django-meta: https://github.com/nephila/django-meta#installation
* django-parler: https://django-parler.readthedocs.io/en/latest/quickstart.html#configuration
* django-taggit-autosuggest: https://bitbucket.org/fabian/django-taggit-autosuggest
* aldryn-search: https://github.com/aldryn/aldryn-search#usage>
* haystack: http://django-haystack.readthedocs.io/en/stable/

* django-cms (framework and content plugins): http://django-cms.readthedocs.io/en
* django-filer (image handling): https://django-filer.readthedocs.io
* django-meta (meta tag handling): https://github.com/nephila/django-meta#installation
* django-parler (multi language support): https://django-parler.readthedocs.io/en/latest/quickstart.html#configuration
* aldryn-search (content search): https://github.com/aldryn/aldryn-search#usage>
* haystack (content search): http://django-haystack.readthedocs.io/en/stable/

.. _auto_setup:

Expand Down

0 comments on commit 500354c

Please sign in to comment.