Mercury File Structure
Here we will look at the structure of a Mercury module. Mercury is built on an MVC architecture. This stands for Model-View-Controller. As described in the previous document a Mercury module will have files in the module root, files in a display folder and files in the functions folder. Files in the module root correspond to the Controller layer. Files in the display folder correspond to the View layer. Files in the functions folder are closely related to the Model layer.
First, a Note on Display
In Mercury modules the only place that display content should EVER come from is the display folder. If you ever want a function to display content then you will call the Mercury d( ) function to include a display file. If you want a controller file to display content then you will also use the same d( ) function to include a display file. The d( ) function is described in more depth in the section called Important Mercury Functions.
How a Module Works
In a previous document you saw how to access a file within a module. With the path /mymodule/my-action we will be dealing with the module mymodule and the my-action.php file. This file will be in top level and will therefore be a controller file. These controller files contain business logic but never display any data (other than by using the d( ) function to get files from the display folder) and they never access the database or perform other generic tasks (these are handled in the functions folder)
A simple controller file mercury/mymodule/my-action.php might look something like this:
<?php
$information= m("mymodule", "getInformation", $m['ItemId']);
require(d("mymodule", "display-information"));
?>
Let's break this file down so that we can understand it.
The first line sets a variable called $information equal to the value of a function. The function is m( ) for Mercury and is explained in more depth in the section called Important Mercury Functions. In this particular case however we are calling a function called getInformation from the module mymodule and we are passing in a ItemId variable. All POST and GET variables are wrapped up together in an array called $m. The function getInformation will be a file called mercury/mymodule/functions/getInformation.php that lives in the functions folder, either globally or locally. In this particular case the function will probably return an array with several values of interest.
The second line uses the PHP function require to include a display file called display-information.php from the mercury/mymodule/display folder. The variable $information will be available to the display file since the display file will be acting in the same variable scope as it is simply included.
A controller might set several variables, calling several functions, and then require one or more display files. It might also update some data and redirect the browser to a subsequent page.
LINK TO SAMPLE CODE FOR EXAMPLES