Documents

Handling and managing documents

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.

Warning!

This page contains security information – please read closely.

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 simple 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 is not 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 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 web page could then use those values to generate the appropriate HTML code based on the most appropriate YouTube API. Something that will possibly 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 may have only a few videos to embed, or they may 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 for a) the reasons mentioned above and b) to avoid common attacks related to HTML such as cross-site scripting, click-jacking and code injection.

This changed with PageSeeder 5.9 and the support of  the content security policy (CSP). It is now possible to specify which external data providers are trustworthy and include their content in PageSeeder documents. 

To test this capability on a development server, use an empty <content-security-policy> element in the layout configuration:

<layout-config>
   <content-security-policy/>
​   ...
</layout-config>

Once deployed to production, “whitelist” all trusted sources.

For further information, click the CSP link above to see a number of detailed examples.

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>

Warning!

As a rule, it is advisable to always use the XHTML syntax when integrating with PSML. At the least, process the HTML content through one of the many free sites that offer Tidy .

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>

Editing

To edit the content of the <media-fragment> element, the document configuration must associate an application with the content of the fragment.

For example, to use the plain text editor, simply ensure that the document-config.xml of the document type includes the following:

<editing>
    <editor name="plain"
            mediatype="application/xhtml+xml"
            format="media-fragment" />
</editing>

For examples of editing non-PSML content in PageSeeder, see AsciiMath or MathML

Created on , last edited on