PresentationML
PresentationML describes the markup which can be used to format and style messages in the Symphony system. PresentationML is a strict sub-set of HTML5 except for a small number of PresentationML V1 tags which will be supported for transitional reasons, but which will be transliterated into standard PresentationML tags by the API Agent on message submission. This will be a one-way transformation, an API caller which submits a message containing transitional markup and then retrieves the message will see the transliterated, standard, markup.
PresentationML consists of exactly the features specified here, other features of HTML5, CSS or any other standard which are not specifically included here, are by definition specifically excluded from PresentationML. This extends to attributes of supported tags, so only the attributes specifically listed are supported and other attributes, even if supported in HTML5 will be rejected or stripped.
Character Encoding
PresentationML does not constitute a complete HTML document, and no DOCTYPE or charset specification is included. All PresentationML MUST be encoded in UTF-8.
Balanced Tags
All PresentationML tags must be balanced and properly closed. For example the use of unbalanced paragraph or line break tags is unsupported. Paragraphs should be represented with balanced <p> and </p> tags and line breaks must be represented as <br/>.
Styles
PresentationML does not include CSS, inline styles specified by the style attribute are specifically excluded from PresentationML, however a set of defined styles are specified as part of PresentationML and where a PresentationML tag supports the class attribute, these standard styles may be applied. The exact presentation of these styles will vary depending on the UI theme selected by the user. The styles are named functionally, as opposed to visually (e.g. alertText rather than red, even though alertText would normally be rendered in a red color). Message originators are encouraged to use these styles in a manner which is consistent with their function so as to present a coherent user experience.
URLs
Images and other elements with URLs (href attributes) represent potential security and privacy issues. For these reasons, the allowable URLs in PresentationML are strictly limited. The following URL types are allowed, all other types are excluded.
| Type | Description |
|---|---|
| Data | Data URLs as specified in https://tools.ietf.org/html/rfc2397 which allows for data provided inline as part of the message. Within this only the following media types will be allowed:
|
| Internal | URLs below https://asset.symphony.com/symphony/ represent various special values which can be used in MessageML contexts. These URLs may or may not be reachable via HTTP using a web browser, and where they are they may be protected by authentication checks. In some cases these will simply be a way of notating data such as a Symphony internal user id. |
| Hosted | For applications where users wish to make frequent use of image assets Symphony may provide a hosting service into which assets can be uploaded. The hostnames for this hosted service will be specifically whitelisted so that URLs referring there may be used. |
PresentationML V2 Elements
Tag | Description | Allowed Attributes |
|---|---|---|
| <div data-format="PresentationML" data-version="2.0">presentationML</div> | The root element of a PresentationML message. The value of the data-format attribute MUST be PresentationML and the data-version attribute MUST be present. | data-format (required) data-version (required) |
| <div class="style" data-entity-id="jsonId">presentationML</div> | Structure and styling. Where the value of class is entity the data-entity-id attribute MUST be present and MUST refer to an element in the associated EntityJSON data structure. Where the class is absent or any value other than entity, the data-entity-id attribute MUST NOT be present. If the data-icon-src or data-accent-color attributes are set, the class attribute MUST be card. | class data-entity-id data-icon-src data-accent-color |
| <span class="style"> | Styling Where the class is absent or any value other than entity, the data-entity-id attribute MUST NOT be present. | class |
| <span class="entity" data-entity-id="keyword123">#tag</span> | Hashtag. The associated EntityJson data identifies this as a hashtag as well as causing the appropriate styling to be applied. The content MUST start with the character #. The data-entity-id attribute value MUST refer to an element in the associated EntityJSON data. | class (required) data-entity-id (required) |
| <span class="entity" data-entity-id="keyword123">$tag</span> | Cashtag. The associated EntityJson data identifies this as a cashtag as well as causing the appropriate styling to be applied. The content MUST start with the character $. The data-entity-id attribute value MUST refer to an element in the associated EntityJSON data. | class (required) data-entity-id (required) |
| <span class="entity" data-entity-id="mention123">@Pretty Name</span> | Mention. The associated EntityJson data identifies this as a mention as well as causing the appropriate styling to be applied. The content MUST start with the character @. The data-entity-id attribute value MUST refer to an element in the associated EntityJSON data. When submitted at the API Agent the content (@Pretty Name) will be validated and the message rejected if it does not match the correct name for the specified user. API callers may find it more convenient to use the MessageML <mention> tag instead. | class (required) data-entity-id (required) |
| <p class="style">text</p> | Paragraph, contains text to be rendered as a single block of text. | class |
| <b class="style">text</b> | Bold, contains text to be rendered in an emphasized way, by presentation as a bold font if possible. | class |
| <i class="style">text</i> | Italic, contains text to be rendered in a (secondary) emphasized way, by presentation as an italic font if possible. | class |
<h1>text</h1> ... <h6>text</h6> | Section heading of level 1-6. | class |
| <br/> | Line break. | |
| <hr/> | Horizontal rule. | |
| <a class="style" href="url">Link Text</a> | Hyperlink to an external URL. Supported URI schemes need to be explicitly whitelisted by the pod. | class href |
| <ul class="style"><li class="style">List Item 1<li/><li class="style">List Item 2<li/></ul> | Unordered list, should be rendered as bullet points if possible. | class |
| <ol class="style"><li class="style">List Item 1<li/><li class="style">List Item 2<li/></ol> | Ordered list, should be rendered as a numbered list if possible. | class |
<table class="style"> <thead> <tr class="style"><th class="style">Col 1</th><th class="style">Col 2</th></tr> </thead> <tbody> <tr class="style"><td class="style">Cell 1,1</td><td class="style">Cell 1,2</td></tr> </tbody> <tfoot> <tr class="style"><td class="style">Footer 1,1</td><td class="style">Footer 1,2</td></tr> </tfoot> </table> | Simple table. | class |
<img src="url"/> | Inline image. Note that size limits will be placed on this element to fit within the wider UI. | src (required) class |
| <audio src="https://asset.symphony.com/symphony/audio/chime.mp3" autoplay="true" /> | Chime. Initially only chime.mp3 will be permitted as a source attribute. The autoplay attribute is required. | src (required) autoplay (required) |
PresentationML V2 Styles
The following styles are allowed as values for the class attribute of tags which support it. The given rendering is indicative only and may vary depending on the UI theme selected by the user.
| Style | Description | Indicative Rendering |
|---|---|---|
| label | Text, formatted as a label, which can be used to indicate the content of other elements. | Grey. |
| alert | Text, formatted as an alert message. | Red. |
| warning | Text, formatted as a warning message. | Yellow. |
| info | Text, formatted as informational data. | Blue. |
| action | Text, formatted as a record of some user action. | Orange. |
| confirmation | Text, formatted as a confirmation message. | Green. |
| Purple. | ||
| Dark Green. | ||
| Dark Blue. | ||
| labelHighlight | Text, formatted as a label, which can be used to indicate the content of other elements. | Bold + Grey. |
| alertHighlight | Text, formatted as an alert message. | Bold + Red. |
| warningHighlight | Text, formatted as a warning message. | Bold + Yellow. |
| infoHighlight | Text, formatted as informational data. | Bold + Blue. |
| actionHighlight | Text, formatted as a call to action. | Bold + Orange. |
| confirmationHighlight | Text, formatted as a confirmation message. | Bold + Green. |
| Bold + Purple. | ||
| Bold + Dark Green. | ||
| Bold + Dark Blue. | ||
| labelBackground | Text, formatted as a badge, which can be used to indicate the content of other elements. | Black text on a Grey background. |
| alertBackground | Text, formatted as an alert badge. | White text on a Red background. |
| warningBackground | Text, formatted as a warning badge. | Black text on a Yellow background. |
| infoBackground | Text, formatted as an informational badge. | White text on a Blue background. |
| actionBackground | Text, formatted as a call to badge. | White text on a Orange background. |
| confirmationBackground | Text, formatted as a confirmation badge. | White text on a Green background. |
| White text on a Purple background. | ||
| White text on a Dark Green background. | ||
| White text on a Dark Blue background. | ||
| badge | A badge, with a colored background and rounded corners and of constrained height. Can be combined with *Background styles as in class="infoBackground badge" | Rounded corners and fixed height. |
| sideBar | A left sidebar which renders a colored border. Can be combined with *Background styles as in class="infoBackground sideBar" | |
| card | A card, which can be opened and closed by the user. The header is always visible, the body is visible only when opened. A card should be represented as a div with this style containing a sideBar, cardHeader and cardBody. | |
| cardHeader | The header section of a card, which can be opened and closed by the user. The header is always visible, the body is visible only when opened. | |
| cardBody | The body section of a card, which can be opened and closed by the user. The header is always visible, the body is visible only when opened. | |
| icon | A small image, that can be rendered alongside the text and have the same perceived size. Intended for use with <src/> | Text size. |
| hashTag | A hashtag, this style causes behavior as well as formatting. Applicable only to <span/>. | Blue underlined. |
| cashTag | A cashtag, this style causes behavior as well as formatting. Applicable only to <span/>. | Blue underlined. |
| mention | A mention, this style causes behavior as well as formatting. Applicable only to <span/>. | Blue underlined. |
Need help? Email help@finos.org we'll get back to you.
Content on this page is licensed under the CC BY 4.0 license.
Code on this page is licensed under the Apache 2.0 license.