API >> reference

Loading Objects

When you load an object, you execute its functionality and any output is sent to the browser screen (STDOUT).

load::element($elementName, $params = array())
This loads an element and echos its output. Keys in the $params array are converted to local variables within the element, in the same manner as those returned from the controller-action. Intended for use within views, layouts and other elements.

load::redirect($url)
This will redirect the browser to the site at $url. Using this is more efficient than sending a "Location" header as this halts processing of the view; you are also not required to have a view file associated with an action that always redirects (since it would never display.)

load::js($args)
Loads JavaScript library; any output goes directly to stdout (echos to the screen) Simplified-access wrapper to htmlHelper::jsLoad()

Getting Objects

When you get an object you execute its functionality and any output is returned in the response.

get::element($elementName, $params = array())
This loads an element and returns its output. Keys in the $params array are converted to local variables within the element, in the same manner as those returned from the controller-action. Intended for use within views, layouts and other elements (but will work in any MVC object.) Use of the email elements (in the /mvc/elements/emails folder) requires using this method from within a controller or component.

get::helper($helperName)
Returns a helper as an object. Intended for use within views, elements, layouts and other helpers (but will work in any MVC object.)

get::component($componentName = null)
Returns a component as an object, if name is blank then it will use the component with the same name as the controller. Intended for use within controllers and other components (but will work in any MVC object.)

get::model($modelName = null)
Returns a model as an object, if name is blank then it will use the model with the same name as the controller. Intended for use within controllers and other models (but will work in any MVC object.)

get::htmlentities($string, $quoteStyle = ENT_COMPAT, $charset = 'UTF-8', $doubleEncode = false)
Operates exactly like the php function htmlentities() but changes the default charset to UTF-8 and the default value for the fourth parameter $doubleEncode to false to be more resilient to coding oversights.

get::xhtmlentities($string, $quoteStyle = ENT_NOQUOTES, $charset = 'UTF-8', $doubleEncode = false)
Operates like get::htmlentities() converting special characters in a string to XHTML-valid ASCII but this method allows the use of HTML tags within your string.

get::$config
This is a container of objects that are user-defined in the .config - presets include:

get::$config->DS
Folder directory separator, either or /

get::$config->SITE_NAME
Convenience constant containing the name of your site

get::$config->SITE_DOMAIN
Convenience constant containing the domain name of your site (eg. yoursite.com)

get::$config->APP_CONSTRUCT
Setting to a filename will execute the file before every page load. File must be in the root of the /mvc directory and contain a class with the same name as the file. To have an action occur upon load use the __construct() method eg. in a file called appController you might have:
<?php
class appController {
    public function __construct() {
        if (strtolower(mvc::$controller) == 'colour') {
            mvc::$controller = 'color';
        }
    }
}

get::$config->APP_DESTRUCT
Same as APP_CONSTRUCT but executes at the end of the page load.

get::$config->isSuperuser()
This is a convenience function (returns Boolean,) you define what constitutes a superuser in the .config file.

get::$config->anythingThatYouWishToDefine
You can define your own constants, variables or methods that would be globally available to any part of your Vork application. Instructions are at the end of the config class within the .config file.

Helpers

The HTML and form helpers are loaded by default and available to the layout as well as every view and element, for the list of available methods in each refer to the HTML helper API and the form helper API.

To create a new helper, create a new file in the /mvc/helpers folder, the name of the file will be the name of your helper. In that file create a new class using the name of your helper plus "Helper" appended to it - eg. in a file named "color" you would have: class colorHelper {}

Next, "get" the helper object from your view, element or layout (you can also get it from the controller or component and then return it to the view) via:
$color = get::helper('color');

Any public methods can be directly access eg.: echo $color->getMyFavorite();

Views

The view file that gets used when an action is set (not the index action) is the first file that exists from this list:

1. /mvc/views/[controller]/[action]
2. /mvc/views/[action]

For the index action it is:

1. /mvc/views/[controller]/index
2. /mvc/views/[controller]

The view can be explicitly defined in the controller via: mvc::$view = 'someOtherView';

In this case the view name is treated like an action and would look for:

1. /mvc/views/[controller]/someOtherView
2. /mvc/views/someOtherView

You can also define the path explicitly (within the /mvc/views folder) via: mvc::$view = 'someFolder' . get::$config->DS . 'someFile';

Elements

These are reusable portions of a view that can be accessed from any view, layout or other element via load::view($viewName) or get::view($viewName) . The special elements in the /mvc/elements/emails folder are only meant to be accessed from a controller via get::view('emails/' . $viewName)

Layouts

Layouts wrap display code around each view and make it easy to reskin your web site at any time (or to have multiple "skins"). For sites with a consistent design theme it is recommended to use only one layout for all normal web viewing (as opposed to mobile or RSS.) Layouts contain a special $view variable that contains the entire contents of the parsed view (along with any elements that make up the view.) You must echo this out for your view to display. The view is the ideal place to echo out the $html->header() and footer() helper functions. The default view supplied with Vork will automatically look for a variable called get::$title and use that for the document title, if the variable was not set then it will default to get::$config->SITE_NAME . Also, if the variable $alert exists then just before outputting the view content it will output the $alert contents wrapped in the errormessage CSS class.

Controllers

A controller is actually optional (the view can load in absence of a controller as long as the default naming convention is maintained,) but in most cases it is necessary.

Controller class names must be the controller file name with "Controller" appended (case-sensitive) eg. in the /mvc/controllers/colors file you would define:
class colorsController {}

