Quick guide to creating a site

This article takes you through the process of setting up a Magnolia website. The objective is to demonstrate the ease with which users of all technical levels can build a site. The article uses the free, open-source Community Edition and the Standard Templating Kit.

Getting started

The first step is to download and install Magnolia Community Edition. You will find instructions on how to do this at Community Edition.

After installation, log in and launch the Pages app. 

Viewing the demo sites

There are two demo sites, demo-project and demo-features, each with several pages. For each page, the following information displays:

• Page name.
• Title that can be different from the name.
• Template. Each page is assigned a template. STK contains ready-to-use templates for many use cases.
• Status that indicates whether the page has been published to the public instance.

To open the demo-project site, select the demo-project page and click Edit page in the action bar or context menu. You can also double-click the page row. 

The demo-project site is displayed in the page editor where content is added and edited.It is a WYSIWYG editor. HTML generation takes place automatically and produces HTML5-compliant code.

When we create our site in the later sections, we will go into more detail about functionality and procedure but for now note the following:

• Pages have different structures because they are based on different templates
• Templates are assigned to pages in the Pages browser subapp.
• Components on the page are grouped into areas that are defined by templates. For example, the Contact, Sitemap and Login/Logout links in the header are in the Meta Navigation area. The components in the vertical column on the right are in the Promos area.
• Navigation is created automatically and corresponds to the page hierarchy.
• To view the page without the editing bars, as it would appear on the live site, click Preview page in the action bar.
• To set page properties and meta data click Edit page properties in the action bar.
• Page layout adapts to the user's viewport. Placement of the content areas is fluid.

Components are added by clicking an area bar. Individual component toolbars are displayed (light green):

• To add components, click the plus icon in the New Component toolbar.
• To edit content, click the edit icon in the component toolbar.
• To move a component, click the move icon in the component toolbar, and then drag and drop the component .

Creating the site structure

In this example we create a website about pet products. In addition to product pages the site contains company information, a contact form and a sitemap. The site structure looks like this:

• Home
  • Dogs
    • Dog Food and Chews
    • Dog Toys
    • Dog Collars and Leads
    • Dog Kennels
  • Cats
    • Cat Food
    • Cat Baskets
  • About Us
  • Service
    • Contact Us
    • Sitemap

To create the site structure:

1. Click Add page to create a home page. In the dialog type the page name and title, and select the Home template.
2. Add as many second and third-level pages as you need. You can go down as many levels as necessary but flat hierarchies usually work better. To add a child page, select the parent page and click Add page.
3. To speed things up you can click:
   
   1. Duplicate page to copy pages.
   2. Rename page to change page names and titles.
   3. Change template to assign a different template.
4. You can also move pages using drag and drop.

To open the Home page in the page editor, select it and click Edit page. The horizontal and vertical navigation menus have been created automatically and match the site structure the browser subapp. The title is used for menu links but can be changed at a later stage.

Browse through the pages and note the skeletal structure of the various templates.

Using assets

Images, documents, videos and other asset files are stored in the Assets app and chosen in component and page dialogs in the Pages app. Read more at Managing assets and Using assets on pages.

To upload an asset:

1. Click Assets in the App launcher.
2. Click Add folder and then Rename folder.
   
3. Select the new folder and click Upload asset.
4. Upload the file in the Asset dialog. There are a number of meta data fields available that are used automatically when referencing images in a dialog.
   

To reference an asset on a page, in a dialog:

1. In the image field click SELECT NEW.
2. In the choose dialog select an asset in either the tree or thumbnail view.
3. Click Choose.
   

Creating the home page

All other pages inherit the header and footer areas that we now create on the home page.

Page properties

Click Edit page properties in the action bar and complete the fields in the dialog. Each page of the site has its own properties dialog. The options available are identical except the home page includes some information that is site-wide. The logo image and slogan are displayed on the page while the keywords and description entered in the META DATA tab are merged into the HTML code. The Abstract is a summary of the page content that is used in teaser components that reference the page. The Search Page field defines the page on which search results are displayed.

