Building A Basic Site

From VYRE

Jump to: navigation, search
Building a Basic Site
Unify Tutorial
Unify Tutorial Series
Difficulty Level Beginner
Position in series 2
Next in Series Introducing Users And Permissions
Previous in Series UnifyTutorial
Prerequisites Installing Unify
Tutorial Introduction


Contents

Building a basic site

Objective

In this tutorial, we’re going to build a simple site to create, edit and display simple news articles. As with many Unify sites, it will have two page trees: an admin branch for administrative tasks such as creating and editing news articles, and a second for the end user to view the news articles. To begin with our news articles will only have a name and description. Later we’ll add custom attributes to make it more realistic.


Creating a user account

It is generally bad practice to work as the Admin user, so the first task is to create a new user account.

  1. Open the Users and Groups module, expand the User realms menu and then expand the Default realm.
  2. Click the Users link. A list of users in the system will load in the main content window. From the top contextual navigation, click "New User" and complete the form. Add yourself to the admin group by moving the "Admin" option from the left to the right window.
  3. Save the form, log out by clicking the logout button in the top right of the screen and log back in again as your newly created user.



Creating your first site

Sites in Unify are the encompassing entity for holding pages and their structure. Sites also hold configurations for error pages, domain names and virtual paths. To create a site:

  1. First click the Publishing Module, and from within the left hand menu tree, click the Sites link
  2. From within the top contextual navigation, click Create
  3. Give the site a suitable name and description and click Save

To provide external access to our site we’ll need to give it a domain name. Any name that points to the IP the instance in running on will suffice, or if you don’t have one, the IP of the server.

To add a domain name:

  1. Click your site from the left hand menu.
  2. Hover over the "Actions..." menu from the top contextual navigation and select "Add Domain Name"
  3. Enter the domain name or IP and click "Save"

Adding CSS

First we need to upload our CSS to the system.

  1. From within the Publishing Module, expand the Files menu and click CSS
  2. Click "Create" from the top navigation, complete the form, giving it a Title and Description.
  3. Click "Browse" and navigate to the CSS file supplied with this tutorial and save.


Creating the page template

Before we can create a page, we must first create a page template on which to base our page. Our template is going to have three content areas. The first will sit at the top of the page and will hold our site banner. We’ll make this area shared, so that our banner can be shared across all pages that use this template. The second content area will be directly below the first, and will hold the content specific to that page; therefore, it should not be shared. The third will hold our site footer so this will also be shared. To create the page template:

  1. From within the Publishing Module, click on the Page Templates link
  2. All templates must live in a folder, so from the top navigation, click "Create" to create a folder, give it a name and description and save. You newly created folder will appear in the left hand navigation, under the Page Templates menu link.
  3. Click your template folder and from the top contextual navigation, click "Create Template".
  4. Open the public_page_template.jsp file which is in the code folder of the tutorial files. Read through the code and paste the contents into the Contents window.


  5. In the CSS window, select the CSS you uploaded earlier.
  6. Give a suitable name and description and save.
  7. Click "View Template" to see the template.
  8. You should see your page template, showing three blue bars, and a large orange banner complaining that this page template is not active. Similar to a deployment level, page templates have an activation level. This means that a template can be modified without affecting the pages using it until it is activated.

  9. Activate your template by clicking "Activate this version"
  10. Before we create our page, we’re going to add a small heading / banner to our top, shared content area that will appear on all pages that use this template. To do this we’re going to use the static code porlet. This simple portlet allows the developer to input any client side code (HTML, CSS, JavaScript) to the page and then have the browser execute / render it. To add the portlet:

  11. Select your page template from the Page Templates menu in the Publishing Module - note only activated templates will appear in the list.
  12. Click the top blue bar and click the Image:Window_add.png (Add Below) icon to open the portlet menu.
  13. Expand the VYRE portlets group menu and select Static Code
  14. Enter some text within <h1> tags for your top header / banner. I used the following:

  15. Save the portlet and click View on the portlet control to return to your page template. It should look something like this:

Creating the home page

