Experiences in migrating a large hack to vb4

[AndrewD]

Over Christmas, I upgraded the Links and Download Manager product (LDM) to work with vb 4.0. Over its six year lifetime, LDM has become a large and quite complex product, with around 200 templates, close to 1Mbyte of php, a wide range of 'add on extras' and translations into five languages. As well as working within the vb 4.0 infrastructure, I set a goal that all pages would validate correctly according to the XHTML transitional rules. Although it was important that the displays would behave sensibly with different sytles, I did not want (at this stage, at least) to get rid of use of tables - this seemed unachievable in the time available.

I thought other developers might benefit from the experience, and could perhaps expand on some of the points made below - and maybe explain things I've missed. None of the points are intended as criticisms of the vb team, or Kier's design philosophy, just things to watch out for and perhaps to get addressed in future releases.

The new template system

Without question, the biggest task was to update templates to work with vb4.0. The new template access mechanism, via the vB_Template class, did not in itself cause great difficulties (code size increases but not hugely), but it threw up a range of 'gotchas' which wasted considerable time during the conversion. These included:

- The <vb:if> tag uses a different (standard php) syntax than other parts of the template, which use the new vB tags, {vb:raw}, etc. I found this quite irritating in itself, but the main problem is that errors are handled differently (and perhaps not at all) depending on where you are. For example, errors in a <vb:if> conditional tag (e.g <vb:if condition="$arrayvar['abc'"> or <vb:if condition="$arrayvar['abc']>) will either generate a syntax error when he template is used or cause the product installer to fail, whereas a (somewhat similar) mistake in a {vb:raw} tag (e.g. specifying {vb:raw arrayvar but forgetting the closing brace) simply places the entire tag as unwanted text in the output, with no error at all.

- When syntax errors are detected during page generation, the report does not tell you which template caused the problem and the reported line number no longer corresponds to the line in that template that actually caused the error. The processing of templates that is done by the vb4.0 infrastructure adds extra lines into the template before actually 'eval'-ing it. This is a real nuisance.

- Unregistered variables are not flagged by the system, so it is very easy during a product update to fail to create complete and accurate calls to templater->register and templater->quickRegister (which does the same thing but I prefer to using multiple templater->register's).

I am not arguing for carelessness in template design, but these types of errors are very easy to overlook and quite time-consuming to track down and correct. I got round the problems by:

a) writing a short Perl script to scan a template file, scan for variables, report errors, and create prototype calls to templater>quickRegister for each valid template, listing all used variables. (Am happy to make this script available on request, although without support.)

b) adding some debugging code in class_core.php function render() to allow me to follow the template processing sequence

c) adding calls to error_reporting(E_ALL) in class_core.php function render() to detect use of uninitialised template variables

Javascript and the template system

The new template system is not too happy with processing embedded Javascript. It is easy to 'lose' lines altogether and to end up with pages (or syntax errors) that bear no resemblence to the contents of the template. Judicious use of the <vb:literal> tag sorts that out. However, the design goal of proper page validation can require use of CDATA tags within the template to encapsulate inline Javascript. You really have to jump through a few hoops to achieve that, unless I am missing something obvious.

Stylevars

The new style variables system is very neat, allowing you to pick up elements of css definitions for use elsewhere. I used this to build the main LDM css template, picking up the most appropriate style variables from vBulletin. One 'gotcha' is that these variables do not have the same names inside templates ({vb:stylevar xxx} as they do inside the $vbulletin->stylevars array. Element names get changed, e.g. from color to backgroundcolor.

Changes in the rest of the vbulletin infrastructure.

So far, I have not experienced too many problems here. Examples include:

The style_fetch hook. In vb3.x, you could temporarily change the choice of style by assigning an integer to $styleid within this hook. In vb4, you also need to assign it to $vbulletin->userinfo['styleid'].

The forum_jump list. In vb3.x, a call to construct_forum_jump() gave you what was needed. In vb4.0, you need to use construct_quick_nav() instead.

It's now a lot easier (imho) to add a product *and its suboptions* to the main vb navbar, although I would appreciate more freedom to specify exactly where to place a menu item (i.e. not just 'at the end', ' somewhere in the middle' etc.)

Translations

The language encoding problem has always existed in vB. Translations into languages which use utf-8 character encoding do not install correctly into vbulletin without a small change to the standard vb code. There is a post on vb.com which explains how to make this fix in class_xml.php. In my opinion, it would be better to change adminfunctions_language.php, where it is possible to detect the encoding used by an imported phrases file and react accordingly.

I know that the vb team intend to make a shift towards full utf-8 character handling, but feel that language imports might be a priority.

Will expand on these points as appropriate, but welcome remarks and other experiences.

[bumsengee3]

Can you post the code for this part?

c) adding calls to error_reporting(E_ALL) in class_core.php function render() to detect use of uninitialised template variables

I would love to see and learn how you did this.
Thank you in advance.

[Zachariah]

Yes you said it Andrew, the code syntax has become more complex.

Time to make more "cheat sheet" of syntax and rule changes with tricks and tips.
(like we did back when we had to go from VB3.0x to VB3.5x. series)

- 3.5 to 3.8x was a good run as most of the hacks did not need a lot of changes.

Love your add-on over the years Sir.