Template architecture design

[bclothier]

Task list (see below for discussion):

• Migrate all hard-coded code templates to template system (e.g. test module/test method)
• Create a setting pane for viewing/customizing templates
• Provide a versioning system for built-in templates to aid in graceful update of the built-in templates without losing users' customizations
• Create a macro system for template (simple text substitution)
• Provide validation of template with macros (?)
• Provide preview dialog (?)

With PR #4225 we introduced the foundation for the template subsystem. Only the minimal work was done to get in for the PR, but the next release should make it a more systematic approach for how we should handle all kinds of code templates.

For example, right now, the test modules and methods are just hard-coded inside the codebase, which kinds of hampers the ability to customize the method. The template subsystem is meant to enable this. However, there are few items to consider in the architecture so comments or ideas are welcome.

First of all, the template subsystem is designed to handle both built-in and user-defined templates. The difference is based on whether the templates has a corresponding entry in its dedicated Template.resx resource file. The built-in templates exist primarily to ensure that Rubberduck won't blow up if the template go missing; it'll just use the default ones stored inside the resource file. But the users would be able to customize the built-in templates if they choose to which brings me to the next point.

The templates are stored as a .rdt (Rubberduck Template) files stored in %APPDATA%\Rubberduck\Templates. In principle, users can edit those -- they're just plain text file fit for direct import into VB* codebase. Currently there is no macro system, and it's very likely that one will be if users would be able to parameterize the template at runtime. The test methods will likely need one anyway in order to provide a placeholder for the procedure name.

But macros are not as useful if there's no decent UI for creating/editing/deleting templates. The settings dialog most likely needs a new section dedicated to templates. That way, users can preview the template and if they customize it, we can help with validating the template.

The Template class likely will need a new property bool HasDedicatedCommand or something similar to ensure that built-in templates do not get exposed via the Template submenu, since the test module/test method has their own dedicated commands, avoiding duplicating the templates in the Template submenu.

For VB6, I understand that it's very common to have a bunch of templates. Some research will be needed in seeing how to leverage the template system and thus provide a easy way of exposing those templates when using RD inside VB6. I also understand that normally those have their popup form. It's not clear if those involve additional inputs from the users beside the selection of a template but in case it does, we might need to consider a popup dialog to support that. That would also allow for previewing with marcos resolved.

I also did not like that we had to use submenu. I originally wanted it on a flat menu (with separators) but unfortunately, XAML did not make it easy to provide appropriate styling for static parts and dynamic parts separately. If anyone can do this, they're more than welcome to make a PR.

If there's something else missing, share it here.

[bclothier]

As realized in the comments in #4622, a simple versioning system may be needed for the built-in template in order to support the scenario where we need to update the built-in template's code in the resource. That also implies prompting the user whether to update the built-in template as they may have already made customization to the template and may not want to lose the changes.

[retailcoder]

IMO versioning is overkill. If you added an earlier version of a template, it's in your project already; adding another instance will use the newer template, and that's fine. Why would a template change anyway? Adding annotations? They can be added later on, inspections can even find the missing ones, at least in the case of @PredeclaredId.

[retailcoder]

Wait I missed the part about user customizations... how about we just list all the available files, and the filename deals with the version?

[bclothier]

No, the issue is that when we first add a component, the subsystem will check the %APPDATA%\Rubberduck\Templates for a rdt file of that template. If it doesn't exist, it will create a new rdt file from the resource file.

So if we issue an updated version where we changed the template, the users who already generated the template .rdt file wouldn't get the changed template unless they delete that file in which case we will then regenerate from the resource file.

If we automatically always overwrite the .rdt file whenever there is a change for any reason, then it can't be customized by the user anymore. The thought was that it'd be permissible to customize to conform to users' needs.

Embedding the version in the filename would be one way, but then the subsystem has to know which one to use?

[retailcoder]

I'd say just list everything that's available; you want to use the file from 3 releases ago, go ahead. Perhaps include a readme.txt in the templates folder, suggesting a naming scheme: rd.template-name.rdt for the "built-ins" (gets overwritten), and user.template-name.rdt for customized ones.

[bclothier]

Ok, but there's 2 still more considerations:

1. in future, users would be able to create their own templates for where there is no corresponding built-in template. Labeling them as user.template-name.rdt seems a bit silly. We can use the convention of template-name.rd.rdt, and say that those will be always overwritten by RD which...
2. means the user needs a way of knowing there's a new version of the built-in template that won't be picked up because their customized template will be always picked above the built-in template, no?

[retailcoder]

Why not just list all available templates, built-in or custom? We could even load the string and hover-preview it with syntax highlighting...