Package de.xima.fc.form.common.interfaces

Interface IFormTheme

  • All Known Implementing Classes:
    StaticFormTheme
    public interface IFormTheme
    Interface for a form theme. Form themes may come from different sources, all must satisfy this interface.

    A form theme is a collection of text and binary resources that are used to style a form, such as JavaScript files, CSS flies, fonts, and images. Users can select a form theme in the form designer; each form can have a different form theme. The form theme affects both the main web form and related pages such as HTML templates.

    All resources are grouped into resource contexts, a theme may have different files for different contexts. The resource context indicates where the resource is used. For example, files from the context WEB_FORM are included when rendering the HTML web form.

    Each form theme may also have a parent it inherits from. If a form theme has a parent, it inherits all resources from the parent. The parent form theme may itself have a parent. When a form theme inherits from a parent, all CSS and JavaScript files are merged together. For other resources such as images or fonts referenced in a CSS file, the file from the child overwrites the file from the parent.

    Since:
    8.3.0
    Author:
    XIMA MEDIA GmbH

    • Method Detail

      • containsFile

        boolean containsFile​(String context,
                     String fileName)
        Checks if the form theme contains a file with the given name. This method only checks files from this particular form theme, implementations must NOT attempt to check files from the parent theme (if any).
        Parameters:
        context - The context from which to retrieve the file. See EFormThemeResourceContext for common contexts. Other resource contexts may be used by plugins.
        fileName - The name of the file to check.
        Returns:
        True if the file exists, false otherwise.

      • getCssClasses

        Set<String> getCssClasses()
        Gets a list of CSS classes that should be added to the container element. The exact nature of the container element depends on how and where the form is used. You should not make any assumptions about the container element, other than that all relevant elements will be inside that container.

        You could e.g. use these CSS classes as part of a CSS selector to style the form.

        Returns:
        A list of CSS classes to add to the container element.

      • getDisplayName

        String getDisplayName​(Locale locale)
        Gets the display name of this theme in the given locale. The display name is a human-readable name that can be shown to the user, e.g. in the form designer.
        Parameters:
        locale - The locale for which to retrieve the display name.
        Returns:
        The display name of this theme in the given locale.

      • getFileInheritanceMode

        EFormThemeFileInheritanceMode getFileInheritanceMode​(String context,
                                                     String filePath)
        Controls the behavior when a IFormTheme and its parent both contain a file with the same name.
        Parameters:
        context - The context for which to retrieve the inheritance mode. See EFormThemeResourceContext for well-known contexts. Other resource contexts may be used by plugins.
        filePath - The path of the file to check. Should be one of the paths returned by getFilePaths.
        Returns:
        The inheritance mode for the given file.
        Throws:
        IllegalArgumentException - If the file does not exist.

      • getFilePaths

        Set<String> getFilePaths​(String context)
        Returns a list of all file paths in this form theme. This method only returns files from this particular form theme, implementations must NOT attempt to access files from the parent theme (if any).

        The order in which the file names are returned is irrelevant. If an order is required, the framework will sort the file names as needed.

        Note regarding file paths: Paths are used as-is, and passed on to other methods that require a file path. If you need case-insensitive file paths, you need to implement the other methods appropriately. Also, when a file name contains a forward slash, this is interpreted as a path separator and used e.g. when generating URLs. For example, a file named a/b/c.css can reference a file named a/b/d.png via background-image: url(../d.png).

        Parameters:
        context - The context for which to retrieve the file name. See EFormThemeResourceContext for common contexts. Other resource contexts may be used by plugins.
        Returns:
        A list of all file names in this form theme.

      • getGroupName

        String getGroupName​(Locale locale)
        Gets the localized group name of this theme in the given locale. The group name may be used on the UI, e.g. when displaying a select list of all available themes.
        Parameters:
        locale - The locale for which to retrieve the group name.
        Returns:
        The group name of this theme in the given locale.

      • getParentFormTheme

        FormThemeReference getParentFormTheme()
        The parent form theme from which this form theme inherits. If this form theme has no parent, this method returns null. When a form theme has a parent.
        Returns:
        The parent form theme, or null if this form theme has no parent.

      • isOfferCssClassesAsSuggestions

        boolean isOfferCssClassesAsSuggestions​(String context,
                                       String filePath)
        Controls the behavior in the form designer. Users can add custom classes to form elements. The form designer offers the CSS classes from themes as suggestions. If this method returns false, the CSS classes from this file (and all files it @imports) are not offered as suggestions.

        This method will only be called for CSS files.

        Parameters:
        context - The context of the CSS file to check. See EFormThemeResourceContext for common contexts. Other resource contexts may be used by plugins.
        filePath - The path of the file to check. Should be one of the paths returned by getFilePaths.
        Returns:
        True if the CSS classes from this file should be offered as suggestions, false otherwise.

      • openFile

        InputStream openFile​(String context,
                     String filePath)
              throws IOException
        Opens an input stream to the file with the given name. The file name must be one of the file names returned by getFilePaths(String) . This method only returns files from this particular form theme, implementations must NOT attempt to access files from the parent theme (if any).
        Parameters:
        context - The context from which to retrieve the file. See EFormThemeResourceContext for common contexts. Other resource contexts may be used by plugins.
        filePath - The path of the file to open. Should be one of path returned by getFilePaths(String).
        Returns:
        An input stream to the contents of the file.
        Throws:
        IOException - If the file could not be opened.

      • readTextFile

        default String readTextFile​(String context,
                            String filePath,
                            Charset charset)
                     throws IOException
        Reads a text file with the given name. The file name must be one of the file names returned by getFilePaths(String) . This method only returns files from this particular form theme, implementations must NOT attempt to access files from the parent theme (if any).
        Parameters:
        context - The context from which to retrieve the file. See EFormThemeResourceContext for common contexts. Other resource contexts may be used by plugins.
        filePath - The path of the file to open. Should be one of path returned by getFilePaths(String).
        charset - The character set to use when reading the file.
        Returns:
        An input stream to the contents of the file.
        Throws:
        IOException - If the file could not be opened.