@sitevision/api 1.0.20 → 1.1.0-alpha.1

package/server/LinkTargetBuilder/index.d.ts

@@ -0,0 +1,146 @@
+import Node from "../../hidden/javax/jcr/Node";
+import LinkTarget from "../../hidden/senselogic/sitevision/api/webresource/LinkTarget";
+
+/**
+ * Sets the target.
+ * @param aNode the target, must be a linkable resource (i.e. a page/article/image/file or such) that isn't trashed.
+ * @return this builder
+ * @throws IllegalArgumentException if <code>aNode</code> is <code>null</code> or not a linkable resource.
+ */
+export function setInternalTarget(aNode: Node): LinkTargetBuilder;
+
+/**
+ * Sets the target.
+ * @param aURL the link target URL
+ * @return this builder
+ * @throws IllegalArgumentException if <code>aURL</code> is <code>null</code> or whitespace only
+ */
+export function setExternalTarget(aURL: string): LinkTargetBuilder;
+
+/**
+ * Sets the target.
+ * @param aMailAddress a mail address
+ * @return this builder
+ * @throws IllegalArgumentException if <code>aMailAddress</code> is <code>null</code>, whitespace only or an invalid mail address.
+ * @see senselogic.sitevision.api.mail.MailUtil#isValidAddress(String)
+ */
+export function setMailTarget(aMailAddress: string): LinkTargetBuilder;
+
+/**
+ * Sets the target.
+ * @param aPhoneNumber a phone number
+ * @return this builder
+ * @throws IllegalArgumentException if <code>aPhoneNumber</code> is <code>null</code>, whitespace only or an invalid phone number.
+ */
+export function setPhoneTarget(aPhoneNumber: string): LinkTargetBuilder;
+
+/**
+ * Sets the description.
+ * @param aDescription the description
+ * @return this builder
+ */
+export function setDescription(aDescription: string): LinkTargetBuilder;
+
+/**
+ * Sets open in new window.
+ * @param aOpenInNewWindow whether or not the target should be opened in new window
+ * @return this builder
+ */
+export function setOpenInNewWindow(
+  aOpenInNewWindow: boolean
+): LinkTargetBuilder;
+
+/**
+ * Creates a LinkTarget instance using current state of this builder.
+ *
+ * <p>
+ *    <em>
+ *       Note! The 'open in new window' state is ignored when creating a LinkTarget with
+ *       a mail or telephone target (these target types can never be opened in a new window).
+ *    </em>
+ * </p>
+ * @return a link target
+ * @throws IllegalStateException if there are no link target.
+ */
+export function build(): LinkTarget;
+
+/**
+ * Builder to create link target instances that can be used to create and update a Link page
+ * via {@link senselogic.sitevision.api.webresource.LinkPageUtil}.
+ *
+ * <p>
+ *    LinkTargetBuilder has one <strong>mandatory attribute</strong>:
+ * </p>
+ * <ul>
+ *    <li>
+ *       <em>target</em> - The target. Must be non-null.
+ *    </li>
+ * </ul>
+ * <p>
+ *    LinkTargetBuilder also has some <strong>optional attributes</strong>:
+ * </p>
+ * <ul>
+ *    <li>
+ *       <em>description</em> - The description. Default is <code>null</code>.
+ *    </li>
+ *    <li>
+ *       <em>open in new window</em> - Whether or not the target should be opened in new window. Default is <code>false</code>.
+ *    </li>
+ * </ul>
+ *
+ * <p>
+ *    Using the LinkTargetBuilder is pretty straightforward, if you remember that it is <strong>stateful</strong>. Conceptually you
+ *    would typically use it like this:
+ * </p>
+ * <ol>
+ *   <li>Get the LinkTargetBuilder</li>
+ *   <li>Set the target</li>
+ *   <li>Possibly set a description</li>
+ *   <li>Possibly set open in new window</li>
+ *   <li>Do build</li>
+ * </ol>
+ * <p>
+ *    When you have built a <code>LinkTarget</code> instance, you can re-use the LinkTargetBuilder to build more instances. Something like:
+ * </p>
+ * <ol>
+ *   <li>Set a new target</li>
+ *   <li>Possibly set a description</li>
+ *   <li>Possibly set open in new window</li>
+ *   <li>Do build</li>
+ * </ol>
+ *
+ * <p>
+ *    <strong>Tip!</strong> The {@link senselogic.sitevision.api.base.Builder Builder interface documentation} contains
+ *    more information about Builders and how to work with them!
+ * </p>
+ *
+ * <p>
+ *    An instance of the Sitevision class implementing this interface can be obtained via
+ *    {@link senselogic.sitevision.api.webresource.WebResourceFactory#getLinkTargetBuilder()}.
+ *    See {@link senselogic.sitevision.api.webresource.WebResourceFactory} for how to obtain an instance of the
+ *    <code>WebResourceFactory</code> interface.
+ * </p>Sets the target.Sets the target.Sets the target.Sets the target.Sets the description.Sets open in new window.Creates a LinkTarget instance using current state of this builder.
+ *
+ * <p>
+ *    <em>
+ *       Note! The 'open in new window' state is ignored when creating a LinkTarget with
+ *       a mail or telephone target (these target types can never be opened in a new window).
+ *    </em>
+ * </p>
+ * @author Magnus Lövgren
+ * @since Sitevision 4.2
+ * @see senselogic.sitevision.api.webresource.LinkPageUtil
+ */
+declare namespace LinkTargetBuilder {
+  export {
+    setInternalTarget,
+    setExternalTarget,
+    setMailTarget,
+    setPhoneTarget,
+    setDescription,
+    setOpenInNewWindow,
+    build,
+  };
+}
+
+export default LinkTargetBuilder;

