JavaDoc for PagesController

ccm-cms/src/main/java/org/librecms/pages/PagesController.java

@@ -33,6 +33,7 @@ import org.libreccm.theming.Themes;
 import org.libreccm.theming.mvc.ThemesMvc;
 import org.librecms.contentsection.ContentItemVersion;
 import org.librecms.pages.models.CategoryModel;
+import org.librecms.pages.models.ContentItemModel;
 import org.librecms.pages.models.SiteInfoModel;
 
 import java.net.URI;
@@ -61,6 +62,95 @@ import javax.ws.rs.core.Response;
 import javax.ws.rs.core.UriInfo;
 
 /**
+ * Controller for the pages MVC application responsible for initializing the
+ * models used by themes for displaying the pages.
+ *
+ * This controller is the main entry point for the Pages application, which is
+ * the primary entry point for most public sites powered by LibreCMS. Based on
+ * the provided path it looks up the matching category and initalizes the models
+ * used by the themes to create the public pages. The application is ,as most
+ * other frontends of LibreCCM/LibreCMS, based on the EE MVC framework.
+ *
+ * In the following description, <code>{placeholder}</code> stands for a
+ * placeholder for a parameter. The placeholder <code>{path}</code> stands for
+ * the requested path. The path might be empty, in this case the root category
+ * of the category system associated with the instance of the pages application
+ * is used.
+ *
+ * Depending on the provided path in the URL this controller does the following:
+ *
+ * <ul>
+ * <li>
+ * If the requested path does <b>not</b> end with <code>.html</code> or
+ * <code>.{lang}.html</code>: Determine the language to use, select the most
+ * appropriate language. Redirect the request the
+ * <code>/@pages/{path}/index.{lang}.de</code>, where lang is the most
+ * approbriate language determined (also called <i>negotiated</i> language).
+ * </li>
+ * <li>
+ * If the requested path ends matches <code>/@pages/{path}/index.html</code>
+ * (the exact regex pattern can be found in the documentation of the responsible
+ * methods) determine the most appropriate of the available languages and
+ * redirect the request <code>/@pages/{path}/index.{lang}.html</code>, where
+ * <code>{lang}</code> is the negotiated language.
+ * </li>
+ * <li>
+ * If the requested path ends matches
+ * <code>/@pages/{path}/{itemname}.html</code> (the exact regex patterns for
+ * <code>{path}</code> and <code>itemname</code> can be found in the
+ * documentation of the responsible methods) determine the most appropriate of
+ * the available languages and redirect the request to
+ * <code>/@pages/{path}/{itemname}.{lang}.html</code>, , where
+ * <code>{lang}</code> is the negotiated language.
+ * </li>
+ * <li>
+ * If the request path matches <code>/@pages/{path}/index.{lang}.html</code>
+ * display the index page of the category together with the index item of the
+ * category, if the category has an index item. If the category has an index
+ * item and the index item is not available in the language requested by the
+ * <code>{lang}</code> parameter in the path, raise a <code>404 Not Found</code>
+ * error using a {@link WebApplicationException}.
+ * </li>
+ * * <li>
+ * If the request path matches
+ * <code>/@pages/{path}/{itemname}.{lang}.html</code> display the item with the
+ * name provided in the <code>{itemname}</code> parameter. If no item with a
+ * matching name is assigned to the category raise a <code>404 Not Found</code>
+ * using a {@link WebApplicationException}. Also, if there is a matching item,
+ * but it is not available in the language requested by the <code>{lang}</code>
+ * parameter, raise a <code>404 Not Found Error</code> using a
+ * {@link WebApplicationException}.
+ * </li>
+ * </ul>
+ *
+ * In the last two cases this controller will initialize the basic models to
+ * provide soem data for displaying theme, and delegate to the theme by calling
+ * {@link ThemesMvc#getMvcTemplate(javax.ws.rs.core.UriInfo, java.lang.String, java.lang.String)}.
+ * {@link ThemesMvc} will determine the theme to use from the requested URL. For
+ * details please refer to the documentation of {@link ThemesMvc}.
+ *
+ * The following models are initialized by this controller:
+ * <ul>
+ * <li>{@link CategoryModel}</li>
+ * <li>{@link ContentItemModel}</li>
+ * <li>{@link SiteInfoModel}</li>
+ * </ul>
+ *
+ * The language to use is determined using the following algorithm:
+ * <ol type="1">
+ * <li>
+ * Check if one of the languages sent by the user agent in the
+ * <code>Accept-Language</code> header is a supported language (see
+ * {@link KernelConfig#supportedLanguages}. If not fall back to the default
+ * language (see {@link KernelConfig#defaultLanguage}.
+ * </li>
+ * <li>
+ * Check if the requested item is available in the selected language, or if a
+ * category without an index item is requested, if the category is avaiable for
+ * the selected language. If yes use the selected language otherwise fallback to
+ * the default default configured in {@link KernelConfig#defaultLanguage}.
+ * </li>
+ * </ol>
  *
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */
@@ -77,11 +167,14 @@ public class PagesController {
     @Inject
     private CategoryRepository categoryRepo;
 
+    @Inject
+    private GlobalizationHelper globalizationHelper;
+
     @Inject
     private ConfigurationManager confManager;
 
     @Inject
-    private GlobalizationHelper globalizationHelper;
+    private ContentItemModel contentItemModel;
 
     @Inject
     private PageManager pageManager;
@@ -114,7 +207,6 @@ public class PagesController {
     @Path("/")
     @Transactional(Transactional.TxType.REQUIRED)
     public Response redirectToIndexPage(@Context final UriInfo uriInfo) {
-
         final String domain = uriInfo.getBaseUri().getHost();
         final Pages pages = getPages(domain);
         final Category category = getCategory(domain, pages, "/");
@@ -130,8 +222,8 @@ public class PagesController {
     @Transactional(Transactional.TxType.REQUIRED)
     public Response getRootPage(
         @Context final UriInfo uriInfo,
-        @PathParam("name") final String itemName) {
-
+        @PathParam("name") final String itemName
+    ) {
         final String domain = uriInfo.getBaseUri().getHost();
         final Pages pages = getPages(domain);
         final Category category = getCategory(domain, pages, "/");
@@ -187,8 +279,11 @@ public class PagesController {
     ) {
         final Versions versions = generateFromPreviewParam(preview);
 
-        final Site site = getSite(uriInfo);
-        
+        globalizationHelper.setSelectedLocale(new Locale(language));
+
+        contentItemModel.setItemName(itemName);
+        contentItemModel.setItemVersion(versions.getContentItemVersion());
+
         return themesMvc.getMvcTemplate(uriInfo, "pages", "page");
     }
 
@@ -308,6 +403,8 @@ public class PagesController {
         final String preview
     ) {
         final Versions versions = generateFromPreviewParam(preview);
+        contentItemModel.setItemName(itemName);
+        contentItemModel.setItemVersion(versions.getContentItemVersion());
 
         final Site site = getSite(uriInfo);
         return themesMvc.getMvcTemplate(uriInfo, "pages", "page");
@@ -538,7 +635,7 @@ public class PagesController {
             this.themeVersion = themeVersion;
         }
 
-        public ContentItemVersion getContentVersion() {
+        public ContentItemVersion getContentItemVersion() {
             return contentVersion;
         }
 

ccm-cms/src/main/java/org/librecms/pages/models/ContentItemModel.java

@@ -93,6 +93,14 @@ public class ContentItemModel {
     public void setItemName(final String itemName) {
         this.itemName = itemName;
     }
+    
+    public ContentItemVersion getItemVersion() {
+        return itemVersion;
+    }
+    
+    public void setItemVersion(final ContentItemVersion itemVersion) {
+        this.itemVersion = itemVersion;
+    }
 
     /**
      * Retrieves the current content item. Depending if {@link #itemName} has
@@ -252,7 +260,7 @@ public class ContentItemModel {
                     builder.equal(from.get("displayName"), itemName),
                     builder.equal(
                         from.get("version"),
-                        ContentItemVersion.DRAFT
+                        itemVersion
                     ),
                     builder.equal(join.get("category"), category)
                 )));