HTML, XML, XHTML & MAML

When Tim Berners-Lee created HTML (HyperText Markup Language) in the early 1990s he based it on the concept of tag markup used by SGML (Standard Generalized Markup Language) and so we all became familiar with the practice of structuring (and formatting in the pre-CSS days) text with tags like <h1> and <p>. HTML was rather loosely defined and the various browsers' developers each created their own versions of it and added their own tags, so HTML evolved, though somewhat haphazardly. Before long two things became clear; one, that HTML was inconsistent and difficult for software to parse and interpret correctly, and two, it was neither extensible, nor sufficient for all of the tasks web developers wished to do. To address these two deficiencies the W3C (World Wide Web Consortium), headed by Berners-Lee, created XML and XHTML. XML stands for eXtensible Markup Language. XML is basically a set of rules for creating markup languages that use tags like HTML. By following these rules any software developer can create a markup language to serve whatever purposes they might have. XHTML is a reformulation of HTML that follows the rules of XML. This slightly stricter version of HTML has supplanted HTML as of version 4.01, and provides web developers several benefits including a cleaner separation of structure and presentation than HTML and the ability to be used and parsed together with other XML-based markup languages.

Molly uses an XML-based markup language named MAML (Molly Active Markup Language) mixed together with XHTML to allow web site developers to easily add sophisticated server-side functionality to their sites without having to learn complex programming languages like PHP, Perl, Java, ASP, or .NET. Instead, web developers use the XHTML tags they already know together with new MAML tags that Molly uses to generate more XHTML dynamically based on things such as database lookups which would normally require a fair amount of custom programming.

History of Molly

In the mid 1990s one of us (Vullo) began building web-based applications for dental education. These included online learning and electronic dental records. Even then, it was clear that web sites needed pages which were dynamically generated from information stored in databases. At the time the database he used was Apple's FileMaker Pro and the tool for embedding that information into a web page was Blue World's Lasso.

Several years later Vullo was called upon to create a new distance education and medical record system. This was to be a more ambitious project and after prototyping with Lasso it became clear that a more robust and flexible system would be required. Fortune smiled and PHP 4 was released about this time and with its maturity was rapidly developing a reputation as an outstanding server-side web development language. PHP also supported access to multiple database systems including the then up-and-coming MySQL.

While the typical PHP approach to building web applications at the time was to simply build HTML pages and embed snippets of stand-alone PHP code wherever dynamic content was required, Vullo decided to take a different approach. He recognized that such a development style quickly becomes difficult to support and scales poorly with large sites. Instead he decided to build an organized code library, encapsulating oft-needed functionality into generic functions. Then, instead of embedding chunks of code into a web page, a single line function call would be used instead, much more like an HTML tag than an embedded program. Thus was born (the as-of-yet unnamed) Molly version 1. Soon after this one of us (Hoey) gave birth to a daughter and named her Molly. Vullo named the software after Molly as a gift to her mother.

Soon thereafter the W3C released XML and XHTML and it became clear that the next logical step was to eliminate the PHP entirely from the web pages and replace the function calls with XML tags designed to be usable by HTML authors without any need of programming or understanding PHP. This change necessitated a new architecture for Molly, and so Molly II was developed.

How Molly is different from other Systems

Over the years Molly has been compared with various other systems such as ColdFusion, Mambo, Joomla, and Ruby on Rails. While each of these systems has its strengths, and share some abilities with Molly, they are also different enough in design, philosophy, architecture, and implementation for us to confidently continue to develop and use Molly. Here then is a brief comparison of Molly's similarities and differences to these other tools:

How Molly Works

Molly is a web server-side technology, which is to say that all of the work that Molly does happens on the web server. The user never sees any of Molly's MAML tags or underlying programming. Contrast this with client-side technologies like JavaScript where all the user needs to do is "View Source" in their browser and they can see all of the code. When a user does that on a page processed by Molly, all they see is the XHTML that Molly generates.

So, being a server-side technology, Molly has to be installed on a web server. How to do that is explained in Appendix I: Installing Molly.

Molly uses special new tags to add server-side functionality to your web pages. Because XHTML is a language built in XML it allows us to add other XML languages' tags to our code. Molly implements one such language — Molly Active Markup Language, or MAML. MAML tags look and are written just like XHTML tags with one difference; they include the "maml:" prefix that tells Molly (and other XML processors) that those tags are not XHTML. That way MAML can have tags with the same name as XHTML tags and there is no problem. For example, XHTML has the <form> tag and Molly has the <maml:form> tag. These can both be used in the same document without any problem. At this point you may be wondering why Molly would have her own form tag and not just call it something else. Well, Molly's forms look and act just like XHTML's forms, except that Molly's automatically connect to the database and process the data when the user clicks the submit button. With an XHTML form the webmaster would have to write all of the necessary server-side programs necessary to do that.

