Important Mercury Functions and Variables
There are a few functions and variables that come up in almost every single Mercury module page request. This page will discuss them.
Variables
$m
Developers are used to working with GET and POST variables resulting from URL variables and form submissions. Mercury wraps all of these incoming variables up into a top-level array called $m. If you pass a url variable "color=red" or submit a form with a field called "age" then can you reference these values using $m['color'] and $m['age'].
Functions
m(module, action [, singleargument])
The m( ) function is used to call a Mercury function. The first argument is the name of the module and the second argument is the name of the function. Mercury convention states that function names are spelled in camel caps with the first letter of the first word in lowercase and the first letter of each subsequent word in uppercase (ie. functionName). The third argument can be a single value (like a primary key or string) or it can be an array. If you need to pass multiple values into a function then you will need to pass in an array. The third argument is optional.
Why don't we just call the module functions through a simpler process? Efficiency and flexibility. This approach lets us do two things:
- Files and functions are only loaded when they are needed.
- We avoid loading entire objects into memory again and again only to use a very small part of their functionality each time
- By routing the function request through another function we can check to see if the function is defined on a per-site basis.
- if the function is defined within the site we use it
- if not then we can look for it in the core Mercury files
This function will first look in html/mercury/modulename/functions/action.php and will then look in the core mercury/modulename/functions/action.php location. Note that ".php" is appended to the action when the file path is determined.
d(module, file)
This function is almost always called in conjunction with PHP's require function. In the same spirit as the m( ) function this function is used to specify the path to a display file.
First it looks in html/mercury/modulename/display/file.php and if there is a file there it will use it. If there is no file there it will look in the core mercury/modulename/display/file.php location.
k(value)
This function is used primarily when assembling MySQL query strings and will ensure that the value passed into it meets MySQL numerical standards. This is a good validation step to prevent SQL injection attack vulnerabilities.
e(value)
This function is used primarily when assembling MySQL query strings and will ensure that the value passed into it can be inserted into MySQL as a string. This is a good validation step to prevent SQL injection attack vulnerabilities.
q(sqlquery)
This function executes a SQL query against the MySQL database. You should assign the result to a variable.
getrow(sqlresult)
This function retrieves one row of data, as an array, at a time. Very useful when looping over a SQL result set.
setlayout(layoutfilename.php)
This is described in the layout section and allows you to specify a layout file that is not html/layout.php for your page to be displayed in.