OFBiz
  1. OFBiz
  2. OFBIZ-2133

Linking End User Documentation to OFBiz

    Details

    • Type: New Feature New Feature
    • Status: Closed
    • Priority: Major Major
    • Resolution: Fixed
    • Affects Version/s: None
    • Fix Version/s: Release Branch 09.04
    • Component/s: None
    • Labels:
      None

      Description

      I have seen that several updates are in progress in this http://docs.ofbiz.org/display/OFBIZ/End+User+Documentation
      area of Confluence.
      Specially the Accounting application seems going to be described with a one-to-one help page to OFBiz screens.

      This is great and I think that having those pages linked to the relative OFBiz screens will be usefull and will also encourage more people to create (and fill) more documentation pages.

      What is attached to this issue is a simple patch that creates this link using the "titleProperty" field.
      It makes no use of the help request that is defined in the framework but uses an even simpler mechanism.

      I would like to discuss this pattern, it is a first trial and I am not sure it will be OK for every case.

      What I was also considering is to have the AccountingHelpUiLabels.xml file not committed but attached to the Confluence documentation main page.
      In this way who updates the documentation can update this "index" file also.

      Who is interested in using the onlline documentation will download this file and install infor OFBiz.

      Who is interested to have a local copy of the help can consider using the export space function present in Confluence.
      This creates a complete static HTML copy of the documentation. A specific version of the AccountingHelpUiLabels.xml can be used to access to this exported copy.

      What do you think?

      1. help.patch
        13 kB
        Bruno Busco
      2. help.patch
        9 kB
        Bruno Busco
      3. help.zip
        634 kB
        Bruno Busco
      4. help.patch
        0.8 kB
        Bruno Busco

        Issue Links

          Activity

          Hide
          Jacques Le Roux added a comment -

          Hi Bruno,

          I like the idea because it would allow for localised help. I think we should commit AccountingHelpUiLabels.xml and have it in Confluence also. Doing so we will hedge one's bets (I took this locution from the Net )

          • We will then see if having it Confluence allows for more documentation/help efforts
          • We will have it ready OOTB
          Show
          Jacques Le Roux added a comment - Hi Bruno, I like the idea because it would allow for localised help. I think we should commit AccountingHelpUiLabels.xml and have it in Confluence also. Doing so we will hedge one's bets (I took this locution from the Net ) We will then see if having it Confluence allows for more documentation/help efforts We will have it ready OOTB
          Hide
          Bruno Busco added a comment -

          Hi Jacques,
          I have spent some time to find a way to integrate in the best way the help pages that are being developed on Confluence into OFBiz.
          And this is what I did find.

          The best would be to be IMO to periodically export the END-USER space in HTML, put all this content in an help component, zip everything and put back on a Confluence page.
          Users could download this zip file and install it in the hot-deploy.
          This should be all a user should do to install an updated help.

          The solution in the patch, at the moment, is not so versatile but I do not know how to do what I have described.
          It would be great to have help in doing it.

          Show
          Bruno Busco added a comment - Hi Jacques, I have spent some time to find a way to integrate in the best way the help pages that are being developed on Confluence into OFBiz. And this is what I did find. The best would be to be IMO to periodically export the END-USER space in HTML, put all this content in an help component, zip everything and put back on a Confluence page. Users could download this zip file and install it in the hot-deploy. This should be all a user should do to install an updated help. The solution in the patch, at the moment, is not so versatile but I do not know how to do what I have described. It would be great to have help in doing it.
          Hide
          Jacques Le Roux added a comment -

          Yes, this could be discussed and seems a good start to think about.
          I only expressed the fact that one of the main goal of OFBiz applications is to be showcases of OFBiz power. So it could be interesting to have something ready to use to better attract new users (OOTB). And documentation is a very important part of convincing users of the power of a software...

          Show
          Jacques Le Roux added a comment - Yes, this could be discussed and seems a good start to think about. I only expressed the fact that one of the main goal of OFBiz applications is to be showcases of OFBiz power. So it could be interesting to have something ready to use to better attract new users (OOTB). And documentation is a very important part of convincing users of the power of a software...
          Hide
          Bruno Busco added a comment -

          I perfectly agree.
          And having the Confluence documentation pages linked to OFBiz would give more "light" to the effort spent there.

          Show
          Bruno Busco added a comment - I perfectly agree. And having the Confluence documentation pages linked to OFBiz would give more "light" to the effort spent there.
          Hide
          Bruno Busco added a comment -

          I am working to have a simple hot-deplyable application containing an html export from the End User Documentation Confluence area.
          This will be ready hopefully soon.

          BTW we should think to better organize the Open End User Documentation in order to have the export easier.
          I would suggest to have a public writable Confluence space enterely dedicated to the End User Doc that we want to export and have available locally with links from OFBiz screens.
          This would make the periodic export painless.
          All pages in this space should follow the structure of OFBiz application screens (like the recently added pages).

          Show
          Bruno Busco added a comment - I am working to have a simple hot-deplyable application containing an html export from the End User Documentation Confluence area. This will be ready hopefully soon. BTW we should think to better organize the Open End User Documentation in order to have the export easier. I would suggest to have a public writable Confluence space enterely dedicated to the End User Doc that we want to export and have available locally with links from OFBiz screens. This would make the periodic export painless. All pages in this space should follow the structure of OFBiz application screens (like the recently added pages).
          Hide
          Bruno Busco added a comment -

          Please find attached my solution to link to OFBiz screens a locally available Confluence end user doc HTML export.
          This is a first trial to share the idea.
          If we are ok with this we should have a cleaner Confluence space dedicated to end-user online documentation.

          The help.zip file could be periodically re-created and attached to a special Confluence page to be downloaded and installed in the hot-deploy.

          Another option is to have the help application committed to SVN with the HTML files and periodically update them with a fresh export from Confluence.

          WDYT?

          Show
          Bruno Busco added a comment - Please find attached my solution to link to OFBiz screens a locally available Confluence end user doc HTML export. This is a first trial to share the idea. If we are ok with this we should have a cleaner Confluence space dedicated to end-user online documentation. The help.zip file could be periodically re-created and attached to a special Confluence page to be downloaded and installed in the hot-deploy. Another option is to have the help application committed to SVN with the HTML files and periodically update them with a fresh export from Confluence. WDYT?
          Hide
          David E. Jones added a comment -

          Rather than looking for the titleProperty, which can change and may not be unique, why not use a combination of the webapp name and the view name? It would not be as "pretty", but it would be more unique and easier to maintain over time.

          The current view name is easy to get with the "CURRENT_VIEW" request attribute.

          Show
          David E. Jones added a comment - Rather than looking for the titleProperty, which can change and may not be unique, why not use a combination of the webapp name and the view name? It would not be as "pretty", but it would be more unique and easier to maintain over time. The current view name is easy to get with the " CURRENT_VIEW " request attribute.
          Hide
          David E. Jones added a comment -

          Also, instead of having a hard-coded location (ie: "/help/control/main?topic=") we would have a lot of nice flexibility if we just put that in a properties file and treat it as a prefix.

          OOTB I think we should just point to the wiki site and not require an export/etc in order to see the help. If people want their own help that is different from that in the wiki (decorated or changed content or whatever) they can just change the help URL prefix in the properties file and off they go...

          The simpler we keep this the more chance of success it will have. We can make it more complicated later should needs arise once we've played with it more.

          Show
          David E. Jones added a comment - Also, instead of having a hard-coded location (ie: "/help/control/main?topic=") we would have a lot of nice flexibility if we just put that in a properties file and treat it as a prefix. OOTB I think we should just point to the wiki site and not require an export/etc in order to see the help. If people want their own help that is different from that in the wiki (decorated or changed content or whatever) they can just change the help URL prefix in the properties file and off they go... The simpler we keep this the more chance of success it will have. We can make it more complicated later should needs arise once we've played with it more.
          Hide
          Adrian Crum added a comment -

          I like David's idea of just pointing to the documentation. I had suggested something like that previously - https://issues.apache.org/jira/browse/OFBIZ-1873?focusedCommentId=12621261#action_12621261.

          Not all of our OFBiz users have internet access, so it would be helpful to have OFBiz "pull down" the wiki content in a dynamic way.

          Show
          Adrian Crum added a comment - I like David's idea of just pointing to the documentation. I had suggested something like that previously - https://issues.apache.org/jira/browse/OFBIZ-1873?focusedCommentId=12621261#action_12621261 . Not all of our OFBiz users have internet access, so it would be helpful to have OFBiz "pull down" the wiki content in a dynamic way.
          Hide
          Jacques Le Roux added a comment -

          +1 for webapp name + view name
          +1 prefix in properties

          Adrian should be consider to put the dynamic "pull dow" in svn repo (to have the dynamyc way working), in hot-deploy like Bruno suggested ?

          Show
          Jacques Le Roux added a comment - +1 for webapp name + view name +1 prefix in properties Adrian should be consider to put the dynamic "pull dow" in svn repo (to have the dynamyc way working), in hot-deploy like Bruno suggested ?
          Hide
          Bruno Busco added a comment -

          David,
          thank you for the suggestion to use the webapp name and the view name. I will try this.

          Regarding using a configuration parameter as prefix, this was my first idea. But then, when I exported a Confluence space and installed locally into hot-deploy I found that while locally I had to link the files with the .html extension, the url to have a page from a live Confluence are without .html and with a "+" instead of spaces. So it seems not to be possible with asimple prefix but we should have a completely different mapping file.

          Adrian,
          your suggestion in OFBIZ-1873 is interesting, I used an iframe in the ftl to render an external .html page in a screen but I was not really happy with this solution.
          When you say ""pull down" the wiki content in a dynamic way" what you mean? Shouldn't the user have an internet access to do this?

          Show
          Bruno Busco added a comment - David, thank you for the suggestion to use the webapp name and the view name. I will try this. Regarding using a configuration parameter as prefix, this was my first idea. But then, when I exported a Confluence space and installed locally into hot-deploy I found that while locally I had to link the files with the .html extension, the url to have a page from a live Confluence are without .html and with a "+" instead of spaces. So it seems not to be possible with asimple prefix but we should have a completely different mapping file. Adrian, your suggestion in OFBIZ-1873 is interesting, I used an iframe in the ftl to render an external .html page in a screen but I was not really happy with this solution. When you say ""pull down" the wiki content in a dynamic way" what you mean? Shouldn't the user have an internet access to do this?
          Hide
          Adrian Crum added a comment -

          Jacques,

          If you look at OFBIZ-1873 you will see that I was proposing a web scraper for the Help feature. So, when a user clicks on the Help link, an internal OFBiz server grabs the associated wiki content (from the wiki site) and stuffs it in the screen.

          Show
          Adrian Crum added a comment - Jacques, If you look at OFBIZ-1873 you will see that I was proposing a web scraper for the Help feature. So, when a user clicks on the Help link, an internal OFBiz server grabs the associated wiki content (from the wiki site) and stuffs it in the screen.
          Hide
          David E. Jones added a comment -

          Wow I hate conversations in Jira... no threading, etc, etc... oh well off we go... It's a good conversation anyway.

          For reference Bruno wrote:

          "Regarding using a configuration parameter as prefix, this was my first idea. But then, when I exported a Confluence space and installed locally into hot-deploy I found that while locally I had to link the files with the .html extension, the url to have a page from a live Confluence are without .html and with a "+" instead of spaces. So it seems not to be possible with asimple prefix but we should have a completely different mapping file."

          These sound like items to take care of on a check list more than issues....

          The "+" instead of spaces is a common way of encoding URLs. You'll find with confluence that a plain space or a %20 works just as well. With the webapp name and view name combination that won't be an issue though.

          For the ".html" we can easily have a configured suffix as well as a configured prefix.

          Show
          David E. Jones added a comment - Wow I hate conversations in Jira... no threading, etc, etc... oh well off we go... It's a good conversation anyway. For reference Bruno wrote: "Regarding using a configuration parameter as prefix, this was my first idea. But then, when I exported a Confluence space and installed locally into hot-deploy I found that while locally I had to link the files with the .html extension, the url to have a page from a live Confluence are without .html and with a "+" instead of spaces. So it seems not to be possible with asimple prefix but we should have a completely different mapping file." These sound like items to take care of on a check list more than issues.... The "+" instead of spaces is a common way of encoding URLs. You'll find with confluence that a plain space or a %20 works just as well. With the webapp name and view name combination that won't be an issue though. For the ".html" we can easily have a configured suffix as well as a configured prefix.
          Hide
          Bruno Busco added a comment -

          David,
          you are right.
          I tested it and effectively an url with space instead of "+" works both on a local export and on the live Confluence.
          I will se two configuration properties for a prefix and a suffix. So that only changing those configuration we could switch between an OOTB Confluence based online help and a local static help.

          I think this could be a simple start. I will do that soon pointing to the Open OFbiz wiki.

          Thank you.

          Show
          Bruno Busco added a comment - David, you are right. I tested it and effectively an url with space instead of "+" works both on a local export and on the live Confluence. I will se two configuration properties for a prefix and a suffix. So that only changing those configuration we could switch between an OOTB Confluence based online help and a local static help. I think this could be a simple start. I will do that soon pointing to the Open OFbiz wiki. Thank you.
          Hide
          Bruno Busco added a comment -

          Could please tell me how can I retrieve the current webAppName in the header.ftl ?
          Thank you.

          Show
          Bruno Busco added a comment - Could please tell me how can I retrieve the current webAppName in the header.ftl ? Thank you.
          Hide
          Bruno Busco added a comment -

          I think I could use "WebSiteId" and adding all missing in web.xml files. Am I correct?

          Show
          Bruno Busco added a comment - I think I could use "WebSiteId" and adding all missing in web.xml files. Am I correct?
          Hide
          David E. Jones added a comment -

          servletContext.getContextPath()

          or if you only have a request object: request.getSession().getServletContext().getContextPath()

          Show
          David E. Jones added a comment - servletContext.getContextPath() or if you only have a request object: request.getSession().getServletContext().getContextPath()
          Hide
          Bruno Busco added a comment -

          Thank you David,
          at the end I decided to use the webSiteId in the help topic key.
          I hope this is OK.
          I found defining webSiteId for ALL webapp usefull for both the help link issue and to associate the VisualThemeSet to webapp (a different issue).

          Please find attached a new patch in which I implemented the online help links as agree (I hope so).

          Basically I created a CommonHelpUrls.xml file in the framework that should be used to define the help url prefix, suffix and the "HelpPageNotFound" page.
          Having the prefix and suffix in a localization file will let us to link localized help pages that could be distinguished by a prefix in the URL or a suffix.

          I have linked some of the pages available on the Open of OFBiz Confluence site so that OOTB OFBiz help will be get from docs.ofbiz.org.
          More page links will come if we agree on this pattern and commit it.

          Show
          Bruno Busco added a comment - Thank you David, at the end I decided to use the webSiteId in the help topic key. I hope this is OK. I found defining webSiteId for ALL webapp usefull for both the help link issue and to associate the VisualThemeSet to webapp (a different issue). Please find attached a new patch in which I implemented the online help links as agree (I hope so). Basically I created a CommonHelpUrls.xml file in the framework that should be used to define the help url prefix, suffix and the "HelpPageNotFound" page. Having the prefix and suffix in a localization file will let us to link localized help pages that could be distinguished by a prefix in the URL or a suffix. I have linked some of the pages available on the Open of OFBiz Confluence site so that OOTB OFBiz help will be get from docs.ofbiz.org. More page links will come if we agree on this pattern and commit it.
          Hide
          Bruno Busco added a comment -

          Just to inform who will test this patch that now the file help.zip is not needed. The "help.patch" works by alone. I do not delete help.zip because it could be usefull for further improvements.

          Show
          Bruno Busco added a comment - Just to inform who will test this patch that now the file help.zip is not needed. The "help.patch" works by alone. I do not delete help.zip because it could be usefull for further improvements.
          Hide
          Bruno Busco added a comment -

          An updated help.patch file with:

          • The complete links of all lately added Accounting help pages
          • A more reused code solution (both default and bluelight themes include a single helplink.ftl file that is responsible for help link calculation)
          Show
          Bruno Busco added a comment - An updated help.patch file with: The complete links of all lately added Accounting help pages A more reused code solution (both default and bluelight themes include a single helplink.ftl file that is responsible for help link calculation)
          Hide
          Jacques Le Roux added a comment -

          I see that Sharan is regularly updating the accouting documentation (actually it's not final draft, just a work in progress, but even OFBiz trunk gives the same feeling nowadays ;o). Maybe we could ask her to update also the help links when she creates/updated wiki pages. I'm not sure she is aware of this help effort...

          Show
          Jacques Le Roux added a comment - I see that Sharan is regularly updating the accouting documentation (actually it's not final draft, just a work in progress, but even OFBiz trunk gives the same feeling nowadays ;o). Maybe we could ask her to update also the help links when she creates/updated wiki pages. I'm not sure she is aware of this help effort...
          Hide
          Jacques Le Roux added a comment -

          Thanks Bruno,

          Your last patch is in trunk at revision: 748884

          I did not close as I don't know if you want to put more effort on this, and especially in this issue or a new one.

          Also I have asked Sharan to update the AccountingHelpUrls.xml file as much as she can.

          Show
          Jacques Le Roux added a comment - Thanks Bruno, Your last patch is in trunk at revision: 748884 I did not close as I don't know if you want to put more effort on this, and especially in this issue or a new one. Also I have asked Sharan to update the AccountingHelpUrls.xml file as much as she can.
          Hide
          Bruno Busco added a comment -

          Thank you Jacques,
          I think it is better to close it. This was scheduled to release 9.3 and we should have a clear picture of what is still to do to release it. (open issues scheduled for 9.3)

          Show
          Bruno Busco added a comment - Thank you Jacques, I think it is better to close it. This was scheduled to release 9.3 and we should have a clear picture of what is still to do to release it. (open issues scheduled for 9.3)

            People

            • Assignee:
              Bruno Busco
              Reporter:
              Bruno Busco
            • Votes:
              0 Vote for this issue
              Watchers:
              0 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved:

                Development