So Molly is at her heart an XML parser, but she's really much more. She's what we call an "abstraction layer." Molly's MAML tags are abstractions that hide all the underlying programming from you so that you can focus on building your web site and not on the details of programming the functionality that makes your site dynamic. Just like XHTML and CSS together form an abstraction layer that hides the complexity of delivering content over the internet and rendering it into the pixels you see on your computer screen.

Molly is written in a programming language called PHP. (Programming languages themselves are abstraction layers above the binary code that computer processors actually read and write.) Molly is designed to be extensible and so if you know PHP and wish to add new functionality that is not only possible, but fairly easy to do thanks to over a decade of experience in designing and building her architecture. Part III: Under the Hood explains that architecture and the rules we follow when programming Molly.

How Molly Helps

Molly helps by eliminating most of the need to write custom server-side code necessary to build dynamic web sites and web applications (WebApps). Molly does this in a way that, while giving the web developer the advantages of a content management system and skinned environment, does not interfere with their ability to handcraft their HTML and CSS however they like. Molly does not impose design or architecture paradigms or constraints. While we provide some default pages and skins, it is just as easy to retro-fit Molly into your own web site's design and architecture and eliminate embedded PHP or add new functionality without writing any.

Part I: Learning Molly & MAML

If you already know how to build web pages in XHTML, then you are well on your way to learning how to use MAML, since MAML uses simple tags very much like those with which you are already familiar. The first thing we will cover is the basic structure of a MAML page. We will demonstrate how MAML is translated by Molly into XHTML. After that we will explain how to to use a few MAML tags, and how they are transformed by Molly into XHTML.

A Basic MAML page's boilerplate code is virtually identical to a normal XHTML page. So to see the difference, let's build "Hello World" in XHTML and in MAML.

