Integrating other XML formats

In PSML, the <media-fragment> element can be used to integrate rich, non-PSML, XML and HTML-based content into a document. This can be useful for situations such as embedding media objects from sites such as YouTube, Vimeo or Soundcloud, interactive objects such as Google Maps, or images in SVG file format.

Content and format

PSML was designed for publishing, and for decades, one of the design objectives that everyone in publishing agrees with is the separation of content from presentation. This idea lets people take advantage of always-evolving, inexpensive, delivery technology without the need to re-engineer, slow-moving, stable content or retrain expensive users / writers / editors.

This is why the best practice in PageSeeder has always been to clearly separate any format-specific output from the rest of the PSML source data. A straightforward example of this would be managing twin JPG and TIFF images so that the process can support either web or paper output (see this tutorial for details on managing images for different outputs).

Separation of content and format encourages simplicity in both the content and publishing processes. It makes the data easier to maintain and easier to adapt when new delivery formats come along. It also helps to manage situations where format-specific data isn’t supported by a certain output.

Process or embed?

Many people are familiar with the concept of technical debt , a term that usually applies to software, but is also applicable to content.

Although it is often regarded as a bad thing, technical debt has a legitimate role in software development, just as credit card debt has a legitimate role in society. 

Ideally, when a user needs to reference a YouTube video from a PageSeeder document, the person designing the document templates would require nothing more than the ID of the video and a title for display. The developer configuring the output of the page could then use those values to generate the appropriate HTML code based on the most appropriate YouTube API—something that might be different in two or three years, regardless of when this article is read.

YouTube and everyone else also separate content and format for the same reasons as PageSeeder.

HOWEVER, back in the real world are people that need to create a proof-of-concept system today. They might have only a few videos to embed, or they might be uncertain about their long-term choice of video platform. For this person, the cost of writing code to generate URLs from IDs is disproportionate to convenience of simply embedding some HTML code.

For these people, PageSeeder makes embedding straightforward and flexible.

Security

PageSeeder has always given the highest priority to security. The early document formats did not support including HTML to avoid common attacks related to HTML such as cross-site scripting, click-jacking and code injection.

We recommend that use content security policy  on your server to mitigate any possible vulnerability.

Media fragment

The purpose of the <media-fragment> element is to enable PSML documents to contain non-PSML content such as MathML, XHTML or SVG. Specifying what type of non-PSML content is in the element is done through the @mediatype attribute.

HTML

To include HTML content in a PSML document, the recommendation is to use XHTML (application/xhtml+xml) rather than HTML (text/html). Besides being processable with XSLT or Schematron, XHTML is more predictable to format.

Following is the PSML markup for an XHTML media fragment:

<media-fragment id="123" mediatype="application/xhtml+xml">

  <!-- Your embedded  XHTML content -->

</media-fragment>

 This example shows how to include a YouTube video in a PSML document:

<media-fragment id="2" mediatype="application/xhtml+xml">
  <iframe width="560"
          height="315"
          frameborder="0"
          allowfullscreen=""
          src="https://www.youtube.com/embed/5Euj9f3gdyM" /> 
</media-fragment>

Document template

The <media-fragment> element cannot be added to a PSML document directly. For it to be accessible by users, the element must be part of the document template.

Following is example of a generic XHTML media fragment. 

<document type="embed" 
          level="portable"
          xmlns:t="http://pageseeder.com/psml/template" >

  <!-- Generic embedded fragment -->
  <t:fragment type="embed" title="HTML embed" >
    <media-fragment mediatype="application/xhtml+xml" >
      <!-- Insert HTML here -->
    </media-fragment>
  </t:fragment>

  <!-- Title -->
  <section id="title" >
    <fragment id="1" >
      <heading level="1" >
        <t:value name="ps.title" />
      </heading>
    </fragment>
  </section>

  <!-- Section including an HTML media fragment -->
  <section id="embedded" >
    <t:fragment-ref id="2" type="embed" />
  </section>
</document>

Video example

Following is a more specific document template featuring fragments for both YouTube and Vimeo videos:

<document type="embed"
          level="portable"
          xmlns:t="http://pageseeder.com/psml/template">

  <!-- Sample YouTube Video insert -->
  <t:fragment type="youtube" title="YouTube Video">
    <media-fragment mediatype="application/xhtml+xml">
      <t:param name="videoid" title="Video ID" />
      <iframe src="https://www.youtube.com/embed/{$videoid}" 
              width="560"
              height="315"
              frameborder="0"
              allowfullscreen="">
      </iframe>
    </media-fragment>
  </t:fragment>

  <!-- Sample Vimeo video insert -->
  <t:fragment type="vimeo" title="Vimeo Video">
    <media-fragment mediatype="application/xhtml+xml">
      <t:param name="videoid" title="Video ID" />
      <iframe src="https://player.vimeo.com/video/{$videoid}" 
              width="560"
              height="315"
              frameborder="0"
              allowfullscreen="">
      </iframe>
    </media-fragment>
  </t:fragment>

  <!-- Title -->
  <section id="title">
    <fragment id="1">
      <heading level="1"><t:value name="ps.title"/></heading>
    </fragment>
  </section>

  <!-- Section including an HTML media fragment -->
  <section id="videos">
    <fragment id="2"></fragment>
    <!-- When adding fragments, users can choose between
         YouTube and Vimeo templates -->
  </section>

</document>