SSML Builder Documentation - v1.0.1
    Preparing search index...

    Class SSMLElementAbstract

    Abstract base class for all SSML elements in the library.

    This class provides the foundation for all SSML elements (voice, paragraph, sentence, etc.) by defining the common interface and functionality that all elements must implement. It serves as the contract that ensures all elements can be rendered to valid SSML XML and handles the proper escaping of special XML characters.

    All SSML element classes must extend this base class and implement the abstract render() method to generate their specific XML representation.

    // Example of a custom element extending SSMLElement
    class CustomElement extends SSMLElement {
      private content: string;
      
      constructor(content: string) {
        super();
        this.content = content;
      }
      
      render(): string {
        // Use escapeXml to ensure valid XML
        return `<custom>${this.escapeXml(this.content)}</custom>`;
      }
    }

    Hierarchy (View Summary)

    Index

    Constructors

    constructor

    Methods

    escapeXml render

    Constructors

    Methods

    • Protected

      Escapes special XML characters in text content to ensure valid XML output.

      This method replaces XML special characters with their corresponding entity references to prevent XML parsing errors and potential security issues (XML injection). It should be used whenever inserting user-provided or dynamic text content into XML elements.

      The following characters are escaped:

      • & becomes &amp; (must be escaped first to avoid double-escaping)
      • < becomes &lt; (prevents opening of unintended tags)
      • > becomes &gt; (prevents closing of unintended tags)
      • " becomes &quot; (prevents breaking out of attribute values)
      • ' becomes &apos; (prevents breaking out of attribute values)

      This method is marked as protected so it's only accessible to classes that extend SSMLElement, ensuring proper encapsulation while allowing all element implementations to use this essential functionality.

      Parameters

      • text: string

        The text content to escape

      Returns string

      The text with all special XML characters properly escaped

      // In a render method implementation
      class TextElement extends SSMLElement {
        private text: string = 'Hello & "world" <script>';
        
        render(): string {
          // Escapes to: Hello &amp; &quot;world&quot; &lt;script&gt;
          return `<text>${this.escapeXml(this.text)}</text>`;
        }
      }

      // Edge cases handled correctly
      this.escapeXml('5 < 10 & 10 > 5');  
      // Returns: '5 &lt; 10 &amp; 10 &gt; 5'

      this.escapeXml('She said "Hello"');  
      // Returns: 'She said &quot;Hello&quot;'

      this.escapeXml("It's a test");       
      // Returns: 'It&apos;s a test'

      // Prevents XML injection
      this.escapeXml('</voice><voice name="evil">');  
      // Returns: '&lt;/voice&gt;&lt;voice name=&quot;evil&quot;&gt;'

    • Renders the element as a valid SSML XML string.

      This abstract method must be implemented by all concrete SSML element classes. The implementation should generate the appropriate XML representation of the element, including its opening and closing tags, attributes, and properly escaped content.

      The rendered output must be valid according to the SSML 1.0 specification and compatible with Azure Speech Service requirements.

      Returns string

      A string containing the XML representation of the SSML element

      // Implementation in VoiceElement
      class VoiceElement extends SSMLElement {
        render(): string {
          return `<voice name="en-US-AvaNeural">${content}</voice>`;
        }
      }

      // Implementation in BreakElement
      class BreakElement extends SSMLElement {
        render(): string {
          return `<break time="500ms"/>`;
        }
      }

      // Implementation in EmphasisElement
      class EmphasisElement extends SSMLElement {
        render(): string {
          return `<emphasis level="strong">${this.escapeXml(text)}</emphasis>`;
        }
      }

    Settings

    Member Visibility

    On This Page

    Constructors
    Methods