Documentation of HeaderCustomizationFile and FooterCustomizationFile: suggestions for extension

[pkiraly]

In the configuration page of the documentation
(http://guides.dataverse.org/en/4.8.5/installation/config.html#headercustomizationfile, source file: https://github.com/IQSS/dataverse/blob/develop/doc/sphinx-guides/source/installation/config.rst) in the Custom Header and Custom Footer sections I would like to read a bit more what does exactly happen, i. e. the HTML snippets will be injected into the main page (and will not overwrite anything existing parts) into the following locations:

the location of the :HeaderCustomizationFile snippet:

<a href="#content" class="sr-only">Skip to main content</a>
  <!-- HERE COMES THE CUSTOM HEADER -->
  <div id="dataverse-header-block"><nav role="navigation" id="navbarFixed" class="navbar navbar-default navbar-fixed-top">

the location of the :FooterCustomizationFile snippet:

<div id="footer">
  ...
</div><!-- HERE COMES THE CUSTOM FOOTER --><div id="ajaxStatusPanel">

As a newcomer to Dataverse it would be helpful for me, and maybe for other as well.

Best regards,
Péter Király

[pdurbin]

@pkiraly it's a good idea to document this a bit more. For now, let me write something here and you can tell me if it makes sense. A pull request to improve the guides can come later. 😄

The custom header, for example, is being added by what we are calling a CustomizationFilesServlet

On the XHTML (i.e. https://github.com/IQSS/dataverse/blob/v4.8.5/src/main/webapp/dataverse_header.xhtml#L12 ) it looks like this:

<o:resourceInclude path="/CustomizationFilesServlet?customFileType=header"...

We see customFileType=header above but as of 4.8.5 there are five of these types (including header, footer, etc) defined at https://github.com/IQSS/dataverse/blob/v4.8.5/src/main/java/edu/harvard/iq/dataverse/customization/CustomizationConstants.java

customFileType is processed as an HTTP request parameter over at https://github.com/IQSS/dataverse/blob/v4.8.5/src/main/java/edu/harvard/iq/dataverse/CustomizationFilesServlet.java#L49

Basically, we're using o:resourceInclude to insert content into the page: http://showcase.omnifaces.org/components/resourceInclude

I'm not sure that I'd put this level of detail into the Installation Guide (the one you linked above) but I think this would be on topic for Developer Guide (or maybe could just be Javadoc somewhere).

Is this helping? Too much detail? To little? Confusing? I hope this helps. 😄

[pdurbin]

@pkiraly it was nice meeting you at the Dataverse Community Meeting! How do you feel about closing this issue in favor of #4775 which has more images?

[pdurbin]

@pkiraly are you ok with closing this issue now that http://guides.dataverse.org/en/4.9.4/installation/config.html#branding-your-installation includes links to @shlake 's poster visualizing the customization options?

[pdurbin]

@pkiraly can you please look at

• issue Documentation: Refactor Branding Your Installation > Custom Header #8617

and

• PR #8617 Branding customization docs refactoring #8638

by @j-n-c and suggest any improvements to that pull request? Thanks!

[pkiraly]

@pdurbin @j-n-c Sorry for being late, I see meantime the PR has been approved. I liked the new texts and the image. Many thanks for these improvements!

[pdurbin]

@pkiraly sure. Do you want to close this issue? Good enough? Or were you planning on making a pull request?