Package com.github.bordertech.wcomponents

Interface WComponent

    • Field Detail

      • ID_CONTEXT_SEPERATOR

        static final String ID_CONTEXT_SEPERATOR
        The default id/name separator character.
        See Also:
        Constant Field Values

      • ID_FRAMEWORK_ASSIGNED_SEPERATOR

        static final String ID_FRAMEWORK_ASSIGNED_SEPERATOR
        The reserved character to prefix framework assigned ids.
        See Also:
        Constant Field Values

      • DEFAULT_APPLICATION_ID

        static final String DEFAULT_APPLICATION_ID
        The default application context id.
        See Also:
        Constant Field Values

      • DEFAULT_NO_ID

        static final String DEFAULT_NO_ID
        The default id name for components with no parent and no id name set.
        See Also:
        Constant Field Values

      • DEFAULT_INTERNAL_ID

        static final String DEFAULT_INTERNAL_ID
        The default internal id name for components with no parent.
        See Also:
        Constant Field Values

      • ID_VALIDATION_PATTERN

        static final String ID_VALIDATION_PATTERN
        User assigned IDs must start with a letter and followed by letters, digits or underscores.
        See Also:
        Constant Field Values

    • Method Detail

      • getInternalId

        String getInternalId()
        Returns:
        the internal identifier of this Component based on its position in the component tree.

      • getIdName

        String getIdName()
        Returns:
        the component identifier of this Component (if any).

      • setIdName

        void setIdName​(String idName)
        Set the component identifier of this Component (if any). Component identifiers must obey the following syntax restrictions:
        • Must not be a zero-length String.
        • First character must be a letter.
        • Underscore ('_') as the first character is reserved by the framework.
        • Subsequent characters must be a letter, a digit or an underscore ('_').

        The specified identifier must be unique among all the components that are descendents of the nearest ancestor Component that is an active NamingContextable.

        Parameters:
        idName - the id name

      • getName

        @Deprecated
