HTML isn't very good for writing applications. We know that because it's our marketing strategy. However it is very good for writing content-based documents that can be written by just about anyone who can type, then viewed anywhere in the world instantly.
This document explains how we use HTML in Laszlo so that it is easy to write and maintain. In particular, this applies to:
I've taken great pains with designing the website to ensure that it's very easy to add and remove pages. In particular, the content is abstracted from the styles as much as possible. In most cases, you should just be able to take an HTML file that you have written for download and drop it into the framework of the website, without worrying about sytles or formatting. The should just read the website's stylesheet and display correctly. This means that in you could have different stylesheets for the web and for bundled files, but use the same content for both.
The idea is that you write your document thinking about it's structure instead of it's final appearance. I wrote most of this document without using a stylesheet. I divided my document into sections and paragraphs and typed away, adding the stylesheet at the very end.
In general I've written the stylesheets in such a way that you should be able to compose pages with all HTML knowledge obtained from a teach-yourself-html-in-31-seconds book. In other words it's very simple.
Here's a really simple example:
<html> <head> <title>My Title</title> </head> <body> <!-- lz_content_start --> <p>Hello, World!</p> <!-- lz_content_end --> </body> </html>
A simple Laszlo HTML Page
Notice how the Hello, World! is enclosed in paragraph (<p>) tags? That's required, even though many books will tell you that you can just write text inside of the body tag, outside of any tags. Similarly you have to open (<p>) and close (</p>) the paragraph - some books tell you that it's OK to use standalone <p> tags between elements.
As a general rule when composing or editing our HTML files, text always has to be inside one of these tags:
Of course that doesn't mean that you can't use other tags, but the above are the only tags which will ensure that the correct fonts get applied to a document. If you write text outside of the above tags, the fonts will seem wrong.
Don't forget you can also write comments in your HTML:
<!-- This is a comment and it won't appear in my browser --> Bad comment: <!--This is a bad example-->
It's important to add the spaces between the dashes (-) and the words, and you can have comments that span several lines.
The paragraph tag divides text into structured paragraphs. Use it even if doing one line. Text in paragraph tags will be automatically formatted. You can make it smaller by adding a style tag:
<p class="smaller">This is a small paragraph.</p>
The span tag is used to apply a specific formatting style to selected areas of text. For example if you want red text within a paragraph tag or in a preformatted text tag:
<p>This is some <span class="redText">red</span> text.</p>
<pre>
<view <span class="redText">x="30"</span> />
</pre>
The span class can also be used as an alternative to the paragraph tag if all you need is the regular formatting:
<span class="regular"> Here is some standard text, which will look similar to paragraph text. </span>
The difference between span and p is that the span tag won't add space before and after the block of text it's enclosing like a paragraph tag will.
Just like the paragraph tag, you can say:
<span class="smaller">Here is some smaller text</span>
If you want code examples within a paragraph, you can use the span tag with the code class:
<p>You should use the <span class="code">attribute</a> tag if you want better control of constraints.</p>
However you can't use the span tag inside of another span tag.
It's best to use the feature of HTML that was designed for headings, rather than hacking a style to look like a heading. We use H1 through H4, which should cover most of your needs. H1 is rarely used - on most pages of the website, the top heading is H2. H1 might get used in the title page of the downloadable LZX reference.
<h2>A big heading</h2> <p>Some text under the big heading</p> <h3>A sub heading of the big heading</h3> <p>Some text under the sub heading</p> <h4>An even smaller heading</h4> <p>Some text under the even smaller heading</p>
There is no need to force extra space between the heading and whitespace (e.g. through the use of <br> tags.
If you really need something smaller than H4, use bold text:
<p> <b>Sub-sub-sub heading</b><br /> Some text under the sub-sub-sub heading. </p>
Notice how it's all actually part of the same paragraph.
HTML ignores most whitespace, so in order to preserve it (for code examples), you must declare it using the <pre> tag. The pre tag also gives the text a courier typeface.
<p>See the LZX example below:</p>
<pre class="code">
<view x="50" y="50" width="300"
height="20"
bgcolor="red">
<view x="50" y="50" bgcolor="blue" />
</view>
</pre>
Usually we use the class="code" for code examples. It adds a gray background, and ensures consistent size. If you want monospaced text within regular text, use the span tag.
You should always work with .html files, which are later converted to .php files for our website. If you have a bunch of files on the same subject keep them in the same folder.
Links come in three flavors:
Relative links are links to other pages relative to the current page. For example, when you link from one tutorial to another, you'll be using a relative link. As mentioned above, use the .html extension of the files when linking - later this will get converted to .php for use on the website.
<p>... see the <a href="../scripting.html">Scripting tutorial</a> for more information.</p>
When writing relative links to other files that you're working on, always use the html extension file name.
Absolute links take you to anywhere on the web. They are usually only used when we're linking to someone else's site or to our homepage.
<p>... see the <a href="http://www.laszlosystems.com/">Laszlo website</a> for news and updates.</p>
Jump links are links to elsewhere on the same page (like the link in the bulleted list above to down here). Note the preceding "#".
<p>... see the <a href="#views-section">Views Section</a> below for more info.</p>
You have to declare the link manually, and you use the <a> tag for that, but with a name attribute instead of a href:
<a name="views-section"></a>
<h2>Views Section</h2>
.....
In HTML it's not legal to use the empty XML-element style for a named anchor tag (<a />). The tag must be empty as shown above. The names cannot contain spaces. Always try to use human-readable names. You can also append the name to a link to another html page, to jump directly to that point in the file.
<p>... see the <a href="sections.html#views-section">Views Section</a>
on the other page for more info.</p>