Ramping Up vs Greenfielding - Consider for a moment: Are you "greenfielding" a project (for example, starting a new site from scratch), as opposed to integrating or embedding Modulo into an existing web application (e.g. "brownfielding")? If you are "greenfielding", then it's probably easiest to start with a starter. For example, the Modulo Starter and Docs Starter ZIP files both have the
static/index.htmlandstatic/components/index.htmlcorrectly set-up. However, if you are "Ramping Up" an integration into an existing project, then consider these options.
Ramping Up
You'll soon "outgrow" an embedded script tag as you develop components beyond simple, one-off components on a single page. Modulo recommends several options to "ramp up" in complexity.
Option 1: Load a File
Much like CSS being separated and brought in using a <link> tag, it's best to
put our <Component> definitions into a separate file, and then bring them in
using Modulo's special -src= attribute, that loads from another file. For
example, it might be called "modulo-component-library.html":
Keep in mind that the the standard name for your library should be
static/index.html, if possible (see Explicit static
import for more info).
Option 2: Static
The recommended usage is creating a directory called static/, and storing
your components in a file called index.html. or implicitly (automatically)
imported.
Keep in mind that the the standard name for your library should be
static/index.html, if possible (see Explicit static
import for more info).
Boot-Up Logic - Modulo will search in 4 steps for top-level definitions: (Step 1) First,
<head>...- Modulo searches children of the head element, and execute definitions synchronously, blocking, and before the page is done loading, with the document still open for writing. (Step 2) Load own dev library and default tools. (Step 3) Wait forDOMContentReady, then implicit static import happens along with default content viewer setup. (Step 4) Finally,<body>- load children of the body element, asynchronously.
HTML tags: Script and template
Understanding the special HTML behavior of <script> and <template> tags is
important, since HTML treats these tags differently. Using the wrong tag can
cause syntax-related errors (in the case of accidentally closing a <script>
tag) or accidentaly "leakage" (global execution) of code. For a demonstration
of this behavior, see the following two examples of correct and incorrect ways
to include Modulo components in an HTML page:
Example 1: Incorrect: Code "leakage"
Example 2: Correct: Embedded "template Modulo" tag
Why iframes? Why not fetch / JSONP? - Modulo will use fetch while on HTTP(S), but for it to work seemlessly over the restricted
file:///scheme, it uses a "hack" where files of any type can be treated as a HTML file and loaded using an iframe. While far from ideal, the only other "hack" is JSONP, which is even more difficult to edit by hand, and offers few advantages over iframe, and thus was cut as an option.
Importing a file
Components can either go directly embedded into a <Modulo> definitions for
quick, one-off JavaScript (what we've mostly seen so far), or in the form of
<Modulo -src="lib.html">... to load separate HTML file(s) containing your
components. You can do this as many times as you want.
Modulo File Header
Using the file header "hack" - While it is cumbersome to rename files to
.htmand add these comments at top, at last there is no need for a closing tag so only the top of the file needs this special comment, and that Modulo uses this relative path for importing as well (see Implicit static import below). Finally, stylistic purposes, consider using.css.htmor.js.htmas a convention, while actual HTML files can still just use.html.
When using http(s), Modulo loads files using fetch (like other frameworks),
but if you are working locally over file, Modulo uses an iframe technique
that requires you to follow two rules: 1) Add a header (below) and .htm
extension to every file you bundle with -src= or <Include>, and
2) Avoid using a closing <-script> tag if you have an openeing one at top,
since that will terminate the "loading" mechanism (this is usually only an
issue if you happen to be writing documentation for something HTML related).
As long as you follow this convention for file type headers, Modulo will be
able to load them in an identical manner over any protocol. Furthermore, since
the HTML is contained in a comment, they remain valid CSS or JS, so they can be
included with <script> and <link> tags as well.
Example 1: Modulo-HTML
static/index.html (Example)
Example 2: CSS-HTML
static/css/my-styles.css.htm (Example)
Example 3: JavaScript-HTML
static/js/main.js.htm (Example)
What goes in static? In other frameworks, this is sometimes called
public/orassets/. Regardless, it consists of all of the static assets that are required to build your site. Components, Core Definitions, as well as CSS, JS, and image assets should go in astatic/directory. HTML routes live outside.
Explicit static import
Modulo expects a directory at the root of your project called static/. The
first file loaded is static/index.html. With the default configuration,
Modulo expects all of your project's dependencies to live in this directory.
In order to simplify the top of your HTML files, you can include Modulo and import static in one simple tag:
Implicit static import
All you need is Modulo.html: In order to make the top of your HTML files as
simple and elegant as possible, all you need to do is place Modulo.html in
a static/ directory ("folder"), and then not attempt define any Modulo
definitions at all in that file. Then, Modulo will automatically attempt to
implicitly import static/index.html. This also works for a subdirectory:
static/js/Modulo.js for example will still import static/index.html.
See below for an example that imports Modulo Docs static directory itself:
Deactivating implicit static import
If you don't want this to happen, be sure to add an explicit embedded Modulo
tag as a tag name or as the first attribute of a tag. This will deactivate
the implicit import feature.
Troubleshooting
Browsers with file: protocol will only load frames if they have the .htm
or .html extension. This means that to keep identical file and http support,
you will need to follow several guideliness to keep things loading the same on
file as with http.
Extensions, "nosniff", and mime-types
Aka, what's in a name? Modulo.html vs Modulo.js
Modulo is one file, but it can be re-named to several extensions: .html
(becomes the help page when viewed), .js (a valid JS file that sets up
Modulo), and .md (version info in a particular Markdown meta syntax). In
general, .html is preferred: It is able to load its own source code when you
run build, even if it's being viewed locally over file. However, some
http dev servers are configured to send .html and .js with "nosniff"
headers and guessed mime-types. This means that only Modulo.js will work, if
you cannot reconfigure your dev server. Ultimately, which extension you use
depends on your target dev setup.
File headers: Unicode and Quirks Mode
This section contains troubleshooting tips for Quirks Mode and Webkit Unicode Support.
BUG #1: "Warnings Galore!"
Are you getting many warnings with text like what's listed below? As long as you are only getting them during develpoment, and they do not affect your app, then they are probably safe to ignore.
See the following warnings:
Quirks Mode: In this guide, little is discussed around QuirksMode. In most cases, this shouldn't make a difference: Websites will display almost identically. However, without a doctype, your content files may prview differently than the final files you produce when building. In this case, simply add a doctype to your header (Modulo will correctly ignore this too when loading). Note that unlike unicode, this only affects pages you directly view during development, although it can generate annoying warnings on other pages.
Developing Using Webkit (Apple Safari, GNOME Web): In some cases, you can get unicode loading issues in Webkit-based browsers such as Safari or GNOME Web. To fix this, ensure "utf8" is set on all HTML documents that contain unicode characters by adding a meta tag (Modulo will correctly ignore this too when loading).
BUG #2: "What have they done to my beautiful logo!"
To illustrate the second bug, here is the same text being rendered in Firefox vs Webkit (Konquer / Epiphany / Safari):
See how the "modulo" logo is completely destroyed? The only remaining characters are "°" (degree sign), "d", and "o", since those are in the plain-text base range. However, the other symbols are all extended unicode, and thus get misread as separate code points.
If you are having unicode issues while developing with Webkit, then keep on reading! However, note that if you are correctly building your site before launching, this should not be an issue on production, since you should always have your UTF8 meta set in final HTML files, and no HTML loading will be done.
Solutions
Soultion 1: Highly Compatible Markdown-HTML
my-page.html (Example)
Solution 2: Highly Compatible HTML fragments
static/content-data/product_info_1.html (Example)