String getName()
        Deprecated.
        No longer used. Use getId() instead.
        Retrieves the name for this WComponent.
        Specified by:
        getName in interface WebComponent
        Returns:
        the name for this WComponent in the current context.

      • getId

        String getId()
        Return an identifier for this component, generating one if necessary.

        The implementation must follow these steps in determining the Id:

        If has id name set: If no id name set:
        • If the component's parent is null, then let the ID be DEFAULT_NO_ID.
        • If has a parent, then let the ID prefix be parent.getId() or parent.getNamingContextID() + ID_CONTEXT_SEPERATOR if the parent is an active NamingContext. Then let the ID be prefix + generate unique id.
        Specified by:
        getId in interface WebComponent
        Returns:
        the id for this WComponent in the current context.

      • serviceRequest

        void serviceRequest​(Request request)

        This is the main entry point during request handling. Only the "top-level" component will have this method called - other components will have handleRequest(Request) called. For efficiency, only visible components are asked to handle the request.

        The basic workflow is:
        1. Collate the list of visible components, in depth-first order. Depth-first traversal is used to ensure that when a parent component's handleRequest method is called, all of its children have already handled the request and are in a stable state.
        2. Call handle request for each visible component found, in order.
        3. At this point, all the components should be in a stable state, and any runnables added using invokeLater(Runnable) will be invoked. These runnables can include e.g. Actions on buttons.

        Applications should not call this method directly.

        Specified by:
        serviceRequest in interface WebComponent
        Parameters:
        request - the request being responded to.

      • invokeLater

        void invokeLater​(Runnable runnable)

        Adds a runnable that will be processed after the completion of the current serviceRequest method. This method is intended to be called from subcomponents' handleRequest methods, to permit processing to continue once the entire WComponent tree has been updated from the incoming HTTP request.

        If this method is invoked more than once, each Runnable will be invoked in turn.

        Parameters:
        runnable - the Runnable to execute after the serviceRequest method has otherwise completed.

      • handleRequest

        void handleRequest​(Request request)
        Subclasses should override this method in order to provide specific request handling logic. For example, a text field may set its value to the value of a request parameter.
        Parameters:
        request - the request being responded to.

      • forward

        void forward​(String url)
        Applications can call this method during event handling to indicate that we should forward to a given url. The event handling will complete and the forwarding will take place before painting.
        Parameters:
        url - the URL to forward to

      • preparePaint

        void preparePaint​(Request request)
        Prepares this component and all child components for immediate painting (e.g. rendering to XML). Note that the parent's preparePaint method is called before the childrens'.
        Specified by:
        preparePaint in interface WebComponent
        Parameters:
        request - the request being responded to.

      • paint

        void paint​(RenderContext renderContext)
        Paints the component by rendering it in the given context.
        Specified by:
        paint in interface WebComponent
        Parameters:
        renderContext - the context to render to.

      • validate

        void validate​(List<Diagnostic> diags)

        The validate method should be called by an Action, or ValidatingAction at points in the application lifecycle where it makes sense to perform validation.

        No side effect of displaying error markers implied by this. This is a pure "function" except that it stores the results in the diags list.

        It is the responsibility of the validatable component to call any of its children that may also require validation.

        Parameters:
        diags - the list into which any validation diagnostics are added.

      • showErrorIndicators

        void showErrorIndicators​(List<Diagnostic> diags)

        This does not affect the diag list at all. The ValidatableComponent should visually mark any fields or blocks that have errors in the given diag list.

        It is the responsibility of the validatable component to call any of its children that may also be validatable.

        Parameters:
        diags - the list of current validation diagnostics.

      • showWarningIndicators

        void showWarningIndicators​(List<Diagnostic> diags)

        This does not affect the diag list at all. The ValidatableComponent should visually mark any fields or blocks that have warnings in the given diag list.

        It is the responsibility of the validatable component to call any of its children that may also be validatable. The default implemntation does nothing.

        Parameters:
        diags - the list of diagnostics for this component.

      • setLocked

        void setLocked​(boolean lock)

        The shared attributes of a component (and all its children) can be locked, preventing users/developers from making further updates. However, attribute values can still be updated on a per session basis.

        This method should normally never be called from application code.

        Parameters:
        lock - true to lock the component, false to unlock

      • isLocked

        boolean isLocked()
        Indicates whether this component is locked. If the component is locked, shared attribute values can not be updated.
        Returns:
        true if the component is locked, false if not.

      • isInitialised

        boolean isInitialised()
        Optionally use this flag to test if some arbitrary initialisation has been performed by this component.
        Returns:
        true if the component has been marked as initialised, false otherwise.
        See Also:
        setInitialised(boolean)

      • setInitialised

        void setInitialised​(boolean flag)
        Optionally use this flag to store whether some arbitrary initialisation has been performed by this component on the given session. This should normally only be used after the UI has been constructed.
        Parameters:
        flag - the initialised flag.

      • isValidate

        boolean isValidate()
        Indicates whether this component should take part in validation processing.
        Returns:
        true if this component is validateable, false if not.

      • setValidate

        void setValidate​(boolean flag)
        Sets whether this component should take part in validation processing.
        Parameters:
        flag - true if this component should be validated, false if not.

      • isVisible

        boolean isVisible()
        Indicates whether this component is visible. Invisible components are normally excluded from all event handling and painting.
        Returns:
        true if this component is visible, false if invisible.

      • setVisible

        void setVisible​(boolean visible)
        Sets the visibility of this component. Invisible components are normally excluded from all event handling and painting.
        Parameters:
        visible - true to set this component visible, false for invisible.

      • isHidden

        boolean isHidden()
        Indicates whether this component is hidden. Hidden components take part in event handling and painting, but are not visible on the client.
        Returns:
        true if this component is hidden, false if displayed.

      • hasTabIndex

        @Deprecated
boolean hasTabIndex()
        Deprecated.
        1.4 causes a11y issues, no replacement.
        Indicates whether this component has a tab index.
        Returns:
        false - For the moment, turn off the tab index feature and see what happens.

      • getTabIndex

        @Deprecated
int getTabIndex()
        Deprecated.
        1.4 causes a11y issues, no replacement.
        Returns:
        the tab index for this component.

      • getLabel

        WLabel getLabel()
        Returns:
        the label associated with this component, or null if there is no label.

      • setFocussed

        void setFocussed()
        Requests that this component be given keyboard focus when rendered.

      • reset

        void reset()
        Resets this component and its children to their initial state.

      • tidyUpUIContextForTree

        void tidyUpUIContextForTree()
        This method removes unnecessary component models from the user session for this component and all its descendants. A component model is deemed unnecessary when it has the same state as the component's default component model.

      • isDefaultState

        boolean isDefaultState()

        WComponents must implement this method in order to protect any session based information they store from being incorrectly removed by the tidyUpUIContextForTree() method.

        It is possible you can write a more exact check for the default state here than the method on the component model itself can provide.

        Returns:
        true if the component is in it's default state, otherwise false.

      • getParent

        Container getParent()
        Returns:
        the current parent of this component.

      • getTag

        @Deprecated
String getTag()
        Deprecated.
        Use WTemplate instead.
        Retrieves the tag used to identify this component in a Velocity template.
        Returns:
        the component's tag.

      • setTag

        @Deprecated
