N2F Training Team Blogtorials

With today’s development release of Yverdon v0.2, I decided I would take some time to highlight a few of the smaller changes we’ve implemented in the next iteration of our PHP 5 framework.

MySQLi Database Extension
We were lucky to be working with Waterfall Data Solutions from the start of N2F Yverdon, so we’ve had some great testing done for us on some specific extensions and sets of core functionality.  One of the biggest contributions that we received was massive amounts of test data for the MySQLi database extension.  With all of the data we ended up doing a complete rewrite of the extension, and we still have more improvements that we weren’t able to get into the v0.2 release.  The rewrite concentrated on resolving issues resulting from the buggy implementation of the MySQLi extension in PHP, as well as some irregularities we found when dealing with parametrized queries.  This all leads to more secure interactions with MySQL through the extension, which is never a bad thing.

PHP 5.3 Compatibility
It makes us very proud to say that we sat down with the intention of making Yverdon v0.2 fully compatible with the PHP 5.3 RC’s, and we ended up changing about 5 lines of code in total.  It’s very possible that we’ll be making more changes in the future to account for bugs we haven’t yet found, but at the least we’re already working hard to make sure we don’t fall behind the times in the PHP world.

Memcache Caching
Chris (ctd1500) put in a bit of work to add memcache functionality to our sponsored cache extension.  This means that anything which uses the cache extension can be easily configured to take advantage of a memcache installation, including the template engine.

New Database Extensions
Another set of additions that have been taking a lot of time are the new database extensions we’ve added to our sponsored list.  Now you have access to MySQL, SQLite and PostgreSQL through our new sponsored extensions.  One of the last things we’re doing to the code is running these three new engines through a test routine that will be used on every release moving forward.

There’s a lot more that we’re working on releasing with the first stable release of v0.2, but we’ll save some of them for that time just to keep it that much more of a surprise.  Hopefully you have a better idea of what we’ve been working on with Yverdon over the past 7 or 8 months.

- Andrew

In Yverdon v0.1, we added the ability to use sys.ext.php files inside of each module.  Their purpose is very simple and yet sometimes beautifully useful.

The Problem
Sometimes we find ourselves working on very large projects.  Inside of those large projects, the tendency is to have each developer concentrate on specific modules or extensions.  The module/extension layout works great in most situations, but it occurred to us that it wouldn’t always be appropriate to put certain system-wide functionality into an extension.  As an example, it would seem odd to build an entire extension just to create some template aliases for one level of the site.

The Solution
Our solution, the sys.ext.php file, allows a developer to include code system-wide on a particular directory level without having to create an extension.  The sys.ext.php files are included after all extensions have been included but before any modules are included.  This gives you the ability to use any of the constructs provided by your extensions and have your code execute before a page.php or data.php is called.  Going back to our example, you will see that the default installation’s main module has a sys.ext.php file inside of it, with the following contents:

<?php

/***********************************************\
* N2F Yverdon v0                              *
* Copyright (c) 2008 Zibings Incorporated     *
*                                             *
* You should have received a copy of the      *
* Microsoft Reciprocal License along with     *
* this program.  If not, see:                 *
* <http://opensource.org/licenses/ms-rl.html> *
\***********************************************/

// Create our template aliases
n2f_template_dynamic::addAlias('header', 'header', 'main', N2F_REL_PATH.'modules', 'default');
n2f_template_dynamic::addAlias('footer', 'footer', 'main', N2F_REL_PATH.'modules', 'default');

?>

This file only needs to be in the main module for all of the other modules in the root level to have access to it’s values.  The result of this code is that now all templates executed in the root level will now be able to use aliases for <%header%> and <%footer%>.

Conclusion
The sys.ext.php files are easy to use and very handy in certain situations.  Hopefully this blogtorial has been helpful in showing you the basic idea behind sys.ext.php files.  Yverdon v0.2 will also be introducing a new file, the mod.ext.php file, but we’ll talk about that when the time comes.  ;)

- Andrew

Part 2 of the series introduces us to the layout of N2F Yverdon module. In this part of the series, I’ll be showing you the basics of the dynamic template extension built for our template system. Our template system, while not required for use of Yverdon, is a fast and simple solution to the problem of separating the presentation and business layers of an application.  In plain English, we just mean to say we’re offering a way to separate the code you write from the way it’s displayed.

Template Extensions

N2F Yverdon utilizes a system of extensions for expanding the capabilities of the framework.  When building the template engine, we realized that there was a lot of value in being able to change how the template system worked in certain situations.  As a result we decided to leverage the extension system for our template engine.  First v0.1, we have created the first of these template extensions, called the Dynamic extension.  That is the flavor of template we will be using in this entry.

