.. _topics-userguide:

===================
Merengue User Guide
===================

This document will show how Merengue CMS can be utilised for your site. We will
use a non-technical approach to show how Merenuge can be configured
graphically, as well as how general site administration is accomplished by you,
the site administrator.

.. admonition:: Technical Stuff
    
    We assume that you have a Merengue instance working properly. If not, have a
    look at :ref:`installing merengue <topics-install>` for more information.


Introduction to the Merengue Admin Site
=======================================

Once your Merengue site is active (for the sake of this guide, we assume your site URL to be 
http://localhost:8000), you can access the admin site at http://localhost:8000/admin.
You will see something similar to this:

.. image:: _images/merengue_admin_site.png

The admin site provides links to several areas where your site can be configured.
This configuration can be performed without writing any code, so you do not need
any kind of programming knowledge to manage a Merengue CMS site.

The configuration areas are organized into blocks, by configuration functionality.
These blocks are as follows:

* **Content management**. Links to manage your site's content. From here, you can
  access *content*, *sections*, *portal menus*, and *portal links*.

* **Multimedia**. Links for editing (and deleting) your site's *photos*, *videos*,
  *audios*, *panoramic views*, and *3D images*.
  
* **Site configuration**. Links to configure how the site looks. Configure the
  appearance of *blocks*, *plugins*, *themes*, *registry*, and even *save and restore
  configurations* for backup purposes.

* **User management**. Links for editing *users* and *groups* as well as their
  *roles* and privileges.

.. _topics-userguide-plugins:

Plugins
=======

Merengue works with external elements called *plugins*. Plugins increase the
functionality of your site, allowing you to customize your site in any way you want.

You can configure plugins by clicking **Plugins** on the main admin page, or going
to the URL http://localhost:8000/admin/pluggable/registeredplugin where you will
see the menu:

.. image:: _images/merengue_plugin_configuration.png

Installing Plugins
------------------

If you are working on a clean (i.e. new) Merengue installation, the **core** plugin
will be the only activated plugin. The **core** plugin cannot be disabled because it 
is essential to the site's proper behaviour.

Now, let's activate some plugins -- for example, the *voting* plugin. We just click
its link to go to the configuration page for that plugin.

.. image:: _images/voting_plugin_configuration.png

To active a plugin, you must first install it, check the *Installed* element, and
save the form. The plugin is now activated. In some cases you will want to deactivate
the plugin but not uninstall it. In that case, just uncheck the *Activate* checkbox.

With the *Voting* plugin, for example, you can allow your users to vote on content. 

.. admonition:: Technical Stuff
    
    You can add additional plugins to the list, or even develop your own plugin. 
    Take a look at the :ref:`plugins documentation <topics-plugins-index>` for more
    information.


Themes
======

Merengue has the ability to abstract your information and other content elements of the
site from the way you see the site itself. This abstraction is called *themes*
and determines how the site appears to your users.

Merengue comes with some default themes, you can change between them and choose
the one you like best. To switch themes, just click on **themes** in the
main admin page, or go to the URL http://localhost:8000/admin/theming/theme/
where you will see a menu that looks like this:

.. image:: _images/theme_configuration.png

If you want to activate a theme, click on the theme you wish to use, and check
the *Activate* block. This action will disable the current theme, because you
cannot have two different themes activated at the same time.

Content Management
==================

Merengue is a Content Management System (CMS) and, as such, its primary purpose
is to deal with content and allow you to build your site around that content. 

Content can be anything you want to use on your site: documents, news, forums, 
articles, tutorials... it's your choice and what you use will depend
on the type of site are you developing.

You should know that your content is closely related to *sections* in Merengue.
Think about sections as containers for your content containers. So first, let's
learn how to work with sections.

Sections
--------

As mentioned above, sections are like containers for content. So, the first step
in creating some content is to create a section. We go the section menu
(in http://localhost:8000/admin/section/section) and see a menu like this:

.. image:: _images/sections_configuration.png

In the upper right corner, there's a button labeled **Add section**. This button 
will bring up a form where we can configure some aspects of the section:

.. image:: _images/add_section_form.png

You can see that there are multiple text lines where you can enter text for the different 
languages that your site will use. For example, we can create a *Foo section*, and
give it separate names to be used for each language.

Another important element is the *Publication status*. This allows for the configuration
of a workflow on this section. For example we want to set it to *published*.
Once we have created our section, we can customize it, and the content, for this
specific section.

Once we have created the *Foo section*, we see a configuration form like the
following:

.. image:: _images/foo_section_configuration.png

In the upper right corner, there is a button called **Section children** that 
is actually a drop-down menu, with the options *custom style*, *documents* and
*main menu*.

.. admonition:: Additional Options

   If we add additional plugins (for example *News*), there will be more options
   available for sections like news, media, etc.

To begin editing some elements in this section, let's add a few menus to the 
section. If we click on *main menu*, the list of items is empty -- which is normal 
because we are working on a new section. Clicking on *Add menu*, brings up the
following form:

.. image:: _images/new_menu_item.png

We just add the options for the new menu item. For example, we can add a 
link to the main page of Merengue project: http://www.merengueproject.org/, with
the title *Merengue project*, and link to that URL. With this approach, we can
create a child of the *Foo section* that will be displayed as a sub-element of
that section on the menu.

Sections URLs
-------------
When we add a section with a slug ``my-section``, the URL ``/my-section/``
will access this section from the main page. This URL is a shortcut for the
longer ``/cms/sections/my-section/`` URL.

Adding Content into Sections
----------------------------

The type of content we can put into a section will depend on what plugins are 
installed in our Merengue instance. For example, we can manage *documents*, the 
default content type included with Merengue.

If we access the documents related to the *Foo section*, we will see a screen 
similar to the following:

.. image:: _images/documents_into_section.png

We have no elements linked with *Foo section*, which is normal because that 
section has just been created and has not been modified. If we want to create a 
new *document* as content in this section, just click on the button *Add document*.

This button will take us to a form very similar to the sections form. We can 
add the *title*, *description*, *publication status*, *tags* etc. For example, we 
can create a document called **Lorem ipsums** and publish it.

This is the way content is created inside Merengue. Remember: content is 
always related to a section.

Announcements
-------------

Site admins can publish announcements for visitors that are displayed throughout 
the site. Click the announcements link on the right of the admin site to manage 
these messages.

An announcement consists of a title and the actual message content, which will be 
displayed as long as the *Site wide* option is enabled. If you want to hide a 
certain announcement for your users, you can simply check off this option.

You can make announcements specific to site members. All announcements marked 
with *Members only* will not be shown to anonymous visitors. If you save the 
announcement with the *Send now* option enabled, the announcement will be mailed to 
site users.

Furthermore, your users can hide announcements permanently by clicking *Hide announcement*. 


Blocks
======

Blocks are very important in Merengue. They define (in various ways) how a page is 
displayed in your browser. Each block is related to a module, and can be 
rearranged at will. If you go the URL 
http://localhost:8000/admin/block/registeredblock/ you can see the blocks currently
available for your site:

.. image:: _images/blocks_list.png

The column called **Placed at** is very important, because it describes where the 
block is displayed. For example the *Voting block* (added by the *Voting* 
plugin) is placed before the content body.

Let's suppose that we want to change the position of the *Voting block*. There are 
two ways to do that. First, the the position can be configured on each block's
configuration page. The block's configuration page is accessed by clicking,
in the list, the block we wish to edit. You should see a form like this:

.. image:: _images/single_block_configuration.png

For example, we can edit the **Placed at** field to move the *Voting block* to the right
sidebar. If we go to the main page (at the URL http://localhost:8000/) we now see
the voting form on the right:

.. image:: _images/main_page_voting_right.png

The second method of changing the block's position is to do so using the graphical
interface. If you let your mouse pointer float above a block (for example *Vote
content*) you will see a green button. If you click it, the display will change
to this:

.. image:: _images/main_page_rearranging.png

Just drag and drop to rearrange the blocks on the page.

You can also configure individual blocks (if the block itself has configurable
parameters):

.. image:: _images/tagcloud_block.png

The configuration form appears with the same user interface:

.. image:: _images/tagcloud_config.png

Blocks for Specific Content
---------------------------

In addition to *general* blocks, you can configure blocks to appear only with
certain, specific content. Also, you can *overwrite* the block configuration
just for that specific block.

To do this, we add a new child *block_content_related* for that content:

.. image:: _images/add_block_content_related.png

You can then select what block you wish to have displayed with that particular content,
in which location, or even the order of that location. The **block specific configuration**
will change dynamically to adapt the form for the selected block.

Your selected configuration will only apply to the block related to that content.
This way, you can have two or more similar blocks, each using a different configuration.

Navigational Elements
=====================

We define navigational elements as the elements that you see on the page
which link the user to a different places inside or outside of your site. 
As examples, consider: a breadcrumb, a menu, portal links, etc.

Breadcrumbs
-----------

A breadcrumb is a set of links that gives users a way to keep track of where they
are in the sitemap. Consider the following image:

.. image:: _images/main_page_breadcrumb.png

In this case, the breadcrumb indicates that the content *Lorem ipsums* is a child
of a section called *Foo section*. This way we can easily navigate to site links upstream
from the user's present location.

These links are autogenerated so we cannot modify them. Still, it's important to
know what they are and how they are used.

Portal Menus
------------

Portal links are links that have always visible on the entire site. When starting
a new site, no portal links will have been configured. However, we can add any
links we want via the URL http://localhost:8080/admin/section/menu/. Click the
top-right button labeled **Add menu**. Let's add links to Google, Twitter and Facebook.

If you go to the main page of your site, you will see links similar to those shown
in the following screenshot:

.. image:: _images/main_site_site_links.png

If you hover your mouse pointer above those links, you will notice that the portal
menus are displayed in a block that you can drag and drop to any location on
the page.

Navigation Block
----------------

The navigation block is generated by the core plugin. By default it appears on the
left sidebar of the site, as you can see on the previous image.

This menu displays the elements of your site in a tree view. At the first level
you see the **Sections** of the site. In our example, we have a *Foo section* and
a *Test section*. We can also see the main menu for each section. In this case,
the *Foo section* has a link to Merengue project, so we see that element in the
navigation block.

We can re-order the block as usual, as well as reorder its sections and change its
location.

Portal Links
------------

Portal links are similar to `portal menus`_, and they work in a similar way. 

.. _`portal menus`: index.html#portal-menus 

There are two different kinds of portal links: **primary links** and **secondary 
links**. We can add any of them via the URL 
http://localhost:8080/admin/portal/portallink/add/ . We then see the form:

.. image:: _images/add_portal_link.png

We are going to create two links: a primary link to GMail, and a secondary link
to Wikipedia, in order to see the differences between them. In the following 
image we notice the differences between them:

.. image:: _images/main_page_menus.png

You can see that all primary links are included together in a separate block.
Secondary links are also placed together in a separate block. Each block can be
rearranged at will. Semantically, **primary links** are links that simplify the
navigation of the site (e.g. linking to important areas of the site -- for example
the *News section*).

To clarify, **portal menus** (discussed in a previous section above) are links
related to a section (e.g. categories in the *News* section).

**secondary links** are links placed in the footer. These are not considered 
essential to site navigation but are still important (e.g. copyright info, about
the site, contact info, etc.)

As you can see, creating and managing portal links is very simple. However, it's
important to know the differences between the two types of links.

Actions
=======

In Merengue, we define **actions** as events that an user triggers with a button.
For example, if we activate the *Facebook* plugin, your users will see a link on content
items that allows them to share the content in Facebook. Clicking on that link is
considered an action.

You can see what actions are available on your Merengue site by accessing the
following URL http://localhost:8080/admin/registry/registereditem/?category=action.
These actions are provided by different modules, as well as by blocks and other stuff.

Permissions in Merengue
=======================

In Merengue, we define permissions as the authorization an user must have in order
to be able to do something. For example, if an user wants to edit some content,
he must have the edit permission for this content. If an user wants to manage sections,
then he needs the manage section permission.

Permissions can be global, as you can see by accessing the URL 
http://localhost:8080/admin/perms/objectpermission/.
Or permissions can be local for each piece of content. Local permissions can be viewed
by adding the string `/permissions/` on to the end of the URL for a specific piece of
content (e.g. http://localhost:8080/admin/base/basecontent/1/permissions/).

To associate permissions with user, we use **roles**. These define a specific set
of permissions. You can then associate a role with an user. This user will have
every permission specified by the role. Additionally, you can assign a role to a
group. Every user of this group will have all permissions associated with that
particular role.

There is a special role called "Anonymous User". This role is assigned to every user.

.. admonition:: More Information

    For more information about Merengue permissions, you can read :ref:`working with permissions <topics-permissions>`.


Maintenance Tasks
=================

There are some tasks that are normallye executed in a shell, but Merengue allows the
admin user to do these tasks using a graphical interface.

Registry
--------

The registry is a page where you can see all of the *registrable items* of the site,
as well as showing the state of those items. You can see this list via the URL
http://localhost:8080/admin/registry/registereditem/ This list provides a 
general view of what is installed in a particular Merengue instance.

Backups
-------

Open the following URL http://localhost:8080/admin/siteconfig/ in you web browser.
You should see the following page:

.. image:: _images/backup_configuration.png

From this page, we can:

* Restore a previous configuration backup
* Create a configuration backup. This backup includes information regarding what
  elements are registered with your site.
* Create a database backup. This is a full content backup, to assist in preventing
  the data loss from your site.
