[[#wd Lookup TitleRecipe26 ]]

Overview

ContextLookupRenderer (alias name 'Lookup') is one of the Renderers predefined by the Coast framework. This recipe explains when a ContextLookupRenderer might be handy and how it is used.

Preface

It is possible to call different sorts of Renderers directly from any HTML-template, and thereby to dynamically create some page content. Such direct calls typically contain the name of the Renderer to be used as well as the parameters required for that Renderer.

Unfortunately a direct call basically hard codes the Renderer to be used into the HTML-template. There are two flaws with this approach:

  1. You might be in a situation where your HTML-template could be readily used for different pages if only that part created by the Renderer changed depending on the context. However since it is hard coded into the HTML-template the Renderer cannot be easily exchanged.
  2. The same Renderer used for one page might be useful on different other pages as well. Now instead of copying the same code to all those pages, would it not be much better to define a building block that could then be used on all those occasions?

Purpose

As its name suggests a ContextLookupRenderer adds a level of indirection to the rendering process: The ContextLookupRenderer uses a symbolic name to dynamically locate a Renderer specification (including a Renderer name and respective parameters) in the current context. It then triggers execution of that Renderer. (When searching a Renderer specification in the current Context different stores contained in the Context are considered: 1.TmpStore, 2.RoleStore, 3.SessionStore, 4. configuration data of the current Page, 5. configuration data of the current Role.)

A ContextLookupRenderer thereby solves the two problems mentioned initially:

  1. The Renderer that is actually found and used may now depend on the current Context: Say you're using the symbolic name 'MyRenderer' as an argument for ContextLookupRenderer. By defining 'MyRenderer' differently in the configuration files of several Pages, you might still reuse the layout defined once in an HTML-template.
  2. A ContextLookupRenderer allows you to invoke Renderer specifications that are defined anywhere in the Context (e.g. some Page/Role configuration file). The same building block may be reused in different places.

Preconditions

  1. You need the Page - i.e. the respective Page configuration file - where you want to use the Renderer.
  2. A ContextLookupRenderer expects to find a valid Renderer specification - or nothing at all - under the slotname that it was given as an argument. (If nothing is found in the Context ContextLookupRenderer degenerates to a 'nop') Usually the referenced Renderer specification is defined in a configuration file (e.g. XxxRole.any or XxxPage.any)
  3. If you want to use ContextLookupRenderer by an alias name (e.g. Lookup) be sure to include that name in the Renderers section of Config.any:
    [[#wd DisplayAnythingRenderer {
    	/AnythingInfo {
    		"/Renderers {"
    		"	/ContextLookupRenderer { Lookup }"
    		"}"
    	}
    }]]
    

Steps to do:

  1. It is usually a good idea to do a bit of planning before rushing to the code writing part. Find - at least - answers to the following questions:

    - What is the structure of the pages I am trying to set up?
    - Which parts do I wish to reuse as building blocks for pages?
    - Which parts need to change under what circumstances?

  2. According to your findings - regarding those questions - define Renderer specification(s) in the Context (This is typically done by placing the Renderer specification in some configuration file. Eventhough it is of course possible to add a specification programmatically at runtime.. say by placing it in the TmpStore).


  3. Include a ContextLookupRenderer that references the Renderer specification in some HTML-template.

Remarks

Glossary

Related Topics

creating new Pages, creating Renderer specifications, using HTML-templates