Package org.zkoss.zk.ui

Interface Page

  • All Superinterfaces:
    ClassResolver, IdSpace, Scope
    All Known Implementing Classes:
    AbstractPage, PageImpl, VolatileIPage, VolatilePage
    public interface Page
extends IdSpace, Scope, ClassResolver
    A page. A desktop consists of a set of pages.

    When a ZK request is asking to render a new page, a new page is created and components that are created during this request all belong to this page.

    If a ZK request is asking an update, it must have at lease one UUID of a component (Component.getUuid(). From this UUID, we know which page it belongs and activate it to process the update.

    By activation, the system guarantees no concurrent access to pages and components (so you don't need use synchronized for them).

    Desktop

    In portal and some environments, a client request (e.g., ServletRequest) might consists of several ZK requests (AuRequest). While each ZK request might ask to create an independent page, all these pages are grouped as a desktop, such that they are activated and removed at the same time. Moreover, pages in the same desktop could communicate to each other (see Inter-page communication).

    A session, Session, might have multiple desktops of pages, Page, while a page belongs to exactly one session. A page, Page, might have many components, Component, while a component belongs to exactly one page.

    All components of the same desktop of pages are removed at the same time if a page become 'obsolete'.

    During each execution (${link Execution}), exactly one desktop of pages are locked (a.k.a., activated). Though an execution serves a client request (e.g., ServletRequest), a client request might consist of multiple ZK request (AuRequest). Each ZK request might target to a different page (of the same desktop).

    Inter-page Communication

    To do inter-page communication, you could do:

    1. Invoke methods of components from another page directly.
    2. Use Execution.postEvent(org.zkoss.zk.ui.event.Event) to post events to components from another page.

    They are the same as handling components from the same page. However, invoking method directly for components from another page has one restriction:
    It cannot create component.

    Author:
    tomyeh

    • Method Detail

      • getUuid

        java.lang.String getUuid()
        Returns UUID (universal unique ID) which is unique in the whole session. The UUID is generated automatically and immutable.

        It is mainly used for communication between client and server and you rarely need to access it.

      • getTitle

        java.lang.String getTitle()
        Returns the title of the desktop this page belongs to (and evaluate it if it contains an expression).

        Default: "".

      • setTitle

        void setTitle​(java.lang.String title)
        Sets the title of the desktop this page belongs to (it might contain an expression).

      • getStyle

        java.lang.String getStyle()
        Returns the CSS style of this page, or empty if not specified.

      • setStyle

        void setStyle​(java.lang.String style)
        Sets the CSS style of this page.

        Note: Unlike setTitle(java.lang.String), you can change the style only in the lifecycle of the loading page.

      • getViewport

        java.lang.String getViewport()
        Return the meta viewport of this page, or "auto" if not specified.

        Default: "auto".

        Since:
        6.5.0

      • setViewport

        void setViewport​(java.lang.String viewport)
        Sets the viewport of this page.
        Since:
        6.5.0

      • getRequestPath

        java.lang.String getRequestPath()
        Returns the request path of this page, or "" if not available.

        It is the same as the servlet path (javax.servlet.http.HttpServletRequest's getServletPath), if ZK is running at a servlet container.

        Note: Desktop.getRequestPath() returns the request path that causes the desktop to create. And, there might be multiple pages in the same desktop.

        See Also:
        Execution.getContextPath(), Desktop.getRequestPath()

      • isAlive

        boolean isAlive()
        Returns whether the desktop is still alive. It returns false once it is destroyed.
        Since:
        5.0.3
        See Also:
        PageCtrl.destroy()

      • getRoots

        java.util.Collection<Component> getRoots()
        Returns a readonly list of the root components.

      • getFirstRoot

        Component getFirstRoot()
        Returns the first root component.
        Since:
        3.5.2

      • getLastRoot

        Component getLastRoot()
        Returns the last root component.
        Since:
        3.5.2

      • getAttributes

        java.util.Map<java.lang.String,​java.lang.Object> getAttributes​(int scope)
        Returns all custom attributes of the specified scope. You could reference them directly, or by use of componentScope, spaceScope, pageScope, requestScope and desktopScope in zscript and EL.

        If scope is PAGE_SCOPE, it means custom attributes shared by components from the same page as this one's.

        If scope is DESKTOP_SCOPE, it means custom attributes shared by components from the same desktops as this one's.

        Parameters:
        scope - one of APPLICATION_SCOPE, SESSION_SCOPE, PAGE_SCOPE, REQUEST_SCOPE or DESKTOP_SCOPE.

      • getAttributes

        java.util.Map<java.lang.String,​java.lang.Object> getAttributes()
        Returns all custom attributes associated with this page.
        Specified by:
        getAttributes in interface Scope

      • getAttribute

        java.lang.Object getAttribute​(java.lang.String name,
                              int scope)
        Returns the value of the specified custom attribute in the specified scope.

        If scope is PAGE_SCOPE, it means custom attributes shared by components from the same page as this one's.

        If scope is DESKTOP_SCOPE, it means custom attributes shared by components from the same desktops as this one's.

        Parameters:
        scope - one of APPLICATION_SCOPE, SESSION_SCOPE, PAGE_SCOPE, REQUEST_SCOPE or DESKTOP_SCOPE.

      • getAttribute

        java.lang.Object getAttribute​(java.lang.String name)
        Returns the value of the specified attribute associated with this page.
        Specified by:
        getAttribute in interface Scope

      • hasAttribute

        boolean hasAttribute​(java.lang.String name,
                     int scope)
        Returns if an attribute exists.

        Notice that null is a valid value, so you need this method to really know if an attribute is defined.

        Since:
        5.0.0

      • hasAttribute

        boolean hasAttribute​(java.lang.String name)
        Returns if an attribute exists.

        Notice that null is a valid value, so you need this method to really know if an attribute is defined.

        Specified by:
        hasAttribute in interface Scope
        Since:
        5.0.0

      • setAttribute

        java.lang.Object setAttribute​(java.lang.String name,
                              java.lang.Object value,
                              int scope)
        Sets the value of the specified custom attribute in the specified scope.

        If scope is PAGE_SCOPE, it means custom attributes shared by components from the same page as this one's.

        If scope is DESKTOP_SCOPE, it means custom attributes shared by components from the same desktops as this one's.

        Parameters:
        scope - one of APPLICATION_SCOPE, SESSION_SCOPE, PAGE_SCOPE, REQUEST_SCOPE or DESKTOP_SCOPE.

      • setAttribute

        java.lang.Object setAttribute​(java.lang.String name,
                              java.lang.Object value)
        Sets the value of the specified custom attribute associated with this page.
        Specified by:
        setAttribute in interface Scope
        Parameters:
        value - the value.
        Returns:
        the previous value associated with the attribute, if any

      • removeAttribute

        java.lang.Object removeAttribute​(java.lang.String name,
                                 int scope)
        Removes the specified custom attribute in the specified scope.

        If scope is PAGE_SCOPE, it means custom attributes shared by components from the same page as this one's.

        If scope is DESKTOP_SCOPE, it means custom attributes shared by components from the same desktops as this one's.

        Parameters:
        scope - one of APPLICATION_SCOPE, SESSION_SCOPE, PAGE_SCOPE, REQUEST_SCOPE or DESKTOP_SCOPE.

      • removeAttribute

        java.lang.Object removeAttribute​(java.lang.String name)
        Removes the specified attribute custom associated with the page.
        Specified by:
        removeAttribute in interface Scope
        Returns:
        the previous value associated with the attribute, if any,

      • resolveClass

        java.lang.Class<?> resolveClass​(java.lang.String clsnm)
                         throws java.lang.ClassNotFoundException
        Resolves the class of the specified name. It first looks at ClassResolver (registered with addClassResolver(org.zkoss.lang.ClassResolver)). If not found, it looks at the current thread's class loader. And then, it looks for classes defined in any loaded interpreters (getLoadedInterpreters()).
        Specified by:
        resolveClass in interface ClassResolver
        Parameters:
        clsnm - the class name. It does not have to be a fully qualified name (i.e., it could have no package name), if the class is imported by use of the import directive (such as <?import class="com.foo.*"?>).
        Throws:
        java.lang.ClassNotFoundException - if the class is not found.
        Since:
        3.0.1

      • getZScriptFunction

        Function getZScriptFunction​(java.lang.String name,
                            java.lang.Class[] argTypes)
        Returns the function of the specified name by searching the loaded interpreters.
        Returns:
        the method, or null if not found
        Since:
        3.0.0
        See Also:
        getLoadedInterpreters()

      • getZScriptFunction

        Function getZScriptFunction​(Component comp,
                            java.lang.String name,
                            java.lang.Class[] argTypes)
        Returns the function of the specified name by searching the logical scope of the specified component in all the loaded interpreters.
        Parameters:
        comp - the component to start the search. If null, this method searches only the page's attributes. In other words, if comp is null, this method is the same as getZScriptFunction(String, Class[]).
        Since:
        3.0.0

      • getZScriptVariable

        java.lang.Object getZScriptVariable​(java.lang.String name)
        Returns the value of the variable of the specified name by searching the loaded interpreters, if any.
        Returns:
        the value of the variable, or null if not found
        See Also:
        getLoadedInterpreters()

      • getZScriptVariable

        java.lang.Object getZScriptVariable​(Component comp,
                                    java.lang.String name)
        Returns the value of the variable of the specified name by searching the logical scope of the specified component in all the loaded interpreters, if any.
        Parameters:
        comp - the component as the context to look for the variable defined in an interpreter. If null, the context is assumed to be this page.
        Since:
        3.0.0

      • getXelVariable

        java.lang.Object getXelVariable​(java.lang.String name)
        Returns a variable that is visible to XEL expressions. It is a shortcut of getXelVariable(null, null, name, false).

        This method is mainly used to access special variable, such as request parameters (if this page is requested by HTTP).

        Since:
        3.0.0
        See Also:
        getXelVariable(XelContext, Object, Object, boolean)

      • getXelVariable

        java.lang.Object getXelVariable​(XelContext ctx,
                                java.lang.Object base,
                                java.lang.Object name,
                                boolean ignoreExec)
        Returns a variable that is visible to XEL expressions.

        Unlike getXelVariable(String), this method can utilize VariableResolverX if you'd like to retrieve a property of another object.

        Parameters:
        ctx - the XEL context
        base - the base object. If null, it looks for a top-level variable. If not null, it looks for a member of the base object (such as getter).
        name - the property to retrieve.
        ignoreExec - whether to ignore the current execution (Execution.getVariableResolver(). If true, it invokes only the variable resolvers define in this page (addVariableResolver(org.zkoss.xel.VariableResolver)). If false, it will first check the execution, so the implicit objects such as page and desktop will be resolved.
        Since:
        5.0.0
        See Also:
        getXelVariable(String)

      • addVariableResolver

        boolean addVariableResolver​(VariableResolver resolver)
        Adds a variable resolver that will be used to resolve a variable by getXelVariable(java.lang.String).

        The new added variable resolver has the higher priority.

        Note: the variables resolver by the specified resolver are accessible to both zscript and EL expressions.

        Returns:
        whether the resolver is added successfully. Note: if the resolver was added before, it won't be added again and this method returns false.

      • removeEventListener

        boolean removeEventListener​(java.lang.String evtnm,
                            EventListener<? extends Event> listener)
        Removes an event listener.
        Returns:
        whether the listener is removed; false if it was never added.

      • isListenerAvailable

        boolean isListenerAvailable​(java.lang.String evtnm)
        Returns whether the event listener is available.

      • invalidate

        void invalidate()
        Invalidates this page to cause all components to redraw.

      • interpret

        void interpret​(java.lang.String zslang,
               java.lang.String script,
               Scope scope)
        Interprets a script in the specified scripting language in the context of the specified scope.
        Parameters:
        zslang - the scripting language. If null, getZScriptLanguage() is assumed.
        scope - the scope used as the context. Since a component is a scope, you can pass a component as the context. By context we mean the attribute of the scope, its space owner, spacer owner's space owner, page and desktop will be searched. If null, this page is assumed.
        Since:
        5.0.0

      • getInterpreter

        Interpreter getInterpreter​(java.lang.String zslang)
        Returns the interpreter of the specified scripting language.

        The interpreter will be loaded and initialized, if it is not loaded yet.

        Parameters:
        zslang - the scripting language. If null, getZScriptLanguage() is assumed.
        Throws:
        InterpreterNotFoundException - if not found.

      • getLoadedInterpreters

        java.util.Collection<Interpreter> getLoadedInterpreters()
        Returns all loaded interpreters.

      • getZScriptLanguage

        java.lang.String getZScriptLanguage()
        Returns the default scripting language which is assumed when a zscript element doesn't specify any language.
        Returns:
        the default scripting language, say, Java. Never null.

      • isComplete

        boolean isComplete()
        Returns if this page is a complete page. By complete we mean the page has everything that the client expects. For example, for HTML browsers, the page will generate the HTML, HEAD and BODY tags.

        It is meaningful only if it is the top-level page (i.e., not included by the include component).

        Default: false. It means ZK loader will enclose the page content with HTML/HEAD/BODY if necessary (such as not included by other Servlet).

        If you have a page that has a complete HTML page and it is included by other page, you have to specify the complete flag to be true.

        Since:
        3.0.4

      • setComplete

        void setComplete​(boolean complete)
        Sets if the page is a complete page.

        Default: false. It means a page is complete if and only if it is not included by other page.

        Parameters:
        complete - whether the page is complete. If true, this page is assumed to be complete no matter it is included or not. If false, this page is assumed to be complete if it is not included by other page.
        Since:
        3.0.4
        See Also:
        isComplete()

      • getFunctionMapper

        FunctionMapper getFunctionMapper()
        Returns the function mapper for resolving XEL functions, or null if not available. The function mapper represents all function mappers being added.
        Since:
        3.0.0

      • addFunctionMapper

        boolean addFunctionMapper​(FunctionMapper mapper)
        Adds the function mapper in addition to the current one.

        The new added function mapper has the higher priority. getFunctionMapper() will return the new

        Parameters:
        mapper - the new function mapper (null to ignore).

      • getLanguageDefinition

        LanguageDefinition getLanguageDefinition()
        Returns the language definition that this page belongs to (never null).

      • addTemplate

        void addTemplate​(java.lang.String name,
                 Template template)
        Adds page scope template
        Parameters:
        name -
        template -
        Since:
        8.0.0

      • removeTemplate

        void removeTemplate​(java.lang.String name)
        Removes page scope template
        Parameters:
        name -
        Since:
        8.0.0

      • getTemplate

        Template getTemplate​(java.lang.String name)
        Gets page scope template by name
        Parameters:
        name -
        Since:
        8.0.0