Maven Site Plugin
  1. Maven Site Plugin
  2. MSITE-378

Support polymorphism for menu inheritance

    Details

    • Type: New Feature New Feature
    • Status: Open Open
    • Priority: Major Major
    • Resolution: Unresolved
    • Affects Version/s: 2.0-beta-7
    • Fix Version/s: None
    • Component/s: inheritance
    • Labels:
      None
    • Number of attachments :
      0

      Description

      Inheritance of menus in an multimodule project environment does not work as intuitively expected (as in OO languages). The following excerpts try to illustrate this. Assume there is a root project R that has one module (project) S. Both contain a site descriptor. Let the site descriptor for R be as follows:

      <project name="${project.name}">
      
      	<!-- ... -->
      
      	<body>
      		<menu name="Main">
      			<item name="Introduction" href="/index.html" />
      			<item name="News" href="/news.html" />
      			<item name="Overwrite" href="/documentation.html" />
      		</menu>
      	</body>
      
      	<!-- ... -->
      	
      </project>
      

      And let the site descriptor for S be:

      <project name="${project.name}">
      
      	<!-- ... -->
      
      	<body>
      		<menu name="Main">
      			<item name="Introduction" href="/index.html" />
      			<item name="Overwrite" href="/overwrite.html" />
      			<item name="Added" href="/added.html" />
      		</menu>
      	</body>
      
      	<!-- ... -->
      	
      </project>
      

      As I'm used to the way inheritance and polymorphism are defined in OO languages such as Java, I would expect the following properties for the "Main" menu in S:

      • item "Introduction" is overwritten in S but refers to the same index.html file; of course, its path is relative to start directory of S
      • item "News" is missing for S but will be inherited from R, thus, it will be rendered to the site as in R
      • item "Overwrite" is overwritten in S and refers now to overwrite.html (instead of documentation.html as in R)
      • item "Added" is new in S, thus, it will be rendered to the site in addition

      Unfortunately, with the current implementation of the site plugin inheritance is as follows:

      • "Main" menu of R is inherited by S as-is, that is, all changes made to the menu in S are not visible/rendered to the site.

      I would like to propose to implement polymorphism regarding menu inheritance as described above. In addition, I would like to propose a new boolean parameter "inherited" (or "inherit") that can be added to menu items. Its semantics would be equivalent to the "inherited" tag in pom.xml. In the following one example for R:

      <project name="${project.name}">
      
      	<!-- ... -->
      
      	<body>
      		<menu name="Main">
      			<item name="Introduction" href="/index.html" />
      			<item name="News 1" href="/news1.html"  inherited="false"/>
      			<item name="News 2" href="/news2.html"  inherited="true"/>
      			<item name="Overwrite" href="/documentation.html" />
      		</menu>
      	</body>
      
      	<!-- ... -->
      	
      </project>
      

      With this example only menu item "News 2" would appear in S because its inheritance is not disabled, while menu item "News 1" appears only in R and not in S because its inheritance was disabled (false). The default if the parameter is missing should be "true".

      Btw, the same extension should be made to the <menu ... > tag to allow to enable or disable inheritance of menus entirely.

      Regards,
      Thorsten

        Issue Links

          Activity

          Hide
          Mark Struberg added a comment - - edited

          There was such a functionality in a very rudimentary form in beta-6 already, but it did not work properly.

          Site descriptors are inherited along the same lines as project descriptors are. When you deploy a project, its site descriptor is also deployed so that it can be inherited.

          By default, only the basic settings are inherited. From the body, only the links are inherited, and these accumulate to contain all the parents' site descriptor links.

          However, it is possible to inherit menus as well. To do so, use the inherit attribute in the site descriptor. This can be either top or bottom , indicating where in the menu it will be placed after inheritance. For example:

          See http://maven.apache.org/plugins/maven-site-plugin/examples/sitedescriptor.html for more information

          This has lead to menu items in sub menus which are not intended because even if you inherit a menu entry to news1.html, where does the page come from?

          I am cured from this weird behaviour since I use beta-7 now.

          To only inherit menu items is simply not enough sadly...

          Show
          Mark Struberg added a comment - - edited There was such a functionality in a very rudimentary form in beta-6 already, but it did not work properly. Site descriptors are inherited along the same lines as project descriptors are. When you deploy a project, its site descriptor is also deployed so that it can be inherited. By default, only the basic settings are inherited. From the body, only the links are inherited, and these accumulate to contain all the parents' site descriptor links. However, it is possible to inherit menus as well. To do so, use the inherit attribute in the site descriptor. This can be either top or bottom , indicating where in the menu it will be placed after inheritance. For example: See http://maven.apache.org/plugins/maven-site-plugin/examples/sitedescriptor.html for more information This has lead to menu items in sub menus which are not intended because even if you inherit a menu entry to news1.html, where does the page come from? I am cured from this weird behaviour since I use beta-7 now. To only inherit menu items is simply not enough sadly...
          Hide
          Thorsten Möller added a comment -

          This has lead to menu items in sub menus which are not intended because even if you inherit a menu entry to news1.html, where does the page come from?

          O.k., to clarify this I give the directory structure for S and R (second example) and assuming only *.apt files:

          R/src/site/apt/
           |
           +-- index.apt
           +-- news1.apt
           +-- news2.apt
           +-- documentation.apt
          
          S/src/site/apt/
           |
           +-- index.apt
           +-- news2.apt
           +-- overwrite.apt
           +-- added.apt
          

          And I just realized that with the proposed polymorphism one detail problem arises, which is the order in which to render the menu items eventually. I would suggest to use that order implied at the lowest level.

          Show
          Thorsten Möller added a comment - This has lead to menu items in sub menus which are not intended because even if you inherit a menu entry to news1.html, where does the page come from? O.k., to clarify this I give the directory structure for S and R (second example) and assuming only *.apt files: R/src/site/apt/ | +-- index.apt +-- news1.apt +-- news2.apt +-- documentation.apt S/src/site/apt/ | +-- index.apt +-- news2.apt +-- overwrite.apt +-- added.apt And I just realized that with the proposed polymorphism one detail problem arises, which is the order in which to render the menu items eventually. I would suggest to use that order implied at the lowest level.
          Hide
          Dennis Lundberg added a comment -

          Thorsten,

          Menus can be inherited, but you have to let Maven know that you want them to be inherited. See the section called "Inheritance" on http://maven.apache.org/plugins/maven-site-plugin/examples/sitedescriptor.html

          In your example you would need to have this in site.xml of R:

          		<menu name="Main" inherit="top">
          			<item name="Introduction" href="/index.html" />
          			<item name="News" href="/news.html" />
          			<item name="Overwrite" href="/documentation.html" />
          		</menu>
          
          Show
          Dennis Lundberg added a comment - Thorsten, Menus can be inherited, but you have to let Maven know that you want them to be inherited. See the section called "Inheritance" on http://maven.apache.org/plugins/maven-site-plugin/examples/sitedescriptor.html In your example you would need to have this in site.xml of R: <menu name= "Main" inherit= "top" > <item name= "Introduction" href= "/index.html" /> <item name= "News" href= "/news.html" /> <item name= "Overwrite" href= "/documentation.html" /> </menu>
          Hide
          Thorsten Möller added a comment -

          Dennis,

          that I didn't use the 'inherit="<xyz>"' attribute in my examples doesn't mean that I don't know about the fact that the site plugin supports inheritance already. In fact, I'm not sure whether you understood what my feature request is all about: It is a request to change respectively extend the way how inheritance is implemented right now in the site plugin.

          Regards,
          Thorsten

          Show
          Thorsten Möller added a comment - Dennis, that I didn't use the 'inherit="<xyz>"' attribute in my examples doesn't mean that I don't know about the fact that the site plugin supports inheritance already. In fact, I'm not sure whether you understood what my feature request is all about: It is a request to change respectively extend the way how inheritance is implemented right now in the site plugin. Regards, Thorsten

            People

            • Assignee:
              Unassigned
              Reporter:
              Thorsten Möller
            • Votes:
              2 Vote for this issue
              Watchers:
              2 Start watching this issue

              Dates

              • Created:
                Updated: