senselogic.sitevision.api.webresource.webcontent

Interface WebContentUtil

@Requireable(value="WebContentUtil")
public interface WebContentUtil

Utility interface for content manipulation of a sv:page, sv:article or a sv:template.

The provided HTML content is converted to Sitevision text, table and image portlets. It is also possible to specify that a horizontal or a vertical layout should be created. Class and styles can be specified. A class must correspond to a Sitevision site font or exists in an external CSS to have any effect. It is possible to specify a name of the subsequent portlet by using a named anchor (<a name="the_name_of_the_portlet"></a>). The name of a layout can also be specified by adding a name attribute to the layout div, se examples below.

Note! Content is per default considered as "text". This means that all content will be put in a single text portlet until the html code indicates something else. An indication can be any of the following:

• a layout is specified (a layout will be created)
• a named anchor is specified (a new portlet with that name will be created)
• content of another type is encountered (i.e. html for an image or a table)

Below are some detailed examples that should explain the format more precise:

Image portlet: Image references are resolved against the images on local page repository and fall-backs to the image repository.

Example 1: an image portlet with name "anImage" is created.

    <a name="anImage" /><img src="logo.jpg" />
 

Example 2: an image portlet is created with alt text and class. Sitevision will decide the name of the portlet.

    <img alt="Sitevision AB logo" class="aClass" src="templates/sitevision_logo.png" />
 

