© 2015 X2Engine Inc.

Difference between revisions of "Introduction To Development"

From X2Engine
Jump to: navigation, search
(Using Classes)
 
(34 intermediate revisions by 3 users not shown)
Line 2: Line 2:
  
 
= Dependencies =
 
= Dependencies =
X2EngineCRM is built using the following frameworks; see their respective documentation for information about their use.
+
X2CRM is built using the following frameworks. Hence, the majority of necessary knowledge for development in X2Engine can be found in their respective documentation.
  
== [http://www.yiiframework.com/doc/guide/ Yii Framework] ==
+
== [http://www.yiiframework.com/ Yii Framework] ==
Yii Framework is a PHP framework based on the time-tested [http://www.yiiframework.com/doc/guide/1.1/en/basics.mvc MVC] (Model-View-Controller) design methodology, which is of particular importance in understanding how requests translate to the execution of class methods.
+
Yii Framework is a PHP framework based on the time-tested [[yiiguide:basics.mvc|MVC]] (Model-View-Controller) design pattern, which is of particular importance in understanding how requests translate to the execution of class methods.  
  
== [http://docs.jquery.com/Main_Page jQuery] and [http://jqueryui.com/demos/ jQuery UI] ==
+
See:
Most of the Javascript in the codebase, including Yii Framework itself, depends on jQuery in some way or another. Thus, for front-end design (especially design that involves asynchronous content loading via [http://en.wikipedia.org/wiki/Ajax_(programming) AJAX]) it is essential to understand the usage of this library. In many cases, Yii Framework provides certain utilities for constructing HTML elements and jQuery-based scripts, and it is thus also important to first search for effort-saving devices available in Yii Framework before writing something from scratch. In particular, [http://www.yiiframework.com/doc/api/1.1/CHtml CHtml] contains methods such as [http://www.yiiframework.com/doc/api/1.1/CHtml#ajaxButton-detail ajaxButton], and the subclasses of [http://www.yiiframework.com/doc/api/1.1/CJuiWidget CJuiWidget] can be used to easily construct most common jQuery UI elements and seamlessly integrate them with Yii as input fields.
+
* [[yiiguide:|The Definitive Guide to Yii]]
 +
* [[yii:|The Yii Framework class reference]]
 +
* [http://www.yiiframework.com/wiki/ The Yii Framework Wiki]
  
= How a Request To The Web Application Translates To Code Executing =
+
== [http://jquery.com/ jQuery] and [http://jqueryui.com/ jQuery UI] ==
 +
Most of the Javascript in the codebase, including Yii Framework itself, depends on jQuery in some way or another. Thus, for front-end design (especially design that involves asynchronous content loading via [[wikipedia:AJAX|AJAX]]) it is essential to understand the usage of this library. In many cases, Yii Framework provides certain utilities for constructing HTML elements and jQuery-based scripts, and it is thus also important to first search for effort-saving devices available in Yii Framework before writing something from scratch. In particular, [[yii:CHtml|CHtml]] contains methods such as [[yii:CHtml#ajaxButton-detail|ajaxButton]], and the subclasses of [[yii:CJuiWidget|CJuiWidget]] can be used to easily construct most common jQuery UI elements and seamlessly integrate them with Yii as input fields.
  
== MVC In a Nutshell ==
+
See:
Relevant pages: [http://www.yiiframework.com/doc/guide/1.1/en/basics.controller Controller], [http://www.yiiframework.com/doc/guide/1.1/en/basics.model Model] and [http://www.yiiframework.com/doc/guide/1.1/en/basics.view View] in [http://www.yiiframework.com/doc/guide/ The Definitive Guide to Yii]
+
* [http://docs.jquery.com/Main_Page jQuery Documentation]
 +
* [http://jqueryui.com/demos/ jQuery UI Demos and Documentation]
  
A request to the server translates to the instantiation of a controller class. Which controller is instantiated depends upon the [http://www.yiiframework.com/doc/guide/1.1/en/basics.controller#route route], which contains the first part of the controller class's name with the first letter in lowercase. Then, the method of the class whose name begins with "action" is run based on the [http://www.yiiframework.com/doc/guide/1.1/en/basics.controller#action action ID] of the request URL. As the action runs, it will retrieve data from the database using a model class. Actions which respond with content will then typically make a call to [http://www.yiiframework.com/doc/api/1.1/CController#render-detail render] or [http://www.yiiframework.com/doc/api/1.1/CController#renderPartial-detail renderPartial], methods inherited from the [http://www.yiiframework.com/doc/api/1.1/CController#renderPartial-detail CController] class. The [http://www.yiiframework.com/doc/guide/1.1/en/basics.view view file], specified by the first argument to that method, will then be used to display the content (contained in the model) that is then passed back to the client.
+
= MVC In a Nutshell =
 +
== How a Request To The Web Application Translates To Execution ==
 +
Relevant pages: [[yiiguide:basics.controller|Controller]], [[yiiguide:basics.model|Model]], [[yiiguide:basics.view|View]] and [[yiiguide:basics.convention|Fundamentals: Conventions]] in [[yiiguide:|The Definitive Guide to Yii]]
 +
 
 +
A request to the server translates to the instantiation of a controller class. Which controller is instantiated depends upon the [http://www.yiiframework.com/doc/guide/1.1/en/basics.controller#route route], which contains the first part of the controller class's name with the first letter in lowercase. Then, the method of the class whose name begins with "action" is run based on the [http://www.yiiframework.com/doc/guide/1.1/en/basics.controller#action action ID] of the request URL. As the action runs, it will retrieve data from the database using a model class. Actions which respond with content will then typically make a call to [[yii:CController#render-detail|render]] or [[yii:CController#renderPartial-detail|renderPartial]], methods inherited from the [[yii:CController|CController]] class. The [[yiiguide:basics.view|view]] file, specified by the first argument to <tt>render</tt> or <tt>renderPartial</tt>, will then be used to display the content (contained in the model) which is then passed back to the client as markup (or json, text, etc.)
  
 
== File Structure ==
 
== File Structure ==
 +
Relevant documentation: [[yiiguide:basics.convention#directory|Fundamentals: Conventions (&sect;5: Directory)]]
 +
 
Modifying the codebase requires an understanding of where the relevant files are located. All PHP files used in the web application, which don't belong to the framework, are under the <tt>protected/</tt> directory. This directory is not accessible from the web per the access rules defined in the .htaccess file; rather, these files are executed by the framework as the application runs. Within <tt>protected</tt> are the following directories:
 
Modifying the codebase requires an understanding of where the relevant files are located. All PHP files used in the web application, which don't belong to the framework, are under the <tt>protected/</tt> directory. This directory is not accessible from the web per the access rules defined in the .htaccess file; rather, these files are executed by the framework as the application runs. Within <tt>protected</tt> are the following directories:
 
;<tt>components/</tt>
 
;<tt>components/</tt>
: Miscellaneous classes used throughout the application, especially those which are extended by other classes.
+
: Miscellaneous classes used throughout the application, especially those which are extended by other classes. Contains its own <tt>views</tt> folder, which is used for storing templates for [[Widgets]].
 
;<tt>config/</tt>
 
;<tt>config/</tt>
 
: Core configuration files for the web application.
 
: Core configuration files for the web application.
Line 26: Line 36:
 
: Base-level controller classes.
 
: Base-level controller classes.
 
;<tt>data/</tt>
 
;<tt>data/</tt>
: (Currently unused) Miscellaneous data files, i.e. SQL scripts
+
: Miscellaneous data files. Currently used to store SQL scripts that are run during installation.
 
;<tt>extensions/</tt>  
 
;<tt>extensions/</tt>  
 
: The designated folder for storing third-party classes.
 
: The designated folder for storing third-party classes.
 
;<tt>messages/</tt>
 
;<tt>messages/</tt>
: Files containing translations of messages within the application (used by [http://www.yiiframework.com/doc/api/1.1/YiiBase#t-detail Yii::t])
+
: Files containing translations of messages within the application (used by [[yii:YiiBase#t-detail|Yii::t]])
 
;<tt>models/</tt>
 
;<tt>models/</tt>
 
: All core/base level model classes.
 
: All core/base level model classes.
 
;<tt>modules/</tt>
 
;<tt>modules/</tt>
: Self-contained modules. Most of the subdirectories here contain modules whose names appear in the main menu. Each subdirectory typically has the same structure as the base application; they each will have directories named <tt>controllers</tt>, <tt>models</tt> and <tt>views</tt>. See [http://www.yiiframework.com/doc/guide/1.1/en/basics.module Fundamentals:Module] in the definitive guide to Yii for more information.
+
: Self-contained modules. Most of the subdirectories here contain modules whose names appear in the main menu. Each subdirectory typically has the same structure as the base application; they each will have directories named <tt>controllers</tt>, <tt>models</tt> and <tt>views</tt>. See [[yiiguide:basics.module|Fundamentals:Module]] in [[yiiguide:|The Definitive Guide to Yii]] for more information.
 
;<tt>runtime/</tt>
 
;<tt>runtime/</tt>
 
: (For the application's use) Temporary files written to by the application
 
: (For the application's use) Temporary files written to by the application
Line 42: Line 52:
 
: View files corresponding to base-level controllers.
 
: View files corresponding to base-level controllers.
  
== URL Rules ==
+
= Using Classes =
 +
Relevant page: [[yiiguide:basics.namespace|Fundamentals: Path Alias and Namespace]] in [[yiiguide:|The Definitive Guide to Yii]].
 +
 
 +
Typically, when you use a class in Yii, you will never have to use an "include" statement. That is because Yii will automatically recognize when you intend to use a class and automatically load it. Directories can be scanned by Yii to recognize class files for automatic inclusion using [[yii:YiiBase#import-detail|Yii::import()]]. Furthermore, many directories are already imported, so there is no need to call the import method a second time. The bulk of importing in X2CRM is done in [[x2doc:ApplicationConfigBehavior|ApplicationConfigBehavior]].

Latest revision as of 01:49, 1 February 2013


Dependencies

X2CRM is built using the following frameworks. Hence, the majority of necessary knowledge for development in X2Engine can be found in their respective documentation.

Yii Framework

Yii Framework is a PHP framework based on the time-tested MVC (Model-View-Controller) design pattern, which is of particular importance in understanding how requests translate to the execution of class methods.

See:

jQuery and jQuery UI

Most of the Javascript in the codebase, including Yii Framework itself, depends on jQuery in some way or another. Thus, for front-end design (especially design that involves asynchronous content loading via AJAX) it is essential to understand the usage of this library. In many cases, Yii Framework provides certain utilities for constructing HTML elements and jQuery-based scripts, and it is thus also important to first search for effort-saving devices available in Yii Framework before writing something from scratch. In particular, CHtml contains methods such as ajaxButton, and the subclasses of CJuiWidget can be used to easily construct most common jQuery UI elements and seamlessly integrate them with Yii as input fields.

See:

MVC In a Nutshell

How a Request To The Web Application Translates To Execution

Relevant pages: Controller, Model, View and Fundamentals: Conventions in The Definitive Guide to Yii

A request to the server translates to the instantiation of a controller class. Which controller is instantiated depends upon the route, which contains the first part of the controller class's name with the first letter in lowercase. Then, the method of the class whose name begins with "action" is run based on the action ID of the request URL. As the action runs, it will retrieve data from the database using a model class. Actions which respond with content will then typically make a call to render or renderPartial, methods inherited from the CController class. The view file, specified by the first argument to render or renderPartial, will then be used to display the content (contained in the model) which is then passed back to the client as markup (or json, text, etc.)

File Structure

Relevant documentation: Fundamentals: Conventions (§5: Directory)

Modifying the codebase requires an understanding of where the relevant files are located. All PHP files used in the web application, which don't belong to the framework, are under the protected/ directory. This directory is not accessible from the web per the access rules defined in the .htaccess file; rather, these files are executed by the framework as the application runs. Within protected are the following directories:

components/
Miscellaneous classes used throughout the application, especially those which are extended by other classes. Contains its own views folder, which is used for storing templates for Widgets.
config/
Core configuration files for the web application.
controllers/
Base-level controller classes.
data/
Miscellaneous data files. Currently used to store SQL scripts that are run during installation.
extensions/
The designated folder for storing third-party classes.
messages/
Files containing translations of messages within the application (used by Yii::t)
models/
All core/base level model classes.
modules/
Self-contained modules. Most of the subdirectories here contain modules whose names appear in the main menu. Each subdirectory typically has the same structure as the base application; they each will have directories named controllers, models and views. See Fundamentals:Module in The Definitive Guide to Yii for more information.
runtime/
(For the application's use) Temporary files written to by the application
tests/
The designated directory for storing unit tests.
views/
View files corresponding to base-level controllers.

Using Classes

Relevant page: Fundamentals: Path Alias and Namespace in The Definitive Guide to Yii.

Typically, when you use a class in Yii, you will never have to use an "include" statement. That is because Yii will automatically recognize when you intend to use a class and automatically load it. Directories can be scanned by Yii to recognize class files for automatic inclusion using Yii::import(). Furthermore, many directories are already imported, so there is no need to call the import method a second time. The bulk of importing in X2CRM is done in ApplicationConfigBehavior.