.. _intro-overview:

=================
Merengue overview
=================

Merengue is a fully featured CMS framework built on top of `Django framework`_.
It's not only a plug-and-play CMS but a framework to build CMS sites at top
speed with clean and re-usable code, using our preferred web framework.

In order to achieve we have:

 * Taken conventions that are not provided in Django; Merengue is designed to
   develop CMS websites and not to develop generic web applications. Thanks
   to these conventions Merengue has features such as skinnable, pluggable, etc.

 * Created both a complete API for managing content and a poweful out-of-the-box
   CMS with all of the basic needs of any CMS site (permissions, theming, plugins,
   actions, etc.).

 * Built a pluggable system that allows plugins to create new models, handle URLs,
   define content or site actions, create blocks, customize admin zones, etc.

 * Created a default data model with all of the requirements to allow content management.
   You can inherit some of these models in your plugins to create new content
   types.

The goal of this document is to provide enough technical specifics to
understand how Merengue works. When you're ready to start a project, you can
:ref:`start with the tutorial <intro-tutorial>` or :ref:`dive right into more
detailed documentation <topics-index>`.

.. _Django framework: http://www.djangoproject.com/

.. admonition:: Django knowledge needed

    Merengue has been created using Django. You need to know some 
    `Django concepts`_ in order to better understand Merengue ones.

.. _Django concepts: http://docs.djangoproject.com/


Main Merengue features
======================

These are some of the Merengue out-of-the-box features

Data model
----------

Merengue comes with a complete data model for managing content. All models will
be translatable by default and may be geolocalized (if you enable GIS).

Some of these models are:

 * Base content: will be inherited by all managed content types (news
   items, events, documents, forums, etc.). These content types will share all
   Merengue CMS features (workflow, featured admin interface, permissions, etc.).
 
 * Sections: will be used to divide websites into several parts, that
   could be managed by different groups of users.

 * Menu items: for creating a navigation inside site or sections. Menu items will
   be hierarchical and will link to some content or external link.

 * Collaborative document: inherits base content to allow collaborative
   edition and translation by simultaneous users.

 * News items, events, and others, which are defined in Merengue plugins.

Pluggable
---------

A pluggable system definition depends on ``plugin`` concept. For Merengue, a
``plugin`` is a thing that is developed by someone and can be installed without
changing a line of code.

In that sense, when you install a plugin, Merengue will (among other things):

 * Synchronize plugin data models.

 * Register plugin as Django application.

 * Include some URL prefixes to be handled by the plugin.

 * Register plugin blocks (areas of the screen to render things).

 * Register plugin actions (pdf export, rss, etc.).

 * Register custom admin sub-sites.

.. admonition:: Django applications

    In our concept of ``pluggable``, Django applications are not plugins,
    because they need some work in order to integrate into websites (URLs
    inclusion, change settings, sync database, work on templates, etc.)

Permissions
-----------

Merengue includes a customizable permissions system, with a good default
permissions for content management. You can define roles, permissions and
grant permissions to roles and contents.

The main advantages with `Django permissions`_ are more granularity and that
all permission configurations will persist in the database, and so can be
configurable by admin users, using management interface.

.. _Django permissions: http://docs.djangoproject.com/en/1.1/topics/auth/#id1

GIS integrated
--------------

Merengue supports GIS. You can enable GIS support in Merengue by setting a flag.
All content is geolocalized and you can edit its position in admin view,
viewing it in a map, or using the Django `GIS API`_ to implement whatever you
want.

.. _GIS API: http://geodjango.org/

Out-of-the-box caching
----------------------

Merengue uses `Johnny Cache`_ to cache all SQL sentences in a smart way. With
this integration you can forget about queryset caching and invalidation.

.. _Johnny Cache: http://packages.python.org/johnny-cache/

Theming
-------

Merengue themes can define the look and feel of websites, uncoupling graphic
design and template logic. With Merengue you can have same content with
different appearances:

.. image:: _images/themes.jpg

But, how does it work? Merengue changes the Django template and media loading
logic including active theme searching.

For example, the next template will render blocks located at ``leftsidebar``
to be placed in the ``rightsidebar`` zone. You only have to create this template as your
``templates/themes/yourtheme/base.html`` and activate your theme in the admin interface.

