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.

Technical Stuff

We assume that you have a Merengue instance working properly. If not, have a look at installing merengue 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:

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.

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:

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

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

Technical Stuff

You can add additional plugins to the list, or even develop your own plugin. Take a look at the plugins documentation 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:

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:

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:

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:

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

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:

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:

../../_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:

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:

../../_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:

../../_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:

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

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

The configuration form appears with the same user interface:

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:

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

Block Caching¶

The HTML rendered in the blocks can be cached if it is configured by the manager user:

The first Activate cache checkbox activates block cache for this block. If this checkbox is selected the next other parameters will be enabled:

Cache will only be active for anonymous users or for both authenticated and anonymous ones.
Cache will vary on the request URL.
Cache will vary on the current language of the user who accesses.
Cache will vary depending on the user who accesses the website.

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:

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:

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.

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:

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:

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.

More Information

For more information about Merengue permissions, you can read working with 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:

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.

Merengue v0.8 documentation

Merengue User Guide¶

Introduction to the Merengue Admin Site¶