Web Studio Tutorial - Custom Site

[resplin]

Obsolete Pages{{Obsolete}}

The official documentation is at: http://docs.alfresco.com

Labs 3Web Studio3.0

NOTE:  Web Studio is no longer part of the Alfresco Community build.  The Surf framework that Web Studio utilised has been committed to Spring Source http://www.springsource.org/extension.../se-surf.  Spring Surf is the underlying framework used by Alfresco Share.

The Web Editor Framework is the recommended platform for developing rich in-context WCM capabilities.

Back to Web Studio Tutorials.

Table of Contents

• 1 Overview
  
  
  
  • 1.1 Getting Started
  
  
  • 1.2 Associate a Presentation Template
  
  
  • 1.3 Add New Pages to your site
  
  
  • 1.4 Build a New Template
    
    
    
    • 1.4.1 Create a 'header' region
    
    
    • 1.4.2 Create a 'nav' region
    
    
    • 1.4.3 Create a 'body' region
    
    
  
  
  • 1.5 Associate your New Template to your New Page(s)
  
  
  • 1.6 Add a Navigation Component
  
  
  • 1.7 Add a Display List Component
  
  
  • 1.8 Configure the Display List Component
  
  
  • 1.9 Add Content Driven Presentation
  
  
  • 1.10 Configure Content Driven Components
  
  

Overview

This tutorial is a more advanced introduction into site building. It introduces the concepts of creating a new web site, navigation trees, dynamic templates, and content associations.

We'll begin by creating a blank web site and then create a few dynamic templates and bind them to pages. Since our web site won't have much content in it, we'll focus on drawing content from the Alfresco Repository.

The following sections are to be followed in order. For the most part, the click paths are described but experiment where appropriate.

This tutorial assumes that you are familiar with the basic concepts presented in the previous tutorial.

Getting Started

To get started, access Web Studio using the following URL:

• http://localhost:8080/studio
  
• Note: This assumes that Alfresco Web Studio is installed on your local machine.
  

Since you are not yet authenticated to Web Studio, you will be prompted to log in:

400px|

You can log in using your Alfresco credentials. However, for this walkthrough, log in using the administrator credentials:

• Login Name: admin
  
• Password: admin
  

The next step of the wizard offers the option create a new web site or import an existing web site from Alfresco Network or from any web template repository your administrator has set up for you.

400px|

• Expand the Create Web Site option
  
• Under Based on the following, select Blank Web Site
  
• Provide a name for your web site
  

400px|

Be sure to specify a name for your new site and click Create.

Web Studio notifies you that it is creating your web site. It will create a Web Project inside of Alfresco WCM and create a home page for you. Your user sandbox will be established, the cache will be refreshed and you will be taken to your web site.

You should then see something like the following:

640px

This is what Web Studio shows when it doesn't know what else to show. In this case, your custom site contains only the minimum set of elements:

• A site configuration
  
• A home page (the root page for the site)
  

Web Studio does its best to render the home page for you.Since the home page doesn't yet have any presentation associated to it, Web Studio shows you a friendly page to tell you this.

Associate a Presentation Template

In order for this page to show something, we first need to tell it what kind of presentation template to use.

Web Studio allows you to have many presentation templates for a single page. Usually, we’re interested in the default format (default) which corresponds to HTML output. However, we may also be interested in other formats such as:

• PDF
  
• Printer friendly
  
• Wireless
  
• RSS
  

In fact, we could have as many different 'formats' as we would like for this page. We can use a different template for each format.

The nice thing about templates is that they can be reused across pages. They provide a way for you to define the look and feel of your site and get the most benefit out of reuse. This helps to establish consistent and easy-to-manage look and branding.

Let's keep it simple for now. Let's just try to set up a default template.

• Click Associate a Presentation Template to bring up the list of the presentation templates in use by this page. They will be listed and sorted by Format. There will be a single presentation template listed for each format.
  

Note that in this case, nothing is listed. This makes sense - we haven’t defined any yet!