Meta navigation links

The meta navigation area is suitable for inserting links to pages such as Contact and Sitemap. Click the area bar, then the Add icon in the component toolbar, choose Internal Link and browse to the target page.

The title of the target page is used automatically as the link text. You can override it in the Link Title field. Keep adding as many link components as you need.

Footer

To add footer components, click the Footer area bar and then the edit icon and add your copyright text. The text is displayed at the bottom of the page.

Click the add icon in the New footer component toolbar to add Footer links and About this site components. The links can be internal or external. The About in footer dialog includes a text editor that gives you control over the formatting.

The components available in each area depend on the area and the template. The other areas of the home page such as stage, main, base and promos are designed for components that tease other pages of the site. We will create these later.

Create content pages

In the site structure, we have two section pages, Dogs and Cats, that are based on the Section template. Pages below them are based on the Article template. Section pages are designed to tease article content so create the Article pages first.

Article pages

Navigate to Dogs > Dog Food and Chews. The page header component is added automatically and the page title is inserted in the Headline field. Click the edit icon in the Page Header toolbar and complete the fields in the dialog.

In the Content area, below the header component, add new content components.

To demonstrate a few components, we added a Text and Image, a Quoted Text and a Video component.

Set up the rest of the pages based on the Article template.

Section pages

Navigate to the Dogs section page. The purpose of the Section template is to summarize and tease article pages within the section. The Section Header component is unique to this template and is usually used to summarize or introduce the section. Open the dialog and type in the title and text.

Add teaser components in the Teasers area after the Page Header component.

The Opener is an internal page teaser component that renders more prominently. The Internal Page Teaser component picks up the title, abstract and first image of the target page automatically. Navigate to the target page in the dialog and select it. On the Teaser Overwrite tab you have the option to overwrite the automatically retrieved information by using a different image, title and abstract.

To see a list of components available in the Teasers area, click the add icon in the New Teaser Component toolbar.

We added an Internal Page Teaser, a Teaser Group - Carousel and a Teaser Group - Finger Tabbed component to demonstrate a few.

Create the Cats section page in similar fashion.

Contact form

To set up the contact form, navigate to Service > Contact. This page is based on the Form template. Click the Content area bar and then the edit icon in the Form toolbar.

The Form tab in the dialog allows for introductory text and the symbol and text for required fields.

Options in the Submit Settings tab control what is displayed on the page after submission.

Options in the E-mail tab define how the information collected in the form is sent to the recipient. You can reference a form fields using FreeMarker tags such as ${subject} to include the information collected in that field.

Options on the Confirmation E-mail tab define a confirmation email sent to the visitor.

Checking the Send confirmation field is not enough. You need to also add an enabled property under the SendConfirmationEMailProcessor form processor and set its value to true. See Form processors.

Form field components are inserted in field sets. A set groups similar fields together, such as all the fields that comprise a street address. Add as many fields sets as you need.

To add a field set, click the Form Fieldsets bar, then the add icon in the New Form Fieldsets Component toolbar.

To add fields, click the Form Fields bar, then the add icon in the New Form Field Component toolbar.

We added four text field components and a submit button component.

In order for the emails to be delivered, enter valid settings in the Configuration app > /modules/mail/config/smtp. Learn more about the Form and Mail modules.

Sitemap

The Site Map template lists all pages in the Site Map component automatically. Navigate to Service > Site Map where a site map based on the default settings is rendered.

If necessary, add content to the header component and change the default settings in the Site Map dialog.

Search

The page linked to in the Search Page field in the page properties dialog on the home page is used to display search. The Search Result component is included automatically when you assign the Search Results template to the page. You can change how the results are displayed in the component dialog. Ideally, this page should be hidden in the navigation. The option to hide the page is available in the page properties dialog.

Extras, Promos and Base areas

All templates have promos and base areas and most have an extras area. These areas are used for teaser components. Many kinds of teasers are available.

Promos area

