To create a web application with Moya you will need to be familiar with writing and editing XML. This document will get you up to speed with working with XML but is not intended to be comprehensive. You should be able to find plenty of resources on the Internet if you would like to know more.

Tags and Text ¶

An XML document consists of tags which looks something like this:

<moya>
</moya>

The text <moya> marks the beginning of a tag, and the text </moya> marks the end. There may be other tags inside a tag. For example:

<moya>
    <macro docname="main">
        <echo>Hello, World</echo>
    </macro>
</moya>

Here we can see there is <macro> tag inside the <moya> tag.

You may have noticed that the <macro> tag has some additional text, docname="main", inside the angular brackets. This is called a tag attribute, which associates information with the tag. In the previous example, the <macro> tag has a tag attribute called docname with a value of main. A tag may contain zero or more attributes.

Tags may also contain text. In the previous example, there is an echo tag which contains the text Hello, World.

If a tag doesn't contain any child tags or text, it may be auto-closed with the following syntax:

<breakpoint/>

Here we can see an auto-closed tag which is equivalent to the following:

<breakpoint></breakpoint>

Comments ¶

You can insert comments in the an XML document which serve has reminders to refresh your memory when re-visiting code you may have written some time ago. Comments are introduced with <!-- and end with -->. Here is an example of an XL comment:

<moya>
    <!-- this is a comment -->
</moya>

Namespaces ¶

XML documents may mix tags defined from various sources. A problem arises that a tag may have the same name as another, and the parser would be unable to know which one was intended. This is true in Moya, which allows third party libraries to implement tags.

As an example, Moya defines a tag called <get> which gets a form, it also defines a tag called <get> which gets an object from the database. The way the parser can know which tag is which is through XML namespaces. You can set the namespace of a tag with the xmlns attribute. For example:

<moya>
    <get xmlns="http://moyaproject.com/db"/>
    <get xmlns="http://moyaproject.com/forms"/>
</moya>

Here we can see two <get> tags with a different xmlns attribute for each. This attribute takes a URL which has been reserved for the namespace. The parser never reads the URL, in fact the URL doesn't need to return any content if you visit it in a browser. URLs are used to identify namespaces because if you only use URLs from domains you own, you can be sure there will not be any conflict with third parties.

Setting the namespace this way can be somewhat verbose if you are mixing tags from a variety of namespaces. A more compact way of setting the namespace is to define a namespace prefix on an outer tag (often the root tag). Here's an example of setting a namespace prefix:

<moya xmlns:db="http://moyaproject.com/db" xmlns:forms="http://moyaproject.com/forms">
    <db:get/>
    <form:get/>
</moya>

The text xmlns:db="http://moyaproject.com/db" introduces the namespace prefix db:. Any child tags with db: will be in the http://moyaproject.com/db namespace. A namespace prefix for forms is defined in the same way. The prefix text may be anything you want, and is generally chosen to be short yet descriptive.

Moya Boilerplate ¶

The first tag (known as the root tag) you write in a Moya project file should be <moya>. Further tags (forms, content, views etc.) should be contained within this root tag.

There are a number of commonly used namespaces that would would be worthwhile including in a template file you can use as a starting point for new code. There may be a feature in your OS or editor to simplify this.

Here's a good start for a blank Moya XML file:

<?xml version="1.0" ?>
<moya xmlns="http://moyaproject.com"
    xmlns:let="http://moyaproject.com/let"
    xmlns:db="http://moyaproject.com/db"
    xmlns:forms="http://moyaproject.com/forms"/>

    <!-- your content goes here -->

</moya>

The first line in the above XML file is a processing instruction which indicates the version of the XML specification. It is not strictly necessary, and Moya will happily parse any XML files without it.

Note the namespace declaration of xmlns="http://moyaproject.com" which sets the default namespace for tags without a namespace prefix (which is most tags in Moya). This is also not strictly necessarily because Moya assumes this namespace by default. However, it is good practice to include it. The other namespace declarations introduce the LET extension, database and form tags.