.. _intro-overview:

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

Merengue is a fully featured CMS framework built on top of the `Django framework`_.
It is not only a plug-and-play CMS but also a web framework with which to build CMS
sites at top speed -- with clean and re-usable code.

In order to achieve this we have:

 * Taken conventions that are not provided for in Django. Merengue is designed to
   develop CMS websites -- not to develop generic web applications. Thanks
   to these conventions, Merengue has features that include being skinnable, pluggable, etc.

 * Created both a complete API for managing content and as well as controlling and
   manipulating a powerful out-of-the-box CMS capable of handling all of the
   basic requirements of a 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 necessary to handle
   content management. You can use some of these models in your own plugins
   to create new content types.

The goal of this document is to provide enough technical specifics to
understand how Merengue works. When you are 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 Required

    Merengue is based on the Django web framework. You need to understand basic 
    `Django concepts`_ in order to better understand how Merengue works.

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


Main Merengue Features
======================

Out of the box, Merengue features the following:

A Complete Data Model
---------------------

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

Models features include:

 * Base content: inherited by all managed content types (news items, events,
   documents, forums, etc.). These content types will share all Merengue CMS
   features (a workflow, a featured admin interface, permissions, etc.).
 
 * Sections: used to divide websites into several parts, to allow management by
   unique user groups.

 * Menu items: used for creating navigation features inside the site or its sections.
   Menu items can be hierarchical and be used to link to other Merengue content
   or external data.

 * Collaborative documents: inherits the base content model to allow collaborative
   editing and translation by simultaneous users.

 * News items, events, and other content items, defined in Merengue plugins.

A Pluggable Architecture
------------------------

A pluggable system definition depends on the ``plugin`` concept. For Merengue, a
``plugin`` is an object developed by someone which can be installed without
changing a single line of code.

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

 * Synchronize plugin data models.

 * Register the plugin as Django application.

 * Include some URL prefixes to be handled by the plugin. You can also use i18n URLs.

 * Register plugin blocks (areas of the screen used to render and display content).

 * Register plugin actions (PDF export, RSS feeds, etc.).

 * Register custom admin sub-sites.

.. admonition:: Django Applications

    In our concept of a ``pluggable`` architecture, Django applications are not
    considered plugins, as they require some work in order to be integrated into
    a website (Django URL configuration, settings configuration, syncing of
    the database, template work, etc.)

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

Merengue includes a customizable permissions system to manage content. The default
permissions configuration is good for the initial CMS setup. You can define roles
and permissions for content editing and access as well as grant permissions to
Merengue users.

The main advantages obtained from using `Django permissions`_ are the increased
granularity and the persistent storage of all permission configurations in the
database. Permissions are configurable by admin users, using the management interface.

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

Integrated GIS
--------------

Merengue supports GIS. You can enable GIS support in Merengue by setting a flag.
All content is geolocalized and you can edit geographic data via the admin user
interface, by viewing it on a map, or by using the Django `GIS API`_ to implement
whatever GIS features you need.

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

Out-of-the-box Caching
----------------------

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

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

Theming
-------

Merengue themes define the look and feel of your CMS website by uncoupling graphic
design and template logic. With Merengue, you can use the same content with
different appearances:

.. image:: _images/themes.jpg

How does this work? Merengue changes the Django logic controlling template and media loading
(including active theme searching).

For example, the next template will render blocks located in ``leftsidebar``
into the ``rightsidebar`` zone. You only have to create this template as your
``templates/themes/yourtheme/base.html`` and activate the 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 Required

    Merengue uses the `Django template system`_. See the Django template documentation
    for more information about Merengue templating.

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

Full Featured Management Interface
----------------------------------

The management interface is based somewhat on the Django admin interface (with steroids)
and a WYSYWYG interface (e.g. for managing block 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

Other Cool Features
------------------------

* **Collaborative edition**

Merengue document management includes a collaborative editing 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 content and language
catalogs:

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

* **Schema evolution**

Merengue uses `South`_ to implement database 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 an enthusiastic team of Python programmers, who love
elegant code and clean APIs but also look for the most pragmatic solution to
a problem.

Keeping that in mind, Merengue has a well-designed data model in addition to a
free, rich Python API. With Merengue, your imagination is the limit!

Some examples follow:

.. 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

An Extensible Data Schema, Not Hierarchical Pages
----------------------------------------------

Some CMSs are based on a simple data model using hierarchical pages or nodes
without a semantic meaning -- just data.

Merengue content management is based on an extensible base model (non-abstract).
All content types (documents, forums, news items, events, etc.) inherit from this
base model.

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
-------------------------

Merengue plugins can do many things; they are not just place holding renderers.

Plugins can:

* Add new content types.
* Add new visual blocks.
* Add new actions for content or site.
* Create/Register new permissions.
* Create/Register a URL namespace (usually to implement some views).


You've Just Scratched the Surface
=================================

This is only an overview of Merengue -- for more information, please see :ref:`Merengue docs <index>`.

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

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