singular reference guide

8/3/2019 Singular Reference Guide

http://slidepdf.com/reader/full/singular-reference-guide 1/28

© 2011 UswebStyle, LLC

Singular Reference Guide



SingularCore

The Heart of Your Productby UswebStyle, LLC

SingularCore engine is a fine product powered by Zend

Framework that provides instruments to create complex

custom solutions where standard CMS's won't work or where

you need too much customization in popular engines.

SingularCore has full themes, localization support and it's

open source. Many tools will help any Zend or PHP Developer

build custom solutions quickly and without any time loss;start easily working with the system as it's documented;

publish and share tweaks and changes to the community.



All rights res erved. No parts of this work may be reproduced in any form or by any means - graphic, electronic, or

mechanical, including photocopying, recording, taping, or information s torage and retrieval systems - without thewritten permiss ion of the publisher.

Products that are referred to in this docum ent may be either trademarks and/or registered trademarks of the

respective owners. The publisher and the author make no claim to these trademarks.

While every precaution has been taken in the preparation of this document, the publisher and the author assume no

responsibility for errors or om iss ions, or for damages resulting from the use of information contained in this

document or from the use of programs and source code that may accompany it. In no event shall the publisher andthe author be liable for any loss of profit or any other comm ercial damage caused or alleged to have been caused

directly or indirectly by this document.

Printed: ентябрь 2011 in (whereever you are located)

Singular Reference Guide


Publisher Special thanks to:

All the people who contributed to this document, to mum and dad

and grandpa, to my sisters and brothers and mothers in law, to our

secretary Kathrin, to the graphic artist who created this great product

logo on the cover page (sorry, don't remember your name at the

moment but you did a great work), to the pizza service down the

street (your daily Capricciosas saved our lives), to the copy shop

where this document will be duplicated, and and and...

Managing Editor

Technical Editors

Cover Designer

Paul Yakubets

Paul Yakubets

Paul Yakubets

Alex Davidovich

UswebStyle

Production

Paul Yakubets

Team Coordinator

Stas Kuzma



Singular Reference Guide4


Table of Contents

Foreword 0

Part I Introduction 6

................................................................................................................................... 61 Useful resources

................................................................................................................................... 62 Installation

Part II Create Application 8

................................................................................................................................... 81 Directory structure

................................................................................................................................... 82 Module structure

................................................................................................................................... 113 Module name

................................................................................................................................... 124 Adding module controllers

Part III Settings 16

................................................................................................................................... 161 Overview

................................................................................................................................... 162 Getting settings

................................................................................................................................... 163 Changing settings

................................................................................................................................... 174 Deleting settings

................................................................................................................................... 175 Adding settings

Part IV Events & Handlers 19

................................................................................................................................... 211 Available events

Part V Authorization 24

................................................................................................................................... 241 Using Singular_Core('Auth')

................................................................................................................................... 242 Using system Auth controller

Index 26



Top Level Intro

This page is printed before a newtop-level chapter starts

Part

I





1 Introduction

SingularCORE is a fine product powered by Zend Framework that provides instruments to createcomplex custom solutions where standard CMS’s won’t work or where you need too much

customization in popular engines.

Singular has intuitive UI and it's open source. Many modules and tools will help any Zend or PHPDeveloper build custom solutions quickly and without any time loss; start easily working with the systemas it’s documented; publish and share tweaks and changes to the community.

Singular will be ideal for products development that would be the best instrument for small webdevelopment companies and freelancers to use as internal CMS or website builder.

Websites, web projects of any kind, easy integration into popular web services - this is only a short listof features Singular was developed for.

1.1 Useful resources

http://www.singularcore.com - Singular CORE official website.http://www.framework.zend.com - Zend framework official website.

1.2 Installation

Installation instructions will be here...

http://www.framework.zend.com/

http://www.singularcore.com/

http://framework.zend.com/



Top Level Intro


Part

II





2 Create Application

This chapter describes application and module directory structure. Also you can learn how to createyour own module step by step.

2.1 Directory structure

Application structure

Directory/file Description

