Hello world tutorial

Hello World Tutorial

In this tutorial, we will create a number of different Hello World pages. In each successive section, you will learn a new aspect of YAFF, such that, by the end of the tutorial, you should be familiar enough with YAFF to start building a simple web application.

Before we start, make sure that:

1. You have YAFF installed on a machine you can access via a browser, and is running (see Installing YAFF if you haven't already).
2. You know where the YAFF code is installed. Unless otherwise noted, all file and directory paths used in this tutorial are relative to the top YAFF-PHP directory.
3. You understand HTML, PHP5, and object oriented programming, at least at a basic level. If you can't already build a simple web app in PHP, this tutorial may not make much sense to you.

Tutorial 1: Hello Old World

YAFF tries to stay out of your way as much as possible. As such, it won't prevent you from using PHP the old fashioned way.

1. In yaff/htdocs/ create a new file named oldworld.php

2. Type (or copy&paste) in the following code into oldworld.php:

   <h1>Hello Old World</h1>
   <?php
   echo '<br>Also from PHP!';
   ?>
   

3. Access oldworld.php in your browser (e.g. access http://myserver.domain.tld/oldworld.php)

In your browser, you should see "Hello Old World" in big bold letters, with "Also from PHP!" underneath that. If that's not what you see, something went wrong. Most likely, you either copied and pasted wrong, or PHP isn't working at all on your server. Or aliens are messing with you.

Tutorial 2: Hello New World

In the previous section, we actually didn't use YAFF at all. The point was to show you that what you already know about PHP doesn't become irrelevant even with YAFF installed. If you want to go makin' a bajillion .php files like you used to, go ahead. But, if you installed YAFF, you're probably looking for something more...

In YAFF, code responsible for generating output is split up into Components. Components are a special kind of class, which contain only public static methods. YAFF's URL mapper works closely with Components, and in fact, you can think of Components like directories, and their methods like files within those directories. Perhaps this tutorial will make this point clearer.

1. In the yaff/components/ directory, make a new file named hello.component.php
2. Type (or copy&paste) in the following code into the new file:

           <?php
           
           class HelloComponent extends Component{
           
               public static function index($ctx){
                   return 'Hello New World';
               }
           
           }
   

   Note: Closing ?> tags are not necessarily, and it is recommended that they be omitted in include files
3. Access /hello/ in your browser (e.g. http://my.server.tld/hello/)

In your browser, you should see "Hello New World". What just happened?

When YAFF gets a request, like GET /hello/, it parses out hello, and looks for a file named hello.component.php inside the yaff/htdocs/components directory. YAFF then looks for a class named HelloComponent, which should be a subclass of Component. Since the "index page" of /hello/ was requested, YAFF calls the method named index(), and passes in one parameter, which is the Context object (which we'll get to later).

So, let's review how to make a new Component. To make a new Component named foo, you would:

1. Create a new file named foo.component.php inside the yaff/htdocs/components/ directory
2. In the file, define a new class named FooComponent which extends the Component class
3. In the class, define at least one new public static method, which should be named index and takes one parameter called $ctx (doesn't have to be, but that's the convention in YAFF).

Tutorial 3: Hello {$var}

The previous tutorial introduced Components, but the code was still pretty static. Since we're here to build dynamic websites, let's look into Templating. PHP allows us to seamlessly switch between PHP and HTML (or JS, or CSS, or text), and while this feature is convenient, it is often what leads to code that is difficult to read, debug, and reuse. In YAFF, it is strongly encouraged that HTML/CSS/JS be completely separated from PHP code. Your PHP files will only contain PHP, and your templates will contain no PHP code. This will make your code easier to read and modify, and will also make your HTML/CSS/JS easier to work with. Or, put it this way: if you separate your HTML from your code, even someone who doesn't know any PHP will be able to make minor changes to the static content. Next time someone tells you to make a minor change to some text somewhere, you'd be able to point them at the relevant template file, and let them go at it, safely knowing that they can't mess up any actual code.

To see YAFF-style Templating in action, do the following:

1. Create a new file named hello3.tpl.php in yaff/htdocs/templates/

2. In the new file, type in the following code:

        <?php return <<<HTML                                   
        
        <html>
        <body>                                                  
        Hello {$var}                                           
        </body>
        </html>                                     
        HTML;  
   

3. Open the yaff/components/hello.component.php file you created in Tutorial 2

4. Add the following method to the HelloComponent class, underneath the index() method:

        public static function templates($ctx){
            $vars = array('var'=>'Me!');
            return Utils::applyTemplate($vars, 'hello3');
        }
   

5. Save changes, and access /hello/templates

In your browser, you should see "Hello Me!"

What happened here? We first created a template file in the yaff/htdocs/templates/ directory. Template files are technically PHP files, but should only contain a single large PHP heredoc block, which contains HTML/CSS/JS/XML or other markup and variables, in the form {$variableName}. (Templates should not contain any other PHP code, other than that one heredoc, and plain old variables.) Then, we added the HelloComponent::templates() method (which maps to the URL /hello/templates), where we first created an array that maps the value 'Me!' to the template variable var. Then, when we called Utils::applyTemplates($vars, 'hello3'), YAFF opened the hello3 template file, and substituted the variable $var for the value 'Me!', and returned the results.