Component lifecycle

A component is created once with new, then takes part in any number of requests until it is garbage collected with its page. In each request it may be rendered, and at the end of each request it is detached. Why the lifecycle looks like this is explained in What happens during a request.

Stages

A component that is not visible goes through configuration but not through preparing to render or rendering.

Hook methods in call order

The table lists every hook of Component in the order Wicket calls it during a request that renders a page. “Super” says where an override must call the super implementation. Wicket checks the ones marked “checked” and throws an IllegalStateException when the call is missing, with a message like onInitialize() in the hierarchy of com.example.HomePage has not called super.onInitialize().

Two more hooks run outside this order:

Order within the component tree

• onInitialize() runs on a container before its children.
• onConfigure() and onBeforeRender() run on a container before its children, because super.onBeforeRender() cascades to the children.
• Feedback components such as FeedbackPanel are prepared after all other components of the page, so they see the messages that onConfigure() and onBeforeRender() of other components report.
• renderHead() runs child first: children contribute before their parents, and the page contributes last, so a parent can override what a child contributed.
• onComponentTag() and onComponentTagBody() run in markup order. A container writes its open tag, then renders its children inside onComponentTagBody(), then writes its close tag.
• onAfterRender() runs on the children before their container.
• onDetach() runs on a container before its children.

Once rendering has started, a component cannot change: adding or replacing children throws an exception. Make such changes in onBeforeRender() before calling super, or in onConfigure().

When a request invokes a listener

When the request clicks a link or submits a form, Wicket loads the page and calls the listener (onClick(), onSubmit(), the onEvent() of an Ajax behavior) before any of the rendering hooks of that request. The listener sees the visibility and enabled state set during the previous render. After the listener, the page or the updated components go through configuration and rendering as above, and every touched component is detached at the end.

Hooks of a behavior

A behavior is called from the matching hook of the component it is added to:

Application-wide listeners

These listeners run for every component of the application. Register them in Application.init().

@Override
protected void init() {
    super.init();
    getComponentInitializationListeners().add(component ->
        log.debug("initialized {}", component.getPageRelativePath()));
}

Which hook to override

Set visibility in onConfigure(), not by overriding isVisible(), which Wicket calls many times per request:

add(new WebMarkupContainer("adminTools") {
    @Override
    protected void onConfigure() {
        super.onConfigure();
        setVisible(currentUser().isAdmin());
    }
});

Change the tag in onComponentTag():

add(new Label("title", titleModel) {
    @Override
    protected void onComponentTag(ComponentTag tag) {
        super.onComponentTag(tag);
        tag.setName("span");
        tag.put("class", "title");
    }
});

To reuse such a change on several components, use an AttributeModifier or a behavior instead; see Change a tag’s attributes.

Replace the body in onComponentTagBody():

add(new Label("status", statusModel) {
    @Override
    public void onComponentTagBody(MarkupStream markupStream, ComponentTag openTag) {
        if (isEnabledInHierarchy()) {
            super.onComponentTagBody(markupStream, openTag);
        } else {
            replaceComponentTagBody(markupStream, openTag, "(not available)");
        }
    }
});

Swap a child in onBeforeRender(), before the super call:

@Override
protected void onBeforeRender() {
    addOrReplace(showDetails ? new DetailsPanel("content") : new SummaryPanel("content"));
    super.onBeforeRender();
}