API >> intro

Note: all files referred to in this guide are to be opened with a text-editor such as Notepad or a development IDE such as Zend Studio, Eclipse or Dreamweaver

Prerequisite: understanding MVC

MVC stands for Model View Controller and is symbolic for an architecture that (respectively) separates your data model (SQL interface and database access), front-end display view (HTML, JavaScript, CSS, etc.) and the business logic that controls the flow of your application (application-specific PHP code.) This allows your designer to reskin your web site, your database administration to optimize SQL and your developer to add functionality without interfering with each other. Each typical web page that you visit is generated from a single view and has the logic powered by a single controller which gets the data that appears on the page from one or more models. MVC has matured to also include additional units:

• Layouts - a master view that wraps around the content of each regular view, commonly used to provide a general page layout, header and footer
• Elements - reusable chunks of display code that can be used within any number of views. A view can include any number of elements and elements can be used within any number of views
• Components - reusable chunks of business-logic code that can be used within any number of controllers. A controller can include any number of components and components can be used within any number of controllers. A component is essentially the same concept as an element, except for a controller instead of for a view.
• Helpers - tools available in your views, layouts and elements to simplify front-end development. Helpers in Vork include tools for form generation, automatically turning an array of URLs into a bulleted menu, embedding a YouTube video and more.

Prerequisite: understanding the URL structure

Everything that comes after http://www.YOURVORKSITE.com/ is parsed by Vork. For example, http://www.YOURVORKSITE.com/products/widget/small/green would have the products/widget/small/green interpreted by Vork. The first level, products, is called the controller and the second, widget, is the action. Anything after this, small and green, is considered "parameters" or "params" for short. So the format is: http://www.YOURVORKSITE.com/[controller]/[action]/[param1]/[param2]/[param3]/...

All the URL parts are optional and there is no limit to the number of parameters that you can have. If the controller or action is missing then Vork will default to using the "index" controller or action.

Create a view

The view is where your HTML display code goes, a view is required for every page (you can use the same view for multiple pages.)

Create a new file in the /mvc/views folder, in this example we will create a file called "products", type into the new file "Hello World"

Now, point your browser at http://www.YOURVORKSITE.com/products and you should see "Hello World" in the browser.

Use a helper

Helpers are tools to assist with the HTML output

Replace the contents of the products view with
<?php
echo $html->h2('Hello World');
And refresh your browser window; you should see the Hello World appear larger in size.

Create a set of related views

Create a new folder in the /mvc/views folder called products and create a file in the products folder called index and type in the new file "Listing of all my products"

Now, point your browser at http://www.YOURVORKSITE.com/products and you should see "Listing of all my products" in the browser

Add to the /mvc/views/products folder a file called widget and type in the new file "This my widget"

Now, point your browser at http://www.YOURVORKSITE.com/products/widget and you should see "This my widget" in the browser

Modify the layout

The layout is a wrapper for all your views, what you put in your layout appears on every page within your site (note: you can set certain pages to use different layouts.)

Open /mvc/layouts/default and on the line after echo $html->header($head); add:
echo $html->link('/products', 'All Products') . '<br />';
echo $html->link('/products/widget', 'Just the widget') . '<br />';

Refresh your browser and you will now see links at the top of every page.

Add a controller

Create a new file in the /mvc/controllers folder called products and type the following into it:
<?php
class productsController {
    public function index() {
        get::$title = 'All My Wonderful Products';
    }

    public function widget() {
        get::$title = 'Fantastic Widget';
    }
}

Refresh the page and you should see the page title in the browser's title bar. Note that the name of your view folder matches the name of the class plus the addition of the word "Controller" (productsController - case-sensitive) and that the index view is accessed in the index() action (aka. method or function) and the other view, widget, matches the name of the widget() action.

Add an element

An element is an HTML snippet that is to be used in more than one view

Create a new file in the /mvc/elements folder called "cart", type into the new file:
<?php
echo $html->div('You have no items in your shopping cart');

