4 User Guide

4.1 Administrative UI

You can do this by browsing to <yourserver-url>/admin if you are using the standalone Weceem WAR. Here you will be prompted for your user name and password. By default new installations have a single "admin" account with password "admin". You must change this password, and you can do so in the Administration section. Logging in to your own application that uses Weceem plugin

Normally this will be a case of browsing to <yourserver-url>/admin but your application may have configured weceem to use a different URL mappings such as /wcm/admin. You need to look at your application's configuration if /admin does not work for you.

Weceem contains administrative UI for users that have access to creating new content and managing existed sources. In your weceem.properties file or in Config.groovy file the user can customize URL that leads to admin UI. By default the mapping "wcm/admin" will be used.

Admin UI consists of two tabs: "Content" and "Administration".

Content tab

The content repository is the main user interface for Weceem.

What you see in the repository is the tree of content for the currently selected space. You can switch spaces using the space selector box.

Each row in the table represents one of your content nodes. You can do the following things with rows:

• To select a node, you click its row (but not the icon).
• To drag a node to a new location in the tree, you drag the content's icon
• To edit the content you click the title of the content

With a row selected, it will be highlighted and when you click the "New Content" or "More Actions" button the operation will be performed on the selected node. So when a node is selected and you choose "New Content", the new content will be a child of the node you selected in the repository.

To deselect a row - so that you can create new content at the root of the repository - you just click the row again.

You can also search for content using the search box. The results can be further filtered by content type and date, and sorted by clicking the column headers.

Administration tab

The tab contains several editors:

• Spaces
• Synchronize files
• Plugins management
• Licenses
• Check links
• Users

4.2 Create Space

About spaces

A Space contains "Content" that is served to your visitors. There are many different types of Content that you can create and arrange in any structure you like within your Space. You can have as many spaces as you like, representing different sites or micro sites.

Spaces are separate content graphs and are imported and exported separately for backup purposes and have a URI alias that defines the web address of that space within your server. You cannot normally use content from one space inside another.

Spaces can have different access rights defined in the Weceem security policy, so the same user may have different permissions in different spaces.

Each Space is determined by its name and alias URI, where alias URI is a prefix for your site (Space), that will be used in URL mappings when you try to review the ready site content.

4.3 File Synchronization

You will be given the option to delete any content nodes that refer to server files or directories that no longer exist.

4.4 Plugins

4.5 Licenses

4.6 Check Links

4.7 CMS User management

When using the Weceem Application, a simple user management system is provided.

To access this, log in as administrator and go to the Administration section and then select Users. From there you can create and edit users.

4.8 Create HTML pages

Content is ultimately what your end-users view on your site. Weceem has an extensible content system, and supplied content types for the most common web content.

The following content types are supplied out of the box:

• Action - A server-side action that will execute the code in a Groovy Script node, for example to create new content

nodes or send an email

• Blog - The root node of a Blog, which has Blog Entry nodes as children
• Blog Entry - An entry (child of) a Blog node
• Comment - A comment on a content node. Any nodes can have comments attached or created.
• External Link - A URL of another website. When this URI is rendered, it redirects to the external site
• Folder - A folder for grouping together content nodes and creating URI hierarchy
• Groovy Script - A piece of Groovy code to execute on the server, used by Action nodes
• HTML - A piece of HTML which may contain GSP (Grails Server Page) tags
• JavaScript - A piece of JavaScript source
• Server File - A file uploaded to the Weceem repository and stored on the server filesystem, e.g. an image file
• Server Directory - A directory on the server filesystem which contains Server File nodes
• Stylesheet - A CSS style sheet
• Template - A GSP template used to layout and decorate the current content node
• Widget - A reusable GSP fragment for rendering sections of a page, e.g. a header/footer or a remote news feed.

The Template, Widget and HTML content nodes can use Weceem tags and other Grails tags to perform view rendering logic. Weceem's content is stored in an SQL database, not in files on the server filesystem. The exception to this rule is uploaded file content, which is stored "as is" in the server filesystem, with information about the files stored in the SQL database.