configs Application configuration directory.The default configuration is placed in application/configs/ application.ini , and contains some basic directives for setting your PHP environment (for instance, turning error reporting on and off),indicating the path to your bootstrap class (as well as its classname), and the path to your action controllers.

layouts Contains common layouts like error.phtml for error handler.

localization For storage modules language translations.Example:

|_ en|_ contacts.php – translation for module "contacts"|_ news.php – translation for module "news"|_ system.php – translation for module "system"

|_ de|_ es|_ fr

modules Modules directory.

temp Temporary files directory.

Directory Description

cache Cache directory. Used for storing locallycached files.

logs Contains txt log files.

sessions Session save path directory.

templates Contains common templates.

Bootstrap.php Application bootstrap.

2.2 Module structure

Module structure

Each module should observe the convention of directories. Next informational table describes it.



Create Application 9



components Components directory contains module components that can beused directly in other modules. Usually needed for display cross-module information blocks, widgets, text information, forms (such as

login form) and so on. You can run components from any place inyour application: controllers, models, views, bootstraps, libraries if itneeded.While creating component simply extend your class withSingular_Component_Abstract . To execute component use followingcode example: Singular_Component::run('CompName', 'module',

$compOptions);

controllers Your application's action controllers contain your applicationworkflow, and do the work of mapping your requests to theappropriate models and views.


Abstract "Abstract" folder needed for storing abstractcontroller classes with basic actionsfunctional and serving for extending mainmodule controllers.

Example:Abstract controller module/controllers/ Abstract/Index.php:

abstract class

Test_Controller_Abstract_Index

extends Singular_Controller_Action

{

public function indexAction ()

{

// page title

$this->title('News adding');

// initialize form

$this->view->form = new

Test_Form_News();

$this->template('news');

}

}

Main controller module/controllers/

IndexController.php:

class Test_IndexController extends


{

}







If programmer needs to modify or redefinedefault abstract controllers functionality thefollowing actions is a good practice:

class Test_IndexController extends


{

public function indexAction ()

{

// page title

$this->title('Hot news

management');

// initialize form

$this->view->form = new

Test_Form_News();

$this->template('newsAdd');

}

}

Then if we update module to higher versionall of custom modifications will stayuntouched.

Never modify abstract controllers i f you are not developer of this

module. This m ay cause code

collisions and im poss ibility to make

correct module update. Redefine

normal controller actions ins tead.

forms Form classes that will be used to render html forms including variousfilters and validators in templates.

handlers Directory for storing event handlers. Classes must be an instance of Singular_Event_Listener_Abstract . See Events & Handlers chapter for information how to create and use event handlers.

helpers Directory for storing view helpers that will be used by current module.

models Store your models and mappers in the root of "models" folder.


DbTable Store your database table models here.Each model class must be an instance of







Singular_Db_Table_Abstract .

templates View scripts directory. The filename convention for auto-rendering isfollowing:moduleName_controllerName_actionName.phtml .You can also use arbitrary filename for your module templates, for example:dashboard.phtml. For manual template rendering use $this->template('dashboard')in controller. If you have specified templatefile extension $this->template('dashboard.phtml')this is also correctway.

lang.php Language keys file in php array format.

Module.php Module information file.

routes.ini Route definitions in ini format.Example: portfolio_category.type =

Zend_Controller_Router_Route_Regex

portfolio_category.route = "category(\d+)/portfolio(\d

{0,})\.html"

portfolio_category.defaults.module = portfolio

portfolio_category.defaults.controller = frontend

portfolio_category.defaults.action = index

portfolio_category.map.1 = category_id

portfolio_category.map.2 = page

portfolio_category.reverse = "category%s/portfolio%s.html"

2.3 Module name

Module name can consist with letters, digits, - and _ symbols, but not only with digits and -, _ symbols.

Correct module names:

· search· listings· look4ward· support24· 4x4wheels· jack_daniels· hot-tours

Bad module names:

· bob&joe store· ruby on rails· 100%respect· sport#major





· club$metro· 44400222· 1+3=4

For example we take "test " (without quotes) name for our module.

Add an empty directory with name "test " as your module name into application/modules directory.

2.4 Adding module controllers

Add "controllers" directory to the module as seen on "Image 2 ".

