Quick Start
Use this quick start to learn about how the framework stores and manages Settings and about the Stage class and how it deals with Controllers and Views. After going through this you should have a general idea as to how to create pages and manage a site using the Lucent Web Framework.
Settings
All settings are stored in the LW_Settings object. (This isn't exactly true as some settings are stored in the config.conf.php file.) You usually populate this object by passing in an INI file at start up. Before anything else is done, the LW_Settings object must be populated with the appropriate settings for the classes you intend to use in the system. This is automatically set up to do in the skeleton site shipped with the framework.
View the code of the skeleton site to get an idea of how settings are loaded into the system.
You can view the documentation of each component of the framework to view which settings are available and how to use them.
Bootstrapping
All calls to a page on your site is directed through the index.php file under the public_html folder, although you're public_html folder may be named something else. The .htaccess file included with the framework in the skeleton site is set to redirect calls to the index.php for further processing. It is then this file that sets up the framework and hands off the call to the LW_Stage class, which hands off the call to the correct Controller and calls the correct Action on that controller. This may be a bit confusing for people that haven't dealt with Views and Controllers before.
The index.php file first includes the config.conf.php file (which includes various configuration parameters required by the framework). It then includes the Autoloader that's included with the framework. After that it includes the settings INI file where all your settings should be set and will include the development settings if the environment is a development environment.
After that it sets up the LW_Compressor component with the correct URLs. Look at the documentation for the LW_Compressor component to learn more about it.
Finally it hands off the call to the LW_Stage class.
Controllers and Actions
Controllers that you create should be extended from the LW_Controller class, which implements the base functionality that a Controller needs in the framework. They should be named with the first letter capitalized and then the word Controller after it.
Examples: "IndexController" "ShoppingController"
Actions in a Controller are simply public functions of the controller class that you created.
For example, a simple Controller with an index (default action), edit and add Action may look like this:
class IndexController extends LW_Controller
{
public function index()
{
/* Index Action */
}
public function add()
{
/* Add Action */
}
public function edit()
{
/* Edit Action */
}
}
To access the controllers and actions, you append to the end of the URL the lowercase name of the controller (without the Controller part) and then a forward slash and the name of the action. So, for example, to get to the index action above you would type in:
http://www.domain.com/index/index
That would correspond to the index action of the index controller. However, the index action is the default action of a controller, so if no action is called, or if the incorrect action is called, it will default to the index action. The same is true with a controller. If no controller is passed in, or a controller that doesn't exist is passed in, it will use the index controller. For example, the index action of the index controller can be accessed like so:
http://www.domain.com/
The above will default to the index action of the index controller.
Note that if the framework doesn't find a controller for the URL you passed in, it will search for an action with that name in the index controller. For example, to access the index controller's edit action, you can do one of the following:
http://www.domain.com/index/edit
http://www.domain.com/edit
Both URLs will call the edit action of the index controller.
The situation becomes more complicated with the addition of sections. Say, for example, that you wanted to have a URL like so:
http://www.domain.com/admin/articles/edit
This can't be done with just controllers and actions. You need another level in there. You can accomplish this by using sections. Sections are simply directories in the controllers folder. For example, to create the above URL you would create a folder named "admin." This would be the admin section, where you can add any number of controllers or sub-sections. You would then create an Articles controller and create an edit action for that controller. Like so:
class ArticlesController extends LW_Controller
{
public function edit()
{
/* Edit Action */
}
}
Note that you can create sub-sections (which are just folders inside of folders) if you want to get more specific with your URLs.
Things can get a little complicated (although power and control is what we want) with sections and controllers and actions. For example, the following URL:
http://www.domain.com/admin/articles/edit
can be the "articles" sub-section inside the "admin" section with an index controller and edit action. Or it can be an edit controller with an index action. Or an articles controller with an edit action inside the admin section. As you can see, there is power in how you want to organize your controllers and actions.
Query Values
Before we get too far away from controllers, let's talk about query values. Query values are what you would normally attach to a URL like so:
http://www.domain.com/admin/edit/?id=3&article_id=4
The "?id=3&article_id=4" part is the query values. In the Lucent Web framework you no longer use query values (although you can if you want). You simply attach query values to the end of a URL like so:
http://www.domain.com/admin/edit/3/4
This would be just as before, except no name is attached to a value. A URL like this could be set up to call the admin controller and the edit action. The query value 3 and 4 would then be assigned to the particular controller's "$query_values" variable in an array. For example, you would access the second query value of the URL (4, in this case) like so:
class AdminController extends LW_Controller
{
public function edit()
{
// Output the query value (4).
$this->query_values[1];
}
}
It's simply an array of all the values inputted to the end of the URL. You would access the first query value (3) by indexing into the 0th element.
Views
Views are simply PHP files with the extension .phtml and placed into the views folder. They are displayed by calling the render_view() method of the controller you're accessing. For example, let's say we wanted to render the index.phtml file inside the index action of the index controller:
class IndexController extends LW_Controller
{
public function index()
{
$this->render_view( 'index' );
}
}
You can place views in sub-folders, in which case you just index into that folder:
$this->render_view( 'sub/folder/index' );
Note that you omit the .phtml extension. It's added for you automatically.
You pass in variables to the view in one of two ways. The normal way you assign variables to controllers is by using the assign() method:
public function index()
{
$this->assign( 'title', 'Title of the page' );
$this->render_view( 'index' );
}
The above example would make the variable $title accessible within the index view.
You can also pass the data into the render_view() function to create variables for use in the view.
class IndexController extends LW_Controller
{
public function index()
{
$this->assign( 'variable', 'First Variable' ); // The first variable.
$this->render_view( 'index', array( 'variabl23' => 'Second Variable' ) ); // The second variable accessible by the view.
}
}
Wrapping Up
Sorry for making this such a long quick start, but hopefully you'll now have a fairly good grasp of how the framework runs and how you can start building sites with it. Don't be afraid to experiment with it. The skeleton site is only an example of how to set up a site. Go ahead and mess with the code. If you come up with anything you think would be useful, don't be afraid to submit a patch or talk on the forums about it.