diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 45823d8..f6d4b1c 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -3,15 +3,16 @@ Contributing ============ Contributions are welcome, and they are greatly appreciated! Every -little bit helps, and credit will always be given. +little bit helps, and credit will always be given. You can contribute in many ways: +********************** Types of Contributions ----------------------- +********************** Report Bugs -~~~~~~~~~~~ +=========== Report bugs at https://github.com/nephila/djangocms-blog/issues. @@ -22,26 +23,26 @@ If you are reporting a bug, please include: * Detailed steps to reproduce the bug. Fix Bugs -~~~~~~~~ +======== Look through the GitHub issues for bugs. Anything tagged with "bug" is open to whoever wants to implement it. Implement Features -~~~~~~~~~~~~~~~~~~ +================== Look through the GitHub issues for features. Anything tagged with "feature" is open to whoever wants to implement it. Write Documentation -~~~~~~~~~~~~~~~~~~~ +=================== -djangocms-blog could always use more documentation, whether as part of the +djangocms-blog could always use more documentation, whether as part of the official djangocms-blog docs, in docstrings, or even on the web in blog posts, articles, and such. Submit Feedback -~~~~~~~~~~~~~~~ +=============== The best way to send feedback is to file an issue at https://github.com/nephila/djangocms-blog/issues. @@ -52,8 +53,9 @@ If you are proposing a feature: * Remember that this is a volunteer-driven project, and that contributions are welcome :) +************ Get Started! ------------- +************ Ready to contribute? Here's how to set up `djangocms-blog` for local development. @@ -77,11 +79,9 @@ Now you can make your changes locally. 5. When you're done making changes, check that your changes pass flake8 and the tests, including testing other Python versions with tox:: - $ flake8 djangocms_blog tests - $ python setup.py test $ tox -To get flake8 and tox, just pip install them into your virtualenv. +To get tox, just pip install them into your virtualenv. 6. Commit your changes and push your branch to GitHub:: @@ -91,8 +91,9 @@ To get flake8 and tox, just pip install them into your virtualenv. 7. Submit a pull request through the GitHub website. +*********************** Pull Request Guidelines ------------------------ +*********************** Before you submit a pull request, check that it meets these guidelines: @@ -100,13 +101,14 @@ Before you submit a pull request, check that it meets these guidelines: 2. If the pull request adds functionality, the docs should be updated. Put your new functionality into a function with a docstring, and add the feature to the list in README.rst. -3. The pull request should work for Python 2.6, 2.7, and 3.3, and for PyPy. Check +3. The pull request should work for Python 2.7, 3.4, and 3.5. Check https://travis-ci.org/nephila/djangocms-blog/pull_requests and make sure that the tests pass for all supported Python versions. +**** Tips ----- +**** To run a subset of tests:: - $ python -m unittest tests.test_djangocms_blog + $ python cms_helper.py test tests.test_views diff --git a/HISTORY.rst b/HISTORY.rst index f3b8f50..eaf62f0 100644 --- a/HISTORY.rst +++ b/HISTORY.rst @@ -1,35 +1,42 @@ .. :changelog: +======= History -------- +======= +****************** 0.8.5 (2016-06-26) -++++++++++++++++++ +****************** * Fixed issues with ThumbnailOption migration under mysql. +****************** 0.8.4 (2016-06-22) -++++++++++++++++++ +****************** * Fixed issues with cmsplugin-filer 1.1. +****************** 0.8.3 (2016-06-21) -++++++++++++++++++ +****************** * Stricter filer dependency versioning. +****************** 0.8.2 (2016-06-12) -++++++++++++++++++ +****************** * Aldryn-only release. No code changes +****************** 0.8.1 (2016-06-11) -++++++++++++++++++ +****************** * Aldryn-only release. No code changes +****************** 0.8.0 (2016-06-05) -++++++++++++++++++ +****************** * Added django-knocker integration * Changed the default value of date_published to null @@ -43,8 +50,9 @@ History * Added API to set default sites if user has permission only for a subset of sites * Added Aldryn integration +****************** 0.7.0 (2016-03-19) -++++++++++++++++++ +****************** * Make categories non required * Fix tests with parler>=1.6 @@ -59,29 +67,33 @@ History * Mitigate issue when apphook config can't be retrieved * Mitigate issue when wizard double registration is triggered +****************** 0.6.3 (2015-12-22) -++++++++++++++++++ +****************** * Add BLOG_ADMIN_POST_FIELDSET_FILTER to filter admin fieldsets * Ensure correct creation of full URL for canonical urls * Move constants to settings * Fix error when no config is found +****************** 0.6.2 (2015-11-16) -++++++++++++++++++ +****************** * Add app_config field to BlogLatestEntriesPlugin * Fix __str__ plugins method * Fix bug when selecting plugins template +****************** 0.6.1 (2015-10-31) -++++++++++++++++++ +****************** * Improve toolbar: add all languages for each post * Improve toolbar: add per-apphook configurable changefreq, priority +****************** 0.6.0 (2015-10-30) -++++++++++++++++++ +****************** * Add support for django CMS 3.2 Wizard * Add support for Apphook Config @@ -91,8 +103,9 @@ History * LatestPostsPlugin tags field has been changed to a plain TaggableManager field. A migration is in place to move the data, but backup your data first. +****************** 0.5.0 (2015-08-09) -++++++++++++++++++ +****************** * Add support for Django 1.8 * Drop dependency on Django select2 @@ -101,8 +114,9 @@ History * Add categories menu * Add option to disable the abstract +****************** 0.4.0 (2015-03-22) -++++++++++++++++++ +****************** * Fix Django 1.7 issues * Fix dependencies on python 3 when using wheel packages @@ -110,14 +124,16 @@ History * Fix various templates issues * UX fixes in the admin +****************** 0.3.1 (2015-01-07) -++++++++++++++++++ +****************** * Fix page_name in template * Set cascade to set null for post image and thumbnail options +****************** 0.3.0 (2015-01-04) -++++++++++++++++++ +****************** * Multisite support * Configurable default author support @@ -133,9 +149,9 @@ History * Django 1.7 support * Python 3.3 and 3.4 support - +****************** 0.2.0 (2014-09-24) -++++++++++++++++++ +****************** * **INCOMPATIBLE CHANGE**: view names changed! * Based on django parler 1.0 @@ -147,8 +163,8 @@ History * Simpler TextField-based content editing for simpler blogs * Add support for custom user models - +****************** 0.1.0 (2014-03-06) -++++++++++++++++++ +****************** * First experimental release diff --git a/README.rst b/README.rst index 6362e04..af7ab1a 100644 --- a/README.rst +++ b/README.rst @@ -56,14 +56,15 @@ Supported django CMS versions: Some plugins have a broken tag management prior to 0.6, in case you have issues with tags, upgrade to latest version to have it fixed. +***************************************** Upgrading cmsplugin-filer from 1.0 to 1.1 ------------------------------------------ +***************************************** Due to changes in cmsplugin-filer/filer which moved ``ThumbnailOption`` model from the former to the latter, ``djangocms-blog`` must be migrated as well. Migrating cmsplugin-filer to 1.1 and djangocms-blog up to 0.8.4 -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ +=============================================================== If you have djangocms-blog up to 0.8.4 (included) installed or you are upgrading from a previous djangocms-blog version together with cmsplugin-filer upgrade, you can just apply the migrations:: @@ -72,7 +73,7 @@ djangocms-blog version together with cmsplugin-filer upgrade, you can just apply python manage.py migrate Migrating cmsplugin-filer to 1.1 and djangocms-blog 0.8.5+ -++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ +========================================================== If you already a djangocms-blog 0.8.5+ or above, you have to de-apply some blog migrations when doing the upgrade:: @@ -86,31 +87,35 @@ doing the upgrade:: to migrate ``ThumbnailOption`` from cmsplugin-filer to filer +******** Features --------- +******** * Placeholder content editing * Frontend editing using django CMS 3.x frontend editor * Multilingual support using django-parler -* Support for Twitter cards, Open Graph and Google+ snippets meta tags -* Optional support for simpler TextField-based content editing -* Multisite support (posts can be visible in one or more Django sites on the - same project) +* Twitter cards, Open Graph and Google+ snippets meta tags +* Optional simpler TextField-based content editing +* Multisite (posts can be visible in one or more Django sites on the same project) * Per-Apphook configuration * Configurable permalinks -* Configurable django CMS menu support +* Configurable django CMS menu * Per-Apphook templates set * Auto Apphook setup -* Django sitemap framework support -* Support for django CMS 3.2+ Wizard -* Haystack index support +* Django sitemap framework +* django CMS 3.2+ Wizard +* Haystack index +* Desktop notifications +* Liveblog +************* Documentation -------------- +************* Check documentation at https://djangocms-blog.readthedocs.io/en/latest/ +***************************** Known djangocms-blog websites -+++++++++++++++++++++++++++++ +***************************** See DjangoPackages for an updated list https://www.djangopackages.com/packages/p/djangocms-blog/ diff --git a/djangocms_blog/templates/djangocms_blog/post_detail.html b/djangocms_blog/templates/djangocms_blog/post_detail.html index d9ab105..4dc6fb3 100644 --- a/djangocms_blog/templates/djangocms_blog/post_detail.html +++ b/djangocms_blog/templates/djangocms_blog/post_detail.html @@ -21,13 +21,13 @@ {% endif %} {% endspaceless %} - {% if view.liveblog_enabled %} - {% include "liveblog/includes/post_detail.html" %} - {% endif %} {% if post.app_config.use_placeholder %}
{% render_placeholder post.content %}
{% else %}
{% render_model post "post_text" "post_text" %}
{% endif %} + {% if view.liveblog_enabled %} + {% include "liveblog/includes/post_detail.html" %} + {% endif %} {% endblock content_blog %} diff --git a/docs/channels.rst b/docs/channels.rst new file mode 100644 index 0000000..9452b45 --- /dev/null +++ b/docs/channels.rst @@ -0,0 +1,143 @@ +.. _channels_features: + +################# +Channels Features +################# + +djangocms-blog implements some channels related features: + +* desktop notifications +* liveblog + +For how to setup channels in your project, please refer to `channels documentation`_. + +.. _knocker: + +************* +Notifications +************* + +``djangocms-blog`` is integrated with `django-knocker`_ +to provide real time desktop notifications. + +See `django-knocker documentation`_ for how to configure +knocker. + + +.. _liveblog: + +******** +Liveblog +******** + +Liveblog feature allows to display any content on a single post in realtime. + +This is implemented by creating a group for each liveblogging enabled post and assigning +the clients to each group whenever they visit a liveblog post. + +Each liveblogged text is a specialized plugin (see `extend_liveblog`_ for information on how to +customize the liveblog plugin). + + +Enabling liveblog +================= + +To enabled liveblog features: + +* Setup django channels according to `channels documentation`_ + +* Add ``djangocms_blog.liveblog`` application to ``INSTALLED_APPS``:: + + INSTALLED_APPS = [ + ... + 'djangocms_blog.liveblog', + ... + ] + +* If you overwrite the post detail template, setup the following javascript code in the custom + template:: + + {% add_data "js-script" "liveblog/js/reconnecting-websocket.min.js" %} + {% add_data "js-script" "liveblog/js/liveblog.js" %} + + +* It's advised to configure ``CMS_PLACEHOLDER_CONF`` to only allow ``Liveblog`` plugins in + ``Liveblog`` placeholder, and remove them from other placeholders:: + + CMS_PLACEHOLDER_CONF = { + None: { + 'excluded_plugins': ['LiveblogPlugin'], + } + ... + 'liveblog': { + 'plugins': ['LiveblogPlugin'], + } + ... + } + + +Using liveblog +============== + +To use liveblog: + +* Tick the ``enable liveblog`` flag in the ``Info`` fieldset; +* Open the blog post detail page; +* Optionally add static content to the ``post content`` placeholder; the default template will + show static content on top of liveblog content; you can override the template for different + rendering; +* Add plugins to the ``Liveblog`` placeholder; +* Tick the ``publish`` flag on each ``Liveblog`` plugin to send it to clients in realtime. + + +.. _extend_liveblog: + +Extending liveblog plugin +========================= + +Liveblog support ships with a default liveblog plugin that provides a title, a body and +a filer image. + +To customize the appearance of the plugin, just override the ``liveblog/plugins/liveblog.html`` +template. Both the real time and non realtime version of the plugin will be rendered accordingly. + +If you need something different, you can create your own plugin by creating your own plugin +inheriting from ``LiveblogInterface`` and calling the method ``self._post_save()`` in the +save method, after the model has been saved. + +In ``models.py``: + +.. code-block:: django + + class MyLiveblog(LiveblogInterface, CMSPlugin): + """ + Basic liveblog plugin model + """ + text = models.TextField(_('text')) + + def save(self, *args, **kwargs): + super(MyLiveblog, self).save(*args, **kwargs) + self._post_save() + + +The plugin class does not require any special inheritance; in ``cms_plugins.py``: + +.. code-block:: django + + class MyLiveblogPlugin(CMSPluginBase): + name = _('Liveblog item') + model = MyLiveblog + plugin_pool.register_plugin(MyLiveblogPlugin) + +While not required, for consistency between between realtime and non realtime rendering, use the +``publish`` field inherited from ``LiveblogInterface`` to hide the plugin content when the plugin +is not published. + + +.. _channels documentation: http://channels.readthedocs.io/en/latest/index.html +.. _django-knocker documentation: http://django-knocker.readthedocs.io/en/latest/index.html +.. _django-knocker: https://github.com/nephila/django-knocker diff --git a/docs/features.rst b/docs/features.rst index 552b67f..400a2ca 100644 --- a/docs/features.rst +++ b/docs/features.rst @@ -1,12 +1,14 @@ .. _features: +======== Features --------- +======== .. _blog-home-page: +******************************* 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. @@ -32,13 +34,14 @@ linked ot the home page (see http://yoursite.com/admin/djangocms_blog/blogconfig .. _multisite: +********* Multisite -+++++++++ +********* django CMS blog provides full support for multisite setups. Basic multisite -^^^^^^^^^^^^^^^ +=============== To enabled basic multisite add ``BLOG_MULTISITE = True`` to the project settings. @@ -47,7 +50,7 @@ it's visible on all sites. All users with permission on the blog can manage all posts, whichever the sites are. Multisite permissions -^^^^^^^^^^^^^^^^^^^^^ +===================== Multisite permissions allow to restrict users to only manage the blog posts for the sites they are enabled to @@ -65,8 +68,9 @@ Example:: .. _cms-wizard: +********************** django CMS 3.2+ Wizard -++++++++++++++++++++++ +********************** django CMS 3.2+ provides a content creation wizard that allows to quickly created supported content types, such as blog posts. @@ -80,8 +84,9 @@ wizard may not show up, but the rest will work as intended. .. _permalinks: +*********************** Configurable permalinks -+++++++++++++++++++++++ +*********************** Blog comes with four different styles of permalinks styles: @@ -106,8 +111,9 @@ And change ``post/`` with the desired prefix. .. _menu: +**** Menu -++++ +**** ``djangocms_blog`` provides support for django CMS menu framework. @@ -121,8 +127,9 @@ category are not added to the menu. .. _templates: +********* Templates -+++++++++ +********* To ease the template customisations a ``djangocms_blog/base.html`` template is used by all the blog templates; the templates itself extends a ``base.html`` @@ -133,8 +140,9 @@ not defines a ``content`` block, copy in your template directory other application templates will use the newly created base template and will ignore the bundled one. +************* Templates set -+++++++++++++ +************* By using **Apphook configuration** you can define a different templates set. To use this feature provide a directory name in **Template prefix** field in @@ -143,8 +151,9 @@ root of your custom templates set. .. _sitemap: +******* Sitemap -+++++++ +******* ``djangocms_blog`` provides a sitemap for improved SEO indexing. Sitemap returns all the published posts in all the languages each post is available. @@ -168,14 +177,3 @@ To add the blog Sitemap, add the following code to the project ``urls.py``:: } }), ) - -.. _knocker: - -django-knocker -++++++++++++++ - -``djangocms-blog`` is integrated with `django-knocker `_ -to provide real time desktop notifications. - -See `django-knocker documentation `_ for how to configure -knocker. diff --git a/docs/index.rst b/docs/index.rst index 35c6365..6a86de6 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -3,14 +3,16 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. +========================================== Welcome to djangocms-blog's documentation! ========================================== .. include:: ../README.rst +******** Contents --------- +******** .. toctree:: :maxdepth: 2 @@ -18,13 +20,15 @@ Contents installation settings features + channels development contributing history +****************** Indices and tables -================== +****************** * :ref:`genindex` * :ref:`search` diff --git a/docs/installation.rst b/docs/installation.rst index c935e35..995e95e 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -1,7 +1,8 @@ .. _installation: +############ Installation ------------- +############ Install djangocms-blog:: @@ -28,8 +29,9 @@ Then migrate:: $ python manage.py migrate +********************* Minimal configuration -+++++++++++++++++++++ +********************* The following are minimal defaults to get the blog running; they may not be suited for your deployment. @@ -90,8 +92,9 @@ suited for your deployment. .. _external_applications: +*********************************** External applications configuration -+++++++++++++++++++++++++++++++++++ +*********************************** Dependency applications may need configuration to work properly. @@ -106,8 +109,9 @@ Please, refer to each application documentation on details. .. _auto_setup: +********** Auto setup -++++++++++ +********** ``djangocms_blog`` can install and configue itself if it does not find any attached instance of itself. diff --git a/docs/settings.rst b/docs/settings.rst index b93484f..a4f4417 100644 --- a/docs/settings.rst +++ b/docs/settings.rst @@ -1,7 +1,9 @@ .. _settings: +############### Global Settings ---------------- +############### + * BLOG_IMAGE_THUMBNAIL_SIZE: Size of the main image when shown on the post lists; it's a dictionary with ``size``, ``crop`` and ``upscale`` keys; (default: ``{'size': '120x120', 'crop': True,'upscale': False}``) @@ -88,8 +90,9 @@ Global Settings * BLOG_FEED_LATEST_ITEMS: Number of items in latest items feed * BLOG_FEED_TAGS_ITEMS: Number of items in per tags feed +****************** Read-only settings -++++++++++++++++++ +****************** * BLOG_MENU_TYPES: Available structures of the Blog menu; (default list **Posts and Categories**, **Categories only**, **Posts only**, **None**) @@ -97,8 +100,9 @@ Read-only settings (default: ``Posts and Categories``) +******************** Per-Apphook settings -++++++++++++++++++++ +******************** The following settings can be configured for each ``Apphook config``: the settings above will be used as defaults.