Image 2. Module controller directory

Let's create Index Controller as your main module controller that should handle some actions. See "Image 3".

Image 3. Creating Index controller

Firstly you need to create abstract controller application/modules/test/controllers/Abstract/Index.php asfollows:abstract class Test_Controller_Abstract_Index extends Singular_Controller_Action

{

/**

* Index action

*

* @return void

*/

public function indexAction()

{

// action code body will be here

}

}

Then create simple controller application/modules/test/controllers/IndexController.phpand extend it from





abstract controller Test_Controller_Abstract_Index . This controller can't be modified except this moduleauthors. Use simple controller instead.

URLs:

· http://your-site.com/test

· http://your-site.com/test/index· http://your-site.com/test/index/index

/**

* Index controller for test module

*

* @see Test_Controller_Abstract_Index

*/

class Test_IndexController extends Test_Controller_Abstract_Index

{

}

Prefix "Test_" in simple controller class name specifies in an accessory to the module " test ". This will

be an empty class that only inherits actions from Test_Controller_Abstract_Index . Developers can usethis controller to modify default actions from abstract controller.

SingularCORE provides to developers two controller types such as "frontend " and "admin". Examplecontroller above has public "frontend " controller type. Lets see how to create "admin" controller type.

To create admin controller you only need to specify " Admin" prefix in your controller name.Create abstract admin controller application/modules/test/controllers/Abstract/Admin.php:

abstract class Test_Controller_Abstract_Admin extends Singular_Controller_Action

{

/**

* Index action

*

* @return void

*/

public function indexAction()

{


}

}

After create simple controller application/modules/test/controllers/AdminController.php:

URLs:

·

http://your-site.com/test/admin· http://your-site.com/test/admin/index

/**

* Index controller for test module

*

* @see Test_Controller_Abstract_Admin

*/

class Test_AdminController extends Test_Controller_Abstract_Admin

{

http://your-site.com/test/admin/index

http://your-site.com/test/admin

http://your-site.com/test/index/index

http://your-site.com/test/index

http://your-site.com/test





}

Thats all! Now you have public "frontend " controller and "admin" controller.

If you need additional admin controller simply add "Admin" prefix to controller name application/modules/

test/controllers/Abstract/AdminCategories.php.

abstract class Test_Controller_Abstract_AdminCategories extends

Singular_Controller_Action

{

/**

* List action

*

* @return void

*/

public function listAction()

{


}}

And finally simple controller application/modules/test/controllers/AdminCategoriesController.php:

URLs:

· http://your-site.com/test/admin-categories· http://your-site.com/test/admin-categories/list

/**

* AdminCategories controller for test module

*

* @see Test_Controller_Abstract_AdminCategories

*/

class Test_AdminCategoriesController extends Test_Controller_Abstract_AdminCategories

{

}

http://your-site.com/test/admin-categories/list

http://your-site.com/test/admin-categories



Top Level Intro


Part

III





3 Settings

3.1 OverviewThis chapter describes how to work with settings.You can access to settings from any part of your project code via Singular_Core::_('Settings')component resource.

3.2 Getting settings

getSettings() — Get all raw settings

Singular_Core::_('Settings')->getSettings()->system->main->site_default_theme->value;This example demonstrates how to get all settings ordered by module name and section where:

· system - module name

· main - section name· site_default_theme - setting name

· value - setting value

getSetting($settingName) — Get setting by name

Singular_Core::_('Settings')->getSetting('site_default_theme');Gets single setting by name. This approach is modular independence.

getModuleSettings($moduleName) — Get settings by module name

Singular_Core::_('Settings')->getModuleSettings('system')->main->site_default_theme->value;Gets all settings by module name where:

· system - module name· main - section name

· site_default_theme - setting name


getAllSetting() — Get all key/val settings

Singular_Core::_('Settings')->getAllSettings();Returns all settings as Zend_Config object.

Singular_Core::_('settings')->getAllSettings()->toArray();

The same but as array.

3.3 Changing settings

changeSetting($settingName, $value) — Change setting value

Singular_Core::_('Settings')->changeSetting('site_default_theme', 'main');Change setting value by setting name.