400px|

• Click Associate a Template
  

This will bring up a form that you can use to create the page-to-template association. You can use this to establish your page's presentation for various formats.

400px|

Under the Formats selector, you will be able to pick from the default out-of-the-box formats. These are Default, Print and Wireless (WAP). You can, of course, add additional ones if you would like. This is done through configuration but is not covered in this tutorial.

200px|

• Click Default to set up the template for the default (HTML) format.
  

Under the Templates selector, you will be able to pick which presentation template to use. There are several which are included with Web Studio but you are also free to create your own. A graphical editor is provided with Web Studio to help you do this and you can also build your own using Freemarker (FTL).

The default templates include:

• Basic - Home Page – a simple home page layout with regions for header, navigation, body content (left, center and right) as well as a footer.
  
• Basic - Landing Page – a simple landing page layout with regions for header, navigation body content (left and right) as well as a footer.
  

In this case, since we’re putting together a “Home” page, we’ll just use the basic home page template.

200px|

• Click Basic – Home Template to set up the association to the pre-built template.
  
• Click Save to save your association.
  

The template associations panel will now reflect the update.

400px|

• Click 'X' in the upper right of the form to close it.
  
• Reload the page by clicking on your browser's reload button.
  

You will now see the home page render using the selected template.

Add New Pages to your site

We will now work on our site's navigation tree to begin to put together a basic page hierarchy.

• Click the Floating Menu at the bottom-left corner of your page.
  

200px|

This will bring up the in-context overlays. On the left-hand side, you will see a slider called Pages. We will use that slider to work on our site's navigation.

• Open the Pages slider to reveal your site's pages and navigation structure.
  

200px|

This presents us with a tree view of our site's pages and navigation structure. The top most page is the root page of the site. This has the name Home Page by default. Child pages will appear underneath the root page and so on.

• Click Home Page. It will highlight for you.
  

Notice that the buttons within the slider change state. You are now permitted to add child pages to this root page.

200px|

• Click Add to add a child page.
  

This will bring up a form that will allow you to fill in details about your new page. The form will appear much like shown here:

400px|

• Provide a name and a description for your site
  
• Click Save to save your new page
  

Web Studio will create your new page for you and it will appear in the navigation tree below the home page.

200px|

Note that these new pages do not yet have any presentation associated with them. Thus, if you double-click them in the tree, they'll take you to the very same page we saw at the beginning.

Build a New Template

We now have a child page (or perhaps child pages if you were cunning) but we do not have any presentation for them. Rather than reuse one of the out-of-the-box templates, let's build our own.

To do so, we will investigate the Templates slider from the left-hand side.

• Open the Templates slider from the left-hand side.
  

alfresco-web-studio-tutorial-custom-13.png

You will see at least two templates there already. These are the out-of-the-box ones. We're not terribly interested in those at the moment. Instead, let's create a new template.

• Click Add within the slider's menu.
  

We will then presented with a dialog where we can provide basic information about our new template.

400px|

• Provide a name and description for your new template
  
• Leave height and width blank for now
  
• Under Layout Types, select Table Layout
  
• Click Save to save your new template
  

Note: Table layouts allow us to configure a layout using columns and rows. We can also do absolute positioning. Other layout types will be made available in the future.

Your template will be created and it will now appear in the list on the left.

• Find your new template in the list and click it.
  

A graphical depiction of your template will be represented on the right hand side. Note that since we haven't done anything with it yet, it is relatively uninteresting.

400px|

If you move your mouse over the template on the right hand side, you'll notice that the entire template shades itself blue. Clicking on the template will allow you to perform operations against it.

• Click the template and select Add Rows.
  

200px|

You will then presented with a form where you can fill in the number of rows that you would like this table layout template to have.

200px|

• Configure the template to have 3 rows
  
• Click Save to save your changes
  

The right hand side will now update with a visual representation of your template's table layout. You will see three columns along with their projected widths and heights.

500px