Now that we have a page template created, we can create the home page.

  1. First, expand the Sites link in the left hand menu and click your newly created tutorial site.
  2. From the top navigation, hover over the "Actions..." menu and select "Create Page".
  3. Expand your folder and select the template you created earlier.

You will now be presented with the create page form. Fill in the following fields with the values below

  1. Path: this is the name of the page used in the URL. For this page use "home"
  2. Name: this is the name of the page. I’ve used "Tutorial Home Page" but you can use what you want
  3. Description: this should be a good explanation of what the page is used for
  4. Publish Status: this has three options:
    1. Published –the page is accessible to the end user. This is the "normal" mode one selects
    2. Not Published – the page is not accessible to the end user
    3. Published but hidden – the page is accessible to the end user but it won’t be included in page searches or navigation / tracer systems. This is used for purely dynamic pages that have no context without being passed dynamic parameters.
  5. Set the publish status to "Published"
  6. Save the page by click the Save button from the top contextual navigation.

Then to view your page, either click View from the top contextual navigation, or click the page from within your site on the left hand menu.

Creating the Admin tree

As explained above, our site will have an admin branch within which a CMS user would create and edit items. In this section we’re going to create a new page template for use in admin pages so if needed we can offer a different general look and feel to the public tree. We’ll then create a page called admin which will act as a launch pad / root page for our admin tree. Below this, we’ll have a page listing the news items with a link to the Create / Edit page beneath.

So our tree would look something like this:

Image:Admin_tree.jpg


  1. First, create a new page template in the same way as before, using the admin_page_template.jsp file supplied with the tutorial. Remember to prefix your content area ids if you’re using a shared instance.
  2. As with the public template, add a static code portlet for a header.
  3. Save and activate the template.
  4. Create a new root page with a path called "admin" by following the steps to create the home page above, but use the new admin template. Then create a sub page of the admin page by first selecting the admin page, then from the top navigation, hover over the "Actions..." menu and click "Create subpage". Give this page a path of "news" and complete the create page form as usual.
  5. For the creation of our create news page we need to make sure we set the page mode to Item Display. This allows the page to listen to an item id being passed in the URL allowing us to work with that item. In this case editing it. Give it a path of "create".


Creating a data store for News Articles

Before we can start creating news articles we need somewhere to store them, so now we’re going to create a data store to hold the news articles. To do this:

  1. Open the Content Module and from the left hand menu, click the Data Store link and from the top contextual navigation, click "Create New"
  2. This store is to be used to store news articles so give it a semantic name and description, set the primary language to English and click Save.

By default, all stores come with some common attributes. These are:

  • Name (mandatory)
  • Description (mandatory)
  • Keywords (optional)
  • Creation Date (system generated)
  • Last Modification Date (system generated)
  • Creator (system generated)
  • Last modifier (system generated)

For the moment, we’re only going to use the name and description fields and will add custom attributes later.


Adding the Content Edit Template

In the tutorial files folder, look for the CET folder and you will find the CET entitled "admin_news_edit.jsp" Open this, read the code, and complete the TODO sections. From within the Publishing Module, expand the Files menu and expand the Code Template menu and click on Content Edit Template. Click on Create and copy the content of the above jsp file, give appropriate values of name, description and tags and Click on Save.

===Creating the edit form

Now that we have a store to hold our news articles, we can create our edit form. To do this we’re going to use the Item - Edit using template Portlet.

  1. Open your news create page by clicking the page link from within your site, in the Publishing Module.
  2. Click the blue portlet bar and select the Image:Window_add.png(Add Below) link from the portlet mode menu.
  3. Expand the Content portlets menu and select Item - Edit using template. The system will display the edit mode for this portlet.
  4. As this portlet is going to be used for both creating and editing items select "Both!" from the Edit Mode section.
  5. For the content store dropdown, Select your news store.
  6. Select the Content edit template (CET) you have created in the previous section from the Content edit template dropdown and click Save.
  7. Go to the Redirect Settings Tab. When we create, edit or delete a news article, we want to return to the news listing page so in the three areas for redirecting, insert the path to the admin news page (don’t forget the leading /).
  8. Click Save to save the portlet configuration and view the page.

It should look something like the following:

Creating the Admin News listing