When editing content, you are shown only the fields appropriate to that type of content. For example when editing JavaScript or CSS you see a code editor, but when editing HTML content you see a rich text editor.

Developers writing their own Grails application that embeds Weceem can easily add their own new content types that have a great deal of flexibility allowing them to customize their behaviour in the editor and when rendered.

When creating new content the currently selected repository node will become the parent. You will be asked what kind of content you wish to create, and then be shown the content editor for that content type.

Different content types have different fields and capabilities, and the editor adapts accordingly. Most content types will have at least a Title and Status, an area for the main content, and the Extras, Metadata, Change history and Parents & Children sections.

In the editor you can Save and return to the repository or save and continue to keep your changes but carry on editing. You can also Preview your changes in a new window without saving them, if the content is able to be rendered in isolation (e.g. Templates and Widgets cannot themselves be previewed).

The HTML editor will present itself as a rich text editor unless you have saved it with "Allow GSP", in which case it will show as a code editor. Style sheets, Javascript, Templates, Widgets and Groovy code all present with a syntax highlighting code editor.

Create HTML page

If the user needs to create HTML page, he needs to select row in the content repository tree by clicking on it. As the result the row is preselected by color. The row selection means that the content will be child to selected content. Then at the top of Content tab there is a button New Content that offers a list of available content types to be created. Select the type "HTML" and press "Create" button. The new content editor should be shown to the user

4.9 Create Blog, Blog Entries and Comments

• Create a Blog content node
• Create a Blog Entry content node underneath (as a child of) the blog node

If you are using the default styling, when you create the Blog you can set the Template to the default blog template supplied.

Blogs in Weceem are just like any other content, and by gluing together a Template, some Widgets and some Weceem GSP ags, you get full blog functionality (caveat: pinging blog aggregators is not yet supported). See the examples in the default space template for further details.

To enable comments on your blog you must edit your Weceem security policy file and allow unauthenticated users to create content of type org.weceem.content.WcmComment. Make sure that you do this for only that type, or malicious users may be able to create non-Comment content on your site!

The default space template for blogs uses widgets to render a single blog entry view, or a list of the most recent posts, and widgets to render the comment form and list of current comments.

The generic content submission mechanism of Weceem is used to submit comments by users, and the comment widget uses the Weceem content submission tags to set this up.

The Weceem archive tags are used to render the months for which there exist child nodes of type "Comment", with links to view those. Finally, the widgets render the list of tags assigned to the blog entry, with links to search for other blog entries based on those tags.

For preparing new blog, the user needs to select row in the content repository tree by clicking on it. As the result the row is preselected by color. The row selection means that the content will be child to selected content. Then at the top of Content tab there is a button New Content that offers a list of available content types to be created. Select the type "Blog" and press "Create" button. The new blog editor should be shown to the user

If the Blog is created, then it is possible to create Blog Entries. The user should select "Blog row" as a parent and press New Content button to select Blog entry content type. The editor contains CKEditor for entering content.

Also it is possible to create or manage existed Comments. If you put a submission form for your Blog Entry page then the users will push comments to your through your site. Also you can create new Comment from "Content" tab by pressing button "New Content" and selecting Comment content type.

Visitor comments and submitted content

Sites often permit visitors to leave comments - be they blog comments, visitor books or comments on Wiki pages.

Weceem supports a generic mechanism for visitors to create new content nodes via a form, filtered through the security policy.

This is, for example, how the default space implements comments on blogs. A widget is used to render a form to capture the comment fields and submit them to Weceem's content submission controller - where they are, if the security policy permits that kind of content at that URI, from that (anonymous) user - saved in an "unmoderated" status. Creating a comment submission form

To allow users to submit content, you need to provide the data from the client browser - usually with a form that the user completes. You will usually do this inside a Widget node so that the code can be reused:

