How Overlays are Selected

An overlay is a specially-named template that you can insert into a blueprint's template tree at any point. An overlay has the same unique name as its parent template, with a prefix of the form:

overlay.key.

where key is a string that identifies the overlay. A template with the unique name config.default.section.sports, for example, might have child overlays with the unique names overlay.dailynews.config.default.section.sports and overlay.worldcup.config.default.section.sports.

These overlays will be activated and actually modify the parent template if their keys (dailynews and worldcup respectively) match either:

• The name of the current publication, or

• A key specified in the wf.overlays parameter of the current section (the section to which the config.default.section.sports template is being applied). wf.overlays is a section parameter that can contain a comma-separated list of overlay keys, for example:

  wf.overlays=worldcup,northeast

An overlay with a key that matches a publication name is usually referred to as a publication-specific overlay, while an overlay with a key that does not match any publication name is referred to as an opt-in overlay, because it is only used in publications or sections where the editor has actively opted in by setting a section parameter.

If the current publication is called dailynews, then config.default.section.sports will be modified by applying overlay.dailynews.config.default.section.sports. If the current section has wf.overlays set as shown above, then it will be modified by applying overlay.worldcup.config.default.section.sports. If both conditions are met, then both overlays will be applied, but overlay.dailynews.config.default.section.sports will have the highest priority if the overlays conflict in any way (publication name matches are always given the highest priority).

If the config.default.section.sports template also had a northeast overlay (overlay.northeast.config.default.section.sports), then that would also be applied in this case, but it would have the lowest priority of all three overlays, since the keys in wf.overlays are specified in order of decreasing priority.