Create a 'header' region

We would like to place a region into our template where our users can bind in components as part of the 'header' of the page.

• Click the top-most row to bring up the row's in-context menu/
  

alfresco-web-studio-tutorial-custom-21.png

• Click Add Columns in the in-context menu
  

This will bring up a dialog asking us to provide the number of columns we would like to add.

alfresco-web-studio-tutorial-custom-22.png

• Set the number of columns to 1 so that we add just a single column
  
• Click Save to save your changes
  

Our top-most row now has a single column within it. We can now place our region into this column. By clicking on the column, we can bring up the in-context menu for the column.

alfresco-web-studio-tutorial-custom-23.png

• Click Add Region to add a region to this column
  

This will bring up a dialog allowing us to specify the properties of our region.

500px|

• For the region name, fill in header
  
• Leave the height field empty
  
• For scope, pick global
  
• Click Save to save the new region
  

That's it. We have created a region with the name header in the global scope.

Create a 'nav' region

Using the methods described previously, create a region in the second row with the following attributes:

• Region name: nav
  
• Region scope: global
  

Create a 'body' region

Using the methods described previously, create a region in the third row with the following attributes:

• Region name: body
  
• Region scope: page
  

Associate your New Template to your New Page(s)

By going back to the Pages slider, you can now double-click on your new page to tell Web Studio to navigate to that page. Since your new page doesn't have any presentation associated with it, it will display with the now familiar 'missing presentation' helper page.

You should see something like this in the middle of the page:

alfresco-web-studio-tutorial-custom-27.png

You should be able to follow the same steps from the Associate a Presentation Template section to associate your new template as the presentation to be used when rendering the page under the Default format.

• Associate your new template to this page for the Default format.
  
• Refresh the page to see your new template
  

Add a Navigation Component

We'll now add a navigation component to our site. We'll bind this into the globally scoped nav region. Since this is a globally scoped region, binding it once will allow all templates to instantly reuse the component.

Note that both of our templates have a nav region in the global scope.

• Open the Components slider
  
• Expand the tree to show the list of Components available to you
  

alfresco-web-studio-tutorial-custom-28.png

The Components shown are those which are included as stock or sample components along with Web Studio. They are standard Surf components which you may elect to use or discard. They may also serve as a reference for building your own.

In this case, they are fully usable and provide some useful, basic functionality. Here, we will binding in the navigation for our site.

• Click the Navigation component
  
• Drag the Navigation component to the nav region on the page
  

When you mouse over the nav region, you will notice that the region darkens to indicate that you can interact with it.

This will tell Web Studio that you wish to bind a Navigation Component to that region. A new instance of a Navigation Component will be created and will be bound to the nav region. The region will reload for you to reflect this update.

alfresco-web-studio-tutorial-custom-29.png

The look-and-feel used by the navigation is the default setting.

Add a Display List Component

We'll now show how you can display a list of items on your web page. We can easily set up lists of content contained inside any of the following:

• Folders inside of our web application
  
• Spaces inside of our Alfresco Document repository
  
• Applications or paths inside of our Alfresco Share sites
  

To set up a list, we can either manually bind a 'Display List Component' or we can simply drag in a container object (like a folder or a space).

Let's try the latter.

• Open the Spaces slider to open up the browser into your Alfresco Documents repository. This reveals a tree control that you can use to traverse your Alfresco installation.
  
• Expand the Spaces tree
  

alfresco-web-studio-tutorial-custom-30.png

• Click Data Dictionary. It will highlight in blue.
  
• Drag the Data Dictionary folder into your page. Drop it someplace convenient such as in one of the page scoped regions.
  

When you mouse over the nav region, you will notice that the region darkens to indicate that you can interact with it.

This will tell Web Studio that you wish to bind a Display List to that region. A new instance of a Display List Component will be created and will be bound to the region. The region will reload for you to reflect this update.

alfresco-web-studio-tutorial-custom-31.png

Configure the Display List Component

