Navigation override mechanism questions

[buzman]

Hi,
  I was wondering if someone would be able to explain the new navigation override mechanism to me. I've tried to deduce how to use it, but my overrides are not taking effect.

Given the a jsf navigation config of this :

<navigation-rule>
      <from-view-id>/jsp/browse/browse.jsp</from-view-id>
      <navigation-case>
         <from-outcome>createSpace</from-outcome>
         <to-view-id>/jsp/dialog/new-space.jsp</to-view-id>
      </navigation-case>
</navigation-rule>
‍‍‍‍‍‍‍‍

… as I understand it, this means :

When on a specific page (from-view-id), when the specified navigation 'event' occurs (from-outcome), navigate to the target page (to-view-id).

I can't seem to work out how this tallys with the new nav overrides. For instance :

   <config evaluator="node-type" condition="fm:forums">
      <navigation>
         <override from-view-id="/jsp/browse/browse.jsp" to-view-id="/jsp/forums/forums.jsp" />
         <override from-outcome="browse" to-view-id="/jsp/forums/forums.jsp" />
         <override from-outcome="showSpaceDetails" to-view-id="/jsp/forums/forums-details.jsp" />
         <override from-outcome="deleteSpace" to-view-id="/jsp/forums/delete-forums.jsp" />
      </navigation>
   </config>
‍‍‍‍‍‍‍‍‍

It's easy enough to see that this is tied to a specific 'object type' (or potentially aspect?), but the area of confusion is how to make the override apply to a specific page (from-view-id in the jsf example).

So, my questions are :

1. The first override line contains a 'to-view-id' attribute. What does this mean when the from-outcome isn't defined?


2. The config mechanism doesn't allow you to specify both a from-view-id and a from-outcome attribute on the same override element, so how do you tie an outcome only to a specific page (from-view-id)?


3. Is there any way to get a debug output of what the system thinks the current overrides are?


4. Is there any way to define an override that's *not* tied to a specific node/aspect type - for instance, to override the new-rule and create-action navigations having created a new action class?

Many thanks
Ben

[gavinc]

Hi Ben,

First of all your deductions are all correct and you ask some very valid questions.

Yes, potentially these rules can apply to aspects as well if you use the "aspect-name" evaluator, although you would have to be careful as you could end up with lots of override rules (as the results from all matching sections get merged) some of which you may not want.

I'll start with a basic explanation of the mechanism and what's going on as that may answer some of your questions.

When you click on a node in the main browse page that node is placed in a "dispatch context". A custom JSF Navigation Handler is called as part of the JSF lifecycle. This handler will perform a lookup in the config for any matching navigation rules for the node that is currently in the dispatch context. You can turn on debugging for the "org.alfresco.web.app.AlfrescoNavigationHandler" class to see what navigation overrides it finds.

If some config is found it will look for an override matching the current outcome or current view-id (in that order). If there is a match the navigation handler will navigate to the view id specified instead of where it was originally going to go. You can also specify a "to-outcome" which will replace the current outcome but we don't have any examples of that right now.

So, for example, in the client, if you clicked on the view details icon for a forum space an outcome (the action attribute of a:actionLink) of "showSpaceDetails" is used. Because of the line

<override from-outcome="showSpaceDetails" to-view-id="/jsp/forums/forums-details.jsp" />
‍‍

the navigation handler will now go to forums-details.jsp instead of space-details.jsp as it normally would for any other space type.

The "from-view-id" in the override element is used when there isn't an outcome. a 'null' outcome can be used in JSF to say "stay on the same page". When this occurrs the navigation handler will try and find a match for the current page.

This happens when you are navigating around spaces in the client, you'll notice that the app always stays on browse.jsp. Well, due to the first override line you quoted below when you click on a forum space in the client the "view" changes i.e. you've been navigated to forums.jsp instead of browse.jsp.

I think that answers questions 1 and 3. For question 2, basically you can't but that's the whole idea, basically it means whenever you use a particular outcome anywhere in the app it will get overridden. For example "showSpaceDetails" is called from a couple of places in the app but we only have to define that override once.

Finally, question 4. Yes you can, for this you would override the navigation rules defined in the JSF config files. We recommend you create a separate file to ease future upgrades. To override the navigation rules you need to place a faces-config.xml file with your changes in a META-INF folder inside a JAR file. Then drop this JAR file into your appserver (<tomcat>/shared/lib or <jboss>/server/default/lib), this will automatically get read in and override our rules.

Using our "showSpaceDetails" example you could add the following to your faces-config.xml:

