Home » Building Modules
» Creating A Module
Submitted by kplawver on Wed, 2006-04-26 13:39.Modules

Introduction

So, you've decided to create a module... Good! You're definitely in the right place! This document should take you from beginning to end in designing, building, uploading, and testing your module. Let's get started.

Designing Your Module

Designing a module is a little different from designing a regular Web page. Here  are a few things to keep in mind:

  • Keep it simple. Try to keep  your module single purpose and as light as possible.  You can always build another module to do whatever else you had in mind. The module above has a single purpose—to display the AIM Pages user's Amazon.com wish list.
  • You don't know what kinds of pages your module will be imported into, what CSS those pages will use, and how the pages will be designed (white text on black, black on white, yellow on purple?).
  • This means you should not set colors, font families, widths, and so forth in your module, because it should fit in whatever container the user wants your module to fit in.
  • Stay flexible, and avoid positioning elements in your module using position: absolute.
  • If you're going to float elements within your module, make sure its container is positioned using position: relative.

Microformats: The Semantic Web

We love microformats, mostly because we like making sense out of nonsense, and order out of chaos.  Microformats provide a standards-compliant way to add meaning to otherwise meaningless or nebulous markup. A microformat gives us the ability to create human-readable and, more importantly, human-writable documents that we can also feed to machines to do intelligent things with them.

A machine is going to take your module, rip it into little pieces and put it back together in a format that it can use. In order to do that, it needs to know what pieces to look for and then what do with them. By using our microformat,   you can build your module in almost complete seclusion, document it , and test it, all in one XHTML document. Cool, huh?

The Module Manifest

Because we love them so much, we decided to create our own microformat. We call it ModuleT. Our microformat allows you do what we said in the paragraph above: create a module, document it ,and test it, all in one XHTML document. 

To get familiar with the microformat, we recommend  you read through the profile and then check out the module skeleton and our cheesy example module. We also recommend using the skeleton as the base for whatever module you plan on building. It will save you time and effort, honest.

What Makes A Module Valid?

The most direct path to a valid module is the AOL ModuleT  microformat profile.  After you've used the microformat, check out our handy 10-point Module Validation Checklist.

Using Ajax: The Proxy Server 

If you read through the profile, you probably saw the section on proxy URLs. If you need to access an external server for your module, please make sure that you put that URL in a link in your manifest and make sure rel="proxy" is in that a tag.

Our proxy is, for now, pretty open. We'll blacklist URLs that do "evil" things. But we want to trust you as fellow developers not to go do "bad" things with the system.

Server-side Modules

This is where we get to the fun part. We thought it would be useful if modules could be more than just HTML, JavaScript, and CSS. We figured there would be folks out there who really liked Web services and XSL, and might want to use them in modules. There are a couple of  ways you can do that with JavaScript, but the libraries are huge! Also, we figured there might be some existing Web services that people  without a lot of JavaScript experience might want to take advantage of. So, in order to make ourselves happy, we came up with the idea of server-side modules! What does that mean? It means you can build a module that sucks in content from another Web site, and displays it in your module without writing any JavaScript at all! Cool, huh?

The server-side piece works by looking for some special attributes in your module manifest, and then grabbing the associated URLs, dumping the content inside those parts of your module, and replacing any default content they may contain.

You might want to think about doing a server-side module if:

  • You have a Web service that returns HTML snippets fit for inclusion in a module.
  • You have an XML-based Web service you'd like to use in a module, but don't want to write JavaScript, and would prefer to write XSL to transform it.

If you fall into one of those two categories, welcome aboard the server-side module train! There are a couple of things you need to do in order to build a server-side module:

  • Add xmlns:pub="http://developer.iamalpha.com/xmlns" to the <html> tag in your module.
  • In the HTML tag for the element you want the content dumped into, add the following:
    • pub:src="http://urltoyoursnippetorxml.com"
    • If you're going to do an XSL transformation: pub:style="http://urltoyourxslfile.com"

A Server-Side Example

Let's say you had a very simple server-side module that grabs a small chunk of HTML and dumps it into your module. To do this (this isn't a complete manifest), you'd have something like the following:

<div class="body my-module" pub:src="http://mycoolsite.com/headlines.txt"></div>

If your list of headlines looked like this (it's a short list):

<ul>
   <li><a href="http://site.com/story1">Story One</a></li>
 </ul>

Your module would return this when shown to the user:

<div class="body my-module" pub:src="http://mycoolsite.com/headlines.txt">
 <ul>
   <li><a href="http://site.com/story1">Story One</a></li>
 </ul>
 </div>

Is that cool, or what? If you want to apply XSL to the content returned by your pub:src URL, then use pub:style to point to your XSL stylesheet.

Uploading Your Module

Once you've created your module, you probably want to show it off, so go upload it! The instructions are pretty simple:

  • If your module is named "Joe's Rich Text Module", your zip file should be named "joesrichtextmodule.zip" or "joes-rich-text-module.zip" and should contain all files needed for that module.
  • The zip file should be a directory with the same name as the zip file.
  • The module manifest should be a file called "index.html" inside that directory.
  • Modules should be tiny, and you should never get close to the 400 KB upload limit.
  • Once you get the all clear that your module was uploaded, you can go test it out in the Playground.

Testing Your Module

Things may not work right away when you upload your module. It happens. There are a couple tips we can give you that should help get you past some of the things that trip us up all the time.

  • If you get stuck at "Loading..." when importing your module onto the page:

    • This is usually because you've got some invalid HTML in your manifest. Try running your manifest through the W3C Validator and then fix any problems you find.
    • Although an XHTML 1.0 Transitional document is valid without it, our scripts currently require you to declare an XML Namespace in the html tag. Make sure your <html> tag has xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en" in it.
  • You should check out the Tips & Troubleshooting page for a more complete lists of errors, their causes, and their fixes.


Skeleton and Module Examples

We mentioned them above, but here are the examples again in handy dandy list:

Notes

You've made it all the way through this document. And because you made it all the way to the end, we just want to say, "Thank you!" We're really excited about the possibilities for these modules, for what can be built and what could come out of it, and we hope that comes across in the content we've created here and in the FAQ.

Also, please check out the Module Best Practices page for more information and guidelines for writing CSS for your modules.

Don't forget our module workshops for step-by-step instructions on how to:

We appreciate your taking the time to read these documents, and hopefully you'll take some time to create a module and tell us how the process went either on the listserv, on the message board or post a comment on the blog. We hope you'll stick around and see this through. We're sure you won't be sorry!

up
printer-friendly version