Scorpio comes bundled with a couple of controllers to help get you started. The CLI scorpio tool will also generate basic files if you ask it too. They are all integrated in the same manner: by adding an entry to a sites controllerMap.xml file, giving a path name and then setting the path attribute to point to the class in question e.g. to use the static controller you would add:
<controller name="static" description="Static Pages" path="mvcStaticController.class.php" />
The bundled controllers are:
Captcha controller is used to display a CAPTCHA image on a form or page that accepts user input to attempt to distinguish and block automated scripts that would otherwise possibly "spam" the form. The captcha is generated via GD and requires FreeType support. Captchas require the session system be loaded and initialised - if no session has been started the controller will throw an exception. Captchas are always generated as JPEG images.
With all built-in controllers the first step to using it is to add the appropriate config details to the sites controllerMap.xml and if setting image properties to the sites config.xml file. By default the captcha controller does not need any site config data.
Next: on your form simply add a link to the captcha controller with or without a .jpeg extension. For example: if the controller is setup on the route "captcha" then the image src path would be:
Note: that if you use ".jpg" and are using the standard Scorpio .htaccess file an actual .jpg image file will be searched for as .jpg files are not redirected to the main mvcDistributor.
When the image is requested it will set a session variable "captcha.code" that you can compare to the submitted value in your controller.
The following config variables are supported by this controller:
|captcha||width||integer width of the image in pixels (no units, default 120)|
|height||integer height of the image in pixels (no units, default 40)|
|length||number of characters in the captcha (default 6)|
The image controller provides a small framework for dynamically generating images e.g. tables, or thumbnails of products etc. It is designed to work with the Imagick extension but GD would work as well.
The image controller is more involved to setup than the other controllers as it requires models for generating the images. These models should be placed in a folder called "images" in the sites libraries folder. This folder will be created automatically if you use the scorpio CLI tool and create a structure with it.
The image model should implement the mvcImageProcessor interface. An abstract implementation (mvcImageModel) is provided as a base that can be extended by your image models. The interface defines the following methods that you should implement:
- render - to actually render the image
- isCached - checks if the requested image has been cached
- setOptions - sets the options for the model
- validateOptions - check that the model has all the required parameters
- getImageMimeType - returns the mime-type based on extension
- getImageLocation - returns the path of the image to be served
Of these methods, getImageLocation, getImageMimeType and setOptions are all implemented in the mvcImageModel.
When creating an image processor the idea is to translate a request identifier and to then manipulate an image by whatever means are necessary, caching the result for subsequent requests and then providing the final location in the getImageLocation method.
How the image is manipulated is entirely up to you however certain details are passed through to the model via the controller. These details are collected from the request URI string. The URI string has a very specific format that must be adhered to for the system to work.
The controller will dispatch the image request to the model during the request processing. The model is identified by the URI request string. The format for this request is:
The URI is interpreted in the following manner:
- /download/image - is the route to the mvcImageController as defined in the controllerMap.xml file,
- MODEL - is the name of the model to be used for rendering,
- PRIMARY IDENTIFIER - is how the image should be referenced,
- DIMENSIONS - are the width and height to apply (XXxYY),
- URINAME - is the friendly URI name (can be anything),
- EXTN - is the extension.
The model should be stored in a file named MODEL.class.php in the images folder. Dimensions should always be specified, however it is up to the model if they are honoured (use validateOptions to check sizes). The extension should be a proper image extension, however care should be taken as by default images are not sent via the mvcDistributor in the default .htaccess file. It is recommended that a path exception be made so that these dynamic images are served, but leaving all other normal images being directly served by the web server.
The static controller provides a simple static page system. Static pages are pages with extremely high cache times - effectively making them static. This basic implementation provides file based static pages, however you could extend or replace the system with a database supporting version.
The static controller is setup in the same manner as the other controllers.
Static page templates are loaded from a "static" folder in the sites views folder. The follow the usual template rules in that they can be inherited, use includes etc. The only difference is that the cache lifetime is set to static (24 hours).
There is a single configuration option for this controller: "cacheStaticPages" this is set in the "site" section of the config.xml file for the site in question. It is either 1/true/on or 0/false/off. This allows the caching to be disabled per site regardless of dev/production mode.
The xajax controller is covered in the AJAX Support article. Please note that this controller will be removed in a future release of Scorpio as xajax will be removed.