Next open both view files in /mvc/views/products and add this PHP code to each: load::element('cart');

Refresh the page and you will now see the cart message at the bottom of each page in the products section.

Add a model

Models are where you access your database. This example should work for most databases as it uses the almost-universal method to retrieve data in PHP, query() and then a loop through fetch_assoc() and ANSI-standard SQL (that is universal, but not optimized or ideal for production use.) Start by adding a table and some rows to your database:
create table widgets (itemid char(4) not null, name char(20) not null, description char(80) not null);
insert into widgets (itemid, name, description) values ('hdcb', 'Hard Triangle', 'Pyramid built in 14th century BC');
insert into widgets (itemid, name, description) values ('fzsq', 'Fuzzy Sqaure', 'Dice hanging from the mirror');
insert into widgets (itemid, name, description) values ('clcy', 'Clear Cylinder', '2-foot glass tube');

Create a new file in the /mvc/models folder called products, type into the new file:
<?php
class productsModel {
    public function getWidgets() {
        $sql = 'select itemid, name from widgets';
        $res = $this->db->query($sql);
        while ($row = $res->fetch_assoc()) {
            $widgets[$row['itemid']] = $row['name'];
        }
        return $widgets;
    }
}

Now get your widgets from your model into your controller and passed along into the view. Add to the index() action of your products controller
$return['widgets'] = get::model()->getWidgets();
return $return;

This makes the entire action look like:
public function index() {
    get::$title = 'All My Wonderful Products';
    $return['widgets'] = get::model()->getWidgets();
    return $return;
}

Whatever array keys that your controller action returns automatically become variables that you can access in your view, layout and elements.

Add to your /mvc/views/products/index file:
foreach ($widgets as $itemid => $name) {
    echo $html->div($html->link("/products/widget/$itemid", $name));
}

Refresh the http://www.YOURVORKSITE.com/products page and you will now see the 3 products displayed as links.
More advanced use of a model

Click one of the links created in the previous step that adds a parameter to the end of the URL. Now add a new method to the products model called getWidget() (notice the singular and plural in the naming convention) that takes an $itemid argument:
public function getWidget($itemid) {
    $sql = 'select name, description from widgets where itemid=?';
    $res = $this->db->pquery($sql, $itemid);
    return $res->fetch_assoc();
}

Note we are now using pquery(), not query(), this will substitute the question-mark in the statement with the $itemid value after removing any potentially insecure content (for more details Google for "SQL injection") and adding quotes around it.

Now add to the widget() action in the products controller:
if (isset(mvc::$params[0])) {
    $return['widget'] = get::model()->getWidget(mvc::$params[0]);
}

This sends the first param, 0, (counting starts at zero) as an argument to the getWidget() method of the products model.

Next, replace the content of your /mvc/views/products/widget file with:
<?php
if (isset($widget)) {
    echo $html->h1($widget['name']) . $html->p($widget['description']);
} else {
    echo <div class="errormessage">You did not select a widget!</div>;
}

Note that the errormessage CSS class is one of the predefined CSS classes in /webroot/css/main.css which is the CSS file loaded at the top of the default layout

That is the basics and sufficient to create a simple web site, check the Quick-Reference to continue learning about Vork

Full SQL control in a model

The cleanString() function adds quotes around strings and removes any potentially insecure content (for more details Google for "SQL injection"). To gain full control over your SQL without introducing vulnerabilities you wrap all SQL variables in cleanString()
public function getWidget($itemid) {
    $sql = 'select name, description from widgets where itemid=' . $this->db->cleanString($itemid);
    $res = $this->db->query($sql);
    return $res->fetch_assoc();
}

Alternatively, cleanString() can take an array of strings and clean them all at once:
public function getWidget(array $items) {
    $items = $this->db->cleanString($items);
    $sql = 'select name, description from widgets where itemid in (' . implode(', ', $items) . ')';
    $res = $this->db->query($sql);
    return $res->fetch_assoc();
}