Public methods (functions) defined within a controller class become actions, if no action is defined in the URL then the default index() action is used. It is recommended (but not required) that all controllers have an index() method defined.

In some cases it may be desirable to not have to define every action explicitly, but use some dynamic logic instead. You can do this by setting the special optionalAction constant in your controller class to true. Eg.:
class colorsController {
    const optionalAction = true;
    public function index() {...}
}

Enabling optionalAction will route all requests that do not have an action defined for them to the index() action and the mvc::$params will begin with the URL parameter immediately following the controller eg. for http://www.MySite.com/clothing/shirts/xl you would have mvc::$params[0] = 'shirts'; and mvc::$params[1] = 'xl';

There are two special controllers that come with Vork and may be modified as needed but not removed, the index controller, without this the root of your web site will not work; also the account component expects it there. The get::$config->errorHandler controller (points to the "errors" view by default) is used to catch 404 not found pages, MVC system errors and can be used to handle any other error as well.

Models

These are classes to access the database are accessed via $yourModelObject = get::model($modelName);

For models with the same name as the controller you can use the shorthand: $yourModelObject = get::model();

Model class names must be the model file name with "Model" appended (case-sensitive) eg. in the /mvc/models/colors file you would define: class colorsModel {}

Methods in the model are accessed like in any other PHP object eg.: $yourModelObject->getMyFavorite();

Components

These are classes containing reusable parts of controllers and are accessed via $yourComponentObject = get::component($componentName);

For components with the same name as the controller you can use the shorthand: $yourComponentObject = get::component();

Component class names must be the component file name with "Component" appended (case-sensitive) eg. in the /mvc/components/colors file you would define: class colorsComponent {}

Methods in the component are accessed like in any other PHP object eg.: $yourComponentObject->getMyFavorite();

There are a number of predefined components, refer to the API for instructions with each.

The MVC Object

MVC contains directives to control MVC behavior and routing.

mvc::$controller
Changing this will load a different controller AFTER the current controller completes, BEFORE the previous-controller's view is loaded. You can return; from the action after setting this to skip any remaining code in the current controller and change controllers immediately. This property should be used to make scripts more portable, eg. in your views: $html->link('/' . mvc::$controller, 'Main page')

mvc::$action
Changing this will load a different action in the current controller AFTER the current action completes, BEFORE the previous-action's view is loaded. You can return; from the action after setting this to skip any remaining code in the current action and change actions immediately. Used in tandem with MVC::$controller you can change controllers and go to a specific action. This property should be used to make scripts more portable, eg. in your views: $html->link('/' . mvc::$controller  .'/' . mvc::$action, 'Clear form data')

mvc::$view
Changes the view that is to be displayed. Intended for use in controllers and components only; is not adjustable from within a view, layout or element.

mvc::$layout
Changes the layout that is to be displayed. Intended for use in controllers and components only; is not adjustable from within a view, layout or element.

mvc::$params
An array set when the URL depth exceeds controller and action eg.: http://www.YourSite.com/controller/action/param1/param2/etc Parameters are indexed in a zero-based array, so the URL http://www.YourSite.com/clothing/shirts/longsleeve/xl would create: mvc::$params[0] = 'longsleeve'; and mvc::$params[1] = 'xl'; if no params are present in the URL then mvc::$params does not get set.

is::class Static Methods

These Methods return Boolean values.

is::mobile()
Identifies a mobile user

is::ssl()
If instance is requested via HTTPS

is::bot()
Identifies a spider/bot/crawler

is::ajax()
If instance is requested via AJAX

is::flash()
If instance is requested from Flash

is::superuser()
Wrapper for get::$config->isSuperuser() to unify syntax

Cache

The cache object contains an instance of your PHP caching object, like Memcache. Users of PHP 5.3+ can access all the built-in caching methods via static calls, PHP 5.2.x and earlier only have access to the following Memcache methods:

• cache::get()
• cache::set()
• cache::delete()
• cache::flush()

To access the remaining methods in PHP pre-5.3 you need to first retrieve the caching object and then call the method from it:
$cache = new cache;
$cache->increment(...)
cache::method($id, $method, array $args = array(), $flag = null, $expires = null)

Attempts to retrieve from cache the data ordinarily returned from the method, if not found in cache then the method will be executed and the response will be saved to cache and then returned. This method is especially useful for caching model data as you only change method syntax, not function.

The $method argument can accept either a function name or a class method sent in standard PHP-argument sytax: array($classObject, 'methodName')

To cache the following method:
$book = $this->model('books')->getBookByIsbn(1847194141);
You would type:
$book = cache::method('someUniqueId', array($this->model('books'), 'getBookByIsbn'), array(1847194141));

The first time this loads it will get the book from the getBookByIsbn() method of the books model, subsequent instances will retrieve the book from cache and skip loading the model altogether.

Debug

To enable the debug functionality open the /webroot/vork file and change the DEBUG_MODE constant at the top to true. If you are using Mozilla Firefox and have the FirePHP extension enabled (requires the FireBug extension to work) then your debug messages will appear in the FireBug console, otherwise they will be echoed out at the bottom of the page. Do NOT leave DEBUG_MODE enabled on a production server!

Debug will show you the page execution time, SQL that was executed along with SQL execution time and SQL error messages if there are any.

Packages

Packages are external products integrated into Vork. You will need to implement each package according to the documentation in that package. The path to the packages folder can be accessed via get::$config->packagesPath()