Table portlet: Table summary and table caption are optional. Table headings (th) will be recognized. A style attribute containing the css property text-align (left, right or center) and background-color will be recognized for table cells (td/th). Note that the background-color property value must start with a hash and match a color that exists on the site (for example #FFFFFF).

Example: a table portlet with two columns and one row is created.

      <table summary="This is an example table">
      <caption>A caption</caption>
         <tr>
            <th>A header</th>
            <th>Another header</th>
         </tr>
         <tr>
            <td>A cell</td>
            <td style="text-align:right">Another cell</td>
         </tr>
      </table>
 

Text portlet: All subsequent text content (i.e. not images or tables) will be placed in a text portlet. It is possible to create links and to provide style and class information to text sections. Links will be resolved to real / internal Sitevision pages if possible. Links to files and images will be resolved from the local image / file repositories and fall-back to the site image / file repository. Text sections specified with <em> or <i> will be handled as emphasized and sections specified with <strong> or <b> will be handled as strong.

Example 1: a text portlet with name "aText" containing text and a link.

       <div>
          <a name="aText" />
          <p>What a <em>nice</em> content management and <a href="/portal.html">portal</a> solution I have
             built today.</p>
       </div>
 

Example 2: two text portlets, one header and one body like text.

       <h2 title="aDecoration">Welcome</h2>
       <div>
          <a name="aText" />
          <p>Welcome to the Sitevision days!</p>
       </div>
 

Layouts: by specifying a div with the attribute layout horizontal or vertical a layout can be created. It is also possible to specify name of the layout and a decoration. Note that the decoration must be a Sitevision site decoration. If both decoration and style is specified the style information will be ignored.

• horizontal - Left-to-right layouting, i.e. a Horizontal/Column layout will be created
• vertical - Top-to-bottom layouting, i.e. a Vertical/Row layout will be created

Example 1: create a horizontal layout with decoration "aDecoration" and name "aName".

       <div layout="horizontal" decoration="aDecoration" name="aName">
          <!-- layout content -->
          ...
       </div>
 

Example 2: create vertical layout with style information and name "aName".

       <div layout="vertical" style="margin: 10px; border: thin solid black" name="aName">
          <!-- layout content -->
          ...
       </div>
 

Here is a more extensive example

       <a name="aHeader" />
       <h2 title="aH2SiteFont">Welcome to Sitevision</h2>
       <img name="anImage" alt="Sitevision AB logo" class="aClass" src="templates/sitevision_logo.png" />
       <div layout="horizontal" decoration="aSiteDecoration" name="aHorizontalLayout">
          <a name="aText" />
          <p class="aTextSiteFont">
             <strong>Sitevision AB</strong> is the company behind the CMS and portal system <em>Sitevision</em>
          </p>
          <div layout="vertical" style="border: thin solid black" name="aVerticalLayout">
             <a name="aText" />
             <p>The table displays the ...</p>
             <a name="aTable" />
             <table summary="This is a data table">
             <caption>Table of data</caption>
                <tr>
                   <th>Time</th>
                   <th>Value</th>
                </tr>
                <tr>
                   <td>1.001</td>
                   <td>Aaaabb+</td>
                </tr>
                <tr>
                   <td>2.22</td>
                   <td>Addabb+++</td>
                </tr>
             </table>
          </div>
       </div>
 

Which creates the following content structure:

     |--aHeader (text portlet)
     |--anImage (image portlet)
     |--aText (text portlet)
     |--aHorizontalLayout (layout)
       |--aText (text portlet)
       |--aVerticalLayout (layout)
          |--aText (text portlet)
          |--aTable (table portlet)
 

An instance of the Sitevision class implementing this interface can be obtained via Utils.getWebContentUtil(). See Utils for how to obtain an instance of the Utils interface.

Since:

Sitevision 2.6.2

Author:

Mikael Wikblom

Method Summary

Modifier and Type	Method and Description
void	appendContent(Node aNode, Map<String,String> aContent) Append the content to the existing node.
void	appendContent(Node aNode, String aContent) Appends the content to the existing node.
void	appendContentWithRawHtml(Node aNode, Map<String,String> aContent) Appends raw HTML (a HTML portlet is created) to the existing content of a node.
void	appendContentWithRawHtml(Node aNode, String aContent) Appends raw HTML (a HTML portlet is created) to the existing content of a node.
String	resolveToResourceURL(Node aNode, String aUnresolvedURL) Resolves an unresolved URL to a resource (potentially needed for all resource references in HTML content that later is updated or appended as raw HTML).
void	updateContent(Node aNode, Map<String,String> aContent) Alters the content of a sv:page, sv:article or a sv:template.
void	updateContent(Node aNode, String aContent) Alters the content of a sv:page, sv:article or a sv:template.
void	updateContentWithRawHtml(Node aNode, Map<String,String> aContent) Alters the content of a sv:page, sv:article or a sv:template with raw HTML (a HTML portlet is created).
void	updateContentWithRawHtml(Node aNode, String aContent) Alters the content of a sv:page, sv:article or a sv:template with raw HTML (a HTML portlet is created).

Method Detail

updateContent

void updateContent(Node aNode,
                   String aContent)
            throws ConstraintViolationException,
                   RepositoryException

Alters the content of a sv:page, sv:article or a sv:template.

If an invalid node type is specified a IllegalArgumentException is thrown. The page content is specified as a HTML string used to generate a portlet structure in the first layout available. The provided content is converted to Sitevision text, table and image modules. It is also possible to specify that a horizontal or a vertical layout should be created.

Note that the content (i.e portlets and layouts) of the first layout will be replaced, not appended.

The current user must be authorized to alter the node or a ConstraintViolationException is thrown.

If no node or no content is specified a NullPointerException is thrown.

Parameters:

aNode - aNode the node that will be altered, typically a node with primary node type sv:page or sv:article. May not be null and may not be the site page.

aContent - the HTML content. May not be null

Throws:

ConstraintViolationException - if the current user is not allowed to alter the node

RepositoryException - if something else goes wrong

See Also:

PermissionUtil.hasEffectiveWritePermission(Node, Node)

updateContent

void updateContent(Node aNode,
                   Map<String,String> aContent)
            throws ConstraintViolationException,
                   RepositoryException

Alters the content of a sv:page, sv:article or a sv:template.

If an invalid node type is specified a IllegalArgumentException is thrown. The page content is specified using the content map containing keys corresponding to layout names (e.g. "mittenspalt") on the page and values containing the HTML used to generate a portlet structure in the layout. The provided content is converted to Sitevision text, table and image modules. It is also possible to specify that a horizontal or a vertical layout should be created.

The names of the content map must correspond to layout names on the page.

Note that the content of the specified layouts (i.e portlets and layouts) will be replaced, not appended.

The current user must be authorized to alter the node or a ConstraintViolationException is thrown.

If no node or no content is specified a NullPointerException is thrown.

Parameters:

aNode - the node that will be altered, typically a node with primary node type sv:page or sv:article. May not be null and may not be the site page.

aContent - a map containing the HTML content. The keys must correspond to layout names on the node. May not be null

Throws:

ConstraintViolationException - if the current user is not allowed to alter the node

RepositoryException - if something else goes wrong

See Also:

PermissionUtil.hasEffectiveWritePermission(Node, Node)

updateContentWithRawHtml

void updateContentWithRawHtml(Node aNode,
                              String aContent)
                       throws NullPointerException,
                              IllegalArgumentException,
                              ConstraintViolationException,
                              RepositoryException

Alters the content of a sv:page, sv:article or a sv:template with raw HTML (a HTML portlet is created).

Note! This method creates a single HTML portlet that contains all supplied content. This method is intended to be used as a temporary solution when the proper updateContent(javax.jcr.Node, java.util.Map) and updateContent(javax.jcr.Node, String) methods for some reason can't be used. Typically when converting badly formatted legacy CMS data into Sitevision content. I.e. this method enables creation of content that later on ought to be manually converted to proper Sitevision portlets.

Note! Content is treated as-is, hence no internal links or references to local resources will be resolved as with the updateContent(javax.jcr.Node, java.util.Map) and updateContent(javax.jcr.Node, String) methods. The resolveToResourceURL(javax.jcr.Node, String) can be used to manually try to resolve "old" resource url to a "new" Sitevision resource url.

Parameters:

aNode - the node that will be altered, typically a node with primary node type sv:page or sv:article. May not be null and may not be the site page

aContent - the HTML content. May not be null

Throws:

NullPointerException - if aNode is null or if aContent is null

IllegalArgumentException - if aNode is of invalid type

ConstraintViolationException - if current user is not allowed to alter aNode

RepositoryException - if something else goes wrong

Since:

Sitevision 3.6

See Also:

PermissionUtil.hasEffectiveWritePermission(Node, Node)

updateContentWithRawHtml

void updateContentWithRawHtml(Node aNode,
                              Map<String,String> aContent)
                       throws NullPointerException,
                              IllegalArgumentException,
                              ConstraintViolationException,
                              RepositoryException

Alters the content of a sv:page, sv:article or a sv:template with raw HTML (a HTML portlet is created).

Note! This method creates a single HTML portlet for each supplied content entry. This method is intended to be used as a temporary solution when the proper updateContent(javax.jcr.Node, java.util.Map) and updateContent(javax.jcr.Node, String) methods for some reason can't be used. Typically when converting badly formatted legacy CMS data into Sitevision content. I.e. this method enables creation of content that later on ought to be manually converted to proper Sitevision portlets.

Note! Content is treated as-is, hence no internal links or references to local resources will be resolved as with the updateContent(javax.jcr.Node, java.util.Map) and updateContent(javax.jcr.Node, String) methods. The resolveToResourceURL(javax.jcr.Node, String) can be used to manually try to resolve "old" resource url to a "new" Sitevision resource url.

Parameters:

aNode - the node that will be altered, typically a node with primary node type sv:page or sv:article. May not be null and may not be the site page

aContent - a map containing the HTML content. The keys must correspond to layout names on the node. May not be null

Throws:

NullPointerException - if aNode is null or if aContent is null

IllegalArgumentException - if aNode is of invalid type

ConstraintViolationException - if current user is not allowed to alter aNode

RepositoryException - if something else goes wrong

Since:

Sitevision 3.6

See Also:

PermissionUtil.hasEffectiveWritePermission(Node, Node)

appendContent

void appendContent(Node aNode,
                   String aContent)
            throws NullPointerException,
                   IllegalArgumentException,
                   ConstraintViolationException,
                   RepositoryException

Appends the content to the existing node.

If an invalid node type is specified a IllegalArgumentException is thrown. The page content is specified as a HTML string used to generate a portlet structure in the first layout available. The provided content is converted to Sitevision text, table and image modules. It is also possible to specify that a horizontal or a vertical layout should be created.

Note that the content (i.e portlets and layouts) of the first layout will be appended, not replaced.

The current user must be authorized to alter the node or a ConstraintViolationException is thrown.

If no node or no content is specified a NullPointerException is thrown.

Parameters:

aNode - aNode the node that will be altered, typically a node with primary node type sv:page or sv:article. May not be null and may not be the site page.

aContent - the HTML content. May not be null

Throws:

NullPointerException - if aNode is null or if aContent is null

IllegalArgumentException - if aNode is of invalid type

ConstraintViolationException - if the current user is not allowed to alter the node

RepositoryException - if something else goes wrong

Since:

Sitevision 2022.08.1

See Also:

PermissionUtil.hasEffectiveWritePermission(Node, Node)

appendContent

void appendContent(Node aNode,
                   Map<String,String> aContent)
            throws NullPointerException,
                   IllegalArgumentException,
                   ConstraintViolationException,
                   RepositoryException

Append the content to the existing node.

If an invalid node type is specified a IllegalArgumentException is thrown. The page content is specified using the content map containing keys corresponding to layout names (e.g. "mittenspalt") on the page and values containing the HTML used to generate a portlet structure in the layout. The provided content is converted to Sitevision text, table and image modules. It is also possible to specify that a horizontal or a vertical layout should be created.

The names of the content map must correspond to layout names on the page.

Note that the content of the specified layouts (i.e portlets and layouts) will be appended, not replaced.

The current user must be authorized to alter the node or a ConstraintViolationException is thrown.

If no node or no content is specified a NullPointerException is thrown.

Parameters:

aNode - the node that will be altered, typically a node with primary node type sv:page or sv:article. May not be null and may not be the site page.

aContent - a map containing the HTML content. The keys must correspond to layout names on the node. May not be null

Throws:

NullPointerException - if aNode is null or if aContent is null

IllegalArgumentException - if aNode is of invalid type

ConstraintViolationException - if the current user is not allowed to alter the node

RepositoryException - if something else goes wrong

Since:

Sitevision 2022.08.1

See Also:

PermissionUtil.hasEffectiveWritePermission(Node, Node)

appendContentWithRawHtml

void appendContentWithRawHtml(Node aNode,
                              String aContent)
                       throws NullPointerException,
                              IllegalArgumentException,
                              ConstraintViolationException,
                              RepositoryException

Appends raw HTML (a HTML portlet is created) to the existing content of a node.

Note! This method creates a single HTML portlet that contains all supplied content and appends it to the existing content. This method is intended to be used as a temporary solution when the proper updateContent(javax.jcr.Node, java.util.Map) and updateContent(javax.jcr.Node, String) methods for some reason can't be used. Typically when converting badly formatted legacy CMS data into Sitevision content. I.e. this method enables creation of content that later on ought to be manually converted to proper Sitevision portlets.

Note! Content is treated as-is, hence no internal links or references to local resources will be resolved as with the updateContent(javax.jcr.Node, java.util.Map) and updateContent(javax.jcr.Node, String) methods. The resolveToResourceURL(javax.jcr.Node, String) can be used to manually try to resolve "old" resource url to a "new" Sitevision resource url.

Parameters:

aNode - the node that will be altered, typically a node with primary node type sv:page or sv:article. May not be null and may not be the site page

aContent - the HTML content. May not be null

Throws:

NullPointerException - if aNode is null or if aContent is null

IllegalArgumentException - if aNode is of invalid type

ConstraintViolationException - if current user is not allowed to alter aNode

RepositoryException - if something else goes wrong

Since:

Sitevision 3.6

See Also:

PermissionUtil.hasEffectiveWritePermission(Node, Node)

appendContentWithRawHtml

void appendContentWithRawHtml(Node aNode,
                              Map<String,String> aContent)
                       throws NullPointerException,
                              IllegalArgumentException,
                              ConstraintViolationException,
                              RepositoryException

Appends raw HTML (a HTML portlet is created) to the existing content of a node.

Note! This method creates a single HTML portlet that contains all supplied content and appends it to the existing content. This method is intended to be used as a temporary solution when the proper updateContent(javax.jcr.Node, java.util.Map) and updateContent(javax.jcr.Node, String) methods for some reason can't be used. Typically when converting badly formatted legacy CMS data into Sitevision content. I.e. this method enables creation of content that later on ought to be manually converted to proper Sitevision portlets.

Note! Content is treated as-is, hence no internal links or references to local resources will be resolved as with the updateContent(javax.jcr.Node, java.util.Map) and updateContent(javax.jcr.Node, String) methods. The resolveToResourceURL(javax.jcr.Node, String) can be used to manually try to resolve "old" resource url to a "new" Sitevision resource url.

Parameters:

aNode - the node that will be altered, typically a node with primary node type sv:page or sv:article. May not be null and may not be the site page

aContent - a map containing the HTML content. The keys must correspond to layout names on the node. May not be null

Throws:

NullPointerException - if aNode is null or if aContent is null

IllegalArgumentException - if aNode is of invalid type

ConstraintViolationException - if current user is not allowed to alter aNode

RepositoryException - if something else goes wrong

Since:

Sitevision 3.6

See Also:

PermissionUtil.hasEffectiveWritePermission(Node, Node)

resolveToResourceURL

String resolveToResourceURL(Node aNode,
                            String aUnresolvedURL)
                     throws NullPointerException,
                            IllegalArgumentException

Resolves an unresolved URL to a resource (potentially needed for all resource references in HTML content that later is updated or appended as raw HTML).

Note! HTML content is treated as-is when using the appendContentWithRawHtml(javax.jcr.Node, java.util.Map), appendContentWithRawHtml(javax.jcr.Node, String), updateContentWithRawHtml(javax.jcr.Node, java.util.Map) or updateContentWithRawHtml(javax.jcr.Node, String). Hence no internal links or references to local resources will be resolved as with the updateContent(javax.jcr.Node, java.util.Map) and updateContent(javax.jcr.Node, String) methods. This method can be used to manually try to resolve "old" resource url to a "new" Sitevision resource url.

Parameters:

aNode - the node that aUnresolvedURL should be resolved for, typically a node with primary node type sv:page or sv:article. May not be null and may not be the site page

aUnresolvedURL - an unresolved URL

Returns:

the potentially resolved URL

Throws:

NullPointerException - if aNode is null or if aUnresolvedURL is null

IllegalArgumentException - if aNode is of invalid type

Since:

Sitevision 3.6