Skip to content
This repository has been archived by the owner on Nov 26, 2017. It is now read-only.

Commit

Permalink
Adding manual documentation for the new Model, View and Controller
Browse files Browse the repository at this point in the history 
packages.
  • Loading branch information
Louis Landry committed Apr 9, 2012
1 parent 4112586 commit 8e7e9e5
Show file tree
Hide file tree
Showing 10 changed files with 447 additions and 0 deletions.
69 changes: 69 additions & 0 deletions docs/manual/en-US/chapters/classes/jcontrollerbase.xml
View file
@@ -0,0 +1,69 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "../../Developer_Manual.ent">
%BOOK_ENTITIES;
]>
<section>
<title>JControllerBase</title>

<section>
<title>Construction</title>

<para>The constructor for <classname>JControllerBase</classname> takes an optional <classname>JInput</classname> object and an
optional <classname>JApplciationBase</classname> object. If either is omitted, the constructor defers to the protected
loadInput and loadApplication methods respectively. These methods can be overriden in derived classes if the default
application and request input is not appropriate.</para>
</section>

<section>
<title>Usage</title>

<para>The <classname>JControllerBase</classname> class is abstract so cannot be used directly. The derived class must
implement the execute method to satisfy the interface requirements. Note that the execute method no longer takes a "task"
argument as each controller class. Multi-task controllers are still possible but not recommended. Each controller class should
do just one sort of 'thing', just as saving, deleting, checking in, checking out and so on. However, controllers, or even
models and views, have the liberty of invoking other controllers to allow for HMVC architectures.</para>

<example>
<title>Example controller</title>

<programlisting> /**
* My custom controller.
*
* @package Examples
*
* @since 12.1
*/
class MyController extends JControllerBase
{
/**
* Method to execute the controller.
*
* @return void
*
* @since 12.1
* @throws RuntimeException
*/
public function execute()
{
echo time();
}
}

// Instantiate the controller.
$controller = new MyController;

// Print the time.
$controller-&gt;execute();</programlisting>
</example>
</section>

<section>
<title>Serialization</title>

<para>The <classname>JControllerBase</classname> class implements <interfacename>Serializable</interfacename>. When
serializing, only the input property is serialized. When unserializing, the input variable is unserialized and the internal
application property is loaded at runtime.</para>
</section>
</section>
51 changes: 51 additions & 0 deletions docs/manual/en-US/chapters/classes/jmodelbase.xml
View file
@@ -0,0 +1,51 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "../../Developer_Manual.ent">
%BOOK_ENTITIES;
]>
<section>
<title>JModelBase</title>

<section>
<title>Construction</title>

<para>The contructor for <classname>JModelBase</classname> takes an optional <classname>JRegistry</classname> object that
defines the state of the model. If omitted, the contructor defers to the protected <methodname>loadState</methodname> method.
This method can be overriden in a derived class and takes the place of the <methodname>populateState</methodname> method used
in the legacy model class.</para>
</section>

<section>
<title>Usage</title>

<para>The <classname>JModelBase</classname> class is abstract so cannot be used directly. All requirements of the interface
are already satisfied by the base class.</para>

<example>
<title>Example model</title>

<programlisting> /**
* My custom model.
*
* @pacakge Examples
*
* @since 12.1
*/
class MyModel extends JModelBase
{
/**
* Get the time.
*
* @return integer
*
* @since 12.1
*/
public function getTime()
{
return time();
}
}</programlisting>
</example>
</section>
</section>
73 changes: 73 additions & 0 deletions docs/manual/en-US/chapters/classes/jmodeldatabase.xml
View file
@@ -0,0 +1,73 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "../../Developer_Manual.ent">
%BOOK_ENTITIES;
]>
<section>
<title>JModelDatabase</title>

<section>
<title>Construction</title>

<para><classname>JModelDatabase</classname> is extended from <classname>JModelBase</classname> and the contructor takes an
optional <classname>JDatabaseDriver</classname> object and an optional <classname>JRegistry</classname> object (the same one
that <classname>JModelBase</classname> uses). If the database object is omitted, the contructor defers to the protected
<methodname>loadDb</methodname> method which loads the database object from the platform factory.</para>
</section>

<section>
<title>Usage</title>

<para>The <classname>JModelDatabase</classname> class is abstract so cannot be used directly. It forms a base for any model
that needs to interact with a database.</para>

<example>
<title>Example database model</title>

<programlisting> /**
* My custom database model.
*
* @package Examples
*
* @since 12.1
*/
class MyDatabaseModel extends JModelDatabase
{
/**
* Get the content count.
*
* @return integer
*
* @since 12.1
* @throws RuntimeException on database error.
*/
public function getCount()
{
// Get the query builder from the internal database object.
$q = $this-&gt;db-&gt;getQuery(true);

// Prepare the query to count the number of content records.
$q-&gt;select('COUNT(*)')
-&gt;from($q-&gt;qn('#__content'));

$this-&gt;db-&gt;setQuery($q);

// Execute and return the result.
return $this-&gt;db-&gt;loadResult();
}
}

try
{
$model = new MyDatabaseModel;
$count = $model-&gt;getCount();
}
catch (RuntimeException $e)
{
// Handle database error.
}
</programlisting>
</example>
</section>
</section>
75 changes: 75 additions & 0 deletions docs/manual/en-US/chapters/classes/jviewbase.xml
View file
@@ -0,0 +1,75 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "../../Developer_Manual.ent">
%BOOK_ENTITIES;
]>
<section>
<title>JViewBase</title>