In this section, we’re going to create our news listing page that will display all the news articles, with an edit link to enable editing of the article. To do this we’re going to use the Advanced Search Results portlet which will take our news articles in XML format and combine them with XSL to produce our HTML. So from the news page:

  1. Click the blue portlet bar and click the Image:Window_add.png(Add Below) button, expand the Content portlets menu and select Item – Advanced Search Results.
  2. For the moment, the only configuration parameter we’ll change is the Search Mode. Set this to "List all items from a store" and select the news store you created earlier.
  3. Click save and then view to see the page. You'll see an error because we've not fully configured the portlet yet. We still need to add a global XML configuration and XSL, which we will do next.

Add the Global XML

A global XML configuration is used to define the data of a unify data or file item that you are interested in rendering on a page. It provides a granular way of selecting what metadata, content, versions, localisation etc etc should be brought back as XML. The main reason for doing this is so that we do not bring back more data than necessary because large sets of search results can potenitally bring back HUGE amounts of XML - most of which we don't need at that given time. So by allowing the developer to choose only what is necessary helps with server load and speeds up rendering times.

To create a global XML config, in the Publishing module expand 'Files' and click on 'Global XML configurations' and then 'Create'. Provide a suitable name (in this case "news list" will be fine), a description and tags (tags are just searchable keywords to help find it again at a later date). Now you have to build up the tree of data that you are interested in rendering. In the collection schema drop down, select your news store and then click on the green plus arrow above the drop down box. This will add the store to the GUI interface below. Click on 'show options' below the news store. This will display the options for which XML nodes you would like to bring back. Have a quick read through them to see all of the options that are available. For the time being, just select 'load content' and 'load metadata'. Click 'Save', and then click 'Deploy'.

Go back to your Advanced Search Results portlet and select your newly created global XML configuration. Click save.

As we haven’t created an XSL yet we'll still see an error on our page, but before we can create an XSL we need to know that the XML looks like. To see the XML output of the Advanced Search Results portlet, click the blue portlet bar, and select XML from the portlet menu. You’ll see that the XML output is printed to the screen. Select this and paste into your favourite XML editor.

This is part of the XML as displayed in FOXE

All Advanced Search Results XML will have similar XML structure. There is always a root node named search-results. It contains a size node defining the total size of results and other nodes giving meta information about the page. The rest of the nodes are defined by the global XML configuration that you set up earlier and will contain the nodes that you defined. The structure of the XML mimics the structure of your global XML configuration.

The area of the XML that you will be most interested in is below the node called 'items' which contains zero or many 'data-item' nodes representing the data items in the news store.

As shown, each data-item node has an attribute for the id, name, version and description. There are also many many other nodes, but for now these are the only ones we’ll be using within our XSL

Adding the XSL

  1. In the tutorial files folder, find the XSL entitled "admin_news_list.xsl" Open this, read the code, and complete the TODO sections.
  2. From within the Publishing Module, expand the Files menu and expand the XSL menu. As we use a lot of XSLs in system, they are already separated into different groups depending on their use. Select the "Item list" link which is the place to store search results XSL.


  3. From the top navigation, create a new folder by clicking Create XSL folder.
  4. Now, open your newly created folder and click Create to create an XSL. Give it a good name and description. Paste your completed admin_news_list.xsl and click Save. If you have any compilation errors, they will display in an orange alert box at the top of the page – fix those before continuing.
  5. Open the admin news page, open the advanced search results portlet, select your XSL and click save.


The page should look like the following:

Adding public news list

We’ve now created the Admin news listing with the ability to edit the items; but we also want to offer the same functionality on the public tree. Unify comes with a clipboard to allow copy and pasting of portlets. We’re going to use this to copy the news list advanced search results portlet to the public homepage.

  1. Select the advanced search results portlet on the admin news page, and click the Image:Copy.png(Copy) icon to copy the portlet to the clipboard.
  2. Open the homepage we created earlier and click the blue portlet bar, click the Image:Window_add.png (Add) button, expand the Clipboard menu and click paste to paste your portlet.


Creating the News Detail

We currently have links on the Public News List page that points to a detail page which we are yet to create. So now create a new page with a path of "detail" under the news listing (home) page. Don’t forget to set the Publish status to "Publish but hidden" and the Mode to "Item display".