(Why "Hello World?" Well this is a computer book, and it's the law. ;o)

Basic HTML Document:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
        "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
    <meta http-equiv="content-type" content="text/html; charset=utf-8" />
    <title>Hello World HTML</title>
</head>
<body>
    <p>Hello World!</p>
</body>
</html>

Basic MAML Document:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
        "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" xmlns:maml="http://interpersonalnet.com/maml/">
<head>
    <meta http-equiv="content-type" content="text/html; charset=utf-8" />
    <title>Hello World MAML</title>
</head>
<body>
    <p>Hello World!</p>
</body>
</html>
 

See the difference? Yeah, it's hard. The only difference is on the third line. Here, this time I'll highlight it so you can see it easier:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
        "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" xmlns:maml="http://interpersonalnet.com/maml/">
<head>
    <meta http-equiv="content-type" content="text/html; charset=utf-8" />
    <title>Hello World MAML</title>
</head>
<body>
    <p>Hello World!</p>
</body>
</html>
 

It's not much, but it's very important. What does that snippet of extra code do? Well, it does a little bit of XML magic and adds the "maml" namespace to the document so that Molly's XML parser can process the file and do all the cool things that make Molly what she is. That namespace declaration is why Molly's tags all begin with "maml:" like this:

<maml:box>Some text with a box around it.</maml:box>

This use of namespaces also makes the MAML XML syntax compliant with XML and XHTML standards, so any XML editor or processing software should have no problem with Molly's MAML code.

OK, so let's take our simple example a little further. We'll add the <maml:box> tag to our Hello World MAML file like this:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
        "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" xmlns:maml="http://interpersonalnet.com/maml/">
<head>
    <meta http-equiv="content-type" content="text/html; charset=utf-8" />
    <title>Hello World MAML</title>
</head>
<body>
    <p>Hello World!</p>
    <maml:box>Some text with a box around it.</maml:box>
</body>
</html>

Now if we save this as a file with a .maml extension like hello_world.maml and view it in a browser from a Molly Server it will look something like this:

	

		
Hello World!
		

	

	

		
Some text with a box around it.		
	


        
 
	

(Remember, Molly is a "server-side" technology and so MAML pages have to be viewed in a web browser via HTTP from a server where Molly is installed. If you view the page from your local hard drive via the browser's file:// URL the browser will not understand the MAML code.)

Molly processes the MAML file and generates an HTML document similar to the following in its place:

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
    <meta http-equiv = "content-type" content = "text/html; charset=utf-8">
    <title>Hello World MAML</title>
    <link rel="stylesheet" type="text/css" href="/~rvullo/decor/default.css" />
    <style type="text/css">
        // Styles go here
    </style>
    <script type="text/javascript">
        // Scripts go here
    </script>
</head>
<body>
    <p>Hello World!</p>
    <div class="box">
        <p class="title"></p>
        <p class="contents">
            <span class="boxbottom">
                Some text with a box around it.
            </span>
        </p>
    </div>
</body>
</html>

Now at this point you don't really have to worry about the specific code that Molly generated, this is simply to illustrate the point that Molly translates the MAML tags into HTML and automates a lot of things like adding CSS and JavaScript when necessary. Note that while Molly requires XHTML as input, current skins generate the newer (but not XML compliant) HTML5 as output. You may incorporate any HTML5 tags into your MAML pages as long as they are "well formed." This means that Every open tag requires a close tag, and all tag attributes must be enclosed in double quotes. As a simple example, HTML5 allows the <br> tag, however in a MAML file that must be typed as <br /> so that the XML parser can process it. Likewise, while HTML5 allows <a href=page.maml>Link to Page</a>, Molly requires that to be expressed as <a href="page.maml">Link to Page</a> with the href attribute's value properly enclosed in double quotes.

Getting Started with Database Access

Molly makes it very easy to fetch information from a database and put it on a web page formatted however you want. Here is a simple example of that:

Notice that clicking the column titles sorts the results.

Here is the MAML and HTML source code to generate the above list (line numbers added for explanation reference):

<maml:fetch table="molly_test" key="name" criteria="true" sort = "name" order = "ascending">
    <table style="width:22em; background-color: #f4f5fb;padding:1em;">
        <tr>
            <th><maml:sort sort="name">Name</maml:sort></th>
            <th><maml:sort sort="eyecolor">Eye Color</maml:sort></th>
            <th><maml:sort sort="age">Age</maml:sort></th>
        </tr>
        <maml:row>
            <tr>
                <td><maml:field name="name"/></td>
                <td><maml:field name="eyecolor"/></td>
                <td><maml:field name="age"/></td>
            </tr>
        </maml:row>
        <tr>
            <th colspan="3" style="text-align:right;">Total Records: <maml:numrows/></th>
        </tr>
    </table>
</maml:fetch>

1. The <maml:fetch> tag is used to set up a query to retrieve information from the database. The table attribute specifies which table to search. The key attribute specifies the key field for the table. The criteria attribute specifies the search. In this case we set criteria="true" so Molly fetches all of the records in the table. You could be more specific with something like criteria="age > 10" and fewer records would be found. Finally sort = "name" and order = "ascending" tell Molly to return the results sorted by the name field.
2. This is an ordinary <table> tag. Because you mix MAML tags freely with HTML you can format your output however you wish. You could use an ordered list instead of a table if you like.
3. Our first table row will have the column headers.
4. This is a simple HTML <th>Name</th> one would normally use to create a table header with the addition of a <maml:sort sort="name"> tag. This simple tag tells Molly to create all the necessary code to allow users to click on the column head and retrieve a sorted list based on the field name specified in the sort attribute.
5. As above we've added sorting, by eye color in this case.
6. And here we're sorting by age.
7. End of the header row of the table.
8. Everything between the <maml:row> and </maml:row> tag pair will be repeated for every record found by the query specified in the <maml:fetch> tag.
9. Because we're building an HTML table we'll repeat a <tr> table row.
10. This HTML <td> contains the <maml:field name="name"/> tag which will be replaced by the results of the search for each row. The name attribute specifies the database field name.
11. Likewise this table data cell will be filled with eye color.
12. And this with data from the table's age field.
13. End of the table row.
14. And end of the record (and the portion of the code which will repeat for every record found).
15. We're adding one last row to our table…
16. Which will display the number of rows Molly found in the database (and rendered above).
17. And we have to close all of our open tags.

Tokens

Tokens are place holders for values which Molly will substitute before sending the page to the browser. (Programmers can think of these as variables.) Some tokens are pre-defined as part of Molly's configuration to make it easy, for example, to create a path to an image which will work from any of the site's pages:

<img src="*[HTMLRoot]*decor/icons/gradcap-7.png" />

Other tokens can be set by the webmaster using the <maml:token> and <maml:persist> tags.

Pre-Defined Tokens

Configuration Tokens (Set in the site's .ini file and molly_config database table)

*[HTMLRoot]* —> HTML Path to the root of the site
*[SkinDirectory]* —> Path to skins directory, relative to *[HTMLRoot]*
*[Skin]* —> Current Skin
*[SystemRoot]* —> HTML Path to Molly's system directory
*[FileRoot]* —> Unix path to the root of the site
*[QueryString]* —> Query String (if any) sent by browser when requesting this page†
*[SkinScripts]* —> JavaScripts Molly will be inserted into the page's head†
*[ConfigTable]* —> The name of the table from which the site's configuration settings have been read.

†In general webmasters should not access these, they are for internal system use only

Tag-Specific Tokens

Some tags as part of their functionality create pre-defined tokens as well. For example, the <maml:login> tag will create tokens when a user logs into the site:

Molly Page Tokens relevant to login

*[LoggedIn]* —> Set to 1 (true) if the user is logged in, 0 (false) if not
*[LastName]* —> logged in user's last name
*[FirstName]* —> logged in user's first name
*[Salutation]* —> logged in user's salutation (i.e. Miss, Mrs, Mr, Dr, etc.)
*[UserID]* —> logged in user's unique user id (integer)
*[LoginName]* —> logged in user's unique username/alias

Currently Defined Tokens

The following is a dynamically generated list of all the currently defined tokens for this page view in the Molly installation you are using to read this page:

• ActiveLinkColor
• AttachmentsDirectory
• BackgroundColor
• BackgroundImage
• BoxFrameColor
• ConfigTable
• CurrentYear
• FileRoot
• FirstName
• FormDark
• FormHandler
• FormLight
• FormMedium
• HTMLRoot
• HoverLinkColor
• LastName
• LinkColor
• LoggedIn
• LoginName
• MenuColor
• MenuLinkColor
• MenuRolloverBackgroundColor
• MenuRolloverTextColor
• MenuSelectedBackgroundColor
• MenuSelectedTextColor
• MenuTextColor
• PageColor
• QueryString
• Salutation
• SelectedTabColor
• SidebarHeadingBackgroundColor
• SidebarHeadingTextColor
• SidebarLinkColor
• SiteLogo
• SiteName
• Skin
• SkinDirectory
• SkinScripts
• SystemFileRoot
• SystemRoot
• TabColorHover
• TextColor
• UnselectedTabColor
• UserID
• VisitedLinkColor
• WebCronLastRun
• WindoidFieldColor
• WindoidFrameColor
• copyright
• javascript
• stylesheet
• tagline

If you wish to see the current values for all of the tokens on your site, you can use the following code on a .maml page:

<div>
   ActiveLinkColor: *[ActiveLinkColor]*<br />
   AttachmentsDirectory: *[AttachmentsDirectory]*<br />
   BackgroundColor: *[BackgroundColor]*<br />
   BackgroundImage: *[BackgroundImage]*<br />
   BoxFrameColor: *[BoxFrameColor]*<br />
   ConfigTable: *[ConfigTable]*<br />
   CurrentYear: *[CurrentYear]*<br />
   FileRoot: *[FileRoot]*<br />
   FirstName: *[FirstName]*<br />
   FormDark: *[FormDark]*<br />
   FormHandler: *[FormHandler]*<br />
   FormLight: *[FormLight]*<br />
   FormMedium: *[FormMedium]*<br />
   HTMLRoot: *[HTMLRoot]*<br />
   HoverLinkColor: *[HoverLinkColor]*<br />
   LastName: *[LastName]*<br />
   LinkColor: *[LinkColor]*<br />
   LoggedIn: *[LoggedIn]*<br />
   LoginName: *[LoginName]*<br />
   MenuColor: *[MenuColor]*<br />
   MenuLinkColor: *[MenuLinkColor]*<br />
   MenuRolloverBackgroundColor: *[MenuRolloverBackgroundColor]*<br />
   MenuRolloverTextColor: *[MenuRolloverTextColor]*<br />
   MenuSelectedBackgroundColor: *[MenuSelectedBackgroundColor]*<br />
   MenuSelectedTextColor: *[MenuSelectedTextColor]*<br />
   MenuTextColor: *[MenuTextColor]*<br />
   PageColor: *[PageColor]*<br />
   QueryString: *[QueryString]*<br />
   Salutation: *[Salutation]*<br />
   SelectedTabColor: *[SelectedTabColor]*<br />
   SidebarHeadingBackgroundColor: *[SidebarHeadingBackgroundColor]*<br />
   SidebarHeadingTextColor: *[SidebarHeadingTextColor]*<br />
   SidebarLinkColor: *[SidebarLinkColor]*<br />
   SiteLogo: *[SiteLogo]*<br />
   SiteName: *[SiteName]*<br />
   Skin: *[Skin]*<br />
   SkinDirectory: *[SkinDirectory]*<br />
   SkinScripts: *[SkinScripts]*<br />
   SystemFileRoot: *[SystemFileRoot]*<br />
   SystemRoot: *[SystemRoot]*<br />
   TabColorHover: *[TabColorHover]*<br />
   TextColor: *[TextColor]*<br />
   UnselectedTabColor: *[UnselectedTabColor]*<br />
   UserID: *[UserID]*<br />
   VisitedLinkColor: *[VisitedLinkColor]*<br />
   WebCronLastRun: *[WebCronLastRun]*<br />
   WindoidFieldColor: *[WindoidFieldColor]*<br />
   WindoidFrameColor: *[WindoidFrameColor]*<br />
   copyright: *[copyright]*<br />
   javascript: *[javascript]*<br />
   stylesheet: *[stylesheet]*<br />
   tagline: *[tagline]*<br />
</div>

Skins

Molly uses a "skins" system to facilitate changing the look and feel of your web site, as well as allowing you to change the way many MAML tags render their output. All of the presentation code and images for Molly are contained in the decor directory in the root of your Molly site. Skins are contained within this decor directory (though the path to skins may be changed in your molly.ini file).

Anatomy of a Skin

Within the skins directory can be one or more directories, the name of which is the name of the skin. The name of the skin currently being used by this particular Molly installation is "hex." Skin directories have a specific structure and set of files. There are two required files:

• main.css
• main.js.htmf

And three required directories:

• images
• scripts
• templates

main.css File

This is the stylesheet that will be linked to every .maml page on your site. The file will be processed to replace tokens with their appropriate values. Most of these (the presentational ones) are set in the molly_config table of the database. Tokens which provide appropriate paths are set in the molly.ini file.

main.js.htmf File

This is a snippet of HTML (.htmf stands for hypertext markup fragment) which will be inserted into the <head></head> section of each page. This is where you should insert any JavaScript code which you would like to have on every page of your site.

images Directory

This directory contains any images used in the design of your site, such as background images, logos, etc. Images which are content (i.e. photos of your business, etc.) do not belong here. They should be outside of the decor directory which is reserved for presentational aspects of the site. Images in this directory may be templates for Molly's colorizing code and if so should be named with ".tplt" before the ".jpg" or ".png" file extension to make this clear.

scripts Directory

This directory contains all JavaScripts required by the skin. At a minimum it should have a main.js file which will be included in every page.

templates Directory

This directory contains all of the template files used by Molly to generate the resulting HTML of most of the MAML tags. In general when creating your own skins you can just copy the default templates directory with all of its template files and you will be fine. Most of the changes you are likely to want to maje can be accomplished by editing the main.js.htmf file. If, however, you wish to actually change the HTML (structure) that Molly generates, then these are the files you would edit.

Template files follow a naming convention and it is important that you understand and respect this convention if you are editing them or creating new ones for new MAML tags you might be creating (in a module, for example, or if you are working on extending Molly). Template files must have a ".tplt" file extension. Template files are named for the tag they are used by and in general since most tags have a begin tag and an end tag there is a separate file for each of these. So, for example, the <maml:windoid> tag uses the windoid.begin.tplt template file and the </maml:windoid> tag uses the windoid.end.tplt template file.

Skins and the molly_config Database Table

Currently Installed Skins

The following is a dynamically generated list (using <maml:filelist path="*[FileRoot]**[SkinDirectory]*" filetype="dir">) of the skins which are installed the decor/skins/ directory of this Molly installation:

• _default
• hex
• mx2

Other Stuff I need to write about:

• Database
• Login/Users
• User Group Permissions
• if/else

Users and Permissions

In your database, there should be a molly_login table and a molly_username table. This is where the information for each user who can log into your Molly site gets stored. The user_id number in the molly_login table must match with the user_id number of the corresponding user in the molly_username table.

The molly_permissions table is where you can set the editing permissions for each user. Again, the user_id number in this table must match with the corresponding user's user_id number. The group_name column lists the permissions each user has. The options are admin, editor, and config. These are the values that can be entered into the permitted attribute in the <maml:block> tag so that only certain users can edit that block. The permitted column shows whether or not the user has that permission; "1" means permitted, "0" means not permitted. The group_type column has three options: shared, independent, and exclusive. Shared means that users in that group can grant and revoke permissions for each other. Independent means that there are also multiple users in that group but they cannot grant or revoke permissions for each other. Exclusive means that there can only be one user in that group.

Part II: Building Sites with Molly

• Page Approach
• Wiki (MVC) Approach
• Skins
  • Location
  • Creating
  • main.css
  • main.js.htmf
  • Templates

Page Approach vs. Wiki Approach

When building a site with Molly, there are two ways to approach it. The first way is to create multiple pages by creating multiple maml files and linking between the pages. The <maml:block> tag can be used to fill in the content of each page so that it can be edited dynamically from the web. The second approach is to use one maml file with multiple wiki pages from the database. Again, the <maml:block> tag can be used to set which wiki page will be displayed on each page, but only one wiki block can be placed on each maml page.

Creating a New Skin

Files for skins can be found in the decor directory. When building your website with Molly, you may want to create some of your own skins in addition to the default skins. If you already have an HTML webpage with a stylesheet that you would like to make into a skin, here are the steps to do so.

1. Test your HTML template with the W3C Validator.
2. Once it checks out, save the template as a .maml file.
3. Replace the doctype and HTML tags with Molly versions (XHTML 1.1).
4. Test your template in Molly to make sure the XHTML is well formatted.
5. Create a new skin by duplicating an existing skin.
6. Delete the existing CSS file in the skin directory and the images in the images folder.
7. Copy your stylesheet into the skin directory and rename it “main.css”.
8. Copy your images into the images folder.
9. Change the skin in the molly.ini file.
10. Fix any image paths in your HTML file or stylesheet.

Now that you’ve created your new skin, you can make the style more intelligent by replacing hard coded colors in your stylesheet with Molly tokens, which come from the molly_config table in your database. You can also colorize your images.

To make your pages more intelligent, you can change your template to a .htmf file and move it into the snippets folder. Use the maml:include tag to include snippets in your webpages. You can also use maml:block tags optionally surrounded by maml:windoid tags to make content editable via the web.

Part III: Under the Hood

Main Directory Structure

The default directory structure of a Molly installation is as follows:

Molly Distribution

.htaccess

system

utilities

forms

scripts

modules

decor

skins

docs

index.maml - you are here!

error

index.maml

etc.

.htaccess

The .htaccess file is Apache's way of setting configurations on a per-directory basis. If your web server does not support .htaccess you will need to enable these configurations in other ways (i.e. via httpd.conf and php.ini). Here is a typical .htaccess file (line numbers added for documentation):

AddType application/x-httpd-php .maml .html .php .tplt .ini .inc .txt .css .mss .php4 .php3 .phtml 
DirectoryIndex index.maml index.html index.php
 
php_flag register_globals off
 
SetEnv MOLLY_INI molly.ini
 
php_value short_open_tag off
 
php_value auto_prepend_file /Users/rvullo/Sites/mx/system/loader.php
php_value auto_append_file /Users/rvullo/Sites/mx/system/parser.php
 
# 404: Not Found
ErrorDocument 404 /~rvullo/mx/error/404.maml
 
IndexIgnore .htaccess
 
Options -Indexes
 
php_value upload_max_filesize 30M

Line-by-line Explanation:

1. Tells Apache to process .maml, .html, .css, etc. files with PHP so that Molly can parse them.
2. Tells Apache that files named "index.maml" should be loaded instead of listing the contents of a directory.
3. #
4. Tells PHP to turn off automatic global generation. This is the default configuration for most PHP installations now. It is included in Molly's .htaccess file just to be sure for security reasons.
   
5. #
6. This is where you tell Molly which .ini file to read for configuration information. By default this is simply molly.ini but if you have multiple Molly installations it is helpful to name each site's .ini file such that you can keep track of them.
   
7. #
8. Some PHP installations have short open tags enabled such that blocks of PHP code can begin with <? instead of <?php. This, however, breaks when you have an <?xml declaration.
9. #
10. Tells PHP to automatically include Molly's loader code at the beginning of every processed file.
11. Tells PHP to automatically include Molly's parser code at the end of every processed file.
12. #
13. #
14. Tells Apache to send Molly's not found page instead of the default apache message. This can be used to automatically redirect users or simply to customize the look of the error page.
15. #
16. Tells Apache not to serve .htaccess files.
17. #
18. Turns off Apache's automatic directory listings.
19. #
20. If your site allows file uploading this directive tells PHP how large of a file to allow.

system

This directory contains the bulk of the code that makes Molly work. See the next section for details.

utilities

This is the directory where the forms and scripts directories are located. These subdirectories control how Molly's forms function separately from HTML forms, and define JavaScript code to be used by Molly.

modules

This is where add-on modules for Molly are located. For details on configuring and using modules see the Modules Reference appendix.

decor

The decor directory is where all files related to the site's look are kept, primarily in the skins subdirectory.

skins

Molly supports the notion of skins for easily varying the look and feel of your site. See the Skins section for details on how they work.

docs

Molly's documentation, primarily this page that you are reading right now. The docs directory is not required on a production site and may be safely removed.

error

Directory for error pages, notably the 404 Not Found page specified in Molly's .htaccess file (above).

index.maml

Default Molly site home page.

System Folder Directory Structure

system

molly.ini

loader.php

parser.php

core

05_utility.inc

10_date_time.inc

15_file.inc

20_database.inc

25_sessions.inc

27_security.inc

30_XML.inc

40_tags.inc

70_modules.inc

80_environment.inc

90_parser.inc

tags

html.override.inc

maml.ajax.inc

maml.constructs.inc

maml.database.inc

maml.format.inc

maml.security.inc

maml.tokens.inc

maml.xml.inc

database

scripts - now located in utilities as of June 11th, 2018

etc.

molly.ini

This file contains Molly's configuration settings including paths, database usernames and passwords, etc. May be named anything.ini to make multiple Molly installations more manageable.

loader.php

This script is automatically run at the beginning of a page load (because of the PHP auto_prepend_file directive in Molly's .htaccess file. It reads the molly.ini file (above) and sets up everything for Molly.

parser.php

This script is automatically run at the end of a page load (because of the PHP auto_append_file directive in Molly's .htaccess file. It does the actual parsing of Molly's MAML tags and substitution of tokens.

core

This directory contains all of the include (.inc) files that provide the bulk of Molly's functionality. All .inc files within this directory (and the tags directory with in it) are automatically included by loader.php (and 40_tags.inc). The include files directly inside the core are named with numerical prefixes because they must be loaded in order due to dependencies.

05_utility.inc

Utility functions for Molly programmers.

10_date_time.inc

Code for converting and manipulating dates, time, time zones, etc.

15_file.inc

File reading functions.

20_database.inc

Database abstraction functionality.

25_sessions.inc

Callback functions for session_set_save_handler() allowing Molly to store sessions and associated information in a database table. Among other things this allows us to easily determine who's logged in, and to share sessions across multiple web servers.

27_security.inc

Molly's user login system.

30_XML.inc

XML, DOM, and XSLT processing (no functionality yet).

40_tags.inc

Contains prototype tag and template classes, page building utility functions, and loads all of the tag class definitions from the tags directory.

70_modules.inc

Loads code for modules. Modules are optional add-ons to Molly. Over time some modules may migrate into Molly's core.

Modules to be loaded are specified in the molly.ini file for the site in the [Modules] section. This file automatically includes any .inc files found within each module's directory.

Each modules directory contains a documentation file named docs.htmf which is automatically be included into the Modules appendix of this document.

80_environment.inc

Utility code that Molly uses to determine the current environment - for example if a tag has been implemented.

90_parser.inc

The actual parser code called by parser.php.

tags

This directory contains the include files with all of Molly's MAML tag class definitions. They are in separate files based on functionality for easier coding and support.

html.override.inc

Molly processes a few HTML tags in order to simplify developing MAML pages. These include the <html>, <head>, and <style> tags.

maml.ajax.inc

Under development: hopefully simple way to implement AJAX.

maml.constructs.inc

Under development: rudimentary branching functionality.

maml.database.inc

Database access tags such as <maml:fetch> and <maml:form> and all of their associated tags.

maml.format.inc

Tags which implement user interface components such as menus and windoids.

maml.security.inc

Tags for implementing user login and user/group specific viewing permissions.

maml.tokens.inc

Tags which allow webmasters to create tokens either on a per-page-view basis or a per-session basis.

maml.xml.inc

Contains the class definition for the <maml:nothing> tag. This tag acts as a root XML element for MAML files which generate non-web-page results for use in AJAX and web services. If we re-implement Molly's SOAP functionality, that would go here.

database

Contains the ADODB database abstraction code employed by Molly. (Longtime Molly developers should note that this open source solution replaces Molly's original database abstraction code which had been developed specifically for Molly.)

scripts

Moved to the utilities structure as of June 11th, 2018.

Utilities Directory Structure

utilities

forms

block_insert.html

class.upload.php

drag_drop_upload.html

insert.html

login.html

logout.html

register.html

replace.html

search.html

upload.html

scripts

tinymce

filedrag.js

jquery-1.8.2.js

jquery-3.3.1.min.js

jquery-migrate-1.4.1.min.js

maml.multiple.js.inc

etc.

forms

Contains all files relevant to the maml:form tag and its functionality in communicating with the database.

block_insert.html

class.upload.php

This file is a PHP script that uploads files for your website and can manipulate images with ease. It can convert, resize, and alter images and add several features to your thumbnails and image galleries. In conjunction with forms, it looks for files uploaded with maml:form and saves the file in memory for later manipulation.

drag_drop_upload.html

insert.html

login.html

logout.html

register.html

replace.html

search.html

upload.html

scripts

Contains all scripts that are used by Molly across the site.

tinymce

filedrag.js

jquery-1.8.2.js

jquery-3.3.1.min.js

jquery-migrate-1.4.1.min.js

maml.multiple.js.inc

Files to be parsed by Molly

Molly's Parsing Engine

Previous versions of molly used the SAX (Simple API for XML) parser using xml_parser_create(). SAX was available in PHP 4 and compatible with PHP 5. It functions as a stream parser with an event-driven API. It is a push parser; the user defines a number of callback methods that will be called when the parsing events occur. The SAX interface does not deal in elements, but in events that correspond to tags. SAX parsing is unidirectional, which means that previously parsed data cannot be reread without restarting the parsing operation. Molly's new engine uses the new XMLReader object. This is a wrapper on Libxml2, which is a widely used XML C parser. Like SAX, XMLReader is also a stream based parser. But unlike SAX, XMLReader is a pull parser, meaning it only parses what is asked for by the application. It acts as a cursor moving forward on the document stream and stopping at each node on the way. XMLReader has a very small memory footprint and is faster than SAX because there is no need for it to process callbacks you do not care about.

Embedded JavaScript

Molly is an XML Parser, so whenever she sees a < she thinks a tag is beginning. Now obviously this isn't the case in a block of JavaScript. Browsers have learned to ignore code inside <script></script> tags, but technically that's not correct. The solution is to place the JavaScript code inside a CDATA block which tells the XML parser not to parse that text.

<script language="javascript" type="text/javascript">
<![CDATA[
 
    // JavaScript code goes here
 
]]>
</script>

Details of the Molly Framework's Processing Steps

Setting things Up

Molly works by running code both before the page is loaded and after the page is loaded. The code that runs before the page sets up the environment and the code after the page parses the page and replaces the various maml tags with the result of their processing. So, we need to configure the web server to automatically load the appropriate scripts at the beginning and end of page loads. The two key scripts are system/loader.php (loads the Molly environment) and system/parser.php (parses the maml tags). This is traditionally done via the Apache web server's .htaccess mechanism (as detailed at the beginning of this appendix) but there are other approaches which can be used, depending on the server's configuration. The directives normally used in the .htaccess file can be incorporated directly into Apache's httpd.conf file, for example. The php.ini file can also be used for configuration. The main advantage of the .htaccess file approach is that it allows multiple distinct Molly installations to be running on a single server. But this too can be managed via the php.ini approach with a little extra code. For example, if in your php.ini file you incorporate something like the following two lines:

auto_prepend_file = /home/username/molly_system_dispach/prepend.php
auto_append_file = /home/username/molly_system_dispach/append.php

Then the prepend.php and append.php files can do, in a centralized place, what the .htaccess files do in a decentralized way. This would also work for non-Apache web server environments.

Sample molly_system_dispach/prepend.php File

<?php
	$pos = strpos($_SERVER["HTTP_HOST"], 'learntech');
	if (!($pos === false)) {
		$gv_Site = 'learntech';
	}
	 
	$pos = strpos($_SERVER["HTTP_HOST"], 'diyvr');
	if (!($pos === false)) {
		$gv_Site = 'diyvr';
	}
	 
	$pos = strpos($_SERVER["HTTP_HOST"], 'vrweb');
	if (!($pos === false)) {
		$gv_Site = 'vrweb';
	}
 
	switch ($gv_Site) {
		case 'learntech':
			$_SERVER['MOLLY_INI'] = 'learntech.ini';
			include '/home/learntech/system/loader.php';
		break;
		 
		case 'diyvr':
			$_SERVER['MOLLY_INI'] = 'diyvr.ini';
			include '/home/diyvr/diyvr/system/loader.php';
		break;
		 
		case 'vrweb':
			$_SERVER['MOLLY_INI'] = 'vrweb.ini';
			include '/home/vrweb/vrweb/system/loader.php';
		break;
	}
?>
 

Sample molly_system_dispach/append.php File

<?php
    switch ($gv_Site) {
        case 'learntech':
                include '/home/learntech/system/parser.php';
            break;
 
        case 'diyvr':
                include '/home/diyvr/system/parser.php';
            break;
 
        case 'vrweb':
                include '/home/vrweb/system/parser.php';
            break;
    }
?>
 

So, as you can see, what the Molly startup mechanism does, whether via .htaccess or php.ini is to specify the filename of the .ini file that contains the configuration values for that particular installation of Molly and includes Molly's loader.php script. Then at the end of the page load, include Molly's parser.php script.

Inside the loader.php Script

Molly's Loader performs the following steps:

1. Sets up a series of global variables with relevant file paths:
   • $gv_CurrentFile
   • $gv_CurrentFilePathInfo
   • $gv_CurrentFileExtension
   • $gv_MollySystemDirectory
   • $gv_MollySystemDirectory
2. Reads the values from Molly's .ini file into the $gv_SiteGlobals array.
3. Checks the .ini Secure setting and redirects to the same page using https if appropriate
4. Checks to see if the current file's extension is ".php" and if so skips the rest of the loading process.
5. Defines three core functions: m_Interpolate(), m_ParentDir(), and m_AutoInclude(). m_Interpolate() processes Molly's tokens and m_AutoInclude() will include all of the files of a particular file extension in a specified directory - this facilitates including all of the other necessary files for Molly.
6. Initializes the global variable $gv_IDNum which is used to generate unique DOM IDs by various maml tags.
7. Initializes the global $gv_Config array with some default values. These are used as tokens for values in the various skins.
8. Using the m_AutoInclude() function, load all the core include files:
   • 05_utility.inc
   • 10_date_time.inc
   • 15_file.inc
   • 20_database.inc
   • 25_sessions.inc
   • 27_security.inc
   • 30_XML.inc
   • 40_tags.inc
   • 70_modules.inc
   • 80_environment.inc
   • 90_parser.inc
   These files are prefixed with numbers to force their include order, as there are dependencies. Additionally, some of these scripts themselves autoinclude other scripts - notably 20_database.inc and 40_tags.inc as well as 70_modules.inc which implements Molly's system for allowing expansion without touching the core. Modules can even implement new tags.
9. Load any persistant tokens from the global $_SESSION array.
10. Fully populate the $gv_Config array from the database table specified in the .ini file (possible now that the core functionality, including database access has now been included).
11. Set up a global variable so Molly can check if someone is logged in
12. Start Buffering PHP's output so that the current file can be captured and parsed before outputting it.
13. Set appropriate headers for files based on their extension (i.e. CSS files get Content-type: text/css, and files like .ini are redirected to a 404 not found page so that Molly doesn't serve them to the web.

At this point PHP reads and outputs the requested file, which Molly is caching rather than outputting so that the subsequently appended parser.php can process it.

Inside the parser.php Script

The first thing the parser.php script does is check to see if the current file has a .php extension, and if so, exits. Next it puts the cached file (i.e. the unprocessed current .maml page) into a global variable and empties the cache, but leaves caching on so as to capture the processed page. (Also, some maml tags will use the PHP caching mechanism themselves to process the contents between their begin and end tags.)

If the current file has a .maml extension, then the captured page is sent to the m_PullParse() function to parse the page and process all of the maml tags, otherwise it is just echoed back into the just emptied cache.

Finally, the cache is once again captured into a variable, the cache cleared and caching turned off. All of the existing tokens in the newly captured cached page are replaced with their values and any non-existent tokens are deleted.

The m_PullParse() Function: The Heart of Molly

The m_PullParse() function is the entirety of the system/core/90_parser.inc file which is the last file included by Molly before the page is processed. It is the essence of the Molly tag-to-code engine.