Documents

Handling and managing documents

Embedding HTML content

PSML <media-fragment> element can be used to include HTML content directly into data. This can be useful to embed a video from external service providers such as YouTube, Vimeo or Google Map directly into PSML.

Note

This article only applies to PageSeeder 5.9 or newer.

To embed or not to embed

Warning!

Please read this before continuing.

PSML is designed to separate content from presentation. So it is not recommended that content that is specific to a publish output, such as some HTML code to appear on a Website, be embedded in PSML. Keeping PSML simple makes it easier to maintain data and update the publish output. It also makes it easier to handle data that isn't supported by a publish output.

For example, to include a video from YouTube or Vimeo, all that is needed in PSML is the title and ID of the video. Storing only the minimum amount of details makes it possible to use different players on a Website without having to change the data. It also makes it possible to filter out the video, or display a thumbnail, when publishing to Word document or PDF.

However, there are cases when copying a piece of HTML from an external service provider is more convenient, and easier to check that the content is correct in the PageSeeder interface.

Security

For security, PageSeeder does not allow any content from untrusted sources. This is to protect end-users from common attacks such as cross-site scripting, clickjacking and code injection.

Starting from PageSeeder 5.9, it is possible to specify which sources are trusted so that they can be included in PageSeeder. 

While testing, the content security policy can be disabled by 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 convenience, a number of common trusted sources have been listed in content security policy.

Media fragment

A <media-fragment> is a special kind of fragment that can be used to include non-PSML content such as MathML, XHTML or SVG. The type of content is specified using the @mediatype attribute.

To include HTML content in PSML, it is recommended that you use XHTML (application/xhtml+xml) rather than HTML (text/html), as it will be possible to process it with XSLT or other XML tools. Here is the PSML markup for an XHTML media fragment:

<media-fragment id="123" mediatype="application/xhtml+xml">
  <!-- Your embedded XHTML content -->
</media-fragment>

 For example, here is the PSML code for a YouTube video:

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

When copying and pasting HTML code, make sure that it uses XHTML syntax: all attributes must have a value (even empty), all elements must be closed and only numeric character entities can be used.

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