@sitevision/api 1.0.19 → 1.1.0-alpha.1

package/server/WebResourceFactory/index.d.ts

@@ -0,0 +1,66 @@
+import ArticleUtil from "../ArticleUtil";
+import FileUtil from "../FileUtil";
+import ImageUtil from "../ImageUtil";
+import LinkPageUtil from "../LinkPageUtil";
+import LinkTargetBuilder from "../LinkTargetBuilder";
+import PageUtil from "../PageUtil";
+
+/**
+ * Gets an instance of an article utility class
+ * @return an article utility class
+ */
+export function getArticleUtil(): ArticleUtil;
+
+/**
+ * Gets an instance of a file utility class
+ * @return a file utility class
+ */
+export function getFileUtil(): FileUtil;
+
+/**
+ * Gets an instance of an image utility class
+ * @return an image utility class
+ */
+export function getImageUtil(): ImageUtil;
+
+/**
+ * Gets an instance of a link page utility class.
+ * @return an instance of a link page utility class
+ */
+export function getLinkPageUtil(): LinkPageUtil;
+
+/**
+ * Gets an instance of a link target builder class.
+ * @return an instance of a link target builder class
+ */
+export function getLinkTargetBuilder(): LinkTargetBuilder;
+
+/**
+ * Gets an instance of a page utility class
+ * @return a page utility class
+ */
+export function getPageUtil(): PageUtil;
+
+/**
+ * Factory for creating instances of web resource utilities.
+ *
+ * <p>
+ *    An instance of the Sitevision class implementing this interface can be obtained via
+ *    {@link senselogic.sitevision.api.Utils#getWebResourceFactory()}.
+ *    See {@link senselogic.sitevision.api.Utils} for how to obtain an instance of the <code>Utils</code> interface.
+ * </p>Gets an instance of an article utility classGets an instance of a file utility classGets an instance of an image utility classGets an instance of a link page utility class.Gets an instance of a link target builder class.Gets an instance of a page utility class
+ * @author Magnus Lövgren
+ * @since Sitevision 4.2
+ */
+declare namespace WebResourceFactory {
+  export {
+    getArticleUtil,
+    getFileUtil,
+    getImageUtil,
+    getLinkPageUtil,
+    getLinkTargetBuilder,
+    getPageUtil,
+  };
+}
+
+export default WebResourceFactory;

package/server/XSLTUtil/index.d.ts

@@ -9,8 +9,7 @@
  *    <em>Note!</em> The template supports a <em>sub-set</em> of HTML elements (the presumed most commonly used elements).
  *    All unsupported elements are completely discarded (i.e. they will not be included at all in the transformation result).
  * </p>
- *
- * @return {string} the default cleanup template for HTML sources
+ * @return the default cleanup template for HTML sources
  */
 export function getDefaultCleanHtmlTemplate(): string;
 
@@ -20,17 +19,57 @@ export function getDefaultCleanHtmlTemplate(): string;
  * <p>
  *    <em>Note!</em> The contents of the XSL Template is always handled as UTF-8.
  * </p>
- *
- * @param {string} aSource the source that should be transformed, HTML, XHTML or XML. Must not be null
- * @param {any} aXslTemplate the UTF-8 XSL template;
- *                     a sv:file Node, a sv:temporaryFile Node, a sv:link Node that targets a sv:file, a char array or a CharSequence
- *                     (typically a String). Must not be null
- * @return {string} the transformation result
+ * @param aSource the source that should be transformed, HTML, XHTML or XML. Must not be null
+ * @param aXslTemplate the UTF-8 XSL template; a sv:file Node, a sv:temporaryFile Node, a sv:link Node that targets a sv:file, a char array or a CharSequence (typically a String). Must not be null
+ * @return the transformation result
  * @throws IOException if the transformation fails (e.g. the aSource is really bad/interpretable HTML or aXslTemplate is invalid XSL)
  * @throws RepositoryException if aNode-operation on aXslTemplate fails
  */
-export function transform(aSource: string, aXslTemplate: any): string;
+export function transform(aSource: string, aXslTemplate: unknown): string;
 