<wcm:submitContentForm parent="${parentContent}" type="org.weceem.content.WcmComment" success="${parentContent}">
  <f:field bean="submittedContent"  property="author"/>
  <f:field bean="submittedContent" property="email"/>
  <f:field bean="submittedContent" property="websiteUrl" label="Website URL"/>
  <f:field bean="submittedContent" property="title"/>
  <f:field bean="submittedContent"  property="content">
    <textarea name="content" cols="20" rows="5"></textarea>
  </f:field>
  <input type="submit" class="button positive" value="Send comment"/>
</wcm:submitContentForm>

Here, three different Grails taglibs are being used to create the form:

• g:hasErrors is a Grails tag used to detect any errors on the submittedContent data and alerts the user if so
• wcm:submitContentForm creates a form that will submit content of a specific type, as set in the "type" attribute.

The "parent" attribute must be set to the node that will be the parent of the new content (or null for root content), and the "success" attribute is the repository URI path or node that should be shown after the content has been submitted - e.g. the original Blog Entry

• f:field tags are from the Grails fields* plugin that is provided as part of Weceem. They make it easy to render

sensible default fields for properties of an object. In this case the object is the "submittedContent" bean used by the content submission form.

The form will include a link to the content submission controller. This controller will save the content if it is valid, or return to the existing content with the "submittedContent" object populated with the previous data and any errors attached. Using the field:* tags of the Grails Fields plugin is merely a convenience, but is very useful as it will display the validation errors associated with each field inline in the form.

If the submission succeeds - which requires the user to have permission to create that type of content under the specified parent in the repository - it will redirect the user to the content specified in the "success" attribute.

The content will be in the "unmoderated" status, until an administrator updates the status to Published.

4.10 Server Directory and Server File

Firstly create Server Directory - the folder on the file system will be created, then put your uploaded files as Server Files to this directory.

4.11 Templates and Widgets

Also it is possible to create widgets, by selecting content type "Widget" to prepare widgets for templates. Usually template is consists from widgets as from blocks. It helps template to be more flexible and customizable.

4.12 Create Action

4.13 Create Binary Content

4.14 Create CSS Stylesheets and Javascript Sources

You can upload JS and CSS files to "Server File" content nodes, or you create JavaScript and Stylesheet nodes and edit the files directly in Weceem.

Whichever approach you choose, you include these files in your Template or Widget nodes something like this:

<html>
<head>
<link rel="stylesheet" href="${wcm.createLink(path:'css/main.css')}"/>
<script type="text/javascript" src="${wcm.createLink(path:'js/main.js')}"></script>
</head>
…
</html>

Here we just use the wcm.createLink tag to get the URL to the content nodes. Whether you used Server File or Stylesheet/JavaScript nodes for these files, this will produce the correct URL if the "path" value points to the correct nodes. Note that the Alias URI of the nodes should include the file extension although it does not have to. Some older browsers may require the file extension for correctly identifying the content type.

You can of course place these files anywhere in your repository as long as you use the correct content path URI.

Note that if your CSS files need to reference external resources like images, you will need to make sure the links make sense in relation to the content repository. Relative links will work for Server File nodes, which must be under a Server Directory node. However a Server Directory node cannot have StyleSheet or JavaScript child nodes, so usually if you need to link to relative images from a stylesheet, you will need to upload it as a Server File instead of a StyleSheet node. That is, unless you have a Server Directory node that is a sibling to the StyleSheet node, and you place your images under there.

At the top of Content tab there is a button New Content that offers a list of available content types to be created. Select the type "CSS Stylesheets" or "JavaScript Sources" and press "Create" button. The simple content editor should be shown to the user.

4.15 Create External Link

4.16 Create Groovy Script

4.17 Create Folder

4.18 Create Wiki page

4.19 Create Virtual Content

4.20 Statuses, Publishing and Unpublishing by date

The following Statuses are provided:

• Draft
• Unmoderated
• Reviewed
• Approved
• Published
• Archived

Each status has a numerical code - e.g. Draft is 100, Unmoderated - 150, Published - 400 etc. Each status has a flag to indicate whether or not it is "public" content i.e. can be viewed by non-administrators. By default Published is the only status with this flag set.