http://framework.zend.com/manual/en/zend.config.html



Settings 17


3.4 Deleting settings

deleteSetting($settingName) — Delete setting

Singular_Core::_('Settings')->deleteSetting('test');

Delete setting by name.

deleteModuleSettings($moduleName, $sectionName - null) — Delete module settings

Singular_Core::_('Settings')->deleteModuleSettings('main', 'section_name');Delete all settings of particular module. Also could be used to delete settings by specific settings

section if $sectionName argument is specified.

3.5 Adding settings

addSettings($settings) — Add settings

$sData = array();

$sData[] = array(

'key' => 'test1',

'value' => 'test',

'title' => 'Title for setting',

'description' => 'Description',

'module' => 'test',

'section' => 'main'

);

$sData[] = array(

'key' => 'test2',

'value' => 'test',


'description' => 'Description','module' => 'test',

'section' => 'main'

);

$sData[] = array(

'key' => 'test3',

'value' => 'test',


'description' => 'Description',

'module' => 'test',

'section' => 'main'

);

// add settingsSingular_Core::_('Settings')->addSettings($sData);

Adds settings to the database as multidimensional array with is key/value logic. Where:· key - setting name


· title - setting title which can be seen for example on admin backend

· value - setting description which describes what logic this setting makes

· module - module accessory

· section - setting section (group)



Top Level Intro


Part

IV



Events & Handlers 19


4 Events & Handlers

There is smart way to create and execute events in SingularCore.All of handler files must be placed into particular module child folder "handlers" how this shown on the

image 1.

image 1

You may name handler files as you want. But it recommended to name handler files with functionalitysense keyword what this class do.

Skeleton class example in handler file:

class Home_Handler_Main extends Singular_Event_Listener_Abstract

{

public function bindListeners(Singular_Event_Dispatcher $dispatcher)

{

// your listeners

}

}

Handler class name is consists of <moduleName>_Handler_<handlerFileName>and must be extendingSingular_Event_Listener_Abstract class. Besides it class must contain public method bindListeners(Singular_Event_Dispatcher $dispatcher)with one argument "dispatcher" as an instance of Singular_Event_Dispatcher object.

Then create one or more arbitrary methods that are describes handlers and call this methods frombindListeners method via Singular_Event_Dispatcher->addListener($eventName, $handler = null).$handler attribute must be an array with two values: array($handlerObject, $method).

Handler class example:

class Test_Handler_Menu extends Singular_Event_Listener_Abstract

{


{





$dispatcher->addListener('adminMainMenu', array($this, 'onAdminMainMenu'));

$dispatcher->addListener('adminSubMenu', array($this, 'onAdminSubMenu'));

}

/**

* Adds pages to admin main menu*

* @param Singular_Wireframe_Frame_Admin_MainMenu $menu

* @return void

*/

public function onAdminMainMenu ($menu)

{

$menu->addPage(

array(

'id' => 'testmod',

'label' => 'Test module',

'icon' => $this->view->imageSrc('icons/test.png', 'test'),

'module' => 'test',

'controller' => 'admin','action' => 'index'

), 'custom');

}

/**

* @param Singular_Wireframe_Frame_Admin_SubMenu $menu

* @return void

*/

public function onAdminSubMenu ($menu)

{

$menu->addPage(

array(

'id' => 'modules_structure','label' => 'Modules structure',

'module' => 'system',

'controller' => 'structure'

), 'structure');

}

}

Full example with event dispatching:

class Home_Handler_Main extends Singular_Event_Listener_Abstract

{

private $test = array(0 => 'hello', 1 => 'world');


{

$dispatcher->addListener('beforeTest', array($this, 'onBeforeTest'));

$dispatcher->addListener('afterTest', array($this, 'onAfterTest'));

}

public function onBeforeTest ($data)

{

var_dump($data);



Events & Handlers 21


$data = $this->test;

}

public function onAfterTest ($data)

{

var_dump($data);}

}

// sample data

$test = array('hi', 'there');

// dispatch "beforeTest" event

Singular_Event::dispatch('beforeTest', $test);

// check for "beforeTest" is dispatched

