Platform Explorer / Nuxeo Platform LTS 2015 7.10

Component org.nuxeo.ecm.application.definition.service

Implementation

Javadoc: org.nuxeo.ecm.mobile.ApplicationRedirectServiceImpl

Services

Extension points

Contributions

XML source

<component name="org.nuxeo.ecm.application.definition.service">

  <documentation>
    The application definition is used to describe a new
    application into the Nuxeo platform.
    It is more a new type of
    navigation than a new application, but we consider that each
    contribution will expose a new ergonomy and new usage - so new
    "application". Typical usage can
    when you create a dedicate webengine
    application for mobile. We may want to keep the user into
    this
    webengine application and redirect to this application even the user
    click on a JSF link.

    The service provide also a possibility to
    contribute a JSP page to select a type of navigation
    from all
    declared or just a selection.

    For instance if you have a mobile
    application and - before user connected to the application -
    you want
    to let him choose to use the default UI (JSF) or the dedicated
    mobile UI.

    @author Benjamin JALON
  </documentation>

  <implementation class="org.nuxeo.ecm.mobile.ApplicationRedirectServiceImpl" />

  <service>
    <provide interface="org.nuxeo.ecm.mobile.ApplicationDefinitionService" />
  </service>

  <extension-point name="applicationDefinition">
    <documentation>
      In this extension you will contribute a new application entry that
      will be caracterized by a name, a baseURL of the application, a relative
      path to a dedicate login page and logout page, a request handler to select the type
      of request that must be redirect to this application and a order.

      Let see that:

      <code>
        <application name="app1" order="10" disable="false">
          <applicationRelativePath>site/app1</applicationRelativePath>
          <loginPage>/auth/login</loginPage>
          <logoutPage>/auth/logout</logoutPage>
          <requestHandlerName>MyRequestHandler</requestHandlerName>
        </application>
      </code>

      Here we define a new application named "app1". We define the base
      url of the application.
      So the full URL to reach it will be:
      <code>
        server/${NuxeoContextPath}/site/app1.
      </code>
      This seems to be, here, a webengine application. And logout page
      will be reachable here:
      <code>
        server/${NuxeoContextPath}/site/app1/auth/login
      </code>
      We have the same things with the logout page. The last but not
      least, the RequestHandler will be the object called to check
      if the request is a candidate to be redirected to the application.
      This handler must implements the org.nuxeo.ecm.mobile.handler.RequestHandler
      interface.

      You just have to implement, in fact this following method:
      <code>
        /**
        * return true if the request is a candidate for the Application
        described into
        * the {@code ApplicationDescriptor}.
        */
        public boolean isRequestRedirectedToApplication(
        HttpServletRequest request);
      </code>

      If this method return true for a given request, the browser will be redirected to
      the baseURL of the application with the initial uri into the
      ApplicationConstant#TARGET_URL_PARAMETER parameter into the redirected URL.

      You can for instance return true each time you detect that browser user
      agent is a mobile browser (you have the MobileRequestHandler implementing that),
      Like that all mobile browser will be redirected to app1.

      For instance if you call
      http://server/nuxeo/nxdoc/default/1239134098234023@view_documents
      is
      called and the handler return true, you be redirected to:

      <code>
        http://server/nuxeo/site/app1?targetURL=%2Fnuxeo%2Fnxdoc%2Fdefault%2F1239134098234023%40view_documents
      </code>

      For the login and logout page, becareful to unprotect resources
      you are using to generate the page.
      The login page must post to the "${baseURL}/nxstartup.faces"", 
      login module will do the authentication stuff and will redirect 
      to the initial url request for you. baseURL is by default /nuxeo, 
      in the webengine context you can use a relative path (becareful of reverse proxy)
      I mean if you use jquery library from here:
      <code>
        http://server/nuxeo/scripts/jquery.js
      </code>
      As you will be redirected to app1 this will not work. So if you do
      that think to contribute to the
      PluggableAuthenticationService to declare your open URL for your external resources, this service
      will also skip the redirect.

      Order of the application will let you organize the call order of handlers by the service.

      Last thing, becareful to have an efficient handler, as this code can be
      called many times. If you have handler that called a webservice, that is long, etc. This
      is a bad idea.

      About the login page you just have to create into the target url
      describe into your contribution a form that post user_name and user_password value to the same page.
      Authenticator of the service will do the authentication and will after redirect to the target URL.

      You can optionally aslo describe the base URL of resources of your application like that:
      <code>
        <application name="app1" order="10" disable="false">
          <applicationRelativePath>site/app1</applicationRelativePath>
          <loginPage>/auth/login</loginPage>
          <logoutPage>/auth/logout</logoutPage>
          <requestHandlerName>myHandler</requestHandlerName>
          <resources>
            <resourcesBaseURL>/site/skin/app1</resourcesBaseURL>
            <resourcesBaseURL>/nuxeo/resources</resourcesBaseURL>
          </resources>
        </application>
      </code>
      Like that request to resources of your application will not be redirected to the base url.
      If your resources are under the base url of your application, this parameter is not needed.


      You have already different RequestHandler implemented (Mobile and Anonymous handler)

    </documentation>
    <object class="org.nuxeo.ecm.mobile.ApplicationDefinitionDescriptor" />
  </extension-point>

  <extension-point name="requestHandlers">
    <documentation>
      In this extension point you will contribute the definition of your handler that implements
      the logic of redirection to your application. Interface to implement for this requestHandler
      is just for a given request do Nuxeo will redirect the user to the given application.

      <code>
        <requestHandler name="MobileWithCookieRequestHandler"
          disable="false">
          <implementation>org.nuxeo.ecm.mobile.handler.MobileWithCookieRequestHandler</implementation>
          <properties>
            <property name="skippedURLPattern">(.*)/nxfile/(.*)|(.*)/nxbigfile/(.*)</property>
          </properties>
        </requestHandler>
      </code>
      And so you will have to implement the interface given by org.nuxeo.ecm.mobile.handler.RequestHandler.
      Means just to implement this following methods:
      <code>
         public RequestHandler init(Map&lt;String, String&gt; properties);

         public boolean isRequestRedirectedToApplication(HttpServletRequest request);

         public boolean isRequestRedirectedToApplicationLoginForm(HttpServletRequest request);
      </code>
    </documentation>

    <object class="org.nuxeo.ecm.mobile.RequestHandlerDescriptor" />
  </extension-point>
</component>

Documentation

The application definition is used to describe a new application into the Nuxeo platform. It is more a new type of navigation than a new application, but we consider that each contribution will expose a new ergonomy and new usage - so new "application". Typical usage can when you create a dedicate webengine application for mobile. We may want to keep the user into this webengine application and redirect to this application even the user click on a JSF link.

The service provide also a possibility to contribute a JSP page to select a type of navigation from all declared or just a selection.

For instance if you have a mobile application and - before user connected to the application - you want to let him choose to use the default UI (JSF) or the dedicated mobile UI.