WysiwygManager (JCMS API)

java.lang.Object
- com.jalios.jcms.wysiwyg.WysiwygManager

All Implemented Interfaces:: JPropertiesListener

public final class WysiwygManager
extends java.lang.Object
implements JPropertiesListener

Field Summary

Fields
Modifier and Type	Field and Description
`static java.lang.String`	`CLEANHTML_CTXT_ATTRIBUTE_CLEANERS` HTML cleanup context map key used to store the `List` of `AttributeCleaner` used to sanitize the HTML attributes.
`static java.lang.String`	`CLEANHTML_CTXT_CLEANDOC` HTML cleanup context map key used to store the current JSoup Document obtained after cleaning process.
`static java.lang.String`	`CLEANHTML_CTXT_DATA` HTML cleanup context map key to use to store the Data instance for which HTML cleanup is being performed.
`static java.lang.String`	`CLEANHTML_CTXT_DIRTYDOC` HTML cleanup context map key used to store the current JSoup Document obtained after parsing of user input.
`static java.lang.String`	`CLEANHTML_CTXT_FIELDNAME` HTML cleanup context map key to use to store the name of the Data field for which HTML cleanup is being performed.
`static java.lang.String`	`CLEANHTML_CTXT_WHITELIST` HTML cleanup context map key used to store the current JSoup Whitelist being used to clean the HTML.
`static java.lang.String`	`FULLHTML_DEFAULT_REGEX` Default regular expression used to detect if a string is a full html content (with html/doctype/meta/head) or a "simpler" HTML fragment (containing only the body)

Fields inherited from interface com.jalios.util.JPropertiesListener
REVISION

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`static java.lang.String[]`	`cleanHtml(java.lang.String[] unsafeStrArray, java.util.Map<java.lang.String,java.lang.Object> contextMap)` Get safe HTML from untrusted input HTML, by parsing input HTML and filtering it through a white-list of permitted tags and attributes.
`static java.lang.String`	`cleanHtml(java.lang.String unsafeStr, java.util.Map<java.lang.String,java.lang.Object> contextMap)` Get safe HTML from untrusted input HTML, by parsing input HTML and filtering it through a white-list of permitted tags and attributes.
`static java.util.Map<java.lang.String,java.lang.Object>`	`getCleanHtmlContextMap(Data data, java.lang.String fieldName)` Retrieve a context map for use in cleanHtml method.
`WysiwygConfiguration`	`getConfiguration(java.lang.String configurationId)` Returns the `WysiwygConfiguration` from the given configuration ID
`java.util.Collection<WysiwygConfiguration>`	`getConfigurations()` Returns all `WysiwygConfiguration` available on the site
`static WysiwygManager`	`getInstance()`
`PluginConfiguration[]`	`getPluginConfigurations(java.lang.String configurationId)` Returns the `PluginConfiguration`s found in the Configuration corresponding to the given ID.
`org.jsoup.safety.Whitelist`	`getWhitelist()` Retrive the JSoup Whitelist used for HTML sanitization.
`static boolean`	`isHtmlFragment(java.lang.String str)` Check if the specified HTML is a "full html content" (with html/doctype/meta/head) or a "simpler" HTML fragment (containing only the body).
`java.util.List<AttributeCleaner>`	`loadAttributeCleaners(JProperties properties)` Initialize HTML attributes cleaner from properties.
`static org.jsoup.safety.Whitelist`	`loadWhitelist(JProperties properties)` Initialize a JSoup Whitelist from configuration available in the specified JProperties.
`void`	`propertiesChange(JProperties properties)` Invoked after properties have been modified in JCMS and save on disk.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - CLEANHTML_CTXT_DATA
```
public static final java.lang.String CLEANHTML_CTXT_DATA
```
    HTML cleanup context map key to use to store the Data instance for which HTML cleanup is being performed.
    
    See Also:
    
    Constant Field Values
  - CLEANHTML_CTXT_FIELDNAME
```
public static final java.lang.String CLEANHTML_CTXT_FIELDNAME
```
    HTML cleanup context map key to use to store the name of the Data field for which HTML cleanup is being performed.
    
    See Also:
    
    Constant Field Values
  - CLEANHTML_CTXT_WHITELIST
```
public static final java.lang.String CLEANHTML_CTXT_WHITELIST
```
    HTML cleanup context map key used to store the current JSoup Whitelist being used to clean the HTML.
    
    See Also:
    
    Constant Field Values
  - CLEANHTML_CTXT_ATTRIBUTE_CLEANERS
```
public static final java.lang.String CLEANHTML_CTXT_ATTRIBUTE_CLEANERS
```
    HTML cleanup context map key used to store the List of AttributeCleaner used to sanitize the HTML attributes.
    
    Since:
    
    jcms-10.0.0 / JCMS-6170
    
    See Also:
    
    Constant Field Values
  - CLEANHTML_CTXT_DIRTYDOC