All changes to status are made manually by repository users, unless the Publish From or Publish Until fields have values.

In the case of Publish From, once the date passes, the status of the content will change to the first status with "public content" flag switched on, which has a higher code number than the current status of the content. This offers scope for other statuses beyond the existing set, and migration upward through those states.

The one caveat here is that the Publish From mechanism will never change the status on content that is currently in the "Unmoderated" or "Archived" status used for visitor-submitted or expired content. If you need to change which status is used for "Unmoderated" or "Archived" content you can do this by setting the configuration variables to the numerical code values of the desired status weceem.unmoderated.status and weceem.archived.status

With Publish Until, the status of any published content that has expired will be set to the "Archived" status or the status defined in the configuration variable weceem.archived.status.

4.21 Search in Weceem

All of your content is automatically indexed as appropriate, all you need to do is add a way for them to start a search, and customise the display of the search results.

To add a default search field, you can use the wcm:search tag:

<wcm:search types="org.weceem.html.WcmHTMLContent,
     org.weceem.blog.WcmBlogEntry,org.weceem.content.WcmComment"/>

This single tag creates the search field and button, which you can style with standard CSS. The "types" attribute is used to limit the types of content that can be returned by the search. You usually don't want your Widgets, CSS or JavaScript code coming back in search results! This also means you can have different searches on your side, for different kinds of content, including custom content types. For example you may have a custom ProductInformation content type and want to add a product-only search feature for users.

Other attributes of this tag allow you to control the parent URI to use as the context for the search, and the content path for the results path which will render the search results. For full details see the wcm:search tag page.

You can also create a completely customized search form and use wcm:searchLink to create the appropriate link to invoke the search for the types and other attributes you specify.

4.22 Operations with content repository tree

• Preview selected content
• Delete content
• Move to Space
• Duplicate...

Preview selected opens a new page/tab with the content previewing. Not all types of a content can be previewed, for example Templates and Widgets cannot be previewed as standalone pages. If the user tries to get preview for them the special message (or error page - depends on configuration settings) will be displayed.

Delete content gives the user possibility to delete selected content. If the content contains children, the error message will be displayed and content won't be deleted.

Move to Space operation should move content from one Space to another one, but currently not implemented yet.

Duplicate should copy the selected content to the other holder, parent content or even in another Space, but currently not implemented yet.

Also there are several operations that can be done on content repository tree, f.e. the user can drag a content and drop it as a child to another content. It is possible such way to move or copy the content to the another location.

4.23 Tags and JSP content

To users of JSP (Java Server Pages) this will be a familiar concept.

These custom tags or "GSP tags" as they are called, use the XML namespacing syntax:

Search:

<wcm:search/>

The "wcm:" prefix is the Weceem tag namespace. This tells you it is a Weceem-specific tag you are using. Grails provides its own "g:" namespace for basic built-in functions like link creation, iteration over items in a list and so on.

Attributes can be passed to these tags as you would with HTML, with the addition of a Groovy-based "Expression Language" (EL) that lets you pass around variables that are available to the page or execute small pieces of code to perform calculations. These are put inside a dollar and brace syntax "${...}":

<g:each in="${node.lineage}">
${node.title.encodeAsHTML()}<br/>
</g:each>

The above would iterate over every item in the "lineage" property of the "node" object. The "node" object represents the current content node being rendered. See the reference section on page variables for more details of the available objects.

You will see here also that the EL can be used outside of tag attributes, to render information into the page output. As a side-note, the encodeAsHTML() method called in that example escapes the resulting title text so that it is safe for inclusion in HTML output (it escapes special characters to HTML entities). This encodeAs functionality is provided by Grails.

Using these features you can code your Template and Widget nodes to perform all kinds of powerful functions, from listing child nodes of the current page, to generating RSS feeds. See the Weceem tag reference for full details.

4.24 Reusing code and page fragments with Widgets

