simply put: Tools - Talks about creating re-usable, self-contained components.

Tools

PIE goes very far in encouraging reusable code, not only through its standardized conventions (file system, namespacing everywhere, etc.) but also by lettig you create self-contained components, which it calls "tools".

To place a tool somewhere in your output, you simply write the following:

<?php echo Pie::tool("$module/$tool_name", $params);>

Each tool typically comes bundled with a couple things, that let the tool do its work right out of the box:

• The $module/$toolname/tool handler. This returns the HTML markup of the tool. It is also responsible for calling Pie_Response::addScript and Pie_Response::addStylesheet to add whatever front-end files the tool depends on.
• The $module/$toolname action. The tool typically has a form that submits things to this action, whether using AJAX or not. The action is responsible for implementing the back-end functionality of whatever the tool is supposed to do.
• On the front end, there is usually a javascript file that enhances the static HTML that the tool outputs, "activating" it and adding things like javascript validation, ajax, or whatever you want.

Pie::tool is a bit similar to Pie::view, except that a tool is much smarter than a view. First of all, it has a dedicated handler (the C in MVC) to render the tool. Also it adds a prefix, which it uses for all id attributes of HTML elements that are produced with Pie_Html methods, while the tool is being rendered. This is to prevent clashes within the document. If you have multiple instances of the same tool, the prefix looks something like id28_youMixer_search_, rather than youMixer_search_.

Tools on the front-end

PIE also wraps each tool in a div that has special class and id attributes. This div is used to locate and "activate" the tool on the front end. If you have tools containing other tools, the prefixes may aggregate, for example:

<div id='youMixer_search_tool' class='youMixer_search_tool'>
  <h2>Let's search:</h2>

  <div id='youMixer_search_pie_textbox_tool' class='pie_textbox tool'>
    <!-- some kind of textbox  -->
    <!-- all id attributes here are prefixed with "youMixer_search_pie_textbox_" -->
  </div>

</div>

Meanwhile, tools may come bundled with javascript files, along the lines of:

	Pie.constructors['youMixer_search_tool'] = function(prefix) {

		// constructor, called after DOM is ready
		// fires in parent tools before child tools
		var me = this;

		me.init = function() {
			// this is called when a tool has finished initializing
			// fires in child tools before parent tools
		}
		
		me.someMethod1 = function() {
			// implement someMethod1
		}
		
		me.someMethod2 = function() {
			// implement someMethod2
		}
	}

The code above is a skeleton for implementing the front-end counterpart of the youMixer/search tool. On the front end, the Pie.ready() function scours the DOM, looking for divs of the class "youMixer_search_tool" and then "activating" that HTML, which involves running the function for each instance found. It also call

User experience

When a tool is placed on a page, it doesn't have to know much about that page. The tool comes with its own action, and the resulting user experience is typically as follows:

• If the tool uses AJAX to submit to its action, then the result comes back as JSON. PIE allows you to request more than one slot, and possibly update more than one area of the page from one request.
  • If there were errors, then the data.errors is an array with the errors.
  • Otherwise, data.slots has the content requested.
• If the tool has a form that gets submitted in the regular way, without AJAX, then the browser starts loading the action associated with that form.
  • If there were errors, the tool's action is shown, with the errors displayed in the errors slot. Typically, this action re-displays the tool all by itself, so you can re-submit the information after you've fixed the input.
  • Once the form has been submitted successfully, the browser is typically redirected back to the page that had the tool in the first place.

Whenever possible, try to enhance your tools with Javascript, because the regular form submission mechanism is just intended to be a sensible fallback.

In general, it is a good idea to write your front end first — keeping it as self-sufficient as possible — and add the back end later (mostly as a set of web services), as this minimizes the load on the web server, and makes your application more responsive.