```yaml
---
slug: transactions-part-1
published: 2006-04-13
description: Gaia's original "transaction manager" explained
excerpt: ~
changelog:
  - on: 2020-02-23
    note: This was rescued from the archives of the old [felocity.org](https://web.archive.org/web/20050507121849/http://www.felocity.org/journal). As a result, many links in this piece were left pointing to archive.org destinations.
---
```

Everything is on track for SXSWi this year, and excited isn't even a good word for how I feel right now. It's 4 am [Ed. Now it is noon the following day…] and I'm downright giddy. Last year I blew my first chance to go because I didn't move fast enough. This year, I jumped on travel planning much quicker and managed to grab a room at the Hilton Austin. I'm in on the 10th and out on the 14th, and if I didn't have some larger projects, I'd be staying much longer. To those going, I'll see you there (just look for the kid who looks like an excited lost puppy). However, if you notice the title, this isn't about SXSWi entirely, but instead is focused much more on some meaty PHP things: transactions. For the new bank code at Gaia, there needed to be a way to move items and gold about the site through a standardized (and [5 nines" reliability) system. Add to that full logging in the event of failure, and the ability to "transact" just about any two things on the site, and you get the foundation of the transaction system. This is part one of a multi-part article which will touch on the surface and theories used in the transactions framework. (Part 2 will focus more or architecture.)

* **Part 1: Theory**
* [Part 2, Transaction Framework](/thunked/transactions-part-2)

When the project first began, transactions were an odd concept. Not like database transactions, but a sequence of events that were atomically linked and reversible. Examples included purchasing from the Gaia Store (give the system gold, the system gives an item), making a trade (place an item into an "escrow" neutral zone), auctioning off an item (again, an escrow style neutral zone), purchasing non-pixels such as a Trading Pass or a Guild Purchase where the result is a database row but no items or gold, and many other things that went beyond the basic "remove gold, add item" mentality. This meant it was time for some research into complex data analysis models. Enter Martin Fowler, whose books I had read back in college, but like most college students made a point of forgetting. Thankfully, John had Analysis Patterns which was all we needed to get underway. I'm going to digress for a moment to say Fowler is a very intelligent man, but I remember why I couldn't remember what he wrote- Fowler has a hard time communicating why a pattern works the way it does in a way that connected with me. If you're someone who needs to know the "why", you might have to suck it up like I had to. After going cover to cover, it appeared there was a very basic system underneath even the most complex banking systems. To abridge the text, we started referring to it as the Conceptual Account Thingy (or CAT for short).