```
public static final java.lang.String CLEANHTML_CTXT_DIRTYDOC
```
    HTML cleanup context map key used to store the current JSoup Document obtained after parsing of user input.
    
    See Also:
    
    Constant Field Values
  - CLEANHTML_CTXT_CLEANDOC
```
public static final java.lang.String CLEANHTML_CTXT_CLEANDOC
```
    HTML cleanup context map key used to store the current JSoup Document obtained after cleaning process.
    
    See Also:
    
    Constant Field Values
  - FULLHTML_DEFAULT_REGEX
```
public static final java.lang.String FULLHTML_DEFAULT_REGEX
```
    Default regular expression used to detect if a string is a full html content (with html/doctype/meta/head) or a "simpler" HTML fragment (containing only the body)
    
    See Also:
    
    Constant Field Values
- Method Detail
  - getInstance
```
public static final WysiwygManager getInstance()
```
  - propertiesChange
```
public void propertiesChange(JProperties properties)
```
    Description copied from interface: JPropertiesListener
    
    Invoked after properties have been modified in JCMS and save on disk.
    You cannot alter the value received in parameters.
    
    Specified by:
    
    propertiesChange in interface JPropertiesListener
    
    Parameters:
    
    properties - the properties which have been modified (may not contain all JCMS properties)
  - isHtmlFragment
```
public static boolean isHtmlFragment(java.lang.String str)
```
    Check if the specified HTML is a "full html content" (with html/doctype/meta/head) or a "simpler" HTML fragment (containing only the body).
    Method behavior can be customized by specifying a regular expression in property wysiwyg.full-html-regex to detect "full HTML".
    Implementation note :
    Empty HTML are considered to be fragments.
    This method implementation is a best effort to differentiate both variation, it is not meant to be perfect.
    
    Parameters:
    
    str - the HTML string to check
    
    Returns:
    
    true if HTML is a fragment, false otherwise.
    
    Since:
    
    jcms-9.0.5
  - getWhitelist
```
public org.jsoup.safety.Whitelist getWhitelist()
```
    Retrive the JSoup Whitelist used for HTML sanitization.
    
    Returns:
    
    a JSoup Whitelist object, never return null.
  - loadWhitelist
```
public static org.jsoup.safety.Whitelist loadWhitelist(JProperties properties)
```
    Initialize a JSoup Whitelist from configuration available in the specified JProperties. Several configuration can be simultaneously declared through properties wysiwyg.sanitize-html.whitelist.*..
```
 # Declare a configuration of whitelist
 # Is this whitelist enabled (if so, it will be added to other enabled whitelist configuration)
 wysiwyg.sanitize-html.whitelist.somewhitelist.enabled: false
 # HTML tags and attributes allowed by this whitelist
 wysiwyg.sanitize-html.whitelist.somewhitelist.tags:\
    a[href|title],\
    blockquote[cite],\
    strong
 # Protocols authorized for use for the specified tag and attribute
 wysiwyg.sanitize-html.whitelist.somewhitelist.protocols.a: href[ftp|http|https|mailto]
 wysiwyg.sanitize-html.whitelist.somewhitelist.protocols.blockquote: cite[http|https]
 
```
    Only the configurations that have been enabled will be used to create the Whitelist object.
    Parameters:
    
    properties - the JProperties from which configuration will be read to create the Whitelist
    
    Returns:
    
    a Whitelist object (never return null)
  - loadAttributeCleaners
```
public java.util.List<AttributeCleaner> loadAttributeCleaners(JProperties properties)
```
    Initialize HTML attributes cleaner from properties.
    Two types of cleaners are being loaded :
    - AttributeCleaner from properties wysiwyg.sanitize-html.attributes.*
    - InlineStyleCleaner from properties wysiwyg.sanitize-html.inline-styles.*
    You can declare several configuration simultaneously, each configuration using a unique identifier.
    
    HTML attribute cleaner.
```
 # Property allowing quick toggle of the enable status for this configuration
 wysiwyg.sanitize-html.attributes.somecleaner.enabled: true
 # Name of attribute being cleaned (optionnal if the cleaner name is the name of the attribute)
 wysiwyg.sanitize-html.attributes.somecleaner.attribute: class
 # Optionnal value delimiter if attribute may contains several value (as it it the case for the class attributes) 
 wysiwyg.sanitize-html.attributes.somecleaner.attribute: \\s
 # Set of authorized values, separated with space
 wysiwyg.sanitize-html.attributes.somecleaner.whitelist: wysiwyg
 # Regular expresion to consider value as whitelisted
 wysiwyg.sanitize-html.attributes.somecleaner.whitelist-regex: mysite-.*
 # Set of forbidden values, separated with space
 wysiwyg.sanitize-html.whitelist.somecleaner.blacklist: wysiwyg
 # Regular expresion to consider value as blacklisted
 wysiwyg.sanitize-html.attributes.somecleaner.blacklist-regex: ajax-.*
 # Default behavior applied for values which are not whitelisted or blacklisted (through list or regex).
 # Default is false: unknown values are considered as unauthorized.
 # Set to true to authorize unknown values
 wysiwyg.sanitize-html.attributes.somecleaner.default-behavior: true
 
```
    Inline styles cleaner is a variation of HTML attribute, for which validation is applied on css property contained in the style attribute.
