001package org.nuxeo.ecm.webengine.samples;
003import javax.ws.rs.GET;
004import javax.ws.rs.Path;
005import javax.ws.rs.Produces;
007import org.nuxeo.ecm.webengine.model.WebObject;
010 * <h1>Web Module Extensibility.</h1> This sample is demonstrating how existing web modules can be extended. To extend
011 * another module you should use the {@code base=BaseModule} in the {@code NuxeoWebModule} directive in
012 * {@code MANIFEST.MF} file. This way the new module will inherit all templates and resources defined in the base
013 * module. You can thus create a chain of inherited web modules.
014 * <p>
015 * Here is how template resolution will be impacted by the module inheritance: <br>
016 * <i>If a template T is not found in skin directory of derived module then search the template inside the base module
017 * and so on until a template is found or no more base module exists.</i> The view resolution is similar to the template
018 * one but it will use the {@code WebObject} inheritance too: <br>
019 * <i></i> <br>
020 * <b>Note</b> that only the <i>skin</i> directory is stacked over the one in the base module. The other directories in
021 * the module are not inheritable.
022 * <p>
023 * Also, resource types defined by the base module will become visible in the derived one.
024 * <p>
025 * In this example you will also find a very useful feature of WebEngine: the builtin <b>view service adapter</b>. This
026 * adapter can be used on any web object to locate any view declared on that object. Let's say we define a view named
027 * <i>info</i> for the <i>Document</i> WebObject type. And the following request path will point to a Document
028 * WebObject: {@code /my/doc}. Then to display the <i>info</i> view we can use the builtin views adapter this way:
029 * {@code /my/doc/@views/info}.
030 * <p>
031 * Obviously, you can redefine the WebObject corresponding to your document type and add a new method that will dispatch
032 * the view <info>info</info> using a pretty path like {@code /my/doc/info}. But this involves changing code. If you
033 * don't want this then the views adapter will be your friend.
034 * <p>
035 * <p>
036 * This example will extend the resource defined in sample4 and will reuse and add more templates. Look into template
037 * files to see how base module templates are reused.
038 * <h1>Managing links.</h1>
039 * <p>
040 * Almost any template page will contain links to other pages in your application. These links are usually absolute
041 * paths to other WebObjects or WebAdapters (including parameters if any). Maintaining these links when application
042 * object changes is painful when you are using modular applications (that may contribute new views or templates).
043 * <p>
044 * WebEngine is providing a flexible way to ease link management. First, you should define all of your links in
045 * <i>module.xml</i> configuration file. A Link is described by a target URL, an enablement condition, and one or more
046 * categories that can be used to organize links.
047 * <ul>
048 * Here are the possible conditions that you can use on links:
049 * <li>type - represent the target Web Object type. If present the link will be enabled only in the context of such an
050 * object.
051 * <li>adapter - represent the target Web Adapter name. If present the link will be enabled only if the active adapter
052 * is the same as this one.
053 * <li>facet - a set of facets that the target web object must have in order to enable the link.
054 * <li>guard - a guard to be tested in order to enable the link. This is using the guard mechanism of WebEngine.
055 * </ul>
056 * If several conditions are specified an {@code AND} will be used between them.
057 * <p>
058 * Apart conditions you can <i>group</i> links in categories. Using categories and conditions you can quickly find in a
059 * template which are all enabled links that are part of a category. This way, you can control which links are written
060 * in the template without needing to do conditional code to check the context if links are enabled.
061 * <p>
062 * Conditions and categories manage thus where and when your links are displayed in a page. Apart this you also want to
063 * have a target URL for each link.
064 * <ul>
065 * You have two choices in specifying such a target URL:
066 * <li>define a custom link handler using the {@code handler</handler> link attribute.} The handler will be invoked each
067 * time the link code need to be written in the output stream so that it can programatically generate the link code.
068 * <li>use the builtin link handler. The builtin link handler will append the {@code path} attribute you specified in
069 * link definition to the current WebObject path on the request. This behavior is good enough for most of the use cases.
070 * <li>
071 * </ul>
072 * <p>
073 * <p>
074 * This example will demonstrate how links work. Look into {@code module.xml} for link definitions and then in
075 * {@code skin/views/Document/index.ftl} on how they are used in the template.
076 *
077 * @author <a href="mailto:bs@nuxeo.com">Bogdan Stefanescu</a>
078 */
079@WebObject(type = "Repository")
081public class ExtendedDocumentsObject extends DocumentsObject {
082    /**
083     * We are reusing bindings declared in the main class from sample5 and only add a new one.
084     */
085    @Path("info")
086    @GET
087    public Object getInfo() {
088        return "This is the 'info' segment added by the derived module";
089    }