-declare namespace xsltUtil {
+/**
+ * XSLT utility for transforming XML/HTML using a XSL template.
+ *
+ * <p>
+ *    <em>Tip!</em> This utility can be combined with {@link senselogic.sitevision.api.render.OutputUtil} to produce modified versions of
+ *    the HTML produced by layouts or modules. Below is a simplistic example of how this can be done in server-side JavaScript.
+ * </p><pre>
+ *    var outputUtil = require('OutputUtil'),
+ *        xsltUtil = require('XSLTUtil'),
+ *        pageNode,
+ *        pageContentNode,
+ *        rawRenderResult,
+ *        transformedRenderResult;
+ *
+ *    pageNode = ...
+ *    pageContentNode = ...
+ *
+ *    rawRenderResult = outputUtil.getNodeOutput(pageNode, pageContentNode, outputUtil.CONTENT_TYPE_TEXT_HTML);
+ *    transformedRenderResult = xsltUtil.transform(rawRenderResult, xsltUtil.getDefaultCleanHtmlTemplate());
+ * </pre>
+ *
+ * <p>
+ *    An instance of the Sitevision class implementing this interface can be obtained via {@link senselogic.sitevision.api.Utils#getXSLTUtil}.
+ *    See {@link senselogic.sitevision.api.Utils} for how to obtain an instance of the <code>Utils</code> interface.
+ * </p>Gets the default XSL template for cleanup of HTML sources.
+ *
+ * <p>
+ *    The template strips all &lt;div&gt;'s, &lt;spans&gt;'s and removes all inline styling, classes and attributes
+ *    that is not mandatory or needed for WCAG purposes.
+ * </p>
+ * <p>
+ *    <em>Note!</em> The template supports a <em>sub-set</em> of HTML elements (the presumed most commonly used elements).
+ *    All unsupported elements are completely discarded (i.e. they will not be included at all in the transformation result).
+ * </p>Transforms a HTML/XML source using a XSL template.
+ *
+ * <p>
+ *    <em>Note!</em> The contents of the XSL Template is always handled as UTF-8.
+ * </p>
+ * @author Magnus Lövgren
+ * @since Sitevision 4.5
+ */
+declare namespace XSLTUtil {
   export { getDefaultCleanHtmlTemplate, transform };
 }
+
+export default XSLTUtil;

package/server/XmlParserUtil/index.d.ts

@@ -1,76 +1,11 @@
-import Node from '../builtins/Node';
-import Collection from '../builtins/Collection';
-
-interface XmlElement {
-  /**
-   * Gets the name of the element
-   *
-   * @return {string} the element name
-   */
-  getName(): string;
-
-  /**
-   * Gets the text content of the element.
-   *
-   * @return {string} the text content of the element or null if no text content is available.
-   */
-  getText(): string;
-
-  /**
-   * Gets an attribute value of the element.
-   *
-   * @param {string} aName the attribute name
-   * @return {string} the attribute value or null if no value is associated with attribute
-   */
-  getAttribute(aName: string): string;
-
-  /**
-   * Check if a sub element with a specific name is available in the element.
-   *
-   * @param {string} aName name of the sub element of this element, must be non-null.
-   * @return {boolean} true if one or more sub elements with the specific name is available
-   */
-  hasElement(aName: string): boolean;
-
-  /**
-   * Gets the first sub element with a specific name of the element.
-   *
-   * @param {string} aName name of the sub element of this element, must be non-null.
-   * @return {XmlElement} the sub element or null if no sub element is found.
-   */
-  getElement(aName: string): XmlElement;
-
-  /**
-   * Gets all sub element with a specific name of the element.
-   *
-   * @param {string} aName name of the sub element of this element, must be non-null.
-   * @return {Collection<XmlElement>}the sub elements or an empty collection if no sub elements are available
-   */
-  getElements(aName: string): Collection<XmlElement>;
-
-  /**
-   * Gets all sub elements of the element.
-   *
-   * @return {Collection<XmlElement>} a list of all sub elements
-   */
-  getElements(): Collection<XmlElement>;
-}
-
-interface XmlElementHandler {
-  /**
-   * Called when a element matching the selection has been parsed.
-   *
-   * @param {XmlElement} aXmlElement the element
-   */
-  handleElement(aXmlElement: XmlElement): void;
-}
+import XmlElementHandler from "../../hidden/senselogic/sitevision/api/xml/XmlElementHandler";
+import Node from "../../hidden/javax/jcr/Node";
 
 /**
  * Parse a XML string.
- *
- * @param {string} aElementSelection the elements in the XML that should be passed to the XmlElementHandler
- * @param {string} aXml the UTF-8 XML string
- * @param {XmlElementHandler} aXmlElementHandler the XmlElementHandler
+ * @param aElementSelection the elements in the XML that should be passed to the XmlElementHandler
+ * @param aXml the UTF-8 XML string
+ * @param aXmlElementHandler the XmlElementHandler
  * @throws XmlParserException if an error occurs while parsing the XML
  */
 export function parse(
@@ -81,10 +16,9 @@ export function parse(
 
 /**
  * Parse a file containing XML encoded using UTF-8.
- *
- * @param {string} aElementSelection the elements in the XML that should be passed to the XmlElementHandler
- * @param {Node} aXmlFile the file containing XML encoded using UTF-8 (sv:file or sv:temporaryFile)
- * @param {XmlElementHandler} aXmlElementHandler the XmlElementHandler
+ * @param aElementSelection the elements in the XML that should be passed to the XmlElementHandler
+ * @param aXmlFile the file containing XML encoded using UTF-8 (sv:file or sv:temporaryFile)
+ * @param aXmlElementHandler the XmlElementHandler
  * @throws RepositoryException if an error occurs while accessing the file
  * @throws XmlParserException if an error occurs while parsing the XML
  */
@@ -96,12 +30,10 @@ export function parse(
 
 /**
  * Parse a file containing XML encoded with the supplied charset.
- *
- * @param {string} aElementSelection the elements in the XML that should be passed to the XmlElementHandler
- * @param {Node} aXmlFile the file containing XML encoded using supplied encoding (sv:file or sv:temporaryFile)
- * @param {string} aCharset the character encoding of the the file content
- *                 (an IllegalArgument will be thrown if aCharset can not be resolved as a java.nio.charset.Charset)
- * @param {XmlElementHandler} aXmlElementHandler the XmlElementHandler
+ * @param aElementSelection the elements in the XML that should be passed to the XmlElementHandler
+ * @param aXmlFile the file containing XML encoded using supplied encoding (sv:file or sv:temporaryFile)
+ * @param aCharset the character encoding of the the file content (an IllegalArgument will be thrown if aCharset can not be resolved as a java.nio.charset.Charset)
+ * @param aXmlElementHandler the XmlElementHandler
  * @throws RepositoryException if an error occurs while accessing the file
  * @throws XmlParserException if an error occurs while parsing the XML
  */
@@ -112,6 +44,75 @@ export function parse(
   aXmlElementHandler: XmlElementHandler
 ): void;
 
-declare namespace xmlParserUtil {
+/**
+ * Utility interface for parsing XML.
+ *
+ * <p>
+ *    <em>Example 1: parse a RSS XML string.</em>
+ * </p>
+ * <pre>
+ *    var xml = '&lt;rss&gt;&lt;channel&gt;&lt;item&gt;&lt;title&gt;Hello World!&lt;/title&gt;&lt;/item&gt;&lt;/channel&gt;&lt;/rss&gt;',
+ *        parser = require('XmlParserUtil');
+ *
+ *    parser.parse('/rss/channel/item', xml, function(aElement) {
+ *       // Handle item direct instead of adding to a list in order to preserve memory!
+ *       out.println(aElement.getElement('title').getText() + '&lt;br&gt;');
+ *    });
+ * </pre>
+ *
+ * <p>
+ *    <em>Example 2: parse a ISO-8859-1 encoded RSS XML file stored in the file repository.</em>
+ * </p>
+ * <pre>
+ *    var xmlFile = require('ResourceLocatorUtil').getFileRepository().getNode('rss.xml'),
+ *        parser = require('XmlParserUtil');
+ *
+ *    parser.parse('/rss/channel/item', xmlFile, 'ISO-8859-1', function(aElement) {
+ *       // Handle item direct instead of adding to a list in order to preserve memory!
+ *       out.println(aElement.getElement('title').getText() + '&lt;br&gt;');
+ *    });
+ * </pre>
+ *
+ * <p>
+ *    <em>Example 3: download and parse a remote RSS XML.</em>
+ * </p>
+ * <pre>
+ *    var requester = require('Requester'),
+ *        parser = require('XmlParserUtil'),
+ *        url = 'https://www.site.com/rss-feed.xml',
+ *        options = {
+ *           dataType: 'file'
+ *        };
+ *
+ *    requester.get(url, options)
+ *       .done(function(result, statusCode, headers) {
+ *          if (statusCode === 200 &amp;&amp; result) {
+ *             parser.parse('/rss/channel/item', result, function(aElement) {
+ *                // Handle item direct instead of adding to a list in order to preserve memory!
+ *                out.println(aElement.getElement('title').getText() + '&lt;br&gt;');
+ *             });
+ *          }
+ *       }).fail(function(message, status) {
+ *          // GET failed, handle appropriately
+ *       });
+ * </pre>
+ *
+ * <p>
+ *    <strong>Important note!</strong><br>
+ *    In order to protected the system against processes that consumes to much memory and to avoid
+ *    OutOfMemoryExceptions the parsing process will be aborted and a RuntimeException thrown
+ *    if more than 5MB of text content is found inside a single element.
+ * </p>
+ *
+ * <p>
+ *    An instance of the Sitevision class implementing this interface can be obtained via {@link senselogic.sitevision.api.Utils#getXmlParserUtil()}.
+ *    See {@link senselogic.sitevision.api.Utils} for how to obtain an instance of the <code>Utils</code> interface.
+ * </p>Parse a XML string.Parse a file containing XML encoded using UTF-8.Parse a file containing XML encoded with the supplied charset.
+ * @author Niclas Hedlund
+ * @since Sitevision 5.1
+ */
+declare namespace XmlParserUtil {
   export { parse };
 }
+
+export default XmlParserUtil;

package/builtins/Binary/index.d.ts

@@ -1,3 +0,0 @@
-interface Binary {}
-
-export default Binary;

package/builtins/Calendar/index.d.ts

@@ -1,3 +0,0 @@
-interface Calendar {}
-
-export default Calendar;

package/builtins/Collection/index.d.ts

@@ -1,3 +0,0 @@
-interface Collection {}
-
-export default Collection;

package/builtins/Date/index.d.ts

@@ -1,3 +0,0 @@
-interface Date {}
-
-export default Date;

package/builtins/InputStream/index.d.ts

@@ -1,3 +0,0 @@
-interface InputStream {}
-
-export default InputStream;

package/builtins/Instant/index.d.ts

@@ -1,3 +0,0 @@
-interface Instant {}
-
-export default Instant;

package/builtins/List/index.d.ts

@@ -1,3 +0,0 @@
-interface List<Type> {}
-
-export default List;

package/builtins/LocalDateTime/index.d.ts

@@ -1,3 +0,0 @@
-interface LocalDateTime {}
-
-export default LocalDateTime;

package/builtins/Locale/index.d.ts

@@ -1,3 +0,0 @@
-interface Locale {}
-
-export default Locale;

package/builtins/Node/index.d.ts

@@ -1,3 +0,0 @@
-interface Node {}
-
-export default Node;

package/builtins/NodeIterator/index.d.ts

@@ -1,27 +0,0 @@
-import Node from '../Node';
-
-interface NodeIterator {
-  /**
-  * Returns true if the iteration has more elements.
-  * @returns {boolean} true if the iteration has more elements 
-  */
-  hasNext(): boolean;
-  /**
-  * Returns the next Node in the iteration.
-  * @returns {Node} the next Node in the iteration 
-  */
-  next(): Node;
-  /**
-  * Returns the next Node in the iteration.
-  * @returns {Node} the next Node in the iteration. 
-  */
-  nextNode(): Node;
-  /**
-  * Removes from the underlying collection the last element returned
-   by this iterator (optional operation).
-  * @returns {default void} undefined 
-  */
-  remove(): void;
-}
-
-export default NodeIterator;

package/builtins/Property/index.d.ts

@@ -1,3 +0,0 @@
-interface Property {}
-
-export default Property;

package/builtins/Serializable/index.d.ts

@@ -1,3 +0,0 @@
-interface Serializable {}
-
-export default Serializable;

package/builtins/Set/index.d.ts

@@ -1,3 +0,0 @@
-interface Set {}
-
-export default Set;

package/builtins/Throwable/index.d.ts

@@ -1,3 +0,0 @@
-interface Throwable {}
-
-export default Throwable;

package/builtins/byte/index.d.ts

@@ -1,3 +0,0 @@
-interface byte {}
-
-export default byte;