GNOME Bugzilla – Bug 640924
More powerful, reusable templates
Last modified: 2012-11-18 11:11:39 UTC
Created attachment 179618 [details] [review] 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: <!--BEGIN TREEVIEW-->[Treeview is enabled]<!--END TREEVIEW--> <!--BEGIN NOTREEVIEW-->[Treeview is disabled]<!--END NOTREEVIEW--> <!--BEGIN SEARCH-->[SearchEngine is enabled]<!--END SEARCH--> <!--BEGIN NOSEARCH-->[SearchEngine is disabled]<!--END NOSEARCH--> 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.
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 <body> 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).
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.
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?
Created attachment 180236 [details] [review] 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 "<!--BEGIN DISABLEINDEX--><!--BEGIN SEARCH-->$searchbox<!--END SEARCH--><!--END DISABLEINDEX-->" 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.
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).
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.