```
 # Property allowing quick toggle of the enable status for this configuration
 wysiwyg.sanitize-html.inline-styles.mycleanerconf.enabled: true
 # Set of authorized values, separated with space
 wysiwyg.sanitize-html.inline-styles.mycleanerconf.whitelist: color text-align
 # Regular expresion to consider value as whitelisted
 wysiwyg.sanitize-html.inline-styles.mycleanerconf.whitelist-regex: font-.*
 # Set of forbidden values, separated with space
 wysiwyg.sanitize-html.whitelist.mycleanerconf.blacklist: position
 # Regular expresion to consider value as blacklisted
 wysiwyg.sanitize-html.inline-styles.mycleanerconf.blacklist-regex: ^(margin|padding).*$
 # Default behavior applied for values which are not whitelisted or blacklisted (through list or regex).
 # Default is false: unknown values are considered as unauthorized.
 # Set to true to authorize unknown values
 wysiwyg.sanitize-html.inline-styles.mycleanerconf.default-behavior: false
 
```
    Parameters:
    
    properties - the JProperties from which configuration will be read to create the cleaners
    
    Returns:
    
    a list of cleaner instanciated and configured from the specified properties. (never return null)
    
    Since:
    
    jcms-10.0.0 / JCMS-6170
  - cleanHtml
```
public static java.lang.String cleanHtml(java.lang.String unsafeStr,
                                         java.util.Map<java.lang.String,java.lang.Object> contextMap)
```
    Get safe HTML from untrusted input HTML, by parsing input HTML and filtering it through a white-list of permitted tags and attributes.
    Cleaning will occurs only if HTML sanitization is enabled with property wysiwyg.sanitize-html: true.
    
    Parameters:
    
    unsafeStr - input untrusted HTML (body fragment)
    
    contextMap - a contextual map used to provide additionnal information regarding sanization context
    
    Returns:
    
    safe HTML (body fragment), original unsafeStr is returned if sanitization is disabled.
  - cleanHtml
```
public static java.lang.String[] cleanHtml(java.lang.String[] unsafeStrArray,
                                           java.util.Map<java.lang.String,java.lang.Object> contextMap)
```
    Get safe HTML from untrusted input HTML, by parsing input HTML and filtering it through a white-list of permitted tags and attributes.
    Cleaning will occurs only if HTML sanitization is enabled with property wysiwyg.sanitize-html: true.
    
    Parameters:
    
    unsafeStrArray - array of untrusted input HTML (body fragment)
    
    contextMap - a contextual map used to provide additionnal information regarding sanization context
    
    Returns:
    
    array of safe HTML (body fragment), original array is returned if sanitization is disabled.
  - getCleanHtmlContextMap
```
public static java.util.Map<java.lang.String,java.lang.Object> getCleanHtmlContextMap(Data data,
                                                                                      java.lang.String fieldName)
```
    Retrieve a context map for use in cleanHtml method.
    
    Parameters:
    
    data - the Data for which the HTML cleanup is being performed
    
    fieldName - the name of the Data field for which the HTML cleanup is being performed
    
    Returns:
    
    a new Map, never return null.
  - getConfigurations
```
public java.util.Collection<WysiwygConfiguration> getConfigurations()
```
    Returns all WysiwygConfiguration available on the site
    
    Returns:
    
    a collection of WysiwygConfiguration object, never return null
  - getConfiguration
```
public WysiwygConfiguration getConfiguration(java.lang.String configurationId)
```
    Returns the WysiwygConfiguration from the given configuration ID
    
    Parameters:
    
    configurationId - ID of WISYWYG configuration
    
    Returns:
    
    WysiwygConfiguration object, or null if there is no configuration with the given ID
  - getPluginConfigurations
```
public PluginConfiguration[] getPluginConfigurations(java.lang.String configurationId)
```
    Returns the PluginConfigurations found in the Configuration corresponding to the given ID.
    
    Parameters:
    
    configurationId - ID of WISYWYG configuration
    
    Returns:
    
    Array of PluginConfigurations

Class WysiwygManager

Field Summary

Fields inherited from interface com.jalios.util.JPropertiesListener

Method Summary

Methods inherited from class java.lang.Object

Field Detail

CLEANHTML_CTXT_DATA

CLEANHTML_CTXT_FIELDNAME

CLEANHTML_CTXT_WHITELIST

CLEANHTML_CTXT_ATTRIBUTE_CLEANERS

CLEANHTML_CTXT_DIRTYDOC

CLEANHTML_CTXT_CLEANDOC

FULLHTML_DEFAULT_REGEX

Method Detail

getInstance

propertiesChange

isHtmlFragment

getWhitelist

loadWhitelist

loadAttributeCleaners

cleanHtml

cleanHtml

getCleanHtmlContextMap

getConfigurations

getConfiguration

getPluginConfigurations