Java Doc for Component.java in  » J2EE » wicket » wicket » Java Source Code / Java DocumentationJava Source Code and Java Documentation

• Identity - All Components must have a non-null id which is retrieved by calling getId(). The id must be unique within the MarkupContainer that holds the Component, but does not have to be globally unique or unique within a Page's component hierarchy.
• Hierarchy - A component has a parent which can be retrieved with getParent(). If a component is an instance of MarkupContainer, it may have children. In this way it has a place in the hierarchy of components contained on a given page. The Component.isAncestorOf(Component) method returns true if this Component is an ancestor of the given Component.
• Component Paths - The path from the Page at the root of the component hierarchy to a given Component is simply the concatenation with dot separators of each id along the way. For example, the path "a.b.c" would refer to the component named "c" inside the MarkupContainer named "b" inside the container named "a". The path to a component can be retrieved by calling getPath(). This path is an absolute path beginning with the id of the Page at the root. Pages bear a PageMap/Session-relative identifier as their id, so each absolute path will begin with a number, such as "0.a.b.c". To get a Component path relative to the page that contains it, you can call getPageRelativePath().
• LifeCycle - Components participate in the following lifecycle phases:
  • Construction - A Component is constructed with the Java language new operator. Children may be added during construction if the Component is a MarkupContainer.
  • Request Handling - An incoming request is processed by a protocol request handler such as WicketServlet. An associated Application object creates Session, Request and Response objects for use by a given Component in updating its model and rendering a response. These objects are stored inside a container called RequestCycle which is accessible via Component.getRequestCycle . The convenience methods Component.getRequest , Component.getResponse and Component.getSession provide easy access to the contents of this container.
  • Listener Invocation - If the request references a listener on an existing Component, that listener is called, allowing arbitrary user code to handle events such as link clicks or form submits. Although arbitrary listeners are supported in Wicket, the need to implement a new class of listener is unlikely for a web application and even the need to implement a listener interface directly is highly discouraged. Instead, calls to listeners are routed through logic specific to the event, resulting in calls to user code through other overridable methods. For example, the wicket.markup.html.form.IFormSubmitListener.onFormSubmitted method implemented by the Form class is really a private implementation detail of the Form class that is not designed to be overridden (although unfortunately, it must be public since all interface methods in Java must be public). Instead, Form subclasses should override user-oriented methods such as onValidate(), onSubmit() and onError() (although only the latter two are likely to be overridden in practice).
  • onBeginRequest - The Component.onBeginRequest method is called.
  • Form Submit - If a Form has been submitted and the Component is a FormComponent, the component's model is validated by a call to FormComponent.validate().
  • Form Model Update - If a valid Form has been submitted and the Component is a FormComponent, the component's model is updated by a call to FormComponent.updateModel().
  • Rendering - A markup response is generated by the Component via Component.render , which calls subclass implementation code contained in Component.onRender . Once this phase begins, a Component becomes immutable. Attempts to alter the Component will result in a WicketRuntimeException.
  • onEndRequest () - The Component.onEndRequest method is called.
• Component Models - The primary responsibility of a component is to use its model (an object that implements IModel), which can be set via Component.setModel(IModel model) and retrieved via Component.getModel , to render a response in an appropriate markup language, such as HTML. In addition, form components know how to update their models based on request information. Since the IModel interface is a wrapper around an actual model object, a convenience method Component.getModelObject is provided to retrieve the model Object from its IModel wrapper. A further convenience method, Component.getModelObjectAsString , is provided for the very common operation of converting the wrapped model Object to a String.
• Visibility - Components which have setVisible(false) will return false from isVisible() and will not render a response (nor will their children).
• Page - The Page containing any given Component can be retrieved by calling Component.getPage . If the Component is not attached to a Page, an IllegalStateException will be thrown. An equivalent method, Component.findPage is available for special circumstances where it might be desirable to get a null reference back instead.
• Session - The Page for a Component points back to the Session that contains the Page. The Session for a component can be accessed with the convenience method getSession(), which simply calls getPage().getSession().
• Locale - The Locale for a Component is available through the convenience method getLocale(), which is equivalent to getSession().getLocale().
• String Resources - Components can have associated String resources via the Application's Localizer, which is available through the method Component.getLocalizer . The convenience methods Component.getString(String key) and Component.getString(String keyIModel model) wrap the identical methods on the Application Localizer for easy access in Components.
• Style - The style ("skin") for a component is available through Component.getStyle , which is equivalent to getSession().getStyle(). Styles are intended to give a particular look to a Component or Resource that is independent of its Locale. For example, a style might be a set of resources, including images and markup files, which gives the design look of "ocean" to the user. If the Session's style is set to "ocean" and these resources are given names suffixed with "_ocean", Wicket's resource management logic will prefer these resources to other resources, such as default resources, which are not as good of a match.
• Variation - Whereas Styles are Session (user) specific, variations are component specific. E.g. if the Style is "ocean" and the Variation is "NorthSea", than the resources are given the names suffixed with "_ocean_NorthSea".
• AttributeModifiers - You can add one or more AttributeModifier s to any component if you need to programmatically manipulate attributes of the markup tag to which a Component is attached.
• Application, ApplicationSettings and ApplicationPages - The getApplication() method provides convenient access to the Application for a Component via getSession().getApplication(). The getApplicationSettings() method is equivalent to getApplication().getSettings(). The getApplicationPages is equivalent to getApplication().getPages().
• Feedback Messages - The Component.debug(String) , Component.info(String) , Component.warn(String) , Component.error(String) and Component.fatal(String) methods associate feedback messages with a Component. It is generally not necessary to use these methods directly since Wicket validators automatically register feedback messages on Components. Any feedback message for a given Component can be retrieved with Component.getFeedbackMessage .
• Page Factory - It is possible to change the way that Pages are constructed by overriding the Component.getPageFactory method, returning your own implementation of wicket.IPageFactory .
• Versioning - Pages are the unit of versioning in Wicket, but fine-grained control of which Components should participate in versioning is possible via the Component.setVersioned(boolean) method. The versioning participation of a given Component can be retrieved with Component.isVersioned .
• AJAX support- Components can be re-rendered after the whole Page has been rendered at least once by calling doRender().
  author:
     Jonathan Locke
  author:
     Chris Turner
  author:
     Eelco Hillenius
  author:
     Johan Compagner
  author:
     Juergen Donnerstag
  author:
     Igor Vaynberg (ivaynberg)