<section>
<title>Construction</title>

<para>The contructor for <classname>JViewBase</classname> takes a <classname>JModel</classname> object and a
<classname>JController</classname> object. Both are mandatory.</para>

<para>Note that these are interfaces so the objects do no necessarily have to extend from <classname>JModelBase</classname> or
<classname>JControllerBase</classname> classes. Given that, the view should only rely on the API that is exposed by the
interface and not concrete classes unless the contructor is changed in a derived class to take more explicit classes or
interaces as required by the developer.</para>
</section>

<section>
<title>Usage</title>

<para>The <classname>JViewBase</classname> class is abstract so cannot be used directly. It forms a simple base for rendering
any kind of data. The class already implements the <methodname>escape</methodname> method so only a
<methodname>render</methodname> method need to be added. Views derived from this class would be used to support very simple
cases, well suited to supporting web services returning JSON, XML or possibly binary data types. This class does not support
layouts.</para>

<example>
<title>Example view</title>

<programlisting> /**
* My custom view.
*
* @package Examples
*
* @since 12.1
*/
class MyView extends JViewBase
{
/**
* Render some data
*
* @return string The rendered view.
*
* @since 12.1
* @throws RuntimeException on database error.
*/
public function render()
{
// Prepare some data from the model.
$data = array(
'count' =&gt; $this-&gt;model-&gt;getCount()
);

// Convert the data to JSON format.
return json_encode($data);
}
}

try
{
$view = new MyView(new MyDatabaseModel, new MyController);
echo $view-&gt;render();
}
catch (RuntimeException $e)
{
// Handle database error.
}
</programlisting>
</example>
</section>
</section>
83 changes: 83 additions & 0 deletions docs/manual/en-US/chapters/classes/jviewhtml.xml
View file
@@ -0,0 +1,83 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "../../Developer_Manual.ent">
%BOOK_ENTITIES;
]>
<section>
<title>JViewHtml</title>

<section>
<title>Construction</title>

<para><classname>JViewHtml</classname> is extended from <classname>JViewBase</classname>. The constructor, in addition to the
model and controller arguments, take an optional <classname>SplPriorityQueue</classname> object that serves as a lookup for
layouts. If omitted, the view defers to the protected <methodname>loadPaths</methodname> method.</para>
</section>

<section>
<title>Usage</title>

<para>The <classname>JViewHtml</classname> class is abstract so cannot be used directly. This view class implements render. It
will try to find the layout, include it using output buffering and return the result. The following examples show a layout
file that is assumed to be stored in a generic layout folder not stored under the web-server root.</para>

<example>
<title>Example HTML layout</title>

<programlisting>&lt;?php
/**
* Example layout "layouts/count.php".
*
* @package Examples
* @since 12.1
*/

// Declare variables to support type hinting.

/** @var $this MyHtmlView */
?&gt;

&lt;dl&gt;
&lt;dt&gt;Count&lt;/dt&gt;
&lt;dd&gt;&lt;?php echo $this-&gt;model-&gt;getCount(); ?&gt;&lt;/dd&gt;
&lt;/dl&gt;</programlisting>
</example>

<example>
<title>Example HTML view</title>

<programlisting> /**
* My custom HTML view.
*
* @package Examples
* @since 12.1
*/
class MyHtmlView extends JViewHtml
{
/**
* Redefine the model so the correct type hinting is available in the layout.
*
* @var MyDatabaseModel
* @since 12.1
*/
protected $model;
}

try
{
$paths = new SplPriorityQueue;
$paths-&gt;insert(__DIR__ . '/layouts');

$view = new MyView(new MyDatabaseModel, new MyController, $paths);
$view-&gt;setLayout('count');
echo $view-&gt;render();
}
catch (RuntimeException $e)
{
// Handle database error.
}
</programlisting>
</example>
</section>
</section>
13 changes: 13 additions & 0 deletions docs/manual/en-US/chapters/interfaces/jcontroller.xml
View file
@@ -0,0 +1,13 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "../../Developer_Manual.ent">
%BOOK_ENTITIES;
]>
<section>
<title>JController</title>

<para><interfacename>JController</interfacename> is an interface that requires a class to be implemented with an
<methodname>execute</methodname>, a <methodname>getApplication</methodname> and a <methodname>getInput</methodname>
method.</para>
</section>
12 changes: 12 additions & 0 deletions docs/manual/en-US/chapters/interfaces/jmodel.xml
View file
@@ -0,0 +1,12 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "../../Developer_Manual.ent">
%BOOK_ENTITIES;
]>
<section>
<title>JModel</title>

<para><interfacename>JModel</interfacename> is an interface that requires a class to be implemented with a
<methodname>getState</methodname> and a <methodname>setState</methodname> method.</para>
</section>
12 changes: 12 additions & 0 deletions docs/manual/en-US/chapters/interfaces/jview.xml
View file
@@ -0,0 +1,12 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "../../Developer_Manual.ent">
%BOOK_ENTITIES;
]>
<section>
<title>JView</title>

<para><interfacename>JView</interfacename> is an interface that requires a class to be implemented with an
<methodname>escape</methodname> and a <methodname>render</methodname> method.</para>
</section>

0 comments on commit 8e7e9e5

Please sign in to comment.