When we want to display information about just one item we can actually use the Advanced search results porlet again! This is because we can select within the 'search mode' for it to retrieve the 'Detect incoming item' only instead of a whole set of items. It just takes the item id that we pass through via the URL so that it knows which item we are referring to.


To build the public news detail page:

  1. Add an Advanced Search Result portlet to the Detail page
  2. Select 'Detect incoming item' as the search mode
  3. Add a global XML config (We can actually use the same one we used on the news list pages because we are still interested in news items and we are still interested in it's content and metadata)
  4. Save the portlet settings
  5. Open the homepage and follow one of the links to view the news article. This should take you through to the detail page but as we haven’t selected an XSL to use we'll see an error
  6. As with the list pages we can now see the XML structure which should mirror the global XML config (Open the portlet and select XML, copy this and paste into your favourite XML editor).
  7. In the tutorial files folder, find the XSL entitled "public_news_detail_v1.xsl" Open this and complete the TODO sections. (You may notice that the creator node that's referenced in the XSL is not in your XML. Think about how you can change this and update as required so that this works).
  8. As you did with the list XSLs, save this XSL under the 'files' -> 'Item list' folder within the publishing module
  9. Open the detail page and edit the portlet so that your new XSL is selected.
  10. Test clicking the view link from a news article on the home page to see your news displayed in the detail page.

Creating Navigation

So far we haven’t provided any navigation for our users. The first thing we need to create is a way for our admin users to access the admin area. Using the same techniques as before, add a static code portlet to the footer area of the public page template. In the static code portlet, add the following code:

<p>
  <a href = "$context_path/admin">Site Administration</a>
</p>

You’ll notice the use of the dynamic variable $context_path. This prints either "vyre4" or "" depending if you’re in the back or front end, ensuring that URLs will work in either context. For more dynamic variables see the wiki page Velocity and XSL parameters. Also, we want our admin user to be able to navigate around the admin site. Unify offers the Navigation Portlet which will render page tree structures as XML. Then you can either write an XSL to style your XML or use the default XSL provided. Open the admin page template and on the left hand content area with id: "admin_tutorial_nav" add a Navigation portlet.

  1. Set the label type to "Do not use any label"
  2. Set the "Tree root page" to "Choose" and save the portlet. It should now display the site tree next to the "choose" radio button
  3. Expand the site tree and select the admin page (click Save at bottom for the site tree to be visible)
  4. Save and view the template to see the navigation.

To allow our admin user to navigate back to the main public site, as with the public page template, add a static code portlet to the footer of the admin site with a link to the public home page. Don’t forget to activate the template for the changes to be visible on the pages.

Deploying and viewing from the front end

Up until now, we’ve been viewing the pages through the back end - vyre4 interface. In this section, we’re going to deploy our pages and files so they are viewable in the front end.



After you deploy a page you will be redirected to the Thread Monitor. If you deploy a lot of pages, you’ll see items on the Page Deployment Queue which list all pages waiting to be deployed.

  1. To deploy a file, open the file and click Deploy from the top contextual navigation. If you’d rather deploy all files in particular folder there is the option to deploy all. Deploy all the XSL files you’ve created.
  2. To deploy the pages, select the page and from the top contextual navigation, hover over the Actions... menu and select deploy page. As with the files it’s possible to deploy more than one page by clicking "Deploy page and Subpages". You can also deploy all pages that inherit a particular template, by opening the page template and selecting Deploy pages form the top contextual navigation.
  3. Now that we’ve deployed we have a couple of thing to do before our site is ready to be viewed in the front end. Firstly, we need to set a start page. The start page is the page that the system serves up if the end user selects the root (/) page.

  4. Open the publishing module, select the Tutorial Site globe. In the top contextual navigation, hover over "Settings..." and click "Set Start page".
  5. Click the public home page you created earlier

View the site on the front end. You’ll notice that if you try to create or edit an item through the front end you’ll get a message complaining that "No user is logged in" as you have to be logged in to modify items. We’ll fix this in the next chapter "Introducing Users and Permissions"


Summary

Areas covered:

Personal tools