If enabling is authorized, a component may decide by itself (typically using it's enabled property) whether it is enabled or not.

There are two uses for this method:

• The 'normal' use is for controlling whether a component is rendered without having any effect on the rest of the processing.

The point of this function is to generate a unique id to make it easy to locate this component in the generated markup for post-wicket processing such as javascript or an xslt transform.

Note: The component must have been added (directly or indirectly) to a container with an associated markup file (Page, Panel or Border).

For component level re-render (e.g.

For component level re-render (e.g.

WARNING: DO NOT OVERRIDE THIS METHOD UNLESS YOU HAVE A VERY GOOD REASON FOR IT.

If enabling is authorized, a component may decide by itself (typically using it's enabled property) whether it is enabled or not. If enabling is not authorized, the given component is marked disabled, regardless its enabled property.

When a component is not allowed to be enabled (in effect disabled through the implementation of this interface), Wicket will try to prevent model updates too. This is not completely fail safe, as constructs like:

 User u = (User)getModelObject();
 u.setName("got you there!");
 

There are two uses for this method:

• The 'normal' use is for controlling whether a component is rendered without having any effect on the rest of the processing. If a strategy lets this method return 'false', then the target component and its children will not be rendered, in the same fashion as if that component had visibility property 'false'.
• The other use is when a component should block the rendering of the whole page. So instead of 'hiding' a component, what we generally want to achieve here is that we force the user to logon/give-credentials for a higher level of authorization. For this functionality, the strategy implementation should throw a AuthorizationException , which will then be handled further by the framework.

Modifications to the map returned don't change the tags attributes. It is just a copy.

Note: The component must have been added (directly or indirectly) to a container with an associated markup file (Page, Panel or Border). markup attributes

The point of this function is to generate a unique id to make it easy to locate this component in the generated markup for post-wicket processing such as javascript or an xslt transform.

Note: The component must have been added (directly or indirectly) to a container with an associated markup file (Page, Panel or Border). This TODO post 1.2 this restriction will be implicitly met after implementing 2.0's constructor change markup id of this component, which is the result of the call toComponent.getPageRelativePath() where the ':' character (theinternal path seperator of Wicket) are replaced by the '_'character.

For component level re-render (e.g. AJAX) please call Component.renderComponent() . Though render() does seem to work, it will fail for panel children.

For component level re-render (e.g. AJAX) please call Component.renderComponent(MarkupStream) . Though render() does seem to work, it will fail for panel children.
Parameters:
  markupStream -

Note: it is not necessary that the page has previously been rendered. But the component must have been added (directly or indirectly) to a container with an associated markup file (Page, Panel or Border).

Renders the component at the current position in the given markup stream. The method onComponentTag() is called to allow the component to mutate the start tag. The method onComponentTagBody() is then called to permit the component to render its body.
Parameters:
  markupStream - The markup stream

WARNING: DO NOT OVERRIDE THIS METHOD UNLESS YOU HAVE A VERY GOOD REASON FOR IT. OVERRIDING THIS MIGHT OPEN UP SECURITY LEAKS AND BREAK BACK-BUTTON SUPPORT.