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.

Process or embed?

Warning!

This page contains security information – please read closely.

PSML was designed for publishing and for decades one of the few publishing principles with unanimous support has been the separation of content from presentation. This principle let systems like PageSeeder take advantage of fast moving, inexpensive delivery technology without imposing additional costs on the slow moving, expensive, editorial process. 

With this in mind, the best practice would be to clearly separate any format-specific output from the rest of the PSML source data. A simple example of this would be managing TIFF and JPG format images so that a publication could be optimized for web or print publishing. 

This separation encourages simplicity in both the content and publishing processes. It makes the data easier to maintain and easier to adapt the output to the latest delivery format. It also helps to manage situations where format-specific data is not supported by a certain output.

To include a video from YouTube or Vimeo in a PSML document, requires only the title and ID of a video. Storing minimal details, then generating the HTML makes it possible for a website to use different players without having to change the data. It also allows the system to filter out the video and display a thumbnail, when publishing to a Word document.

However, there are cases when copying HTML code from an external service provider is more convenient and easier to check. As with many things, this short-term convenience should be weighted against the long-term document maintenance. 

Security

Previous versions of PageSeeder did not support the inclusion of content from external sources. This was to protect end-users from common attacks such as cross-site scripting, clickjacking and code injection.

However, from PageSeeder 5.9, it is now possible to specify which external data providers are trustworthy. This allows their content to be included in PageSeeder documents. 

While in development, testing the content security policy can be done using an empty <content-security-policy> element in the layout configuration:

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

Once in production, it is recommended that trusted sources be whitelisted. For further information, examples of a number of trusted sources can be seen in content security policy.

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!

Whenever working with HTML, use the XHTML syntax:. This means all attributes must have a value, even if the value is empty.  Close all elements and use only numeric character entities.

Document template

Although media fragments are part of PSML, they cannot be used directly without a document template. The easiest way to set up a document template is to create a dedicated section as in the example below:

<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>

Videos example

Below is a more specific example using a Template for a youtube video:

<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

In order to be able to edit a media fragment via the user interface, the document configuration must define an editor associated with that kind of 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>

Created on , last edited on