krpano 1.19-pr16 (build 2018-04-04)

Basic XML Syntax Rules

krpano uses simple xml text files for storing the settings for the krpano viewer. These files can be written or edited with any usual texteditor, but when writting the xml code, it is important that the xml-syntax-rules will be respected! These basic rules are the same for all xml files and not specific to krpano.
The syntax rules of xml files are simple, logical, easy to learn and easy to use.
So here now the rules:

The Basic XML Structure

  • A xml file is structured by several xml-elements, also called xml-nodes or xml-tags.
  • The name of a xml-element is enclosed by < > brackets: 
    <element>
  • Each xml-element needs to closed.
    This can be written in two forms - either with start- and end-elements: 
    <element> ... </element>
    or for simple-cases just this way: 
    <element />
  • A xml-element can contain additional children xml-elements inside it.
    In this case, the xml-element need to be written in that form: 
    <parentelement>
   <childrenelement />
</parentelement>
  • A xml-element can have one or more attributes. Each attribute is build out of an attribute-name and an attribue-value. The attribute-value must be written inside single or double quotes. 
    <element attribute="value">
   <childrenelement test1="value1" test2="value2" />
</element>
    Note - duplicate attributes on one element are not allowed and will cause a syntax error!
  • There must be always one, so called 'root-element', in the xml. This is the hierarchically top-most xml-element. All other xml-elements need to be within it.
    For the krpano viewer this element is always the <krpano> element - e.g.: 
    <krpano onstart="...">
   ...
   <preview url="..." />
   <image>
     <cube url="..." />
   </image>
   ...
</krpano>
  • Comments - comments are parts of the xml that will be ignored when reading/parsing the xml. A xml-comment starts with: 
    <!--
    and ends with: 
    -->
    The string '--' (double-hyphen) is not allowed inside comments - this means comments can not be nested.
    Example: 
    <krpano ...>
   <!-- this is a krpano example -->
   ...
</krpano>

Case / Character Encoding / Whitespaces / Not allowed Characters

  • The names of xml-elements and xml-attributes are case-sensitive. That means the name of start- and end-elements need to be written in the same case.
    Note - for the xml syntax rules the case is very important, but for the krpano viewer itself, the case of the krpano xml elements doesn't matter - the krpano viewer will automatically convert all element and attribute names to lower case to make their krpano-usage case-insensitive.
  • To avoid character encoding problems all xml files should be saved as Unicode UTF-8 or UTF-16 files. The text-editor will add a small hidden header (called UTF-BOM) at the beginning of the xml file in this case.
  • Whitespace characters like blanks, tabs and line-breaks between xml-elements and between the xml-attributes will be ignored. But inside attribute-values they will be respected.
    This allows to freely write and structurate the xml in many ways. But for better readability it often makes sense to indent elements in a way that make their hierarchical structure more clear.
  • Some characters are reserved by the xml syntax itself, so they can't be used directly.
    To use them anyway there are some replacement-entities that can be used:
    not allowed characterreplacement-entitycharacter description
    <&lt;less than
    >&gt;greater than
    &&amp;ampersand
    '&apos;apostrophe
    "&quot;quotation mark

XML Error Checking / Checklist

  • To check the syntax of a xml file, just open it directly in the browser. The most modern browsers are directly showing the location and the type of the error when there is one.
  • Here a quick checklist for xml errors:
    1. Is there a root xml-element? 
      <krpano>
    ...
</krpano>
    2. Are all xml-elements correctly closed?
      wrong correct 
      <element> ... <element>
      		 
      <element> ... </element>
      		 
      <element ... >
      		 
      <element ... />
    3. Are all xml-comments correctly? (begin with <!-- and end with --> and no -- between) 
      <!-- <!-- nested comment --> -->
      <!---------->
    4. Are there some reserved-characters? (e.g. &, < or >)
      wrong correct 
      text="krpano & xml"
      		 
      text="krpano &amp; xml"
      		 
      text="<xml>"
      		 
      text="&lt;xml&gt;"
      		 
      if(x < 10, ...)
      		 
      if(x LT 10, ...)
    5. Are all attribute values within quotes?
      wrong correct 
      <element x=123 ... />
      		 
      <element x="123" ... />
      		 
      <element x=123 ... />
      		 
      <element x='123' ... />
    6. Are there duplicated attributes on one element? 
      <element x="123" x="456" ... />
    7. Are there missing whitespaces between two attributes?
      wrong correct 
      <element x="123"y="456"
      		 
      <element x="123" y="456"

Flash - HTML5 Differences

  • There is sometimes the case that a xml file is working fine in the Flashplayer, but is showing an error message in the HTML5 version.
  • The reason for that behavior is that the xml-parser of the Flashplayer is much more tolerant to xml syntax errors than the xml-parsers of the HTML5-browsers.
  • The solution to make it working everything is simple - just make sure that there are no xml syntax errors and it will automatically work in Flash and in HTML5.