| |
| This stage is reached each time a component is rendered, typically when a page is requested or when the component or one of its ancestors is refreshed via AJAX. |
| |
| === Method onConfigure |
| |
| Method _onConfigure()_ has been introduced in order to provide a good point to manage the component states such as its visibility or enabled state. This method is called on all components whose parent is visible. |
| |
| As stated in <<_hiding_or_disabling_a_component,chapter 6.1>>, _isVisible()_ and _isEnabled()_ are called multiple times when a page or a component is rendered, so it's highly recommended not to directly override these method, but rather to use _onConfigure()_ to change component states. On the contrary method _onBeforeRender_ (see the next paragraph) is not indicated for this task because it will not be invoked if component visibility is set to false. |
| |
| === Method onBeforeRender |
| |
| The most important hook method of this stage is probably _onBeforeRender()_. This method is called on all visible components before any of them are rendered. It is our last chance to change a component's state prior to rendering - no change to a component's state is allowed afterwards. |
| |
| If we want to add/remove child components this is the right place to do it. In the next example (project LifeCycleStages) we will create a page which alternately displays two different labels, swapping between them each time it is rendered: |
| |
| [source,java] |
| ---- |
| public class HomePage extends WebPage |
| { |
| private Label firstLabel; |
| private Label secondLabel; |
| |
| public HomePage(){ |
| firstLabel = new Label("label", "First label"); |
| secondLabel = new Label("label", "Second label"); |
| |
| add(firstLabel); |
| add(new Link<Void>("reload"){ |
| @Override |
| public void onClick() { |
| } |
| }); |
| } |
| |
| @Override |
| protected void onBeforeRender() { |
| if(contains(firstLabel, true)) |
| replace(secondLabel); |
| else |
| replace(firstLabel); |
| |
| super.onBeforeRender(); |
| } |
| } |
| ---- |
| |
| The code inside _onBeforeRender()_ is quite trivial as it just checks which label among _firstLabel_ and _secondLabel_ is currently inserted into the component hierarchy and it replaces the inserted label with the other one. |
| |
| This method is also responsible for invoking children _onBeforeRender()_. So if we decide to override it, we have to call _super.onBeforeRender()_. However, unlike _onInitialize()_, the call to superclass method should be placed at the end of method's body in order to affect children's rendering with our custom code. |
| |
| Please note that in the example above we can trigger the rendering stage pressing F5 key or clicking on link “reload”. |
| |
| WARNING: If we forget to call superclass version of methods _onInitialize()_ or _onBeforeRender()_, Wicket will throw an _IllegalStateException_ with the following message: + |
| `_java.lang.IllegalStateException: org.apache.wicket.Component has not been properly initialized. Something in the hierarchy of <page class name> has not called super.onInitialize()/onBeforeRender() in the override of onInitialize()/ onBeforeRender() method_` |
| |
| === Method renderHead |
| |
| This method gives all components the possibility to add items to the page header through its argument of type _org.apache.wicket.markup.head.IHeaderResponse_ |
| |
| === Method onRender |
| |
| This method does the actual rendering -- you will rarely have to implement it, since most components already contain a specific implementation to produce their markup. |
| |
| === Method onComponentTag |
| |
| Method _onComponentTag(ComponentTag)_ is called to process a component tag, which can be freely manipulated through its argument of type _org.apache.wicket.markup.ComponentTag_. For example we can add/remove tag attributes with methods _put(String key, String value)_ and _remove(String key)_, or we can even decide to change the tag or rename it with method _setName(String)_ (the following code is taken from project OnComponentTagExample): |
| |
| *Markup code:* |
| |
| [source,html] |
| ---- |
| <head> |
| <meta charset="utf-8" /> |
| <title></title> |
| </head> |
| <body> |
| <h1 wicket:id="helloMessage"></h1> |
| </body> |
| ---- |
| |
| *Java code:* |
| |
| [source,java] |
| ---- |
| public class HomePage extends WebPage { |
| public HomePage() { |
| add(new Label("helloMessage", "Hello World"){ |
| @Override |
| protected void onComponentTag(ComponentTag tag) { |
| super.onComponentTag(tag); |
| //Turn the h1 tag to a span |
| tag.setName("span"); |
| //Add formatting style |
| tag.put("style", "font-weight:bold"); |
| } |
| }); |
| } |
| } |
| ---- |
| |
| *Generated markup:* |
| |
| [source,html] |
| ---- |
| <head> |
| <meta charset="utf-8" /> |
| <title></title> |
| </head> |
| <body> |
| <span wicket:id="helloMessage" style="font-weight:bold">Hello World</span> |
| </body> |
| ---- |
| |
| Just like we do with _onInitialize_, if we decide to override _onComponentTag_ we must remember to call the same method of the super class because also this class may also customize the tag. Overriding _onComponentTag_ is perfectly fine if we have to customize the tag of a specific component, but if we wanted to reuse the code across different components we should consider to use a behavior in place of this hook method. |
| |
| We have already seen in <<_modifing_tag_attributes,chapter 6.2>> how to use behavior _AttributeModifier_ to manipulate the tag's attribute. In <<_enriching_components_with_behaviors,chapter 19.1>> we will see that base class _Behavior_ offers also a callback method named _onComponentTag(ComponentTag, Component)_ that can be used in place of the hook method _onComponentTag(ComponentTag)_. |
| |
| === Methods onComponentTagBody |
| |
| Method _onComponentTagBody(MarkupStream, ComponentTag)_ is called to process the component tag's body. Just like _onComponentTag_ it takes as input a _ComponentTag_ parameter representing the component tag. In addition, we also find a _MarkupStream_ parameter which represents the page markup stream that will be sent back to the client as response. |
| |
| _onComponentTagBody_ can be used in combination with the _Component_'s method _replaceComponentTagBody_ to render a custom body under specific conditions. For example (taken from project OnComponentTagExample) we can display a brief description instead of the body if the label component is disabled: |
| |
| [source,java] |
| ---- |
| public class HomePage extends WebPage { |
| public HomePage() { |
| |
| add(new Label("helloMessage", "Hello World"){ |
| @Override |
| protected void onComponentTagBody(MarkupStream markupStream, ComponentTag tag) { |
| |
| if(!isEnabled()) |
| replaceComponentTagBody(markupStream, tag, "(the component is disabled)"); |
| else |
| super.onComponentTagBody(markupStream, tag); |
| } |
| }); |
| } |
| } |
| ---- |
| |
| Note that the original version of _onComponentTagBody_ is invoked only when we want to preserve the standard rendering mechanism for the tag's body (in our example this happens when the component is enabled). |
| |
| === Methods onAfterRender |
| |
| Called on each rendered component immediately after it has been rendered - _onAfterRender()_ will even be called when rendering failed with an exception. |