New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

More powerful, reusable templates (Origin: bugzilla #640924) #4124

doxygen opened this Issue Jul 2, 2018 · 0 comments


None yet
1 participant

doxygen commented Jul 2, 2018

status RESOLVED severity enhancement in component general for ---
Reported in version unspecified on platform Other
Assigned to: Dimitri van Heesch

Original attachment names and IDs:

On 2011-01-30 01:20:05 +0000, Haffmans wrote:

Created attachment 179618
Powerful templates functionality patch

In an effort to make the HTML header/footer templates more powerful - and especially more reusable - I've written some adjustments for Doxygen adding some options to these files.

The main problem was that several javascript/css files for e.g. the treeview and search functionality had to be added inside the templates. With this new functionality, the template files have a few extra markers available which are filled in with the necessary javascript and css tags, depending on the Doxygen configuration. As such, the header/footer files can be used regardless of the treeview or search settings, without manual modifications.

Also, to allow the templates to generate different output depending on the treeview or search options (and especially the former, see bug 640908), they can contain conditional blocks of HTML code. When Doxygen is run, the proper blocks will be kept or removed.

The added markers for javascript/css are:
$treeviewcss - CSS for the tree view, if enabled
$treeviewjs - Javascript for the tree view, if enabled
$searchcss - CSS for the search field, if enabled
$searchjs - Javascript for the search field, if enabled
$mathjaxjs - Javascript for MathJax, if enabled

The blocks that can appear in the headers are:

[Treeview is enabled] [Treeview is disabled] [SearchEngine is enabled] [SearchEngine is disabled]

The text between the brackets [] in these examples can be customized. The boundaries are strict; adding spaces etc. implies Doxygen will not detect the blocks.

The patch is attached.

On 2011-01-30 01:42:42 +0000, Haffmans wrote:

I forgot to mention that the patch will also pull in the jquery.js file if search is enabled, even if the treeview is disabled. This is necessary to use $(document).ready(), as using the onload attribute in the tag would be less convenient to use. The patch may need to be adjusted, such that the jquery.js file is created only if a custom header is used (right now it also creates the file using the default header).

On 2011-02-06 11:56:00 +0000, Dimitri van Heesch wrote:

I like this idea, but shouldn't the default footer file also make use of the blocks, so that it becomes independent of the config options? I didn't see that in your patch.

On 2011-02-06 13:37:17 +0000, Haffmans wrote:

If you mean the footer generated with -w html, then yes. Especially the tree/notreeview option as the closing HTML should differ depending on that setting. However, I'm unsure if the one generated when running without -w shares the code or not... if substituteKeywords is not used with the default footer that could cause problems, I think?

On 2011-02-06 16:43:38 +0000, Haffmans wrote:

Created attachment 180236
Improved patch

I've updated the patch, so the templates generated with -w have the blocks as well. Note that this now shares less code with the HTML generated during normal Doxygen invocations (especially for the header).

Additionally, this adds the following marker:
$searchbox - The correct (server or client side) search box, to be used if DISABLE_INDEX and SEARCHENGINE are both on.

Additional blocks (besides those in original report):
PROJECTNAME/PROJECTNUMBER/PROJECTBRIEF/PROJECTLOGO and NO* for all of these: selected depending on whether a project name, number, brief or logo (respectively) is configured (that is: the value is not empty).

TITLEAREA: used when either the project name, brief or logo is configured, or DISBALE_INDEX is on and SEARCHENGINE is on (which requires a search box in the title area). Otherwise the block "NOTITLEAREA" is selected.

Additional "bug" fix: the generated templates (with -w) do not point to doxygen.css anymore, but to the CSS file given on the command line. So "doxygen -w html header.html footer.html style.css" will generate a header pointing to style.css rather than doxygen.css.

Possible improvements:

  1. Select the correct blocks only once during the entire execution of Doxygen, and save that result. Right now this is done for every HTML file that is generated, which might be overkill.

  2. Replace $searchbox with actual content (rather than the empty string) only if DISABLE_INDEX and SEARCHENGINE are on (right now it's done regardless of DISABLE_INDEX).

  3. Add SEARCHBOX block, as substitute for "$searchbox"

  4. To share code between generating templates and using default (auto-generated) HTML, an option is to fill the g_header/g_footer using the same templates as generated with -w at the start of Doxygen. Then, rather than checking if g_header/g_footer is empty, deal with the default templates in the same way as if they were custom ones. I suggest this patch goes in first, before making such radical changes again. This would reduce code maintenance for HTML changes, as the place to change the default header/footer HTML can be kept in one place.

  5. Rather than write the content in the way it is now, seperate include files with the actual default header/footer files can be created and included, much like search_php.h, jquery_js.h etc.

On 2011-02-15 20:58:18 +0000, Dimitri van Heesch wrote:

I'll include your patch (still without the suggested improvements). I'm going to rearrange things a bit such that the HTML specific parts are in htmlgen.cpp and I will rename the block names so they match the corresponding config option (where applicable).

On 2011-03-28 14:18:53 +0000, Dimitri van Heesch wrote:

This bug was previously marked ASSIGNED, which means it should be fixed in
doxygen version 1.7.4. Please verify if this is indeed the case. Reopen the
bug if you think it is not fixed and please include any additional information
that you think can be relevant.

@doxygen doxygen closed this Jul 2, 2018

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment