Authoring an Element

Creating an element from scratch may sound daunting at first but if you have any PHP experience at all it should be a snap. Elements are basically PHP scripts or snippets with a few caveats, that extend the functionality of Odin Assemble. Let's review the caveats:

• Elements do not start with an opening "Elements do not end with a closing "?>"
• Elements do not end with a "return;"

It's important to remember those three basic rules because failure to comply will cause elements to fail or render incorrectly.

When your element is executed whatever is printed or echoed to the standard output will be captured in a buffer. Wherever you have referenced the filename of this object sans extension, in your page block or template block, the resulting buffer will then take the place of your original reference.

Simple PHP Elements

When I think about PHP elements, I normally break them into two groups; simple and complex. Simple elements generally take no arguments and thus usually offer canned response, sometimes random (random images) and even sometimes event driven (current date).

Hello World!

Most programmers have encountered the "Hello World" example before. To walk you through creating a (very simple) valid element that will return the statement "Hello World!"

	echo "Hello World!";

Saving the above code as "hello_world.php," I would then upload it to my /elements directory. Then somewhere in either by page block or template block I will need to place a reference to my new element. In my page block I will add {hello_world} (because that is filename sans extension of the element I uploaded).

Visiting the corresponding page in my browser at the spot I placed {hello_world} I can now see Hello World! instead.

Complex PHP Elements

Complex elements take arguments passed either from the reference to the element itself or via a query string argument.

Hello World! Take Two

Revisiting our Hello World! example from above, lets modify our code:

	
	if (strlen($_GET['emotion'])) 
		$emotion = $_GET['emotion'];
	else
		$emotion = "unsure";

	echo "Hello World! My name is ".$element_passed_value." 
              and I am feeling ".$emotion."!";

Saving our code again, this time as "hello_world_complex.php" and then I would upload it to /elements. In my page block this time I am going to make a few reference, all to the same element. Here is an excerpt from the HTML of my page block.

	
	{hello_world_complex value="Brian"}
	<br/>
	{hello_world_complex value="Jake"}	

Visiting the page in my browser again the response will be:

	
	Hellow World! My name is Brian and I am feeling unsure!

	Hello World! My name is Jake and I am feeling unsure!

If I add ?emotion=happy to my query string then the results change. Now they show:

	
	Hello World! My name is Brian and I am feeling happy!

	Hello World! My name is Jake and I am feeling happy!

By passing arguments to your elements either via the query string or the reference itself you can turn a simple element into a powerful and reusable component.