Topics

Create an Exponent Module - Part 1

In this tutorial we are going to create a module to keep track of an album collection. While this module might not be very useful, the concepts we are learning will be. Using the methods in this tutorial, you can write a module for Exponent that can do almost anything.

There are 4 basic steps for creating a module using the MVC Framework in Exponent. They are as follows:

  1. Create the Table Definition(s) & install tables
  2. Create the model file(s)
  3. Create the controller(s)
  4. Create actions & views

Make the Module Folders

Before we can create our files we need create some directories for our module. In fact, an Exponent CMS module is really just a controller, model, and views that are laid out in the proper place with a proper directory structure. To create the module:

  1. Create directory framework/modules/albums – This is our main module folder. You can name this directory whatever you want. There is no naming convention that applies to module folders.
  2. Create directory framework/modules/albums/definitions– The folder is where we put the model definitions for our module.
  3. Create directory framework/modules/albums/models– The folder is where we put the models for our module. Most modules only have one model, but they can have more than one if needed.
  4. Create directory framework/modules/albums/controllers – The folder is where we put the controllers for our module. Most modules only have one controller, but they can have more than one if needed.
  5. Create directory framework/modules/albums/views – This is where we will put our views. The views will be in subdirectories (see next step). There will be one subdirectory per controller.
  • Create (sub)directory framework/modules/albums/views/albums – This is our albumsController view directory. The naming convention for a controller's view directory is the name of the controller, minus the word “Controller”. So in the case we name the directory albums since our controller that we will create in the next step will be named albumsController.

Creating Table Definitions

As you can see the first thing we need to create is the Table Definition file. Table Definitions are located in the framework/modules/albums/definitions. Table Definition files are sudo-sql files. Not using raw SQL allows Exponent to support any database, though currently the only database officially supported is MySQL. Table Definitions simply return an array of information about a table that we wish to create in the database. After we make a Table Definition we will run install tables to have Exponent create the table we create the Table Definition for.

The information we are going to store about the albums in our album collection module are:

  1. Title
  2. Description
  3. Artist
  4. Year
  5. Sorting Order (I'll explain this later)

Our first step then is to create the model definition for our song collection module. Not surprisingly we are going to call this table albums. So in your framework/module/albums/definitions directory create a file called albums.php.

After you have created the albums.php copy and paste the following code into the file:

if (!defined('EXPONENT')) exit(''); 

return array( 
	'id'=>array( 
		DB_FIELD_TYPE=>DB_DEF_ID, 
		DB_PRIMARY=>true, 
		DB_INCREMENT=>true), 
	'title'=>array( 
		DB_FIELD_TYPE=>DB_DEF_STRING, 
		DB_FIELD_LEN=>200), 
	'body'=>array( 
		DB_FIELD_TYPE=>DB_DEF_STRING, 
		DB_FIELD_LEN=>100000), 
	'artist'=>array( 
		DB_FIELD_TYPE=>DB_DEF_STRING, 
		DB_FIELD_LEN=>50), 
	'year'=>array( 
		DB_FIELD_TYPE=>DB_DEF_INTEGER),
	'rank'=>array( 
		DB_FIELD_TYPE=>DB_DEF_INTEGER), 
	'poster'=>array( 
		DB_FIELD_TYPE=>DB_DEF_INTEGER), 
	'created_at'=>array( 
		DB_FIELD_TYPE=>DB_DEF_TIMESTAMP), 
	'edited_at'=>array( 
		DB_FIELD_TYPE=>DB_DEF_TIMESTAMP), 
	'location_data'=>array( 
		DB_FIELD_TYPE=>DB_DEF_STRING, 
		DB_FIELD_LEN=>250, 
		DB_INDEX=>10) 
);

Look at the first array element named 'id'. This definition says to create a database column named 'id' or type 'id' which is just Exponent parlance for an integer column. The flag we are passing set the column as the primary key and turn on auto incrementing. Almost every database table in Exponent will need an id field like this one, so get familiar with it.

The next array element creates a column named 'title'. While this will be the name of the album, we called this 'title' to keep with the loose standard inside of Exponent. Most content tables call name or title fields 'title' and body or description fields by the name 'body'. Just get used to using that terminology. You can see that we set the DB_FIELD_TYPE to DB_DEF_STRING. This tells Exponent that this is a text field. Other common types we use quite a bit are DB_DEF_INTEGER, DB_DEF_TIMESTAMP, DB_DEF_BOOLEAN. You will also notice that DB_DEF_STRING takes another flag, DB_FIELD_LEN. This will set the size of the column in the database.

You might also notice some columns that I didn't mention earlier in the list of fields we wanted to keep for our albums. We also added:

  1. rank
  2. poster
  3. created_at
  4. edited_at
  5. location_data

These are what we refer to as “Magic Fields”. Just having them in your database table will cause things to happen automagically. Rank will be populated with the sorting order of the song (more on this later). Poster will have the user id of the user who entered the album. created_at and edited_at are timestamp fields that will keep a record of the date/time the record was created and edited last. Location data is something Exponent needs to keep track of to know which pages module are located on. We won't go into detail about it in this tutorial.

Go ahead and save the file. Then go to the Exponent Administration Bar and run Install Tables.

After you run install tables, you should see the new table show up in the list of tables.

Creating Model Files (getting to know expRecord)

Exponent Models are the “M” in MVC. They are our models. To create our Model for this module, create a new file in framework/modules/albums/models named albums.php. Open the file for editing and paste in the following code:

<?php

class albums extends expRecord {

	public $validates = array(

		'presence_of'=>array(

			'title'=>array('message'=>'Album name is a required field.'),

		));
}

?>

Then save the file. That's all there is to it for now. We created our model and we actually just put some automagic validation, making the title field required.

The Album Controller

In the Exponent MVC framework, controllers are where you put your actions. Actions are just the business logic that dictates how your module behaves. Many basic actions are already defined for you when you create your controller and tell it to extend expController. Some of the more commonly used actions you will have for free are show, showall, edit, update and delete.

To create your albumsController:

  1. Create and then edit framework/modules/albums/controllers/albumsController.php.
  2. Paste in the following code and save file:
<?php

class albumsController extends expController {

	public $useractions = array('showall'=>'Show all');

	function name() { return $this->displayname(); } //for backwards compat
	function displayname() { return "Album Collections"; }
	function description() { return "Allow you to keep track of your albums."; }
	function author() { return "Adam Kessler - OIC Group, Inc"; }
	function hasSources() { return true; }
	function hasViews() { return true; }
	function hasContent() { return true; }
	function supportsWorkflow() { return false; }
	function isSearchable() { return true; }	

}

?>

What can I do with it?

That's it! We're done. You have now created a new Exponent CMS module. It was really that easy.
What? You don't believe me? I'll prove it to you.

Activating the Module

Login to your site as an Administrator. Go the your slingbar->Exponent->Extensions->Manage Modules. On the Manage Modules page you should see should see a listing for “ Album Collections”. It should be near the top as they are order alphabetically. Click the “Activate Module” link. Your new module is now active and can be added to pages on your site.

Adding the Module

You can add the module to your site using the “Add Module Here” links in the container modules on your page. You should have one action, showall and default view for it. You can also edit and delete your albums too.

What's Next

You now have new Exponent module. It doesn't do much and it probably isn't very pretty. In the next tutorial we will talk about how to customize the views for the module. In the third part of this tutorial we will look at adding songs to the albums and discuss permissions.

Loading Help