## Accounts, Entries, and All That Jazz
Keeping with our simplified version of things, an Account was described as nothing more than a container. This container could hold things, and those things belong to some entity. As an added bonus, [Gaia's "DAO"](http://72squared.com/index.php/module/Articles/action/Display/id/37) information was also stored with the Account in order to provide a means to get out and save data when needed. Accounts were then abstracted and an Account class was created for the "things" on Gaia that were owned by "someone". The initial list included:

* Gold (owned by user)
* Inventory (owned by user)
* Trades (owned by the trade row, with two users participating)

The third one is very interesting because a Trade became what was called a "Summary Account" in that it contained two Accounts inside of it, a left half and a right half. The left half was owned by the trade row and by the left user, while the right half was owned by the trade row and the right user. Because of this, the only entity that owns the entire trade is the trade row itself. When retrieving Accounts, they are always fetched by their owner which is often a primary key. This ensures speed of performance during the Account loading process. With a means to load and save the data, the next step is to manipulate it.

According to Fowler, the Entry class is nothing more than an entry that will be logged to an Account. Think of recording a check in the checkbook's ledger. This process is formally called Posting an entry, but for practical purposes, entries are applied to an Account, and then the changed Account is saved back to the database. To soften the load on PHP, the entries became lightweight containers of metadata which provided little more than a pretty interface for method calls. A simplified version of an Entry looked like: (note, "Container" is nothing more than an abstracted hash table in order to provide useful namespacing functionality. In this case, the `datatypecontainer` enforces typecasting on items going in and coming out of it.)

```php
<?PHP
/**
* Required Include Files
*/
require_once(DIR_CLASSES . 'container/datatypecontainer.php');

class TransactionEntry
{
    function TransactionEntry()
    {
        $this->Container = new DataTypeContainer();
    }
    function importData($data) {}

    function exportData($preserveId = true) {}

    function setEntryId($v) {}
    function getEntryId() {}

    function setTransactionId($v) {}
    function getTransactionId() {}

    function setEntityId($v) {}
    function getEntityId() {}

    function setAccountType($v) {}
    function getAccountType() {}

    function setObjectId($v) {}
    function getObjectId() {}

    function setAttribute($v) {}
    function getAttribute() {}

    function setAsAdd() {}
    function setAsSubtract() {}
    function setPolarity($v) {}
    function getPolarity() {}

    function setTimestamp($v) {}
    function getTimestamp() {}

    function setStatus($v) {}
    function getStatus() {}

    function cloneInverse()
    {
        $obj = new TransactionEntry();
        $data = $this-&gt;exportData(false);
        $data["polarity"] = $data["polarity"] * -1;
        $obj-&gt;importData($data);
        return $obj;
    }
}

?>
```

I left the `cloneInverse` statement because it was of particular note. From above, it was said that everything done to an Account needs to be able to be undone. The secret to this is being able to "reverse" all of the entries that have been applied to a transaction, and then reapply them. The net result of this will always be the Account's original state. In extensions of this Entry object, decoration aliases are used such as `setUserId()` in order to simplify the application programmers' work. With entries, and things to apply those entries to, the next step is to set up the rules.

## Posting Rules
When the transaction manager hands an entry to an Account, it is the Account's responsibility to take that entry and apply it. For different Accounts, applying an entry means different things. Inventory Accounts (owned by a user) are by far the hardest with their need to add/remove binary strings. An Account can always look at the class of an Entry object if that Account supports multiple types of entries. At present, since the inventories on Gaia (housing, main, game inventory, etc) are separated, there is no need to develop sophisticated entry handling. Fowler gets into extreme detail about Posting Rules and covers more than is needed by this system. However, the basics of how to apply a rule and what happens when applying an entry to an Account need to still be established. It was agreed upon that should a posting rule fail, it will fail all future objects in the posting rule change, and triggering a rollback of the transaction by taking the `cloneInverse()` of each Entry and reapplying them.

![image](https://user-images.githubusercontent.com/1795/146686016-cfbac26c-f5a8-4af8-99c9-f263450b608b.png)

Every `Account` then has a public `postEntry()` method, which takes an `Entry` object as an argument. Using the generic accessor functions from the base `TransactionEntry` object, the `Account` can apply the Object ID, Attribute, and Polarity to their entry. Each call to `postEntry()` returns `TRUE` on rule posting success. All that remains is to tackle the fact that the web (and the Accounts) are constantly in use. Collisions can occur when a second transaction manager is started while the first one is still in process. Since the first transaction hasn't saved, the second process has dirty stale old data.

Fowler presents two methods of avoiding collision, both which are worth touching on briefly. Mileage varies with either one.

## Posting Rules With "Catchup"
Of the two methods Fowler discussed, journaling is by far the most widely employed. To draw a real-life analogy, it functions much like a checkbook register. At any given point, a quick glance through the register can tell someone what the "balance" is, including all transactions which haven't cleared. Much like processing checks out of order, an Account can be measured by taking its present state, and then applying all deduction Entry objects which have not cleared yet. This gives the transaction manager the net low for the account, making it possible for the system to check for insufficient funds, missing items, and incomplete database rows. In a set of linear steps in PHP/MySQL, you might get something like the following:

1. Process 1 writes what it wants to do (status uncleared) to the DB
2. Process 1 gets an insert ID as a result of this
3. Process 1 loads the Account
4. Process 1 loads all deducting transactions up to its insert ID on top of the Account
5. Process 2 can start, and at any point after #<span/>1, its Net Account will include all of Process 1's unresolved deductions.

While this is a very reliable system, the need to constantly bring an Account to current isn't a very cheap process query wise. Also, every system needs to implement this transaction system so that a blind write to someone's inventory isn't destroyed in the process. Since the Vending system, Shopping system, Item Granting System (used in games) all would not start equipped with this transaction manager, it was not meant to be. If you're starting from scratch, this is certainly the way to go. If not, well, you can always improvise.

## Improvising with innoDB Locking
The problem was, as stated above, the asynchronous nature of Account objects. Lacking the ability to journal the transactions, the other solution to an Asynchronous problem is to break it. By redefining the Accounts to be as small a data set as possible and introducing a simple retry. The most likely collision on the site is the Gold Account, which would require a user to earn gold on the site within the same timeframe as say, completing a Marketplace Transaction. Marketplace can see the lock, wait a split second, and try again. The resulting failing collision rate is so low that it's considered acceptable to have a user retry in the event of a complete lockout.

I've made mention a few times to locking, and this is done with two tools: innoDB and the MySQL `SELECT...FOR UPDATE` syntax. We've made liberal use of the innoDB storage engine for it's transaction support, and according to MySQL, using the `SELECT...FOR UPDATE` syntax places a good lock on the innoDB row, letting the process finish what it was doing. If during the select phase some database row it needs is locked, it reseeds at a small random interval and performs its work on a retry. When complete, the transaction is committed and the changes recorded.

For spanning multiple databases with a single transaction, John developed a DB spanning object for the DAO he developed. It chains commits to fire off in sequence, effectively minimizing the failing window gap. Half commits are still a problem should for example, all the servers magically lose power and they are mid-commit. Unfortunately, this is a failing of the improvisation that can only be solved with a true multi-phase commit. In production testing, it's failure rate is wholly dependent on the hardware's reliability. While this has a low failing rate, it is substantial enough to warrant exploring extensions to the DAO's DB-spanning system.

## Conclusions

The system is currently in testing with a very good success rate. There are a few tweaks needed to optimize the system of Account and Entry objects in order to reduce weight when including them for processing. I'd also like to better explore the DAO's integration into the Account object- the current method alters the conceptual DAO behavior in order to solve a problem where more than one Account object may be tied to the same database row. More on that next time though.

This was rescued from the archives of the old [felocity.org](https://web.archive.org/web/20050507121849/http://www.felocity.org/journal). As a result, many links in this piece were left pointing to archive.org destinations.

Document

Gaia's original "transaction manager" explained

Link

code

<?PHP
/**
* Required Include Files
*/
require_once(DIR_CLASSES . 'container/datatypecontainer.php');

class TransactionEntry
{
    function TransactionEntry()
    {
        $this->Container = new DataTypeContainer();
    }
    function importData($data) {}

    function exportData($preserveId = true) {}

    function setEntryId($v) {}
    function getEntryId() {}

    function setTransactionId($v) {}
    function getTransactionId() {}

    function setEntityId($v) {}
    function getEntityId() {}

    function setAccountType($v) {}
    function getAccountType() {}

    function setObjectId($v) {}
    function getObjectId() {}

    function setAttribute($v) {}
    function getAttribute() {}

    function setAsAdd() {}
    function setAsSubtract() {}
    function setPolarity($v) {}
    function getPolarity() {}

    function setTimestamp($v) {}
    function getTimestamp() {}

    function setStatus($v) {}
    function getStatus() {}

    function cloneInverse()
    {
        $obj = new TransactionEntry();
        $data = $this-&gt;exportData(false);
        $data["polarity"] = $data["polarity"] * -1;
        $obj-&gt;importData($data);
        return $obj;
    }
}

?>


Fence

Transacting Items on Gaia Online

```yaml
---
slug: just-in-time-javascript
published: 2007-11-27T00:00:00-08:00
description: Chained CSS and JavaScript loading
changelog:
  - on: 2020-02-23
    note: This was rescued from the archives of the old [felocity.org](https://web.archive.org/web/20050507121849/http://www.felocity.org/journal). As a result, many links in this piece were left pointing to archive.org destinations.
---
```

Web apps are heavy, and wait times suck. For every interaction you build, there's that much more code being added to the project. Eventually, it's going to be too much for the user to handle, especially if they are on dialup or slow DSL (though I suppose even an iPhone on EDGE would qualify). For example, the Cash Shop we just launched at Gaia weighed in at over 400k (~100k gzip compressed and minified). While we're a graphic heavy site, waiting for an additional 100k was needlessly painful. To boot, _there was no promise the user was even going to use that feature_, making loading all that JavaScript and CSS a really silly exercise. We needed a way to load the JS and CSS on the fly across all browsers.

Getting the JIT Loader

- [Get the most recent JIT Loader](https://gist.github.com/Jakobo/7a5aec5fcebc8f4886193b114c9ec4f0) (23k)
- [Get the most recent JIT Loader - min + packed](https://gist.github.com/Jakobo/7a5aec5fcebc8f4886193b114c9ec4f0) (5.6k)

The locking utility is also included, but if Lock exists, it won't be used. Enough thanks can't go to Ryan Grove for the [original LazyLoad](https://web.archive.org/web/20071215020306/http://wonko.com/article/527) utility. The JIT loader, like LazyLoad is released under the New BSD License.

## Putting off Loading the CSS and JavaScript
The method of loading we are specifically looking at is known as "event based loading" or "lazy loading". While the [wikipedia article on lazy loading](https://web.archive.org/web/20071215020306/http://en.wikipedia.org/wiki/Lazy_loading) is not very detailed, the summary of the article is that lazy loading allows us to wait on loading stuff until we need it. In computer science, usually the discussion revolves around expensive objects or data calls. In our case, it's all about the browser load time. There's little reason to put JavaScript or CSS into the head of a document unless we know it is 100% needed for the page. We want to put off the expensive http connection and download as long as possible.

A very practical example (and one already out there) is to defer the loading of images until they are within the viewport. Both the [jQuery Lazy Load Plugin](https://web.archive.org/web/20071215020306/http://www.appelsiini.net/projects/lazyload) and the [YUI Image Loader](https://web.archive.org/web/20071215020306/http://developer.yahoo.com/yui/imageloader/) do exactly this, reducing load times on pages by holding out on pulling down images until you need them. For these examples, scrolling the page (and moving a placeholder into the viewport) is an event that triggers the load. If this has proven successful for images and content, there's no reason this can't be applied to scripts and CSS as well.

## Loading JavaScript In Existing Frameworks
To a certain extent, Dojo and YUI have both built in a loading system for including packages before executing script. They are the [`dojo.require()` directive](https://web.archive.org/web/20071215020306/http://dojotoolkit.org/book/dojo-book-0-9/part-3-programmatic-dijit-and-dojo/functions-used-everywhere/dojo-require) and the [YUI Loader Utility](https://web.archive.org/web/20071215020306/http://developer.yahoo.com/yui/yuiloader/) respectively. These two were specifically called out because their methods of including requested files are so different.

In the case of Dojo, an XMLHttpRequest (XHR) is made to load the JavaScript package, and then is ran through `eval()` to convert the request into functional code. This lets Dojo use a package style syntax similar to Java for including libraries to run. Each call to `require()` is synchronous and blocks, meaning you can trust a directive to fully complete before getting into your code. This method is highly effective for lazily loading a package since Dojo is clever enough to not include something twice. The crutch though is the XMLHttpRequest, which is subject to any cross site scripting issues. (Note: AOL has managed to do a custom Dojo build with XHR support across domains and the process is pretty well documented, but it is not the default behavior.)

On the other end of the spectrum, the folks at Yahoo! have taken a different approach, writing to the DOM directly using the `<script>` tag. This eliminates the cross browser issues that Dojo grapples with, but trades it for the limitations of inline script writing exposing the DOM to Internet Explorer in a state when it's not "complete" in IE's mind, resulting in the dreaded Operation Aborted error. In order to use the loader, there's also a lot that needs to be done if custom modules are going to be used. (As of this writing, the YUI Loader constructor does not take the config object, so it's hard to dynamically add to the object without using `YAHOO.lang.augment()`.)

Ryan Grove built a library independent utility for including scripts, similar to YUI, called Lazy Load. It was a good strong start, and needed a steroid boost to provide the CSS support and streamlined DOM writing. Because the API was radically changed, the name was changed as well.

## Just In Time Loader (JIT Loader) Basics
In most situations, the behavior we are looking for is "on event X, load this, then load this, then load this, then execute Function X". To provide access to this streamlined interface, `JIT.startChain()` was created. Calling `startChain()` returns a method-chaining object that you can use to build up a series of JavaScript and CSS includes. The following methods are available on the object returned from the `startChain()` call.

- `addCss(urls, verifier, ie_version)`: adds a CSS File (or array of CSS files) to the execution stack. It will continue when `verifier` returns true. By default, all verifiers simply make sure the nodes have been written to the DOM, not that they have been processed internally. In the case of CSS, you can specify a specific IE version you want to apply this CSS to in order to keep your CSS files clean.
- `load(urls, verifier)`: adds a JavaScript file to the execution stack
- `loadOnce(urls, verifier)`: adds a JavaScript file to the execution stack. When fired, if the URL has already been added by another JIT load or an external source, it won't be loaded again.
- `onComplete(fn, obj, scope)`: Starts the execution chain. When the execution chain has completed, `fn` will be ran. If `obj` is suppled, it will be passed as an argument. If `scope` is `true`, `fn` will instead be directly ran in the context of `obj`.

The most primitive example of chaining would then look something like:

```js
JIT.startChain()
  .loadOnce(jsfile, function () {
    /* verifier */
  })
  .addCSS(cssfile)
  .onComplete(function () {
    // run this when everything is loaded
  });
```

If chaining is not your thing, you can also make direct calls to the JIT object (see examples at the end). After the verifier, each of the above calls takes a callback function, object, and scope; the `onComplete()` doesn't exist in the root JIT object and is used solely for the purposes of chaining. These are left available in case more advanced functionality is required.

## Optimizations
Because JavaScript is (mostly) single threaded, if there are multiple calls to the Lazy Loader, we shouldn't wait on the current code execution block to write to the DOM and clean up when it is finished. The original Lazy Load used a queue system that let multiple calls stack as pending, even if they were for different load requests. The smallest synchronous operation is the DOM write, which can be pushed out to a method and can be locked using a [spinlock](./javascript-threading) to emulate fake threads. Any events that get queued up between DOM writes can be added to the stack, and can then execute while slow scripts take a while. This speedup is surprisingly most noticeable on Internet Explorer, where events are allowed to interrupt the current JavaScript thread, to write more concurrent nodes into the DOM.

## Limitations
The verifier function that is passed in is the linchpin of the event based loading. When the verifier resolves to `true`, the loading process continues with the assigned callback. When working with CSS, this is exceptionally difficult. There are two options when dealing with event loading the CSS files, either find a testable property in the CSS, or pass in `null` for the verifier slot, and load the CSS first. While the first offers more reliability, the second tends to be more practical, since the CSS won't usually apply to anything other than nodes created by the JavaScript. A simple example of a CSS verifier would be (assuming your CSS sets the body's background image to the below mentioned URL:

```js
var verifier = function () {
  return (document &&
  document.body &&
  document.body.backgroundImage = "http://example.com/load_complete.gif")
    ? true
    : false;
};
```

The second major limitation of the system is in `loadOnce()` which requires script nodes to exist in the DOM to test if they have been properly loaded. This testing method makes it incompatible with the `dojo.require()` directive which uses the XHR to perform script includes. In the future, the verifier check might be ran once to preemptively test for component loading, but that will cause issues with testing in the `YAHOO` namespace.

## Enough Already, Examples Please!
You can see JIT in use on the website [Gaia Online for the Cash Shop](https://web.archive.org/web/20071215020306/http://www.gaiaonline.com) (under the market submenu) and eventually the same technique will be in place for the world map and other header-based events.

JIT.startChain()
  .loadOnce(jsfile, function () {
    /* verifier */
  })
  .addCSS(cssfile)
  .onComplete(function () {
    // run this when everything is loaded
  });


var verifier = function () {
  return (document &&
  document.body &&
  document.body.backgroundImage = "http://example.com/load_complete.gif")
    ? true
    : false;
};


Just In Time JavaScript

```yaml
---
slug: transactions-part-2
published: 2006-10-02
description: More on Gaia Online's "Bank Transaction Manager"
changelog:
  - on: 2020-02-23
    note: This was rescued from the archives of the old [felocity.org](https://web.archive.org/web/20050507121849/http://www.felocity.org/journal). As a result, many links in this piece were left pointing to archive.org destinations.
---
```

It's been a while since I've touched on the topic, mostly because I've been busy with work for Gaia. However, this incubation period has let the transaction system mature, and it continues to hold out well with over 29 million completed transactions in the last 7 months. Since its inception, it's been adjusted to support item granting, and is currently being extended to support transactions in the Gaia Marketplace / Auction House. In the first article, I covered the surface of the transaction manager, and some of Fowler's theories which were behind it. In order to avoid recoding large parts of the site, a lock-first mentality was chosen for how to handle keeping an account up to date. This time, we're going to focus on all the players / classes of the transaction manager and how they work together.

* [Part 1: Theory](/thunked/transactions-part-1)
* **Part 2, Transaction Framework**

As in most programming languages, PHP provides support for both public and private methods within a class. In development, one of the primary objectives was to minimize the external facing interface for the end-developer, while still keeping the backend components easy for a developer to maintain. Each component was given specific tasks, responsibilities, and a list of classes that it would couple with in order to provide functionality.

## Bank Transaction Manager
The first component is the first of three end-developer facing classes. The Bank Transaction Manager is responsible for creating Transaction Entries, adding Transaction Entries to its internal stack, and then processing the entry stack while reporting on the success or failure of the process. When a Bank Transaction Manager is initialized, it creates an Account Manager object for tracking the accounts which it needs to load. As entries are created with the `createEntry()` method, they are fed to the end developer and then added back in to the system via `addEntry()`.

A Transaction Entry is nothing more than a shell object, providing a clean interface for setting an object's ID, it's attribute, quantity, and other associated properties. When `addentry()` is called, the Bank Transaction Manager uses these properties in order to decide what Account to load (via the Account Manager). This pairing is then set aside until execution.

During the execution phase, the Bank Transaction Manager tells the Account Manager to initialize all relevant accounts. It then loops through every entry/account pair and passes the entry into the account. In processing terms, these are called posting rules. Every posting rule has a boolean success, and the sum of all functions returning an ultimate success or failure for `execute()`.

If any errors are encountered, the Bank Transaction Error (a simple static class) is written to with information about the failure.

## Account Manager
In a horizontally scaled environment, a user's inventory or a row of trading information might reside on completely separate machines. To encapsulate the loading and saving of these various things is the reason for the Account Manager object. Requested accounts are queued up, and then loaded via a single call to `loadAccounts()`. Beyond simply loading accounts, the account manager should be able to

- handle information if the account has changed
- prevent data overlap by avoiding querying for duplicate data
- provide an interface for the instantiation of new Account objects

During the execution of the Bank Transaction Manager, the Account Manager is called (specifically when `BankTransactionManager::addEntry()` is used). Accounts are queued for loading as entries are added, and are then loaded at once. There are two ways to load the account data, one which uses blocking, and one which does not. Even at 4.5 million registered members, the blocking method has not been an issue, and so that is the method we'll be talking about. In an InnoDB database, a row can be locked during the select phase as part of a transaction by using the following syntax: `SELECT 'columns' FROM 'table' WHERE 'criteria' FOR UPDATE;`

The `FOR UPDATE` places a lock on the row, leaving your PHP script as the only script that has access until the lock expires. This feature is only available on InnoDB however, as the MyISAM engine supports neither row locking nor transactions.

When asked to save, the `AccountManager` calls the `isChanged()` method on every account in order to verify if it has been altered. Accounts which have been altered are then saved back to the database and the locks released.

## Transaction Entry
There's not much to say about the `TransactionEntry` object. As a shell, all it contains is a data payload. It's information consists of: "how many", "of what", "with what serial", and "adding or subtracting". To help simplify the development end, the Entry object is extended to support Game items, Regular Items, Gold, and Gift Credits. During execution, these small instruction sets are passed to the Account object.

## Account
Defined as the authoritative source regarding all data coming in and going out, these objects are modeled in spirit after the VO J2EE pattern. They exist to hold an account's data, and are decorated with methods to support the changing of that data. When the Account Manager calls `loadAccounts()`, every queued account object is asked for its database information and required fields. The sum of this data is aggregated, and passed into the `importData($fieldName, $data)` function. When the Bank Transaction Manager executes, it then takes every Transaction Entry object, and passes it directly into `postEntry($t)`. It is at this point that the heavy lifting is actually done.

Every account maintains a ruleset for how its data is to be altered, known as "posting rules". These rules are very strict, and breaking them should cause the entire transaction to fail for the user and return an error. The most common example of failure is if the posting rule contains an item type that the account does not support, such as posting gold information to an inventory account. With a single public interface, the logic of altering the account information is also internalized, protecting it from the outside world. Upon altering the account, `postEntry()` will return either `TRUE` or `FALSE`, which will be evaluated by the Bank Transaction Manager object.

Adding new accounts or extending existing accounts to add functionality is very easy. The methods exposed publicly are small, specifically `getDaoName()` and `getDaoFields()` for Gaia's database support, `importData()` for loading, `exportAccount()` for saving, `isChanged()` for the Account Manager's save required check, and `postEntry()` for altering the account's data.

## Code in Practice (End Developer Side)

```php
$btm = new BankTransactionManager($transaction);

// create entry (Account, Entry Type)
$e = $btm->createEntry("Gold.Gold");
$e->setUserId($user_id);
$e->addGold($gold_amount);
$btm->addEntry($e);

$e = $btm->createEntry("ServerGold.Gold");
$e->setUserId(ENTITY_SERVER);
$e->subtractGold($gold_amount);
$btm->addEntry($e);

try {
    $btm->execute();
}
catch (Exception $e) {
    throw $e;
}
```

More on Gaia Online's "Bank Transaction Manager"

$btm = new BankTransactionManager($transaction);

// create entry (Account, Entry Type)
$e = $btm->createEntry("Gold.Gold");
$e->setUserId($user_id);
$e->addGold($gold_amount);
$btm->addEntry($e);

$e = $btm->createEntry("ServerGold.Gold");
$e->setUserId(ENTITY_SERVER);
$e->subtractGold($gold_amount);
$btm->addEntry($e);

try {
    $btm->execute();
}
catch (Exception $e) {
    throw $e;
}


Transacting Items on Gaia Online, Part 2

```yaml
---
slug: stylizing-form-submits
published: 2006-10-28T00:00:00-08:00
description: Camino and Safari & styling type=submit
changelog:
  - on: 2020-02-23
    note: This was rescued from the archives of the old [felocity.org](https://web.archive.org/web/20050507121849/http://www.felocity.org/journal). As a result, many links in this piece were left pointing to archive.org destinations.
---
```

"The buttons aren't styling" I remarked as I stared at the page in Camino and Safari. Testing on the Mac platform has been the absolute bane of my existence as of late, mostly because for some reason, these browsers in particular are very protective of their form widgets. Coming back to [Cameron Adams' Entry on Styling Form Widgets](https://web.archive.org/web/20061218112920/http://themaninblue.com/writing/perspective/2004/04/28/), I found that none of the Macromedia examples were actually working for Camino/Safari, although they looked beautiful in Firefox. The submit button simply would not take the background settings. Interesting enough though, something of `input type="button"` styled perfectly.

However, the value attribute of the button wasn't getting passed in. For the legacy code around Gaia, we have forms with more than one possible "submit" for an action. The most common case of this is preview and submit buttons we traditionally use in the forums. This left us with two scenarios:

```html
<form id="myForm" action="some.php" method="POST">
  <input type="text" name="foo" value="" />
  <input id="submitBar" type="submit" name="action" value="bar" />
  <input id="submitBaz" type="submit" name="action" value="baz" />
</form>
```

or Button tags that wouldn't pass in their value to the PHP script (and shouldn't technically perform a submit either)

```html
<form id="myForm" action="some.php" method="POST">
  <input type="text" name="foo" value="" />
  <input id="submitBar" type="button" name="action" value="bar" />
  <input id="submitBaz" type="button" name="action" value="baz" />
</form>
```

The final solution ended up being something right down the middle and using JavaScript to make up for Safari / Camino's shortcomings. Starting with a default submit button, we can replace it with a input `type="button"` node, and add a bit of JavaScript to the `onClick` to make up for the stylized button's shortcomings. The first block of JavaScript goes into the head, and the second block can either go into an `onLoad` handler or at the end of the form tag, depending on how soon you need the replacement.

```js
////////
// SwapSubmit - A Tool for Stylizing Submit Buttons on All Browsers
// Licensed under CC-GPL-2.0
// http://creativecommons.org/licenses/GPL/2.0/
////////
var RJH_SwapSubmit = {
  replacedEles: new Object(),
  replace: function (formid, eleid) {
    if (typeof eleid == "string") var ele = document.getElementById(eleid);
    else var ele = eleid;

    if (typeof formid == "string") var f = document.getElementById(formid);
    else var f = formid;

    if (ele) {
      var o = this.build(formid, ele);
      var name = ele.getAttribute("name");
      var value = ele.getAttribute("value");

      var pn = ele.parentNode;
      pn.removeChild(ele);
      pn.appendChild(o);

      if (!document.getElementById(name))
        f.appendChild(this.buildInputField(formid, name));

      this.replacedEles[eleid] = new Object();
      this.replacedEles[eleid]["name"] = name;
      this.replacedEles[eleid]["value"] = value;
      this.replacedEles[eleid]["form"] = formid;
    }
  },
  build: function (formid, ele) {
    var o = document.createElement("button");
    var f = document.getElementById(formid);

    var oldOnclick = ele.onclick;
    o.id = ele.id;
    o.className = ele.className;
    o.onclick = function () {
      if (oldOnclick) {
        if (oldOnclick() == false) return false;
      }
      RJH_SwapSubmit.submitForm(this);
    };

    return o;
  },
  buildInputField: function (formid, name) {
    var o = document.createElement("input");

    o.setAttribute("type", "hidden");
    o.id = name;
    o.setAttribute("name", name);

    return o;
  },

  // ORIGIN: onClick of a button
  submitForm: function (ele) {
    var clickId = ele.id;
    var name = RJH_SwapSubmit.replacedEles[clickId]["name"];
    var value = RJH_SwapSubmit.replacedEles[clickId]["value"];
    var formid = RJH_SwapSubmit.replacedEles[clickId]["form"];
    document.getElementById(name).value = value;
    document.getElementById(formid).submit();
  },
};
```

```js
RJH_SwapSubmit.replace("FORMID", "SUBMITBBUTTONID");
```

Replace `FORMID` and `SUBMITBUTTONID` with the relevant values.

## Drawbacks
The largest drawback hands down is the addition of JavaScript. It's not something to depend on, and many steps were taken to ensure that the enhancement is progressive in nature.

Styled images will have to be styled to reflect the change from an input to a button node, and can be referenced via `button#idNameofElement` to apply all the necessary stylization.

////////
// SwapSubmit - A Tool for Stylizing Submit Buttons on All Browsers
// Licensed under CC-GPL-2.0
// http://creativecommons.org/licenses/GPL/2.0/
////////
var RJH_SwapSubmit = {
  replacedEles: new Object(),
  replace: function (formid, eleid) {
    if (typeof eleid == "string") var ele = document.getElementById(eleid);
    else var ele = eleid;

    if (typeof formid == "string") var f = document.getElementById(formid);
    else var f = formid;

    if (ele) {
      var o = this.build(formid, ele);
      var name = ele.getAttribute("name");
      var value = ele.getAttribute("value");

      var pn = ele.parentNode;
      pn.removeChild(ele);
      pn.appendChild(o);

      if (!document.getElementById(name))
        f.appendChild(this.buildInputField(formid, name));

      this.replacedEles[eleid] = new Object();
      this.replacedEles[eleid]["name"] = name;
      this.replacedEles[eleid]["value"] = value;
      this.replacedEles[eleid]["form"] = formid;
    }
  },
  build: function (formid, ele) {
    var o = document.createElement("button");
    var f = document.getElementById(formid);

    var oldOnclick = ele.onclick;
    o.id = ele.id;
    o.className = ele.className;
    o.onclick = function () {
      if (oldOnclick) {
        if (oldOnclick() == false) return false;
      }
      RJH_SwapSubmit.submitForm(this);
    };

    return o;
  },
  buildInputField: function (formid, name) {
    var o = document.createElement("input");

    o.setAttribute("type", "hidden");
    o.id = name;
    o.setAttribute("name", name);

    return o;
  },

  // ORIGIN: onClick of a button
  submitForm: function (ele) {
    var clickId = ele.id;
    var name = RJH_SwapSubmit.replacedEles[clickId]["name"];
    var value = RJH_SwapSubmit.replacedEles[clickId]["value"];
    var formid = RJH_SwapSubmit.replacedEles[clickId]["form"];
    document.getElementById(name).value = value;
    document.getElementById(formid).submit();
  },
};


RJH_SwapSubmit.replace("FORMID", "SUBMITBBUTTONID");


Stylizing Form Submits

```yaml
---
slug: phpbb-permissioning
published: 2004-12-02T00:00:00-08:00
description: How Gaia's volunteer moderator system outstripped phpbb's capabilities
changelog:
  - on: 2020-02-23
    note: This was rescued from the archives of the old [felocity.org](https://web.archive.org/web/20041207010434/http://felocity.org/) site. Writing on the internet was pretty different back then. As an aside, this was how I ended up working for one of the coolest social gaming companies at the time.
---
```

Currently, I've been doing a lot of work with the way phpbb handles its permissions. The method is a group based Moderator scheme, which then uses a different user attribute for most moderation functions. Many people know about Gaia's two moderator groups, and this is actually more in line with how phpbb intended permissions to be. Give a group power to modify forum X, give another group power to modify forum Y. The problem is, all moderation functions check to see if you are an admin. In phpbb's architecture, there is no admin "group". The only reasoning I could find for it was that it simply wasn't thought of. Many other large scale systems (Xoops comes to mind) use an administrative group just like any other group. Permissions are then applied on the group level.

So then, in centralizing the permissioning model, we see two primary approaches. The first of these is to centralize permissions into groups, and then add users to groups. However, with over 1.3 million users, the group table will grow very large, very quickly. However, you could change permissions for an entire group of people by just adjusting the group. The other way that came to mind was to centralize the permissions on the users themselves. This would allow for "groups of permissions" instead of "groups of users". From a management perspective, this actually isn't the better of the two solutions. However, assuming a static package of permissions relative to a user's power on the site, it makes sense to simply give a user a level / value / package. You could still potentially build a model for a finer granularity of control, but in the case of Gaia, a moderator / admin / etc has a predefined series of tools. The likelihood of adding someone who would mod area A but not area B is actually small (compared to the total user base) and so these individual cases are realistic enough to handle in a separate table.

The other piece of rationale to a user-centric permissioning system is its need to be both forward-compatible with future development, and yet backwards compatible with everything else that has been written. This is where the nightmare truly begins. Several pieces around the site need to be reengineered to the new permission model, including the way our forum tree is built, the piece that says if you can view a topic or not, forum viewing, jumpboxes, etc. However, there are prefabricated templates and expected results. So the new code has expected input, and output, but a completely different internal engine. Essentially then, we are emulating phpbb's authorization functions while everything under the hood changes. Thankfully, all future developments already include the user-centric model, so the biggest overhaul is in the forums.

I've got some 3 pages of notes about ideas of where to change code. It's time now to see if anything out of these notes will pan out.

This was rescued from the archives of the old [felocity.org](https://web.archive.org/web/20041207010434/http://felocity.org/) site. Writing on the internet was pretty different back then. As an aside, this was how I ended up working for one of the coolest social gaming companies at the time.

How Gaia's volunteer moderator system outstripped phpbb's capabilities

phpbb Permissioning

```yaml
---
slug: defining-social-fun
published: 2007-03-24T00:00:00-08:00
description: Belonging makes you an evangelist
changelog: ~
---
```

In professional talks about Gaia Online, I've been asked the question "what makes your users so passionate?" although never in such a direct way. Usually, the questions are "how does the site sustain itself?", "what is there to do on the site?", and "how do you have that many people?" Everyone always seems amazed at the volume of users that are on Gaia at any one time; there was a record 86,738 users online a few months ago (January 4), and we cleared the 5 million registration mark awhile ago. The site's addictive in a way that has never been explained. There's a magic "secret sauce" at work- a sauce that Newsvine has picked up on, that MySpace didn't know they had, and that Gaia Online happily cultivates. In each site's own way- it's fun. Now, if only it was possible to qualify what exactly "fun" means, then everyone would have an awesome community website. Try and define fun by itself though, and the result is a meaningless description that certainly can't be coded.

## Beyond "Fun"
The concept of fun is so confusing, that the more a person tries to define it, the more confusing the concept becomes. Instead, fun is better described as a summation of things; interestingly, these things in and of themselves are not necessarily fun, but instead are foundations of an online emulation of life. In 1943, Maslow created a [Hierarchy of Needs](https://web.archive.org/web/20070724041038/http://en.wikipedia.org/wiki/Maslow's_hierarchy_of_needs), which described the basic needs of human beings. Later, Nevis revised this theory slightly, adapting it based on his studies of East Asian values.

| Maslow             | Nevis                        |
| :----------------- | :--------------------------- |
| Self-Actualization | Self-Actualization (non ego) |
| Esteem             | Safety                       |
| Love/Belonging     | Physiology                   |
| Safety             | Belonging                    |
| Physiological      | -                            |

We can assume that because visitors to community websites have access to the Internet, they also have their physiological and safety needs met. This leaves "belonging" as the common denominator of needs between both Maslow and Nevis' studies. It can be concluded then that "fun", is the combination of a sense of belonging, a venue for satisfying esteem, and ultimately achieving a state of self-actualization. When all three needs are met, as the sites we will be discussing show, users have a higher retention rate, contribute to the larger community as a whole, and become evangelists of the site in question. They become passionate users.

## The Sites Being Talked About
**[Gaia Online](https://web.archive.org/web/20070724041038/http://www.gaiaonline.com/)**: Gaia Online labels itself as the premier social hangout for teenagers, with the largest forums on the Internet, several games, and a customizable avatar system. (Disclaimer As of this writing, I am employed by Gaia Interactive, creators of Gaia Online.)

**[Newsvine](https://web.archive.org/web/20070724041038/http://www.newsvine.com/)**: "Get Smarter Here" is the tagline for the online news site that is rapidly growing in popularity. Its primary features include commenting and voting on news stories, as well as a "Doppleganger" technology which can harvest information off of the popular newswire services. Members can run their own columns or get together and form groups to produce their own online focused mini news sites.

## The Most Common Need: Belonging
As mentioned above, the most common need expressed across both hierarchies is the need to belong. Belonging in the most literal sense means to feel a part of a group. A very basic belonging can be achieved in simple groupings of interests, likes, and dislikes. Newsvine Top Seeds Newsvine, for example, makes it easy for readers browsing by a category of interest to immediately locate people who are talking and writing about related topics. Thanks to Newsvine's weighting technology, there's a high chance the articles found will be interesting and the users will return once, then twice, then thrice. Eventually, the users will keep returning since the articles the users finds are of value to them. They have achieved belonging and are ready to contribute to the collective group.

Gaia Online doesn't have the direct categories of Newsvine, and therefore depends on the more conventional social networking means. Through forums, profiles, and journals, users communicate with each other while sharing a common goal- the quest for virtual items to improve their online avatar. While this isn't always a driving force behind users' site activity, it's a commonality all users on the site share, so users start interacting primarily for the gold. They play games, post, vote in arenas, and ultimately find their first friends on the site. When this happens, users find their "home", a thread or two they always return to where most of their friends are chatting. That first connection and those first friends create a strong sense of belonging, as those friends will often pull the new users into their favorite threads and hangouts, immersing them in a smaller subset of the Gaia community.

Some popular social networking sites achieve belonging by creating locations central to a users' network of friends. This sense of belonging users get is no less valid than those previously mentioned. However, the sense of belonging becomes very dependent on the users' primary network to remain on the site/service. A very solid case that illustrates this belonging pattern is Facebook and its "seasonal disorder". Before Facebook started broadening its audience outside of the college community, a wave pattern could be identified in the site's average traffic, with dead times in the summer and surges in the fall. This corresponded with the typical academic calendar. Additionally, as students moved through their final year of college, their "belonging" on Facebook faded. The use of Facebook as a tool for class information, parties, and networking became less valuable as the users' friends also stopped using the service. This resulted in a constant amount of attrition which ate away at any longevity the site hoped to achieve.

## After You Belong
Continuing with the pyramid of needs outlined above, when users of a site have achieved a sense of belonging, the next tiers of esteem and self-actualization become available. In Western cultures, esteem is a highly valuable component of a community's success. People who feel they have accomplished something socially return to the places that make them feel better. Still, esteem isn't just about popularity, although being popular in the context of the community is certainly a draw. A site that promotes a sense of self-rewarding can also further a users' esteem. Much like how people who play MMORPGs feel proud of their characters, people who participate in communities feel good about their contributions. Following this logic, sites that make users feel good about their contributions will have users who contribute more. One popular method to measure a users' contributions is with a karma system. Newsvine has taken it a step further with its Vinacity system, which takes the traditional +/- karma system, and rewards users based on their participation on the site. As users post, comment, and participate, pieces of their vine fill up, providing an outward status icon to the community of their accomplishments.

Gaia, like many other community/game hybrid sites, reflects esteem through the collection of the game's items or status symbols. Much how the vine plaque of Newsvine indicates someone's contributions to the community, a large amount of virtual wealth and item-based accomplishments can also provide a point for esteem. One of the most common activities on Gaia is the process of "questing," which has little to do with the MMORPG concept, but instead is a way for users to share their progress toward an expensive item on the site. During the quest, the users provide updates, take donations, and ask the community for help and support. Other members help out, and eventually the users' goal is reached. That item they acquired then becomes a symbol of status they wear proudly. As users participate in the site and accrue items and virtual wealth, they also achieve a sense of accomplishment. In both Gaia and Newsvine's cases, users feels like they belong, and feel good about their activity. At this point, it's safe to say they are regular users. All they need is something that makes them want to evangelize the site.

## From Regular to Evangelist
Adding more ways to build esteem and provide opportunities for users to belong is not enough to promote a regular user to an evangelical one. Instead, users who are passionate about a site had an event which has pushed them from the point of being regular users to the point of telling others actively. There are several contributing factors which can collectively drive users to this point (in no specific order):

- Enjoyment of the site's experience
- Enjoyment of the people on the site
- Kicking-Ass at something
- Explaining the to others and what makes it fun

Beyond this, coming together in real life can accelerate this process greatly. Taking the online community "offline" puts faces and real names to friends who were once only pixels, and the site becomes a common ground. The [Newsvine Relay For Life](https://web.archive.org/web/20070724041038/http://spring.newsvine.com/_news/2006/05/30/234195-the-first-newsvine-charity-event) was the first community-wide event, that brought individuals together in real life while supporting the American Cancer Society. Those who participated still remain some of the site's most active users. The events that bring forth a "Random Act of Vineyness" (the highest honor at Newsvine) come with dozens of users who have taken an online experience and turned it into something personal and important to them. In short, it made a difference in their lives.

At Gaia, we see how we change people's lives all the time through the letters that we get and at the conventions that we attend. We've seen people who used our community to break drug addiction, find friends, and become better people. We've also seen the people who help community members selflessly in our Life Issues forum, and donate to the previously-mentioned quests. At the convention, these people get to meet for the first time. In the years I've been with the company, it's happened hundreds of times; people meet at the Gaia booth, shriek, hug, and then spend the next thirty minutes to an hour talking about the website. At conventions the users' real lives are brought back to their virtual ones with the ability to play real life games to gain virtual items for their avatars. The [Gaia Panel experience](https://web.archive.org/web/20070724041038/http://www.youtube.com/watch?v=RZozJ20gZok) is also amazing. A small section of the community comes together for two hours to talk about features, voice complaints, and ask questions. In this offline space, users feels responsible for the development of the website, and as stakeholders, take a deep interest in it.

## So is it Kool-Aid?
Like Maslow's pyramid, a community site's success should be built from the foundation up. Deep moments of connection cannot occur until the prerequisite experiences of belonging and esteem are fulfilled. The end goal is to make something important to people and to make their experience "fun." When the social networking cloud settles, it's on these sites that the users will continue to invest their time.

### Additional Reading
- [Harlow, The Nature of Love](https://web.archive.org/web/20070724041038/http://psychclassics.yorku.ca/Harlow/love.htm)

Gaia Online

2007

Just In Time JavaScript

Defining Social Fun

2006

Transacting Items on Gaia Online

Transacting Items on Gaia Online, Part 2

Stylizing Form Submits

2004

phpbb Permissioning