package/server/LinkValueBuilder/index.d.ts

@@ -1,64 +1,141 @@
+import Node from "../../hidden/javax/jcr/Node";
+import LinkValue from "../../hidden/senselogic/sitevision/api/metadata/value/LinkValue";
+
 /**
- * A temporary representation of a link metadata value.
+ * Sets the target.
+ * @param anURL the link target URL
+ * @return this builder
+ * @throws IllegalArgumentException if <code>anURL</code> is <code>null</code> or whitespace only
  */
-interface LinkValue { }
+export function setExternalTarget(anURL: string): LinkValueBuilder;
 
-export interface LinkValueBuilder {
-  /**
-   * Creates a LinkValue instance using current state of this builder.
-   * @returns {LinkValue} a link value 
-   */
-  build(): LinkValue;
+/**
+ * Sets the target.
+ * @param aMailAddress a mail address
+ * @return this builder
+ * @throws IllegalArgumentException if <code>aMailAddress</code> is <code>null</code>, whitespace only or an invalid mail address.
+ * @see senselogic.sitevision.api.mail.MailUtil#isValidAddress(String)
+ */
+export function setMailTarget(aMailAddress: string): LinkValueBuilder;
 
-  /**
-  * Sets the link description.
-  * @returns {LinkValueBuilder} this builder 
-  * @param {string} aDescription - the link description
-  */
-  setDescription(aDescription: string): LinkValueBuilder;
+/**
+ * Sets the target.
+ * @param aPhoneNumber a phone number
+ * @return this builder
+ * @throws IllegalArgumentException if <code>aPhoneNumber</code> is <code>null</code>, whitespace only or an invalid phone number.
+ * @since Sitevision 4.2.1
+ */
+export function setPhoneTarget(aPhoneNumber: string): LinkValueBuilder;
 
-  /**
-  * Sets the target.
-  * @returns {LinkValueBuilder} this builder 
-  * @param {string} anURL - the link target URL
-  */
-  setExternalTarget(anURL: string): LinkValueBuilder;
+/**
+ * Sets the target.
+ * @param aNode the target, must be a linkable resource (i.e. a page/article/image/file or such) that isn't trashed.
+ * @return this builder
+ * @throws IllegalArgumentException if <code>aNode</code> is <code>null</code> or not a linkable resource.
+ */
+export function setInternalTarget(aNode: Node): LinkValueBuilder;
 
-  /**
-  * Sets the target.
-  * @returns {LinkValueBuilder} this builder 
-  * @param {Node} aNode - the target, must be a linkable resource (i.e. a page/article/image/file or such) that isn't trashed.
-  */
-  setInternalTarget(aNode: Node): LinkValueBuilder;
+/**
+ * Sets the link name.
+ * @param aName the link name
+ * @return this builder
+ */
+export function setName(aName: string): LinkValueBuilder;
 
-  /**
-  * Sets the target.
-  * @returns {LinkValueBuilder} this builder 
-  * @param {string} aMailAddress - a mail address
-  */
-  setMailTarget(aMailAddress: string): LinkValueBuilder;
+/**
+ * Sets the link description.
+ * @param aDescription the link description
+ * @return this builder
+ */
+export function setDescription(aDescription: string): LinkValueBuilder;
 
-  /**
-  * Sets the link name.
-  * @returns {LinkValueBuilder} this builder 
-  * @param {string} aName - the link name
-  */
-  setName(aName: string): LinkValueBuilder;
+/**
+ * Sets open in new window.
+ * @param aOpenInNewWindow whether or not the link should be opened in new window
+ * @return this builder
+ */
+export function setOpenInNewWindow(aOpenInNewWindow: boolean): LinkValueBuilder;
 
-  /**
-  * Sets open in new window.
-  * @returns {LinkValueBuilder} this builder 
-  * @param {boolean} aOpenInNewWindow - whether or not the link should be opened in new window
-  */
-  setOpenInNewWindow(aOpenInNewWindow: boolean): LinkValueBuilder;
+/**
+ * Creates a LinkValue instance using current state of this builder.
+ * @return a link value
+ * @throws IllegalStateException if there are no link target.
+ */
+export function build(): LinkValue;
 
-  /**
-  * Sets the target.
-  * @returns {LinkValueBuilder} this builder 
-  * @param {string} aPhoneNumber - a phone number
-  */
-  setPhoneTarget(aPhoneNumber: string): LinkValueBuilder;
+/**
+ * Builder to create LinkValue instances that can be used to set link metadata.
+ *
+ * <p>
+ *    LinkValueBuilder has one <strong>mandatory attribute</strong>:
+ * </p>
+ * <ul>
+ *    <li>
+ *       <em>target</em> - The link target. Must be non-null.
+ *    </li>
+ * </ul>
+ * <p>
+ *    LinkValueBuilder also has some <strong>optional attributes</strong>:
+ * </p>
+ * <ul>
+ *    <li>
+ *       <em>name</em> - The link name. Default is <code>null</code>.
+ *    </li>
+ *    <li>
+ *       <em>description</em> - The Link description. Default is <code>null</code>.
+ *    </li>
+ *    <li>
+ *       <em>open in new window</em> - Whether or not the link should be opened in new window. Default is <code>false</code>.
+ *    </li>
+ * </ul>
+ *
+ * <p>
+ *    Using the LinkValueBuilder is pretty straightforward, if you remember that it is <strong>stateful</strong>. Conceptually you
+ *    would typically use it like this:
+ * </p>
+ * <ol>
+ *   <li>Get the LinkValueBuilder</li>
+ *   <li>Set the target</li>
+ *   <li>Possibly set a name</li>
+ *   <li>Possibly set a description</li>
+ *   <li>Possibly set open in new window</li>
+ *   <li>Do build</li>
+ * </ol>
+ * <p>
+ *    When you have built a <code>LinkValue</code> instance, you can re-use the LinkValueBuilder to build more instances. Something like:
+ * </p>
+ * <ol>
+ *   <li>Set a new target</li>
+ *   <li>Possibly set a name</li>
+ *   <li>Possibly set a description</li>
+ *   <li>Possibly set open in new window</li>
+ *   <li>Do build</li>
+ * </ol>
+ *
+ * <p>
+ *    <strong>Tip!</strong> The {@link senselogic.sitevision.api.base.Builder Builder interface documentation} contains
+ *    more information about Builders and how to work with them!
+ * </p>
+ *
+ * <p>
+ *    An instance of the Sitevision class implementing this interface can be obtained via
+ *    {@link senselogic.sitevision.api.metadata.MetadataUtil#getLinkValueBuilder()}.
+ *    See {@link senselogic.sitevision.api.metadata.MetadataUtil} for how to obtain an instance of the <code>MetadataUtil</code> interface.
+ * </p>Sets the target.Sets the target.Sets the target.Sets the target.Sets the link name.Sets the link description.Sets open in new window.Creates a LinkValue instance using current state of this builder.
+ * @author Magnus Lövgren
+ * @since Sitevision 3.6
+ */
+declare namespace LinkValueBuilder {
+  export {
+    setExternalTarget,
+    setMailTarget,
+    setPhoneTarget,
+    setInternalTarget,
+    setName,
+    setDescription,
+    setOpenInNewWindow,
+    build,
+  };
 }
 
-const linkValueBuilder: LinkValueBuilder;
-export default linkValueBuilder;
+export default LinkValueBuilder;

package/server/ListWrapper/index.d.ts

@@ -0,0 +1,172 @@
+/**
+ * Appends the specified element (if non-null) to the end of the wrapped list.
+ *
+ * <p>
+ *    <strong>Important!</strong> Null values in lists are inherently bad. This method will <strong>not</strong>
+ *    delegate any <code>null</code> to the wrapped list.
+ *    If you <em>must</em> add a <code>null</code> value, you can explicitly do it to the wrapped list, i.e:
+ * </p>
+ * <pre><code>
+ *    #set ($myList = $instanceCreatorUtil.listWrapper)
+ *    ...
+ *    $myList.add($anObject.aMethod())          <em>## Will only delegate non-nulls to the wrapped list</em>
+ *    $myList.unwrap().add($anObject.aMethod()) <em>## Will add any value directly to the wrapped list</em>
+ * </code></pre>
+ * @param anObject the element to be appended to the wrapped list, <code>null</code> will be ignored.
+ */
+export function add(anObject: unknown): void;
+
+/**
+ * Removes all of the elements from the wrapped list.
+  
+    */
+export function clear(): void;
+
+/**
+ * Checks if the wrapped list contains a specified object.
+ * @param anObject an element to check for in the wrapped list.
+ * @return <code>true</code> if the wrapped list contains the specified element
+ */
+export function contains(anObject: unknown): boolean;
+
+/**
+ * Returns the element at the specified position in the wrapped list.
+ * @param anIndex index of the element in the wrapped list to return
+ * @return the element at the specified position in the wrapped list
+ * @throws IndexOutOfBoundsException if the index is out of range (<code>index &lt; 0 || index &gt;= size()</code>)
+ */
+export function get(anIndex: number): unknown;
+
+/**
+ * Whether or not the wrapped list is empty (contains no elements).
+ * @return <code>true</code> if the wrapped list contains no elements
+ */
+export function isEmpty(): boolean;
+
+/**
+ * Returns an iterator for the wrapped list.
+ * @return an Iterator.
+ */
+export function iterator(): unknown;
+
+/**
+ * The size (number of elements) of the wrapped list.
+ * @return the number of elements in the wrapped list
+ */
+export function size(): number;
+
+/**
+ * Returns an array containing all of the elements in the wrapped list.
+ * @return an array containing the elements of the wrapped list
+ */
+export function toArray(): unknown;
+
+/**
+ * Sorts the wrapped list.
+ * @param aComparator the comparator to use when sorting
+ * @since Sitevision 4.0
+ */
+export function sort(aComparator: unknown): void;
+
+/**
+ * Returns the wrapped List.
+ * @return the List wrapped by this ListWrapper
+ */
+export function unwrap(): unknown[];
+
+/**
+ * An convenience <code>java.util.List</code> wrapper that delegates method calls to the wrapped list.
+ *
+ * <p>
+ *    This is a convenience wrapper that bypasses potential problems with the <code>add</code> method of a <code>java.util.List</code>.
+ *    The <code>List.add</code> method accepts <code>null</code> values and returns a <code>boolean</code>.
+ *    When working with Velocity, this boolean gets part of the output if not suppressed via a <code>#set</code>, <code>#if</code>,
+ *    <code>#elseif</code> or via {@link senselogic.sitevision.api.script.ScriptUtil#swallow(Object)})
+ * </p>
+ *
+ * <p>
+ *    An example with the add problem of a java.util.List:<br>This Velocity code:
+ * </p>
+ * <pre><code>
+ *    #set ($myList = $instanceCreatorUtil.list)
+ *    $myList.add("Magnus Lövgren") <em>## Returns true</em>
+ *    $myList.add("Mikael Wikblom") <em>## Returns true</em>
+ *
+ *    $someObject.someMethod($myList)</code></pre>will result in the following Velocity output
+ *    (the <code>add</code> method of <code>List</code> returns a <code>boolean</code>):<pre><code>
+ *    true true</code></pre>
+ * <p>
+ *    If a non-void method is invoked and the return value isn't handled, it will be part of the Velocity output.
+ *    Using an <code>ListWrapper</code> will prevent that:
+ * </p>
+ * <pre><code>
+ *    #set ($myList = $instanceCreatorUtil.listWrapper)
+ *    myList.add("Magnus Lövgren") <em>## Silent</em>
+ *    myList.add("Mikael Wikblom") <em>## Silent</em>
+ *
+ *    $someObject.someMethod($myList.unwrap()) <em>## Get wrapped List</em>
+ * </code></pre>
+ *
+ *  <p>
+ *     <strong>Important Velocity #foreach note!</strong><br>
+ *     Iterating a <code>ListWrapper</code> via the Velocity <code>#foreach</code> loop is not possible in all Velocity versions
+ *     (proper <code>Iterable</code> support not present). To ensure proper <code>#foreach</code> iteration in all Velocity versions,
+ *     you should use one of the following alternative ways:
+ *  </p>
+ *  <pre><code>
+ *     #set ($myList = $instanceCreatorUtil.listWrapper)
+ *     ...
+ *
+ *     <em>## ALTERNATIVE A - unwrap, i.e. do actual iteration on the wrapped list itself</em>
+ *     #foreach ($item in $myList.<strong>unwrap()</strong>)
+ *        ...
+ *     #end
+ *
+ *     <em>## ALTERNATIVE B - explicitly hand over the Iterator</em>
+ *     #foreach ($item in $myList.<strong>iterator()</strong>)
+ *        ...
+ *     #end
+ *
+ *     <em>## ALTERNATIVE C - extract as array</em>
+ *     #foreach ($item in $myList.<strong>toArray()</strong>)
+ *        ...
+ *     #end</code></pre>
+ * <p>
+ *     For best performance, you should choose alternative A or B over C.
+ * </p>
+ *
+ * <p>
+ *    An instance of the Sitevision class implementing this interface can be obtained via {@link InstanceCreatorUtil#getListWrapper()}.
+ *    See {@link InstanceCreatorUtil} for how to obtain an instance of the <code>InstanceCreatorUtil</code> interface.
+ * </p>Appends the specified element (if non-null) to the end of the wrapped list.
+ *
+ * <p>
+ *    <strong>Important!</strong> Null values in lists are inherently bad. This method will <strong>not</strong>
+ *    delegate any <code>null</code> to the wrapped list.
+ *    If you <em>must</em> add a <code>null</code> value, you can explicitly do it to the wrapped list, i.e:
+ * </p>
+ * <pre><code>
+ *    #set ($myList = $instanceCreatorUtil.listWrapper)
+ *    ...
+ *    $myList.add($anObject.aMethod())          <em>## Will only delegate non-nulls to the wrapped list</em>
+ *    $myList.unwrap().add($anObject.aMethod()) <em>## Will add any value directly to the wrapped list</em>
+ * </code></pre>Removes all of the elements from the wrapped list.Checks if the wrapped list contains a specified object.Returns the element at the specified position in the wrapped list.Whether or not the wrapped list is empty (contains no elements).Returns an iterator for the wrapped list.The size (number of elements) of the wrapped list.Returns an array containing all of the elements in the wrapped list.Sorts the wrapped list.Returns the wrapped List.
+ * @author Magnus Lövgren
+ * @since Sitevision 3.5
+ */
+declare namespace ListWrapper {
+  export {
+    add,
+    clear,
+    contains,
+    get,
+    isEmpty,
+    iterator,
+    size,
+    toArray,
+    sort,
+    unwrap,
+  };
+}
+
+export default ListWrapper;