Promos and many extras are inheritable. This means that you create the component once on a parent page and it is displayed on all child pages. Promo components are internal page teaser components displayed in their own area. On wider viewports the promos area is on the far right in the page layout. Promos are usually used to promote entire sections of a site but are also useful to tease special offers, seasonal promotions and landing pages.

To create promos, click the Promos area bar on the home page and add a new promo components.

If you check the Show in subpage field, the promo will be inherited by all child pages. For the example below, we resized the screen so that the promos render below the main and extras areas.

Extras area

Extras are also teaser components but there are a few exceptions. The extras area is to the right of main area. Many extras are inheritable.

On the Dogs page, we included an Internal Page Teaser, an External Page Teaser and a Download File Teaser component to demonstrate a few.

Base area

The base area is above the footer. Teaser carousel and category cloud components are available.

Complete the home page

Add a stage component and teaser components in main area on the home page. In the stage area you can either tease a single page or a number of pages using the Stage Paging component. We selected the paging option and made a few edits in the Teaser Overwrite tab.

In main area you can select from a number of teaser components.

We added Internal Page Teasers with link lists.

Create a custom theme

The STK is a templating framework that gives you control over of all aspects of your site, including the functionality, visual identity, templates and components. Read more about the Standard Templating Kit.

The demo sites are based on the pop theme that is predominantly black, white and pink. This theme is assigned in STK > Site Definitions.

Change this assignment to orange. We will create the orange theme below. A more comprehensive tutorial  Creating a custom theme is available.

To create the new orange theme, go to STK > Themes. The visual identity of the site is controlled by a single CSS file, styles.css, linked to in the pop/cssFiles/styles/link node. Create the orange configuration as shown in the screenshot below using the Add content node and Add property actions. The extends property tells Magnolia to use the entire pop theme except for the new styles.css that will be stored in a folder to be created in STK > Resources.

The CSS files used by the pop theme are accessible in STK > Resources. In /templating-kit/themes, create a new folder structure /orange/css using the New folder command. Next, copy /pop/css/styles into the new folder.

The new styles.css file can be edited inline. Select the file and click Edit item. In the dialog, change the styling to suit your theme. We changed the colors to orange and gray.

The images referenced by /pop/css/styles.css are stored in STK > Resources in /templating-kit/themes/pop/img/bgs and /icons.

Either recreate the images or download and edit them to suit your styling. Upload the new images to new folders /templating-kit/themes/orange/img/bgs and /icons, leaving the file names intact. styles.css uses relative URLs so the correct images will be merged in the template.

These minor changes give the site a new visual identity without touching the templates or content.

Activating content

The last step is to publish the content to the public instance. Magnolia is preconfigured with two instances: author and public. Up until now we have worked on the author instance. Both instances are installed automatically. The public instance is set up as a subscriber of the author instance. Open the Configuration app and navigate to /server/activation/subscribers/magnoliaPublic8080/URL. This property tells Magnolia where to publish the content.

Magnolia Enterprise Edition supports multiple subscribers per authoring instance, meaning that you can publish to multiple sites from a single authoring instance.

Login to the public instance at localhost:8080/magnoliaPublic/.magnolia/admincentral. In the Pages app you can find the demo sites but not the pet-products site as it is yet to be published.

To publish the site, select the pet-products page on the author instance and click Publish incl.sub pages. The status indicator of all pages changes from red to green.

Publish the folder and all assets in the Assets app using the Publish action.

On the public instance refresh the Pages app and the pet-products page structure will appear. On the public website the pop theme is applied as the orange theme has not yet been published.

On the author instance, publish the following nodes using the Publish incl.sub nodes action:

• STK > Site Configuration /theme.
• STK > Themes /orange.
• STK > Resources /templating-kit/themes/orange.

Refresh the page on the public site and the orange theme is applied.

This quick guide has shown you only the very basics. There is much more that Magnolia can do.

Browse documentation, join the Users mailing list and visit the Forum to learn more.

Credits:

• Vikram Vaswani, original article at Webreference.com
• Ruth Stocks, content examples and design