Now that the display list component is in place, we may want to configure properties about this component binding.

• Click the region that contains your display list
  

This will bring up the component's back panel. From the back panel we can inspect basic properties about the component as well as take actions against it.

Three icons will appear:

150px|

These icons allow you to edit component properties, execute the component in standalone mode and remove the component, respectively.

• Click the 'edit properties' icon
  

This will bring up a component editor form. Using this form, we can change properties about the component binding.

500px

• Change the icon size to 96 pixels
  
• Set the style to Four by Four View
  
• Save your changes
  

The region will reload for you to reflect this update. We have just told the display list component to render using a different look and feel. This is updated automatically for the end user.

640px

Add Content Driven Presentation

So far, we've looked at the association of presentation to pages. If Alfresco Surf is told to dispatch a page, this association tells Surf which template to use.

This is convenient if our site involves users clicking on navigation links (or pages). However, we may not always want to dispatch from a page. We may want to dispatch from a piece of content.

Consider the case where users click things like articles or press releases in your web site. You may want to set up specific content presentation templates. These templates would provide the end with their requested content but also provide relevant things like related items, navigation or contact information.

We can use Web Studio to set up these content presentation templates. [[Surf Platform|Alfresco Surf] supports dispatching of templates for an arbitrary number of content types. First and foremost, it has excellent support for Alfresco Content Types.

Let us revisit our Display List component from the previous section. It is rendering a list of folders. It appears as shown here.

alfresco-web-studio-tutorial-custom-31.png

If a user selects a folder, a URL is generated which tells Surf to dispatch based on the content object id. You can give it a shot to see how this works.

• Select a folder from the list
  

This will tell the Surf framework to dispatch to the template responsible for rendering that content in the current format. The current format happens to be Default so it will look for the template associated to the content object for the given format.

Of course, this currently just takes us to a page which tells us that no such association exists. In the middle of the page, you should see something like the following:

alfresco-web-studio-tutorial-custom-36.png

This means that Surf can't figure out which template to use. Why?  Well, because we don't have any content-associated presentation templates set up. Web Studio is just being nice to us and giving us a friendly update on the situation.

We can now set up a Content Presentation Template for this content type. To do so, we can either click the link given to us or we can use the Content Associations menu option under the Web Projects menu. This will bring up the Content Type Associations panel.

alfresco-web-studio-tutorial-custom-37.png

• Click New Association to create a new content association
  

This will bring up a form where we can fill in details about our new content association.

alfresco-web-studio-tutorial-custom-38.png

What we would like to do here is tell Alfresco Surf how to display content of the given type.

In this case, we have a listing of Alfresco folders within our Display List component. When a user selects one of the folders, they are clicking on an object of type {http://www.alfresco.org/model/content/1.0}folder. Thus, we can fill in the form:

• Set content type to {http://www.alfresco.org/model/content/1.0}folder
  
• Select the Basic - Content Template template from the list.
  
• Click Save to save your content type association
  

Note: It is important that the selected template not have any page scoped regions.'

That's it. Now close the panel and refresh your page. Your template should render as the means of presenting the currently selected content item.

Configure Content Driven Components

In building a content-driven presentation template, the very next to consider is how to have components bound into the template respond to the currently selected object.

The answer is that any component which sources its content from Surf's resource loader will be able to participate. This includes most of the stock components provided in the sample package.

To take advantage of this, simply edit the properties of your component.

500px

Set the drop down for Source Type to be Currently Selected Content.

By doing so, the component will 'bind itself' to the currently rendering object. The object's metadata will be loaded ahead of time by the Alfresco Surf framework. It will be available to your component.

Components operate against this content in exactly the same way as they would operate against content loaded from the Alfresco Spaces or Sites repositories, retrieved from a remote URL or fetched via virtual content retrieval from a web project.

The net effect is that component developers only need to write their components once. A component can be used on content presentation templates just as well as page templates.

Note:  More information will follow on this after Alfresco Labs 3C.