Directory Structure
One of the first things to know about how dynamic templates work is the directory structure you must use for storing your templates.  We opted to organize templates by skins inside of each module.  The name for the skin Yverdon comes configured to use is simply, ‘default’.  If you are inside of an ‘aboutme’ module, your template directories will look as such:

/home/someuser/public_html/modules/aboutme/tpl
/home/someuser/public_html/modules/aboutme/tpl/default

You can create however many skins you like, but we’re not going to get into using different skins in this post.

The Template File
The system expects templates to have a .tpl extension on them, but beyond that naming the extension is up to your wildest dreams and desires.  As a habit, the N2F Yverdon staff almost always uses index.tpl as the base template for a module.  We’re going to create three files for this post:

/home/someuser/public_html/modules/aboutme/tpl/default/index.tpl
/home/someuser/public_html/modules/aboutme/tpl/default/header.tpl
/home/someuser/public_html/modules/aboutme/tpl/default/footer.tpl

We’ll put the following code into the header.tpl file:

<html>
<head>
<title>My Page</title>
</head>
<body>

The following code into the index.tpl file:

This is the body of my page.

And the following code into the footer.tpl file:

</body>
</html>

Once all the files are saved, we’ll move onto creating one of the nice features of the dynamic template extension.

Aliases Are Short For Something
With a dynamic template, we found the need to include blocks of HTML here and there across multiple pages and modules.  To solve this common problem, we created the alias system.  There are lots of different terms and ways of explaining this part of the extension, but the basic idea remains the same.  All this does is allow you to break pieces of your markup (HTML/XHTML/CSS) into separate .tpl files and use it across the rest of your Yverdon installation.  To define aliases, you will create a page.php file similar to this:

<?php

// Pull the global n2f object
global $n2f;

// Define our header and footer aliases
n2f_template_dynamic::addAlias('header', 'header', 'aboutme', './modules', 'default');
n2f_template_dynamic::addAlias('footer', 'footer', 'aboutme', './modules', 'default');

?>

All aliases are currently defined using the n2f_template_dynamic::addAlias() method.  You can view the method signature here, but the quick and dirty is that the first argument is the text to match in templates for this alias, the second argument is the name of the .tpl file to pull from, the third is the module the .tpl file comes from, the fourth is the base path (you won’t need to change that normally) and the final argument is the skin where the alias resides.

To use a defined alias, you must put the text in between the <% and %> tags.  We’ll put these two to use inside of our index.tpl file, making it now look like this:

<%header%>
This is the body of my page.
<%footer%>

Bringing It All Together
Finally, we get to use our template.  Because of the aliases we made, we only need to display one template.  Anytime you wish to display a template, you must create a new n2f_template object.  I’ll add the code to our page.php file first, and explain after:

<?php

// Pull the global n2f object
global $n2f;

// Define our header and footer aliases
n2f_template_dynamic::addAlias('header', 'header', 'aboutme', './modules', 'default');
n2f_template_dynamic::addAlias('footer', 'footer', 'aboutme', './modules', 'default');

// Create the template object
$tpl = new n2f_template($n2f, 'dynamic');

// Set the module and file to use
$tpl->setModule('aboutme');
$tpl->setFile('index');

// Render and display the template
$tpl->render();
echo($tpl->fetch());

?>

An n2f_template object can be initialized several different ways, but the way used here offers the global $n2f object as the first argument (this helps with default configuration) and the string ‘dynamic’ as the second argument to tell the n2f_template object that it is to use the dynamic template extension.  The n2f_template::setModule() and n2f_template::setFile() methods are fairly self-explanatory.  The n2f_template::render() method prepares the template for being displayed.  This is where the work is done to pull the <%header%> and <%footer%> aliases into the template.  The n2f_template::fetch() method does little more than return the string produced by the template, which we immediately echo to the browser.