void setTag​(String tag)
        Deprecated.
        Use WTemplate instead.
        Sets the tag used to identify this component in a Velocity template.
        Parameters:
        tag - the component's tag to set.

      • getEnvironment

        Environment getEnvironment()
        Retrieves the environment for the current session. If there is no environment for the session, a dummy environment is returned.
        Returns:
        the environment for the user session.

      • setEnvironment

        void setEnvironment​(Environment environment)
        Sets the environment.
        Parameters:
        environment - the environment to set.

      • getHeaders

        Headers getHeaders()
        Retrieves the headers.
        Returns:
        the headers.

      • getBaseUrl

        String getBaseUrl()
        Exposes the base URL for this environment. Renderers can call this method to construct URIs to sub-resources. The baseurl is ultimately derived from com.github.bordertech.wcomponents.Environment
        Returns:
        the base URL

      • setAttribute

        void setAttribute​(String key,
                  Serializable value)
        Associates an arbitrary attribute with this component.
        Parameters:
        key - the attribute key.
        value - the attribute value.

      • getAttribute

        Serializable getAttribute​(String key)
        Retrieves an arbitrary attribute which has been previously associated with this component.
        Parameters:
        key - the attribute key.
        Returns:
        value the attribute value if set, otherwise null.

      • removeAttribute

        Serializable removeAttribute​(String key)
        Removes an arbitrary attribute.
        Parameters:
        key - the attribute key.
        Returns:
        the value for the attribute which was removed, or null if no attribute was found with the given key.

      • setToolTip

        void setToolTip​(String text,
                Serializable... args)
        Sets the component's tool tip. Note that not all components support displaying tool tips.
        Parameters:
        text - the tool tip text, using MessageFormat syntax.
        args - optional arguments for the message format string.

      • getToolTip

        String getToolTip()
        Retrieves the component's tool tip.
        Returns:
        the component's tool tip.

      • setAccessibleText

        void setAccessibleText​(String text,
                       Serializable... args)
        Deprecated.
        use setToolTip
        Sets the text used by screen readers to describe the component.
        Parameters:
        text - the screen reader text, using MessageFormat syntax.
        args - optional arguments for the message format string.

      • getAccessibleText

        String getAccessibleText()
        Deprecated.
        use getToolTip
        Retrieves the text used by screen readers to describe the component.
        Returns:
        the screen reader text.

      • setTrackingEnabled

        void setTrackingEnabled​(boolean track)
        Sets the flag if tracking is enabled for this component. This flag is used by isTracking().
        Parameters:
        track - set true if tracking is enabled for this component.

      • isTrackingEnabled

        boolean isTrackingEnabled()
        Returns true if tracking is enabled for this component.This flag is used by isTracking().
        Returns:
        true if tracking is enabled for this component.

      • isTracking

        boolean isTracking()
        Returns true if this component should be tracked.

        A component will only be tracked if setTrackingEnabled(boolean) is set true and the component has an id set via setIdName(String). If the id has not been set, then the id used for tracking will be dynamic and constantly changing which makes it useless for analysing.

        Returns:
        true if this component should be tracked.

      • setHtmlClass

        void setHtmlClass​(String className)
        Sets additional HTML class name string for this component. Multiple HTML class names may be added to an instance of a component using a space separated string. Some values in the HTML class name attribute are determined in the theme and are used for core functionality and styling.
        Parameters:
        className - the HTML class attribute's value to add to the component

      • setHtmlClass

        void setHtmlClass​(HtmlClassProperties className)
        Sets additional HTML class name for this component from a set of preset values.
        Parameters:
        className - the HTML class attribute's value to add to the component derived from the utility enum

      • addHtmlClass

        void addHtmlClass​(String className)
        Append value to the HTML class name for this component.
        Parameters:
        className - the HTML class attribute's value to add to the component

      • addHtmlClass

        void addHtmlClass​(HtmlClassProperties className)
        Append a value to the HTML class name for this component from a set of preset values.
        Parameters:
        className - the HTML class attribute's value to add to the component derived from the utility enum

      • getHtmlClass

        String getHtmlClass()
        Returns the HTML class name string to apply to a component. Some values in the HTML class name attribute are determined in the theme and are used for core functionality and styling. This method will only return class name values which are added in the application, it has no knowledge of theme's class names.
        Returns:
        the value to add to the HTML class attribute of the output component

      • getHtmlClasses

        Set getHtmlClasses()
        Returns:
        the HTML class list HashSet for this component

      • removeHtmlClass

        void removeHtmlClass​(String className)
        Remove a value from the set of HTML class name values added to the current component.
        Parameters:
        className - the value to remove

      • removeHtmlClass

        void removeHtmlClass​(HtmlClassProperties className)
        Remove a value from the set of HTML class name values added to the current component.
        Parameters:
        className - the property representing the value to remove