Home

The SpazCore Component Library

SpazCore is a set of JavaScript components designed to make development of Web RunTime applications easier. Primarily it’s been used in the Spaz microblogging clients, so functionality is primarily focused on making common tasks in these applications easier. It is suitable for applications based on AIR, Titanium, and webOS, although most browser engine-based platforms should be able to utilize many aspects. It attempts to offer a common API for its functionality that works cross-platform.

Major Elements

SpazCore is made up of four major elements: libraries (libs), helpers, platform-specific extensions (platforms), and vendor libraries (vendors)

Libraries libs/

These are components that handle more complex functionality. Right now SpazCore has the following libs:

• SpazCore (libs/spazcore.js): the base library

• SpazFileUploader (libs/spazfileuploader.js) a library for uploading files via HTTP, primarily images to image hosting services like yfrog and TwitPic
• SpazImageURL (libs/spazimageurl.js) a library for generating links to common image hosting services
• SpazPhotoMailer (libs/spazphotomailer.js) a library for emailing photos to common image hosting services
• SpazPingFM (libs/spazpingfm.js): a Ping.fm library under development
• SpazPrefs (libs/spazprefs.js): a preferences library under development
• SpazShortText (libs/spazshorttext.js): a text shortening library (think txtspeak)
• SpazShortURL (libs/spazshorturl.js): a URL shortening/expanding library
• SpazTemplate (libs/spaztemplate.js): a simple library for storing and parsing templating methods
• SpazTimeline (libs/spaztimeline.js): a library for updating and managing a chronological list of items in the UI (like, say, a Twitter timeline)
• SpazTMDB (libs/spaztmdb.js): a library for working with TheMovieDB.org’s API
• SpazTwit (libs/spaztwit.js): a Twitter API library

As of this writing, many of these libraries range from “mostly done and usable” to “barely a skeleton.” Additionally, database abstraction and possibly ORM libraries are planned.

Helpers helpers/

Helpers are single-task functions to handle common tasks. All helpers in SpazCore are under the sc.helpers namespace to avoid collisions. Helper definitions are separated by task into different files:

• Date and Time (helpers/datetime.js): functions to handle common date/time tasks, like generating relative time descriptions
• Event (helpers/event.js): event listening and triggering helpers, based on standard DOM events
• File (helpers/file.js): helpers for reading and writing files on the local filesystem. These require loading a platform-specific definition file
• Hash (helpers/hash.js): utility functions for generating string hashes (base64, md5, sha1, etc) and unique IDs
• JavaScript (helpers/javascript.js): JS language helpers for things like type checking
• JSON (helpers/json.js): JSON encoding and decoding helpers (based on the JSON2.js library)
• Network (helpers/network.js): functions for performing common network tasks. Right now has platform-specific helpers for HTTP file uploads
• Strings (helpers/string.js): string tasks, like converting URLs and Twitter @usernames into links
• System (helpers/sys.js): Platform and OS-related tasks like platform detection and file manipulation. Most of these require loading a platform-specific definition file
• View (helpers/view.js): Helpers for common view (UI) tasks, like removing duplicate elements in an HTML Twitter timeline
• XML (helpers/xml.js): XML processing helpers

Platforms platforms/

SpazCore attempts to provide a common API for its functionality, regardless of the platform. Some functionality requires platform-specific code, such as file operations. To accommodate this, some function definitions in SpazCore are “stubs,” and the developer has to load a platform-specific set of definitions for their target platform. At the moment, platform-specific files are needed for the System, Network and File helpers, and the SpazPrefs library:

• platforms/[platform]/helpers/file.js
• platforms/[platform]/helpers/network.js
• platforms/[platform]/helpers/system.js
• platforms/[platform]/libs/spazprefs.js

As of this writing, the SpazPrefs library has not had its platform-specific code separated into platform files.

Vendor Libraries vendors/

SpazCore is built on some open-source JS libraries. All of these are stored in the vendors/ folder. These include:

• jQuery: (currently version 1.3.2); used for AJAX and DOM manipulation
• JSON2.js: for encoding and decoding JSON safely. Included in builds
• date.js: For sophisticated date manipulation. Included in builds

jQuery is not included in single-file spazcore builds currently. You must include it in addition to the spazcore file.

Other elements

Tests tests/

We aren’t TDD monkeys or anything, but we’ve attempted to write unit tests where reasonable. We have a decent set of tests, especially for the helpers, but more are needed.

Examples examples/

Documentation is slim for SpazCore right now. The best place to learn how to use it is to examine the examples directory, which demonstrates many libraries and helpers.

Current Plans and Needs

Reduce the reliance on jQuery

We’ve done a lot of this already by developing the Event helpers and using those instead of jQuery binding and triggering. We should also add helpers for event delegation, as that’s something we do often and for now rely on jQuery. Our view helpers still mainly use jQuery as well, but if we move the actual DOM queries into wrapper functions and use native methods as much as possible, we can make it a lot easier for the developer to override the DOM stuff with their own code.

SpazTwit still can utilize jQuery triggering, but will only do so if a specific option is passed.

That being said, if we are careful to use jQuery in a non-conflicting manner, we should be able to utilize it fairly seamlessly, so devs using another popular framework don’t have issues.

Fill in skeletal libraries

Lots of the libraries just aren’t filled-in yet. They need to be.

Complete platform implementations

Some helpers and libs only work on certain platforms. This needs to be fixed so all targeted platforms support the same functionality.

Remove all inline platform-specific code

SpazPrefs especially has a lot of if (isPlatform) {...} type code in it, and this needs to be broken out into platforms.

More data/api libraries

We have lots of ideas, and would like to include more. We’re also interested in hearing your ideas, and would love to see code contributions.