<navigation-rule>
   <from-view-id>/jsp/*</from-view-id>
   <navigation-case>
      <from-outcome>showSpaceDetails</from-outcome>
      <to-view-id>/custom/your-space-details.jsp</to-view-id>
   </navigation-case>
</navigation-rule>
‍‍‍‍‍‍‍‍

Then (if there were no navigation overrides in place) any showSpaceDetails outcomes would go to your custom JSP.


This needs a wiki page but we've held off writing one so far as this is part of a larger piece of UI framework work we are looking at for 1.3, which will hopefully enable people to customize the web client a lot easier. As that gets fleshed out we will add more info to the wiki so stay tuned!

Hope this helps.

[buzman]

Gavin,
  Many thanks for your reply.

It sounds like I was (slowly) heading in the right direction - however, I do have an override rule currently in place that doesn't appear to be taking effect. I'll have a go with looking at some debug output to see why it's not firing.

Thanks again
Ben

[buzman]

In reference to my previous post, I'm having difficulty getting the overrides to take effect.

I'm replacing the editInline outcome for our custom node type in the web-client-config-custom.xml file :

<config evaluator="node-type" condition="etl:abc">
   <property-sheet>
      <show-property name="etl:clientStatus" displayLabelId="client_status"/>
      <show-association name="etl:policy" displayLabelId="policy"/>
   </property-sheet>
   <navigation>
      <override from-outcome="viewETLInline" to-view-id="/jsp/dialog/edit-etl-inline.jsp" />
      <override from-outcome="editETLInline" to-view-id="/jsp/dialog/edit-etl-inline.jsp" />
      <override from-outcome="changePolicies" to-view-id="/jsp/dialog/change-etl-policies.jsp" />
   </navigation>
</config>‍‍‍‍‍‍‍‍‍‍‍

However, with debug turned on for the NavigationHandler, I'm seeing this in the log file when I try to edit that node :

09:09:58,264 DEBUG [org.alfresco.web.app.AlfrescoNavigationHandler] handleNavigation (fromAction=null, outcome=editETLInline)
09:09:58,264 DEBUG [org.alfresco.web.app.AlfrescoNavigationHandler] Current view id: /jsp/browse/browse.jsp
09:09:58,264 DEBUG [org.alfresco.web.app.AlfrescoNavigationHandler] No dispatch context found
09:09:58,264 DEBUG [org.alfresco.web.app.AlfrescoNavigationHandler] Passing outcome 'editETLInline' to original navigation handler
09:09:58,264 DEBUG [org.alfresco.web.app.AlfrescoNavigationHandler] handleNavigation (fromAction=null, outcome=null)
09:09:58,264 DEBUG [org.alfresco.web.app.AlfrescoNavigationHandler] Current view id: /jsp/browse/browse.jsp
09:09:58,264 DEBUG [org.alfresco.web.app.AlfrescoNavigationHandler] No dispatch context found
09:09:58,264 DEBUG [org.alfresco.web.app.AlfrescoNavigationHandler] Passing outcome 'null' to original navigation handler‍‍‍‍‍‍‍‍

I should probably add that the the edit link is being passed through CheckinCheckoutBean.editFile (as in the core product), resulting in this line

fc.getApplication().getNavigationHandler().handleNavigation(fc, null, "editETLInline");‍

Could you give me any pointers as to why this isn't working?

Thanks
Ben

[gavinc]

Looking at the debug output a dispatch context is not being setup before the request. This happens when you are navigating around spaces but there may not be hooks in every situation (as you have found).

You'll need to setup this context. If you look at the updateUILocation() method in BrowseBean right at the bottom is the following line:

this.navigator.setupDispatchContext(new Node(ref));‍

You will need to add something similar to your scenario before the handleNavigation method is called.

Let me know if that helps.

[buzman]

Gavin,
  That did the trick. Thanks very much for your help.

Ben

[shmoula]

Hi guys, looks like it doesn't work on my side,
  I have following navigation rules:

<config evaluator="aspect-name" condition="txt:folder">
         <navigation>
        <override from-view-id="/jsp/browse/browse.jsp" to-view-id="/jsp/txt/browse.jsp" />
        <override from-outcome="browse" to-view-id="/jsp/teletext/browse.jsp" />
        <override from-outcome="dialog:close" to-view-id="/jsp/teletext/browse.jsp" />
     </navigation>
   </config>
   
   <config evaluator="aspect-name" condition="txt:folder">
         <navigation>
        <override from-view-id="/jsp/dialog/container.jsp" to-view-id="/jsp/txt/browse.jsp" />
        <override from-outcome="browse" to-view-id="/jsp/teletext/browse.jsp" />
        <override from-outcome="dialog:close" to-view-id="/jsp/teletext/browse.jsp" />
     </navigation>
   </config>
‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

Also my own dialog:

public class ModifyTxtFolder extends BaseDialogBean {
. . .
@Override
public String cancel(){
    String outcome = super.cancel();

    navigator.setupDispatchContext(navigator.getCurrentNode());
    FacesContext fc = FacesContext.getCurrentInstance();
    fc.getApplication().getNavigationHandler().handleNavigation(fc, null, outcome);

    return outcome;
}
. . .
}
‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

My log after cancel button is pressed (and view is returned back to default browse.jsp):

18:33:34,558 User:admin DEBUG [web.app.AlfrescoNavigationHandler] handleNavigation (fromAction=null, outcome=dialog:close)
18:33:34,558 User:admin DEBUG [web.app.AlfrescoNavigationHandler] Current view id: /jsp/dialog/container.jsp
18:33:34,559 User:admin DEBUG [web.app.AlfrescoNavigationHandler] Closing dialog
18:33:34,559 User:admin DEBUG [web.app.AlfrescoNavigationHandler] Popped item from the top of the view stack: /jsp/browse/browse.jsp
18:33:34,560 User:admin DEBUG [web.app.AlfrescoNavigationHandler] view stack: []
18:33:34,560 User:admin DEBUG [web.app.AlfrescoNavigationHandler] handleNavigation (fromAction=#{DialogManager.cancel}, outcome=dialog:close)
18:33:34,560 User:admin DEBUG [web.app.AlfrescoNavigationHandler] Current view id: /jsp/browse/browse.jsp
18:33:34,560 User:admin DEBUG [web.app.AlfrescoNavigationHandler] Attempting to close a dialog with an empty view stack, returning 'browse' outcome
18:33:34,560 User:admin DEBUG [web.app.AlfrescoNavigationHandler] Passing outcome 'browse' to original navigation handler
18:33:34,560 User:admin DEBUG [web.app.AlfrescoNavigationHandler] view stack: []
‍‍‍‍‍‍‍‍‍‍‍‍

I've got problems with this in another project two years ago and as I can see it still doesn't work. Am I doing anything wrong?

(crosspost: https://forums.alfresco.com/en/viewtopic.php?f=12&t=25829&p=120171#p120171 and https://forums.alfresco.com/en/viewtopic.php?f=10&t=2392&p=120173#p120173)