Release of v0.17.0

Posted on | December 13, 2011 | 6 Comments

2nd month in a row that we had to postpone the release of DocBlox. I don’t intend to make this a habit as I do not like this at all. BUT! It was worth the effort in the end. DocBlox now has improved support for templating and a nice performance increase has been made.

This release also has 3 breaks with backwards compatibility related to templates; if you do not have custom templates then you are not affected by this. If you do use custom templates: please check the chapter ‘Why these changes?!’ later on in this posting.

The following changes and fixes were applies in this release:

• Templates are no longer automatically installed (except for the default template); you can install your own template using the template:install task.
• A website showcasing the available templates is now up: http://templates.docblox-project.org
• A new, more light-weight, template: Abstract. This template is intended to be a starting point for your own templates as it is more versatile and less heavy on the CSS. In time all existing templates will be based on this one.
• Performance is improved with a complete new inheritance module
• Class constants are now inherited too
• Renamed the default theme to new_black
• Removed ambiguity between themes and templates and merged the two concepts into template
• Renamed the task template theme to template (thus instead of theme:generate there is now a template:generate task)
• When specifying a template using an absolute path was the template copied to the data/themes/cache/[template_name] folder; this has changed to data/templates/[template_name]
• Added new meta-data to the template.xml for packaging: author, email, description and version, dependencies.

Why these changes?!

I want it to be easy for the user to work with DocBlox; to present as little configuration and overhead as possible. As such I discovered several naming errors:

1. Themes and Templates, while different in a technical way it was totally unclear to the user which was which. As such the most fitting name was chosen to name both and that was Template. Unfortunately this meant breaking Backward Compatibility because every template.xml file needed to be changed to point to the templates/[template_name] path instead of the themes/[theme_name] path.
2. Default template, by naming the template ‘Default’ it had to remain the default template indefinately. As such I see no other option then to radically change the default template because I want a new look. This would break backwards-compatibility and user expectancy. So now I let go of the name option and rename the template to new_black. The downside to this is that anyone who has built a template on top of the default name now has to change the references in their template.xml or XSL templates that point to the templates/default/* path to now point to templates/new_black/*.

In short

If you have a custom template you have to:

1. Update the template.xml and change every word theme into template
2. If your theme is derived from the default theme you have to update your template.xml and replace every instance of default with new_black

Documentation

I am not able to tell every aspect of these changes in this blog posting. It is just too much for that. In the upcoming month I will be writing a verbose set of documentation on templating and using templates.

Conclusion

This release has been thoroughly tested but sometimes something slips through the cracks. If you are the unlucky one to find an issue, do not hesitate to leave an issue report on Github, tweet me (@mvriel) or drop by on IRC at Freenode in the #docblox channel.

Thank you and until next month!

Comments