Widgets can use the same GSP tags as Templates, which makes them very powerful. The News content on the home page of this site is a Widget, and the default space renders blog entries using Widgets.

To render widgets inside a Template (or GSP-enabled HTML content node) you use the <wcm:widget> tag:

<html>
  <head>
    <wcm:widget path="widgets/resources"/>
    <wcm:widget path="widgets/metatags"/>
  </head>
  <body>
    <wcm:widget path="widgets/header"/>
    <wcm:content/>
    <wcm:widget path="widgets/footer"/>
  </body>
</html>

The above could be used as a generic template for content, pulling in your standard SEO meta tags from a "metatags" widget, and JS and CSS resources from a widget called "resources".

The "resources" widget might look something like this:

<link rel="stylesheet" type="text/css" href="${wcm.createLink(path:'css/main.css')}"/>
<script type="application/javascript" src="${wcm.createLink(path:'js/jquery.js')}"/>

This uses the <wcm:createLink> tag to get the full URI to the resources within the current space.

4.25 Using images in HTML content

This will allow you to:

• upload a new image
• use one that has been uploaded already
• insert a URL to an image on the web

When using the option to upload or browse the images on the server, the files will be located in the "/Image" folder on your server (<weceem-application-path>/WeceemFiles/<space-alias>/Image).

If you have uploaded files as Server File nodes, if you did not put them inside the /Image folder then they will not be visible to the FCK file editor browser, but you can still link to them by entering in their full or relative URI.

4.26 Uploading and linking to files

Creating Server File nodes

When you create a Server File node in the repository, it will be uploaded from the Weceem editor into the server directory allocated to the space, at a path defined by the Alias URIs of its ancestor Server Directory nodes.

Once the file has been uploaded it cannot be changed - the node can be deleted and the file will also be deleted.

You link to server file nodes in the same way as you do any other content, using the wcm.createLink or wcm.link tags.

Uploading while editing HTML content

You can also upload files - most likely images - using the file uploader in the rich HTML editor when editing a HTML content node. It is important to note that all such files are uploaded to a /Image folder under your space's server folder. Server File nodes will not automatically be created for these, and they are not needed - unless you use the "Synchronize Files" option in the Administration section of Weceem.

4.27 Controlling who can see content and when

Automatic publishing and removal of content

Every type of content has a Status, a Publish From and a Publish Until field. Together these work to provide a simple automatic publishing workflow.

Writing content for automatic publishing later

To write content today but have it available to view only at some point in the future you just do the following:

• Set the status of the content to Draft, Approved or some other non-"published" status (apart from Archived!)
• Set a value in the Publish From field in the "Extras" section of the editor

Once saved, Weceem will automatically publish your content when the time has passed (within a minute or so of the time) by moving it into the Published status.

Writing content that disappears after a certain date and time

To perform the opposite - automatic removal of public content - you simply set the Publish Until date and time on your content. When this time has passed, the content will be put into the "Archived" status which is not visible to the public. You will still be able to view the content in the repository.

Restricting access by user

To limit the content that different users can view, you need to edit your Weceem security policy file.

All that is required is that you grant the "view" permission only on the URIs and content types that you wish the user role to be able to see.

4.28 Creating sites with content in different languages

It is often the case that not only does the text differ in other languages, but images, CSS and other resources may have differ, and in fact due to different territory restrictions you may have very different content for each language.

With this in mind, the recommended way to achieve this in Weceem is to create a Folder node for each language you support, and add the translated content under those folder nodes. For content that is the same as the primary language, you could create Virtual Content nodes to "defer" to the original primary content.

To give your users access to this content, you simply add some links or a selection box to your page templates - so they click on the language they want and it takes them to the content for that language.

4.29 Site performance and caching content

So as with regular websites it makes sense to use standard browser caching features to reduce the number of requests for content and supporting HTTP mechanisms for detecting changes to content.

Weceem supports both of these aims by implementing smart ETag handling as well as allowing you to tell the browser how long to keep the content for before checking for new versions using ETag. With ETags, the browser still makes a request to the server to check for changes, but if there has been no change, receives no new content.

