On Tue, 2010-12-07 at 14:08 -0500, Jim Fulton wrote:
On Tue, Dec 7, 2010 at 1:57 PM, Chris McDonough <chrism@plope.com> wrote:
Independent of my previous call for discussion about ZCML conflict resolution, I'm cutting and pasting my side of a discussion about the ZCML "includeOverrides" directive from an IRC chat, because it may come in useful for folks grappling with its behavior. There's not really any human-consumable docs about it.
If I've made any mistakes, please let me know.
[13:42] <mcdonc> so ftr, i've found that ZCML's includeOverrides and include to do (at least on one vector) exactly the opposite of what you might expect them to do [13:42] <mcdonc> "includeOverrides" is a poor name [13:42] <mcdonc> what it does is to emulate the behavior of inlining stuff into the file you use it from [13:43] <mcdonc> when you use includeOverrides it's as if you typed all the directives in the included file into the file you're including from [13:43] <mcdonc> otoh, "include" doesnt behave like this [13:44] <mcdonc> you can actually define the same directive in three files [13:44] <mcdonc> configure.zcml, one.zcml, and two.zcml [13:44] <mcdonc> and if you use "include" from configure.zcml of one and two [13:44] <mcdonc> there will be no conflict [13:45] <mcdonc> this is because non-conflicting "rootmost" directives win [13:45] <mcdonc> otoh, if you use includeOverrides of one and two from configure.zcml [13:45] <mcdonc> all three will conflict [13:45] <mcdonc> because its as if you typed them all in configure.zcml by hand [13:45] <mcdonc> and that means there are three conflicting rootmost directives [13:46] <mcdonc> if you mentally substitute "inline" for "includeOverrides" it makes a little more sense
Maybe. It described the mechanism better, but includeOverrides conveys the intent. <shrug>
Sorry, not a criticism, just a personal observation. I assume I'm not wrong about the behavior I describe above?
[13:48] <mcdonc> override is exactly the wrong phrase to use in the name of this directive [13:51] <mcdonc> what it boils down to is that you never, ever really want to use includeOverrides except in your rootmost zcml file [13:51] <mcdonc> and probably not even there [13:51] <mcdonc> because you can get the same effect by typing the directives there by hand
Why would you want to type the directives by hand?
I *think* I'm of the opinion that libraries (or even "reusable applications") probably shouldn't need to use includeOverrides. You might disagree. I'd actually like to hear your take on that, because I'm only about 90% confident about that. ;-) I realize that not every application knows whether it's going to be reused or not, but, even so, it's always an option to cutnpaste the topmost ZCML from that application into a new file and disuse the old one. But if you take for granted the idea that libraries shouldn't use "includeOverrides", the place that it is actually potentially useful is in the "deployment" ZCML file (the topmost ZCML file that includes other ZCML from libraries and other application packages). But in this scenario, I already "own" the topmost ZCML file, and since it's deployment-specific, there's no sense in breaking out the included stuff into a separate file, because no one else will ever reuse it. It's all deployment-specific policy.
I've used includeOverrides in cases where:
1. I want to use 2 high-level components, one of which customizes the other, or in which
2. I wanted to organize overrides in various ways where I don't want to put everything in a root (or high-level file).
Of course, you can sometimes get the same effect in other ways. For example, if one high-level component overrides another, then the overriding component can just include the overridden one.
Jim