When you load up your browser to the aboutme module (http://www.mysite.com/?nmod=aboutme), the template system will produce the following markup from your work:

<html>
<head>
<title>My Page</title>
</head>
<body>
This is the body of my page.
</body>
</html>

Summary
That’s it!  There are many more things you can do with the template engine, and we’re still working on building the proper documentation for you to get into the nitty-gritty of the system.  On top of that, we have at least one other template extension planned for release with Yverdon v0.2.  If you have any problems, feel free to drop by IRC or on our forums so we can give you a hand.  Part 3 of the series will be about using our MySQLi database extension, so be sure to stay tuned!

- Andrew

In Part 1 of this series I gave a brief overview of what little effort is needed to install N2F Yverdon, as well as a look at the basic layout of the system. In Part 2, we’re going to spend some quality time with Yverdon’s module system.

Why Modules?
A lot of people may be wondering why we chose to use a modular layout for our framework. The reason for our choice can be traced back to two of our goals. Firstly, building a module is easy (as you are about to find out), which falls directly in line with our simplicity goal for the framework. Secondly, modular systems are extremely flexible. Using a modular system we are even capable of turning the framework into an MVC architecture, or any number of others available.

A Typical Module
In Yverdon, a typical module always resides in the modules directory. When you first install Yverdon you should have 4 modules inside of the directory. The modules (error, main, resources and wheretostart) are there to give you examples of how to use the system, as well as provide a bit of structure for your default installation. Always trying to keep things simple, accessing a module from your browser is as simple as adding the module’s name onto the URL.

http://www.mysite.com/?nmod=<module_name>

Whatever is entered as <module_name> (without the brackets of course) will be checked by the system to see if it contains the base module structure, and if it does will be displayed by Yverdon.

The Base Module Structure
Every module must exist within the modules directory, and must have a file called page.php in order for Yverdon to accept that it is a valid module. What you put in the page.php file is up to you though, and in Part 3 we’ll get into using Yverdon’s built-in template system with your module.

A New Module
That’s it! The basics of the module system are very simple, just as we like things. Now it’s time to build our own module so we can keep moving forward with Yverdon. We will call our module ‘aboutme’, and for now we will just have it display a simple string. First, create the module’s directory:

/home/someuser/public_html/modules/aboutme

Then create the page.php file inside that directory:

/home/someuser/public_html/modules/aboutme/page.php

Almost done, now we just need to have it display a string which we can do by adding this line to our page.php file:

<?php echo('Hello world, I am HERE!'); ?>

Finally all that’s left is to save the page.php file, and visit our module through our site here:

http://www.mysite.com/?nmod=aboutme

You should be greeted with a message announcing yourself (or me) to the world.

Summary
Congratulations, you’ve made your first module with N2F Yverdon. In the second to last part, I’m going to introduce you to the template system and show how you can do some time-saving things with it in Yverdon.

- Andrew

Welcome to the first in my short series of introductory posts on using N2F Yverdon. I can’t say enough how happy I am with the first release of Yverdon, nor how thankful I am for all the work everyone is putting into the framework. Since I’m so elated, I thought I’d give everyone a little break and handle introducing the world to using N2F Yverdon. Without further adieu, let’s get started!

Installation
If you haven’t already, make sure you grab a copy of our framework from the downloads page. You’ll notice we have quite a few different formats available for you so that it’s easy to figure out the best one for your system. Once you have downloaded Yverdon, you’ll need to extract it to the folder where your web site will be located. Let’s say for this situation you’re using a *nix environment and the directory your website points to is /home/someuser/public_html/. Move the Yverdon files and folders over to the directory, and you’re finished! Almost too good to be true, but that’s what we’re working for here!

Structure
Now that you’ve installed the system, let’s take a quick look at the structure that we provide you with Yverdon. Going off of the same folder structure we spoke of before, your directories and files should look like this:

/home/someuser/public_html/modules
/home/someuser/public_html/resources
/home/someuser/public_html/system
/home/someuser/public_html/index.php
/home/someuser/public_html/credits.txt
/home/someuser/public_html/license.txt

Here on the core team, we call this the top-level view. The modules directory is where all of the current level’s modules reside. The resources directory is our way of gently nudging you towards organizing your images, stylesheets and javascript files. You are in no way required to use this structure, but it’s there if you’re willing to be so organized.

The system directory is organized into three sub-directories. The classes directory holds the class files for Yverdon’s core features. The extensions directory holds all extensions for the system. Extensions will be covered at a later time (not within this series unfortunately), but the basic idea behind them is that you use them to either modify the way our system works or to create reusable code for use in your installation. The includes directory holds several files that aid the core in providing functionality and localization.

The third directory, the modules directory, is where most of your work will take place with Yverdon. Modules are the method we’ve chosen for creating site content. I’ll be getting more into how they work in Part 2, but for now know that each immediate sub-directory in the modules directory is an actual module. Modules are accessed by the system through a variable on the end of the URL, and they have special files that do certain things for you (and your application).

Summary
That’s it! We try our darndest to keep the system simple and straightforward, while still maintaining a level of organization that is helpful for you the developer. In Part 2 we’ll be concentrating entirely on building a module for the system you’ve just installed. As you go through this 4 part series, I hope you will find yourself becoming comfortable with Yverdon and getting ready to build some great applications.

- Andrew