This is done by calculating ETags for all URIs in your repository, based on the contents of other nodes on which those depend. For example even a simple home page is dependent on at least a Template node and likely at least a couple of widgets. This information is cached by Weceem, so checking for new content is very quick.

However this means that the ETag for your home page must change if the Template or widgets have been edited - otherwise users will continue to see your old home page styling for some time.

Weceem handles this by allowing you specify the URIs of content that a node is dependent on, a "maximum age" and also whether content contains user-specific information (which means that a different ETag is used per user).

Content Dependencies

When editing content, there is a "Content dependencies" field in the Advanced settings. This is where you enter a comma-delimited list of URIs on which the content node depends. By dependency we mean that this content's visual representation may change if any of these nodes are changed.

Wild cards of the form / are supported, to represent any dependents.

There is however no need to specify dependency on the content Template, because this is handled automatically for you.

For example a Template used for your entire site may render widgets for header and footer. If you want all content that uses this template to become invalidated if the header or footer change, you would set the content dependencies to e.g:

widget/header, widget/footer

If you had a dependency on a lot of widgets, you could simplify this with the wildcard:

widget/

Another example is a News widget that uses wcm:eachChild to iterate over the news article nodes at URI "news-articles". Here you'd set the content dependencies of the widget to:

news-articles/

This way, any template that depends on this news widget, will also depend on the news articles, and hence everything invalidates as appropriate.

NOTE: some content types are smart and add some implicit dependencies. For example Blog automatically depends on its BlogEntry children. This is required because a Blog page normally lists its child nodes, and needs to update if new entries are added.

Controlling how long a browser may keep a cached page

Aside from the dependencies, you can tell the browser how long to wait before checking for new content. For example if you know that usually you don't post more than one news article per day, and that even if you did you didn't mind someone not seeing the very latest, you can tell Weceem this.

Each content node has a setting labelled "Is updated" in Advanced. Here you can select how often the node is likely to be updated. If you never want it to be cached you can set this to "All the time". If you know that the content is unlikely to change you can set it to something like "Weekly" or "Never"

Doing this reduces the requests made to your server - saving you CPU time and bandwidth, and improving the response time of your site for users.

Note that if a user uses the "refresh" button in their browser, they will always get the newest content.

User-specific content

In some cases you may use Weceem's advanced scripting and widget features to present user-specific information. This typically uses the HTTP session to store user information, such as the contents of a shopping cart, or their user ID.

By ticking the "User specific content" option (available on Template nodes only in 1.0), you can instruct Weceem to allow the client to use cached content but still update if that user's rendering of the content will have changed.

When checked, this option forces Weceem to create a user-specific ETag for the content using that template. This is done by monitoring the HTTP session for changes. Any changes to the HTTP session result in a new ETag for pages using that template.

If you have other data changes that should invalidate the user's view of the content, but don't directly change the session, you can force this simply by writing to the session.

For example if you have a Widget that renders a log in / log out button depending on whether the user has a cookie or not (perhaps for a separate app on the same domain) you simply make that widget set a variable in the session if the cookie value is no longer present:

<g:set var="hasCookie" value="${request.cookies.find { it.name == 'userInfo' }?.value}"/>
<%-- only if the presence of cookie has changed to we change the session --%>
<g:if test="${session.userLoggedIn != hasCookie}">
   <g:set var="userLoggedIn" scope="session" value="${hasCookie}"/>
</g:if>
<%-- render the links --%>
<g:if test="${hasCookie}">
  <wcm:link path="user/logout">Log out</a>
</g:if>
<g:else>
  <wcm:link path="user/login">Log in</a>
</g:else>

4.30 Publishing Feeds

This tag will create the correct <meta> tag in the HEAD section of your HTML so that any RSS readers that request the feed will get a list of nodes in reverse date order:

<head>
<wcm:feedLink type="rss" path="${node}"/>
</head>

This would add a feed for the children of the current page. For full details see Tags section.