if (Singular_Event::isDispatched('beforeTest')) {

echo "<br>Dispatched!<br>";

}

// dispatch "afterTest" event

Singular_Event::dispatch('afterTest', $test);

4.1 Available events

Event name Input parameter / description Usage area

routeStartup $request Zend_Controller_Request_Abstract

admin / frontend

routeShutdown $request Zend_Controller_Request_Abstract

admin / frontend

dispatchLoopStartup $request Zend_Controller_Request_Abstract

admin / frontend

preDispatch $request Zend_Controller_Request_Abstract

admin / frontend

postDispatch $request Zend_Controller_Request_Abstract

admin / frontend

postDispatchOnce $request Zend_Controller_Request_Abstract

Executes postDispatch event only once, nomatter how many times dispatcher processruns.

admin / frontend

dispatchLoopShutdown $request Zend_Controller_Request_Abstract

admin / frontend

taxonomyModuleUpdate $activeRecord Singular_Taxonomy_ActiveRecord

admin / frontend





Event name Input parameter / description Usage area

taxonomyRecordUpdate $activeRecord Singular_Taxonomy_ActiveRecord

admin / frontend

taxonomySectionUpdate $activeRecord Singular_Taxonomy_ActiveRecord admin / frontend

taxonomyModuleInsert $activeRecord Singular_Taxonomy_ActiveRecord

admin / frontend

taxonomyRecordInsert $activeRecord Singular_Taxonomy_ActiveRecord

admin / frontend

taxonomySectionInsert $activeRecord

Singular_Taxonomy_ActiveRecordadmin / frontend

componentRender $abstract Singular_Component_AbstractRuns before component render process

admin / frontend



Top Level Intro


Part

V





5 Authorization

Singular Core provides two optional ways of authorization depending on specific task:1. Sungular_Core('Auth')->....

2. Predefined auth controller from system module.

5.1 Using Singular_Core('Auth')

login($username, $password, $successRedirectURI = null);

$auth = Singular_Core::_('Auth');

if (!$this->login('username', 'password', '/success')) {

// handle auth error

}

If authorization is success it's simply redirect to url you have provided in $successRedirectURI.

authenticate($username, $password);

$auth = Singular_Core::_('Auth');

/** @var $result Zend_Auth_Result */

$result = $auth->authenticate('username', 'password');

// Process auth result

switch ($result->getCode()) {

case Zend_Auth_Result::FAILURE:

// handle failure

break;

case Zend_Auth_Result::FAILURE_CREDENTIAL_INVALID

// handle invalid credential

break;

...........

case Zend_Auth_Result::SUCCESS:

// success code

break;

}

5.2 Using system Auth controller

For using Auth controller from system module simply add "/login" action parameter to form.In other words system route "login" forwards to system module, auth controller, login action.

Authorization form example:<form action="/login" method="post">

<?php if (isset($this->errorMessage)): ?>

<div class="login-for-row">

<?=$this->errorMessage?>

</div>

<?php endif; ?>

<input type="hidden" name="login_type" value="1"/>



Authorization 25



Username: <input type="text" name="username"/>

</div>


Password: <input type="password" name="password"/>

</div> <div class="login-for-row">

<input type="submit" name="submit" value="Login"/>

</div>

</form>

Specify "username" and " password " field. Hidden field "login_type" is not required but if available informsthe controller to redirect if authorization is succeeds to appropriate area.1 (Singular_Core_System_Controller_Auth::LOGIN_TYPE_ADMIN) — "admin_dashboard " route

2 (Singular_Core_System_Controller_Auth::LOGIN_TYPE_USER) — "frontend_home" route

If wasn't set (default value) redirect to " frontend_home" route.





Index

- [ -[PICTURE clip0001.bmp] 19

- { -{

$this->template('newsAdd'); 8

$this->title('Hot news management'); 8

$this->view->form = new Test_Form_News(); 8

// initialize form 8

// page title 8{ 8

} 8

public function indexAction () 8

- } -} 8

- C -class Test_IndexController extendsTest_Controller_Abstract_Index 8



Endnotes 2... (after index)

27




Back Cover

singular reference guide

Documents