Aspen Framework

From Aspen Documentation

Items documented on this page are currently in development. Features or methods documented here are most likely incomplete and may change prior to official release. Please consider these features experimental.

Over the past six months we've been hard at work preparing some necessary changes, excellent enhancements, and bug fixes to Aspen Framework.

The main goals of Aspen 1.1 "Mercury" have primarily focused on the database interaction classes. The largest change is the migration of the single-instance Model class to the new multiple-instance, single-point-validation model system.

You may now also extend the model class for any tables and those libraries will be loaded any time someone interacts with that table. Typical methods within the custom classes are common data validation libraries, pre and post query functions, etc.

There's been a fair amount of minor bug fixes, internal reworking, cleanup, and some foundational preparations for 1.2 work.

View all bugs resolved against this target milestone.

New Features & Functions

cache->noCache
Sends headers to prevent browse cache of current page

router->redirectToUrl
Redirects to any url and allows for HTTP status codes. It will return the proper header for the given status code.

user->allowAnonymous
Anonymous users now controlled via null user/groups in permissions table.

Debug
New class to assist with debugging. Extra features wrapped around print_r, var_dump, as well as an easy-to-read stack trace.

$config['usergroup_default_modules']
Specify an array of user groups and their default modules. May override system-set default module.

VERSION_COMPLETE
Full version/build/framework revision string in new constant.

Model

whereLikeSearch
Adds an array of fields to search for a value using the LIKE query.

count
Adds a COUNT selection to the query.

before_insert
Model extension function that allows you to interact with the fields before they're inserted (pre-validation).

after_insert
Model extension function that allows you to receive the new record id after the insert has completed. Also called if insert fails.

before_update
Model extension function that allows you to interact with the fields before they're updated (pre-validation).

after_update
Model extension function that allows you to receive the boolean update result as well as original record ID after the insert has completed. Also called if update fails.

parenthStart
All queries added between this and parenthEnd will be enclosed within parenthesis.

parenthEnd
All queries added between this and parenthStart will be enclosed within parenthesis.

enumExists
Checks that a value is an acceptable ENUM value for a field.

setDefaultIfEmpty
Allows you set default values if any fields in an insert/update query are empty.

inSchema
Checks if a field exists within the current table schema.

select_single
Prepares the model class to only return a single record for the current query.

addError
Adds a validation error to an array.

getErrors
Returns any validation errors.

error
Boolean if a validation error was triggered or not.

whereFuture
Where condition for date in the future.

wherePast
Where condition for date in the past

selectSubquery_begin and selectSubquery_end
Model class now has basic support for building subqueries. By using a second instance of the model class.

Template

truncateString
Truncates a string to a specific number of characters.

addCss
Adds a CSS file for inclusion. Pages may use this as a shortcut rather than creating a specific header template for each module/method.

addJs
Adds a javascript file for inclusion. Pages may use this as a shortcut rather than creating a specific header template for each module/method.

htmlHide
Print a value within the html comment markup.

na
Prints a substitute value if the existing value is empty. "N/A" is the default.

encodeTextEntities
Encodes characters you normally find within text into entities. Like &.

paginateLinks
Generates an unordered list of pagination links based on model pagination functions.

truncateFilename
Truncates a filename to a specific number of characters, but maintains the file extension.

IS_EDIT_PAGE
Template class sets this to a boolean if the current template appears to be editing an existing record. False if it's adding a new record. This assists with using the same form template for both add/edit functionality.

ADD_OR_EDIT
Template class sets this to 'add' or 'edit' string depending on the boolean above. Useful for including templates or changing the current language keyword being used. This assists with using the same form template for both add/edit functionality.

Renamed / Aliased Functions

form->loadTable and form->loadRecord have been merged into a new function called load.

model->getLastQuery has an alias called model->lq

sml->addNewMessage has an alias called sml->say.

Deprecated / Removed Functions

model->executeInsert was removed. Use model->insert instead.

model->executeUpdate was removed. Use model->update instead.

model->generateInsert was removed. Use model->insert instead.

model->generateUpdate was removed. Use model->update instead.

APP->generateAdminMenu was removed. Use APP->generateInterfaceMenu instead.

form->is___
All form class validation functions have been removed in favor of the model-based validation that can be done with the help of the Peregrine library.

Feature Changes

Function Changes

sml->say
No longer accept a "hide" toggle, but rather a css string for use in displaying difference styles. notice, success, error are default to blueprint. Can also be bool: true = success, false = error

settings->getConfig and settings->setConfig
Both now accept a user_id, allowing you to set custom configs on a per-user basis in the same config table.

model->where and model->whereNot
Both accept a fourth argument $val_is_column_name which does not print double quotes in the query, allowing reference to a mysql column.

router->redirect
Now accepts a third argument for the interface.

model->open
Accepts second argument of primary key id. If table provided, it will simply return the single record.

router->loadModuleLanguage
Function is now public, allows for dynamic loading of language files from any module (within the current interace).

form->getErrors and form->printErrors
Now accepts an array that allows you to sort the error message in any way you want. Default is by order in schema (if available), or by order set using addField/s.

Other Changes

Improved pagination support
Improvded xml class can now handle multidimensional arrays
Database table structure converted to InnoDB for foreign key support
Errors class logs new VERSION_COMPLETE constant
Upgraded Thumbnail (3.0) class
Upgraded HTMLPurifer (3.0) class

Model Class Changes

Previously, a new query using the model class was done by using single instance:

$this->APP->model->function();

Because that method was re-using the same instance, there wasn't enough separation of queries and too many problems arose. The model class is now used with a new instance for every query or set of related queries being run. This avoids previous confusions and also allows you to build multiple queries at once.

Now, a query may be run:

$table = $this->APP->model->open('table');
$table->insert( array('field'=>'value' );

The structure of the model class has changed in such a way that modules can now extend the class and provide core validation rules, that will prevent invalid queries from being run against the database at the core level.

Module Base Class

A new system class called "Module" may now server as the base class for any application modules. This base class contains the constructor that assigns an instance of the original app to the $this->APP member variable, so that you no longer need this code in every module. Currently, this is all that the class does, so it's mostly for shortcut purposes.

You may replace the following in your module:

class Myclass_Admin {
 
	/**
	 * @var object $APP Holds our original application
	 * @access private
	 */
	protected $APP;
 
 
	/**
	 * @abstract Constructor, initializes the module
	 * @return Index_Admin
	 * @access public
	 */
	public function __construct(){ $this->APP = get_instance(); }
 
}

With:

class Myclass_Admin extends Module {
 
  ...
 
}

If you need to override the constructor in your module, make sure to call the parent::__construct() function properly.