.. code-block:: html+django

    {% extends "base/layout.html" %}

    {% load block_tags %}

    {% block rightsidebar %}
      {% render_blocks "leftsidebar" for content %}
      {{ block.super }}
    {% endblock %}

.. admonition:: Django knowledge needed

    Merengue uses the `Django templates system`_. See `Django templates` to get more
    information about Merengue templating.

.. _`Django templates system`: http://docs.djangoproject.com/en/1.1/topics/templates/

Full featured management interface
----------------------------------

The management interface is half based on Django admin (with many steroids)
and half a WYSYWYG interface (for example to manage blocks layout).

* **Content management**

Merengue allows the manager to create any content

.. image:: _images/content_creation.png

* **Theme management**

.. image:: _images/theme_management.png

* **Visual block reordering**

.. image:: _images/block_reordering.png

* **Plugin management**

.. image:: _images/plugin_management.png

Some other cool features
------------------------

* **Collaborative edition**

Merengue document management includes a collaborative edition tool that allows
users to work on the same document simultaneously:

.. image:: _images/collaborative_edition.png

* **Translation tools**

Merengue has several tools for translating both contents and language
catalogs:

 - ``Transhette``: application based in `django-rosetta`_ to do `Django translation`_ via web.
 - `django-inlinetrans`_: cool WYSYWYG translation application that allows the translation of every label in the same view that you see the untranslated text.
 - `django-transmeta`_: application for model translation.

* **Schema evolution**

Merengue uses `South`_ to implement schema evolution.

.. _django-rosetta: http://code.google.com/p/django-rosetta/
.. _django-inlinetrans: http://code.google.com/p/django-inlinetrans/
.. _django-transmeta: http://code.google.com/p/django-transmeta/
.. _Django translation: http://docs.djangoproject.com/en/1.1/topics/i18n/#topics-i18n
.. _South: http://south.aeracode.org/

Philosophy
==========

Focused on programmers
----------------------

Merengue was created by a Python enthusiastic team, who love elegant code and
clean APIs but with pragmatic approaches to solutions.

With that in mind, you've got a free, and rich, Python API to do almost all
of the things you can imagine, with a well designed data model for content
management.

Here are some examples:

.. code-block:: python

    >>> from merengue.base.models import BaseContent

    # all contents published in your CMS
    >>> BaseContent.objects.published()
    [...]

    # create a content from a plugin (a news item, that inherits from BaseContent)
    >>> from plugins.news.models import NewsItem
    >>> newsitem = NewsItem(name_es='Mi noticia', name_en='My news item')
    >>> newsitem.publish_date = datetime.datetime.now()
    >>> newsitem.save()

    # managing permissions
    >>> from django.contrib.auth.models import User
    >>> staff_user = User.objects.create(username='roque')
    >>> from merengue.perms.utils import register_permission, register_role
    >>> register_permission('Vote news item', 'vote_newsitem', 
                            for_models=[NewsItem])
    >>> editor = register_role('Editor')
    >>> editor.add_principal(staff_user) # add user to role 'Editor'
    >>> grant_permission(newsitem, editor, 'vote_newsitem')
    >>> has_permission(newsitem, staff_user, 'vote')
    True

Extensible data schema. Not hierarchical pages
----------------------------------------------

Some CMSs are based on a simple data model with hierarchical pages or nodes,
without a semantic meaning, only data.

Merengue content management is based on a extensible base model (non abstract),
where all content types (documents, forums, news items, events, etc.)
inherit from that base model.

So, with Merengue you can build a managed system that maps into an existing
reality. For example, in the following models we have mapped books and authors,
which will be managed in Merengue, because both inherit from ``BaseContent``:

.. code-block:: python

    from merengue.base.models import BaseContent

    class Author(BaseContent):
        first_name = models.CharField(max_length=100)
        last_name = models.CharField(max_length=100)

    class Book(BaseContent):
        authors = models.ManyToManyField(Author)

Plugins are not renderers
-------------------------

Developed plugins can do many things; they are not only place holding renderers.

Plugins can:

* Adding new content types.
* Adding new visual blocks.
* Adding new actions for content or site.
* Register new permissions.
* Register a URL namespace, usually to implement some views.


This is just the surface
========================

This is only a Merengue overview, for more information, see :ref:`Merengue docs <index>`.

You can now go to `download Merengue`_ and read :ref:`the tutorial <intro-tutorial>`.

.. _download Merengue: http://www.merengueproject.org/download/
