Package ch.ivyteam.ivy.htmldialog

Interface IHtmlDialogContext

  • public interface IHtmlDialogContext

    The IHtmlDialogContext specifies the interface of the ivy.html environment variable.

    This environment variable / interface provides methods to generate form controls, build links, format process attributes and many other useful things for HTML process pages. All these methods will mostly be used as macros inside process pages
    (e.g. <a href="<%=ivy.html.ref("LinkA.ivp")%>">My Link</a>)

    Use the HtmlDialogContextFactory to create a new object that implements this interface

    Since:
    15.11.2007
    See Also:
    HtmlDialogContextFactory, HtmlDialogContext
    API:
    This is a public API.

    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      String applicationHomeRef()
      Returns the URL to the application home.
      String coref​(IContentObject co)
      Returns the reference to the specified content object for download (empty string, if co is null or not downloadable).
      String coref​(String cmsUri)
      Returns the reference to the specified content object URI for download (empty string, if co does not exist or is not downloadable).
      String escape​(Object obj)
      Does format the object with the default format and then escape the characters in a String using HTML entities.
      String escape​(String str)
      Escapes the characters in a String using HTML entities.
      String fileref​(File file)
      Returns the url to the specified file for download (empty string if file is null).
      String fileref​(String path, boolean isTemporary)
      Returns the url to the specified file for download (empty string if path is null).
      String get​(String attributeName)
      Gets the default formatted and HTML-escaped value of the specified process attribute.
      String get​(String attributeName, String format)
      Gets the formatted and HTML-escaped value of the specified process attribute.
      String getCurrentContentPageUri()
      Gets the current content page cms uri if available.
      String getFormValue​(String attributeName)
      Gets the default formatted and HTML-escaped value of the specified process attribute for the use in an HTML form input field.
      String getFormValue​(String attributeName, String format)
      Gets the formatted and HTML-escaped value of the specified process attribute for the use in an HTML form input.
      Object getObject​(String attributeName)
      Gets the value object of the specified process attribute.
      String pageArchiveRef​(IPageArchive pageArchive)
      Returns the URL to the specified page archive.
      String pageArchiveRef​(IPageArchive pageArchive, ISession session)
      Returns the URL to the specified page archive.
      String processStartListRef()
      Returns the URL to the process start list.
      String ref​(String linkName)
      Returns the url to the specified process link.
      String ref​(String linkName, boolean useSecureProtocol)
      Returns the url to the specified process link.
      String startInFrameRef​(String startName)
      Returns the url to the specified process link.
      String startRef​(String startName)
      Returns the url to the specified process link.
      String taskListRef()
      Returns the URL to the task list.
      String taskStartInFrameRef​(ITask taskToStart)
      Gets a reference to start the specified task (empty string if task is null or not in a startable state).
      String taskStartRef​(ITask taskToStart)
      Gets a reference to start the specified task (empty string if task is null or not in a startable state).
      String wr​(String relativeWebContentUri)
      Creates a link to a file in the static webContent folder of the current project.

    • Method Detail

      • get

        String get​(String attributeName)
        Gets the default formatted and HTML-escaped value of the specified process attribute. The format depends on the formatting locale of the actual request ( IApplicationRequest.getFormattingLocale()). 
         E.g. english (en) or US (en_US) locale:
 ivy.html.get("in.date")               = "1/31/2000"
 ivy.html.get("in.time")               = "9:01:59"
 ivy.html.get("in.dateTime")           = "1/31/2000 9:01:59"
 ivy.html.get("in.number")             = "123456.789"
 ivy.html.get("in.notInitialized")     = ""
 ivy.html.get("in.invalid")            = ""
 
         E.g. switzerland (de_CH, fr_CH, it_CH) locale:
 ivy.html.get("in.date")               = "31.01.2000"
 ivy.html.get("in.time")               = "09:01:59"
 ivy.html.get("in.dateTime")           = "31.01.2000 09:01:59"
 ivy.html.get("in.number")             = "123456.789"
 ivy.html.get("in.notInitialized")     = ""
 ivy.html.get("in.invalid")            = ""
 
         E.g. UK (en_UK) locale:
 ivy.html.get("in.date")               = "31/01/2000"
 ivy.html.get("in.time")               = "09:01:59"
 ivy.html.get("in.dateTime")           = "31/01/2000 09:01:59"
 ivy.html.get("in.number")             = "123456.789"
 ivy.html.get("in.notInitialized")     = ""
 ivy.html.get("in.invalid")            = ""
 
         E.g. german (de) or germany (de_DE) locale:
 ivy.html.get("in.date")               = "31.01.2000"
 ivy.html.get("in.time")               = "09:01:59"
 ivy.html.get("in.dateTime")           = "31.01.2000 09:01:59"
 ivy.html.get("in.number")             = "123456,789"
 ivy.html.get("in.notInitialized")     = ""
 ivy.html.get("in.invalid")            = ""
        Parameters:
        attributeName - The name of the attribute to get (e.g. 'in.xhrm.employee.name')
        Returns:
        default formatted value of the specified process attribute or empty string if there is no value or the value is uninitialized or invalid
        API:
        This public API is available in IvyScript and Java. It has the visibility NOVICE.

      • get

        String get​(String attributeName,
           String format)
        Gets the formatted and HTML-escaped value of the specified process attribute.

        This method will only work correctly if invoked on a page request (i.e. when rendering a process page).

        Parameters:
        attributeName - the name of the attribute to get (e.g. 'in.xhrm.employee.name')
        format - the name of the format config or a pattern to format the attribute with.
        Returns:
        formatted value of the specified process attribute or empty string if not on a page
        API:
        This public API is available in IvyScript and Java. It has the visibility ADVANCED.

      • getObject

        Object getObject​(String attributeName)
        Gets the value object of the specified process attribute.

        This method will only work correctly if invoked on a page request (i.e. when rendering a process page).

        Parameters:
        attributeName - The name of the attribute to get (e.g. 'in.xhrm.employee.name')
        Returns:
        the specified attribute as Object or null if not on a page
        API:
        This public API is available in IvyScript and Java. It has the visibility ADVANCED.

      • ref

        String ref​(String linkName)
        Returns the url to the specified process link.

        This method will only work correctly if invoked on a page request (i.e. when rendering a process page).

        The protocol of the url will be the same as the protocol of the page request (i.e. if the page request uses https the generated url also uses https and if it uses http the generated url also uses http.)

        Parameters:
        linkName - the name of the process link (e.g. 'LinkA.ivp')
        Returns:
        encoded URL to the specified process link or empty string if not on a page
        See Also:
        ref(String, boolean)
        API:
        This public API is available in IvyScript and Java. It has the visibility NOVICE.

      • ref

        String ref​(String linkName,
           boolean useSecureProtocol)
        Returns the url to the specified process link.

        This method will only work correctly if invoked on a page request (i.e. when rendering a process page).

        The protocol of the url will be https if useSecureProtocol is true and http if false

        Parameters:
        linkName - the name of the process link (e.g. 'LinkA.ivp')
        useSecureProtocol - if true the generated url uses https. If false uses http.
        Returns:
        encoded URL to the specified process link or empty string if not on a page
        See Also:
        ref(String)
        API:
        This public API is available in IvyScript and Java. It has the visibility NOVICE.

      • fileref

        String fileref​(File file)
        Returns the url to the specified file for download (empty string if file is null).
        Parameters:
        file - the file to get an URL for
        Returns:
        encoded URL to the specified file or empty string if specified file is null
        API:
        This public API is available in IvyScript and Java. It has the visibility NOVICE.

      • fileref

        String fileref​(String path,
               boolean isTemporary)
        Returns the url to the specified file for download (empty string if path is null).
        Parameters:
        path - the path of the file (relative)
        isTemporary - if file is temporary
        Returns:
        encoded URL to the specified file or empty string if specified path is null
        API:
        This public API is available in IvyScript and Java. It has the visibility NOVICE.

      • taskStartRef

        String taskStartRef​(ITask taskToStart)
        Gets a reference to start the specified task (empty string if task is null or not in a startable state).
        Parameters:
        taskToStart - the task to get an URL for
        Returns:
        encoded URL to start the specified task or empty string if the specified task is not valid (either null or in a state that doesn't allow starting it)
        See Also:
        taskStartInFrameRef(ITask)
        API:
        This public API is available in IvyScript and Java. It has the visibility ADVANCED.

      • taskStartInFrameRef

        String taskStartInFrameRef​(ITask taskToStart)
        Gets a reference to start the specified task (empty string if task is null or not in a startable state). Start specified task within the Frame of the DefaultFramePage (if supported by the Workflow UI)
        Parameters:
        taskToStart - the task to get an URL for
        Returns:
        encoded URL to start the specified task in frame or empty string if the specified task is not valid (either null or in a state that doesn't allow starting it)
        See Also:
        taskStartRef(ITask)
        API:
        This public API is available in IvyScript and Java. It has the visibility ADVANCED.

      • startRef

        String startRef​(String startName)
        Returns the url to the specified process link.

        E.g. 'MyProcess/start.ivp' -> 'http://hostname/ivy/pro/myapp/MyProcess/1571D80B8D735240/start.ivp'

        The search scope is the current case's project or - if not available - the current project of the request and all of it's required projects.

        Parameters:
        startName - name of the process start (Format: ProcessName/startName.ivp) to get an URL for
        Returns:
        encoded URL to the process start with the specified name or empty string if no process start with such a name exists
        See Also:
        startInFrameRef(String)
        API:
        This public API is available in IvyScript and Java. It has the visibility NOVICE.

      • startInFrameRef

        String startInFrameRef​(String startName)
        Returns the url to the specified process link.

        E.g. 'MyProcess/start.ivp' -> 'http://hostname/ivy/pro/myapp/MyProcess/1571D80B8D735240/start.ivp?embedInFrame'

        The search scope is the current case's project or - if not available - the current project of the request and all of it's required projects. Start specified process within the Frame of the DefaultFramePage (if supported by the Workflow UI)

        Parameters:
        startName - name of the process start (Format: ProcessName/startName.ivp) to get an URL for
        Returns:
        encoded URL to the process start with the specified name or empty string if no process start with such a name exists
        See Also:
        startRef(String)
        API:
        This public API is available in IvyScript and Java. It has the visibility NOVICE.

      • coref

        String coref​(IContentObject co)
        Returns the reference to the specified content object for download (empty string, if co is null or not downloadable).
        Parameters:
        co - the co to get an URL for
        Returns:
        encoded URL to the given content object or empty string if the specified co is null or not downloadable
        API:
        This public API is available in IvyScript and Java. It has the visibility ADVANCED.

      • coref

        String coref​(String cmsUri)
        Returns the reference to the specified content object URI for download (empty string, if co does not exist or is not downloadable).
        Parameters:
        cmsUri - the uri of the content object to create an URL for
        Returns:
        encoded URL to the given content object or empty string if the specified co is null or not downloadable
        API:
        This public API is available in IvyScript and Java. It has the visibility NOVICE.

      • wr

        String wr​(String relativeWebContentUri)
   throws PersistencyException

        Creates a link to a file in the static webContent folder of the current project. This method is useful to refer to e.g. JavaScript extensions or other static web content. For images, banners and labels it is recommended to link to content management system entries.

        Only the current project's webContent folder will be searched. The webContent folders of any required projects will not be taken into consideration.

        Example: An argument such as myDir/myStyle.css will reference .../webContent/myDir/myStyle.css.

        Important Note: This method has visibility EXPERT because it is not really needed. You can address all webContent files of a project with a link that is relative to the current JSP page.

        Example: A link <a href="myDir/myStyle.css">MyLink</a> on a JSP page will have exactly the same effect as <a href="<%=ivy.html.wr("myDir/myStyle.css")%>">MyLink</a>. Obviously the version without macro is much simpler and better readable and thus recommended.

        Parameters:
        relativeWebContentUri - relative URI to a file in webContent folder, e.g. myDir/myStyle.css
        Returns:
        a valid URL reference to the file in your project's "webContent" folder
        Throws:
        PersistencyException - if anything goes wrong
        API:
        This public API is available in IvyScript and Java. It has the visibility EXPERT.

      • getCurrentContentPageUri

        String getCurrentContentPageUri()
        Gets the current content page cms uri if available.

        This method will only work correctly if invoked on a page request (i.e. when rendering a process page).

        Returns:
        cms uri of the current content page (e.g. "/ProcessPages/MyProcess/page1") or empty string if not on a page
        API:
        This public API is available in IvyScript and Java. It has the visibility NOVICE.

      • pageArchiveRef

        String pageArchiveRef​(IPageArchive pageArchive)
        Returns the URL to the specified page archive. It can be used to display the page that was archived in a web browser.
        Parameters:
        pageArchive - the page archive to get an URL for
        Returns:
        The URL to the specified page archive for display. Could be a empty string if not found.
        API:
        This public API is available in IvyScript and Java. It has the visibility ADVANCED.

      • pageArchiveRef

        String pageArchiveRef​(IPageArchive pageArchive,
                      ISession session)
        Returns the URL to the specified page archive. It can be used to display the page that was archived in a web browser.
        Additionally to the pageArchiveRef(IPageArchive) the returned link is extended with the given session informations, that the page archive could be executed with the permissions of the given session, as long as the given session exists. E.g. used to display page archive entries in a web browser outside a RIA context.
        Parameters:
        pageArchive - the page archive to get an URL for
        session - The session in which the request should be executed.
        Returns:
        The URL to the specified page archive for display. Could be a empty string if not found.
        API:
        This public API is available in IvyScript and Java. It has the visibility ADVANCED.

      • taskListRef

        String taskListRef()

        Returns the URL to the task list. The task list contains all tasks on which the currently logged in user can work.

        Consult the engine guide to learn how to customize the task list for your application.

        Returns:
        The URL to the task list.
        API:
        This public API is available in IvyScript and Java. It has the visibility NOVICE.

      • processStartListRef

        String processStartListRef()

        Returns the URL to the process start list. The process start list contains all processes which the currently logged in user can start.

        Consult the engine guide to learn how to customize the process start list for your application.

        Returns:
        The URL to the process start list.
        API:
        This public API is available in IvyScript and Java. It has the visibility NOVICE.

      • applicationHomeRef

        String applicationHomeRef()

        Returns the URL to the application home. The application home is the entry point to the application.

        Consult the engine guide to learn how to customize the application home page for your application.

        Returns:
        The URL to the application home page.
        API:
        This public API is available in IvyScript and Java. It has the visibility NOVICE.

      • escape

        String escape​(Object obj)

        Does format the object with the default format and then escape the characters in a String using HTML entities.

        For example:

        "bread" & "butter"

        becomes:

        &quot;bread&quot; &amp; &quot;butter&quot;

        Supports all known HTML 4.0 entities, including funky accents. Note that the commonly used apostrophe escape character (&apos;) is not a legal entity and so is not supported).

        Parameters:
        obj - the String to escape, may be null
        Returns:
        a new escaped String, null if null object input
        See Also:
        escape(String), StringEscapeUtils.escapeHtml4(String)
        API:
        This public API is available in IvyScript and Java. It has the visibility NOVICE.

      • escape

        String escape​(String str)

        Escapes the characters in a String using HTML entities.

        For example:

        "bread" & "butter"

        becomes:

        &quot;bread&quot; &amp; &quot;butter&quot;

        Supports all known HTML 4.0 entities, including funky accents. Note that the commonly used apostrophe escape character (&apos;) is not a legal entity and so is not supported).

        Parameters:
        str - the String to escape, may be null
        Returns:
        a new escaped String, null if null string input
        See Also:
        escape(Object), StringEscapeUtils.escapeHtml4(String)
        API:
        This public API is available in IvyScript and Java. It has the visibility NOVICE.

      • getFormValue

        String getFormValue​(String attributeName)

        Gets the default formatted and HTML-escaped value of the specified process attribute for the use in an HTML form input field. Line breaks will not be converted to <br> tags. The format depends on the formatting locale of the current request ( IApplicationRequest.getFormattingLocale()).

        Examples of the format can be seen in the documentation of the get(String) method. This method will only work correctly if invoked on a page request (i.e. when rendering a process page).

        Parameters:
        attributeName - The name of the attribute to get (e.g. 'in.xhrm.employee.name')
        Returns:
        Formatted value of the specified process attribute ready for the use in an HTML form input field or empty string if not on page
        API:
        This public API is available in IvyScript and Java. It has the visibility EXPERT.

      • getFormValue

        String getFormValue​(String attributeName,
                    String format)

        Gets the formatted and HTML-escaped value of the specified process attribute for the use in an HTML form input. It is formatted with the specified format (either the name of a config or a pattern). Line breaks will not be converted to <br> tags.

        In case the attribute is a Number and the format uses digit grouping, the thousands separators will be removed to ensure that the number can be parsed back after submitting the form.

        The formating depends on the formating locale of the request ( IApplicationRequest.getFormattingLocale()). This method will only work correctly if invoked on a page request (i.e. when rendering a process page).

        Parameters:
        attributeName - The name of the attribute to get (e.g. 'in.xhrm.employee.name')
        format - The name of the format config or a pattern to format the attribute with. If null then the default format will be used.
        Returns:
        Formatted value of the specified process attribute ready for the use in an HTML form input field or empty string if not on page
        API:
        This public API is available in IvyScript and Java. It has the visibility EXPERT.