JCustom Mod is a mod system to improve your arcade site experience through the use of the newest web technology. This mod is actually just a subsystem or a container to handle various supported mod plugins in the best and most user friendly way.
Version History:
Requirements:
Installation:
Installing a mod has never been this easy.
Gets a game's data.
$gid:Int - the game ID
$force_all:Boolean - include the unpublished games; requires Game Meta plugin
Object - the game's data object
Get a list of games data via optional arguments.
$args:Array - game arguments for query; if omitted, returns all games
Default argument key fields primkey, gamename, description, tags, width, height, filename, category, totalplays, sponsor, swftype, highscore, userkey, imagesmall, imagelarge and gameurl can be a array of it's respective data type or the actual data type value itself. Same keys can be apended with "_exclude" so that the provided value shall be excluded, "_rel" so that the relationship of provided value is specified (>, >=, <, <=, !=, LIKE) other than equal (=), or "_end" so that the provided value is the higher limit for query comparison.
| sql arguments | ||
|---|---|---|
| key | data Type/possible values | description |
| order | String ASC, DESC, NONE, RAND | the sorting order; defaults to DESC |
| orderby | String | the table field to sort by |
| limit | Int | the number of rows to return |
| offset | Int | the offset row |
Array - a list of game's data objects that matched the arguments
// this argument shall get 10 games from action category where
// primkeys should not be 1, 2 or 3 and is sorted by total plays
$args = array( "primkey_exclude" => array(1, 2, 3), "category" => "action", "orderby" => "totalplays", "limit" => 10 );
get_games( $args );
// this argument shall get 6 games from action & puzzle category
// where game name's have "ball" and width is less than 800
$args2 = array( "gamename" => "ball", "gamename_rel" => "LIKE", "category" => array("action", "puzzle"), "width_end" => 800, "limit" => 6 );
get_games( $args2 );
Gets the number of games via optional arguments.
$args:Array - game arguments for query; if omitted, returns number of all games
Int - number of games that matched arguments
Gets a list of distinct game categories.
$args:Array - game arguements for query but limited to keys: category, category_exclude, order, limit and force_all
Array - list of game categories that matched the arguments
Gets a list of games from the same category.
$gid_exclude:Int |Array - game ID's to exclude
$category:String - the category to relate from
$limit:Int - the number of games to get
Array - a list of game's data objects
Note: If the result from the category is less than the limit, random games will be included to fill the limit.
Gets the user data.
$userkey:Int - the user's ID. If omitted, the currently logged in user's ID will be used.
Object - the user data
user-data - function( $userData ) - applies filters on the user data
Gets the user ID.
$user:String | Int |Object - the user name, user ID or user data. If omitted, the currently logged in user's ID will be returned.
Int - the user ID
Gets a list of users data via optional arguments
$args:Array - user arguments for query; if omitted, returns all users
Default argument key fields userkey, username, permissions, ip, datereg, email, gamesplayed, avatar and academpoints can be a array of it's respective data type or the actual data type value itself. Same keys can be apended with "_exclude" so that the provided value shall be excluded, "_rel" so that the relationship of provided value is specified (>, >=, <, <=, !=, LIKE) other than equal (=), or "_end" so that the provided value is the higher limit for query comparison.
| sql arguments | ||
|---|---|---|
| key | data Type/possible values | description |
| order | String ASC, DESC, NONE, RAND | the sorting order; defaults to DESC |
| orderby | String | the table field to sort by |
| limit | Int | the number of rows to return |
| offset | Int | the offset row |
Array - a list of user's data objects that matched the arguments
Adds arcadem points to the user
$userkey:Int - the user's ID
$points:Int - [default = 1] the points to add
Boolean - true on success; otherwise false
A shortcut to either call user_form_logout() or user_form_login() if the user is already logged in or not respectively.
$return_hash:Boolean - [default = false] if true, nothing will be printed, instead will return the input hash value. Note that the POST request would require the hash in a variable named either "user-logout" or "user-login" repectively.
String - the request hash only if $return_hash is set to true; otherwise null
Prints a hidden input field or returns the variable hash for logging in on if the user is not already logged in.
$return_hash:Boolean - [default = false] if true, nothing will be printed, instead will return the input hash value. Note that the POST request would require the hash in a variable named "user-login"
String - the request hash only if $return_hash is set to true; otherwise null
login_success - function( $userkey ) - triggered if user was successfully logged in. The logged in user's ID is passed.
login_user_pending - function( $userData ) - triggered if the user's account is not yet activated (through email activation or admin approval). The user's data is passed.
login_fail - function() - triggered if the user name & password does not match or exist
<form method="post" action="<?php echo get_my_url();?>">
<?php user_form_login();
/* output:
<input type="hidden" name="user-login" value="80b39353a93c99f0eaeefb94f627e585" />
*/ ?>
<strong>Login: </strong><br/>
<label for="username">Username</label>:
<input type="text" id="username" name="name" title="User Name" /><br/>
<label for="username">Password</label>:
<input type="password" id="password" name="pass" title="Password" />
<input type="submit" value="Log in" />
<input type="checkbox" value="1" id="remember" name="rememb" title="Remeber" checked="checked" />
<label for="remember">Remember</label>
</form>
Prints a hidden input field or returns the variable hash for logging out only if the user is currently logged in.
$return_hash:Boolean - [default = false] if true, nothing will be printed, instead will return the input hash value. Note that the POST request would require the hash in a variable named "user-logout"
String - the request hash only if $return_hash is set to true; otherwise null
logout_success - function( $userID ) - triggered on successful log out. The just logged out user's ID is passed.
<form method="post" action="<?php echo get_my_url();?>">
<?php user_form_logout();
/* output:
<input type="hidden" name="user-logout" value="518e72e4106c6f7255d12f90ccd8f6a3" />
*/ ?>
<input type="submit" value="Log out" />
</form>
Prints a hidden input field or returns the variable hash for new user account form.
$return_hash:Boolean - [default = false] if true, nothing will be printed, instead will return the input hash value. Note that the POST request would require the hash in a variable named "new-user-account"
String - returns the request hash only if $return_hash is set to true; otherwise null
new-user-account - function( $userkey ) - triggered on successful new account submission. The new user's ID is passed.
user-data-default-avatar - function( $avatar ) - applies a filter to alter the default avatar image
user/event/new_account/error/required_username - A unique username is required
user/event/new_account/error/invalid_username - Username must be at least 3 and maximum 50 charaters
user/event/new_account/error/required_password - A strong (recommended) password is required
user/event/new_account/error/invalid_password - Password must be at least 3 and maximum 50 charaters
user/event/new_account/error/inconsistent_password - Password was not consistent, please re-type your password
user/event/new_account/error/required_email - An email address is required
user/event/new_account/error/invalid_email - A valid email address is required
user/event/new_account/error/invalid_email_taken - The email address you provided has already been used to register an account
Evaluates the new user account submission request. Prints or returns a corresponding message if new account is successful, otherwise errors are printed or returned. The new account is automatically proccessed on "post_init" custom event only if the POST variable "new-user-account" hash is valid (retrieved from this user_form_new_account() method). Field names defaultly required are "username", "password", "password2", "email" and "new-user-account" which determines that the request is for new user accounts.
$echo:Boolean - set to true to print the response
String - the corresponding text on success
Array - an array list of jc_error on fail
user/event/new_account/success - <h3>Account Successfully Created!</h3>\n<p>Your account was successfully created, you can now start by logging in and editting your profile.<br/><br/>Thank your for signing up & enjoy!</p>\n
user/event/new_account/wait_admin_approval - <h3>Waiting Admin Approval</h3>\n<p>Your new account is now waiting approval from the admins. Please wait for a confirmation within 48hrs.<br/><br/>Thank you for signing up!</p>\n
user/event/new_account/wait_activation - <h3>Waiting Activation</h3>\n<p>Your new account is now waiting activation, we have already sent you an email containing details on how to activate your account.</p>\n
Gets a text, that can be printed, about the current account status of the user. If however the actual user permission variable is needed, use the user data variable permissions instead.
$userkey:String - the user ID
String - a text about the current user account status; otherwise null if user does not exists or is already activated
user/event/account_status/wait_activation - <h3>Waiting Activation</h3>\n<p>We have already sent you an email containing details on how to activate your account.<br/><br/><u><a href=\"%s\">RESEND ACTIVATION EMAIL</a></u></p>\n
user/event/account_status/wait_admin_approval - <h3>Waiting Admin Approval</h3>\n<p>Your account is now waiting approval from the admins. Please wait for a confirmation within 48hrs.
Sends an email containing account activation details for the pending user and displays a success text.
$userkey:String - the user ID
$return:String - [default = false] if true will return the success text
Boolean - true on success
jc_error - a jc_error corresponding on why send email failed
user/event/send_email_acct_activate/success - <h3>Waiting Activation</h3>\n<p>We have sent you an email containing details on how to activate your account, you should receive it shortly.</p>\n
user/event/send_email_acct_activate/error - <h3>Sending Activation Email Failed</h3>\n<p>An error occured while trying to send the activation details to your email. It is required to activate your account to experience registered member's benifits.<br/><br/><u><a href=\"%s\">RESEND ACTIVATION EMAIL</a></u></p><br/><br/>\n
Note: If file %theme_path%/templates/email_accnt_activate.php exists, this will be used as email contents template.
Validates activation and prints or returns a correspoding message on the user account page.
$return:String - [default = false] if true will return the success text
Boolean - true on success; otherwise null
String - if $return is true, will return the corresponding message instead
Displays a request input field for updating user account. This method should be called within the html form.
$return_hash:Boolean - [default = fase] if true, nothing will be printed, instead will return the input hash value. Note that the POST request would require the hash in a variable named "user-update-account"
String - returns the request hash only if $return_hash is set to true; otherwise null
Displays a request input field for updating user avatar. This method should be called within the html form.
$return_hash:Boolean - [default = fase] if true, nothing will be printed, instead will return the input hash value. Note that the POST request would require the hash in a variable named "user-update-avatar"
String - returns the request hash only if $return_hash is set to true; otherwise null
Evaluates whether the request for update account/avatar is successful else displays corresponding errors.
$echo:Boolean - set to true to print the response
Boolean - true on success
Array - an array list of jc_error on fail
<?php if ( user_evaluate_update() === true ) echo "<strong>Updated Avatar</strong>"; ?>
<form method="post" enctype="multipart/form-data">
<?php user_update_avatar();
// output: <input type="hidden" name="user-update-avatar" value="5633d4514152f0965773eb033f87c7ed"/>
user_update_account();
// output: <input type="hidden" name="user-update-account" value="ccca259545458400c39528e3042d6afa"/>
?>
<input type="file" name="avatar"/>
<input type="submit" value="submit"/>
</form>
Sends an email containing details on how to reset the user's password and displays a corresponding message if a reset password POST request exists, else displays an input field for reset password request (call this method within the form).
$return_hash:Boolean - [default = fase] if true, nothing will be printed, instead will return the input hash value. Note that the POST request would require the hash in a variable named "user-update-avatar"
Boolean - true if successful
jc_error - a jc_error corresponding why the update failed
Resets the password and displays the new password if a reset POST request exists.
Boolean - true if successful
jc_error - a jc_error corresponding why the update failed
<form method="post">
<?php
if ( is_jc_error($new_password = user_get_reset_password()) || ! $new_password ):
if ( true === $forgot = user_forgot_password() ):
echo "<br/><br/><br/>";
else:
?>
<p>If you have already registered but forgot your<br/>password use this to reset your password.</p>
<label for="email">Email address:</label><br />
<input type="text" name="email" id="email" size="30" /><br />
<input type="submit" value="Submit" /><br />
<?php endif; // end user_forgot_password() ?>
<?php else: // if there is new password ?>
<h3>Reset Password Successful</h3>
<p>Your request was validated and accepted. Your new password was reset, so PLEASE NOTE your new password:</p>
<h1><?php echo $new_password;?></h1>
<p><small>This new password is randomly generated so it is highly recommended to login now and change your password into something else you could remember.</small></p>
<?php endif; ?>
</form>
Gets the corresponding sql table name from given name
$name:String - the specified nickname for the sql table
String - the sql table name
| name | sql table name |
|---|---|
| options | jc_options |
| games | AMCMS_games |
| users | AMCMS_users |
| favorites | AMCMS_favs |
| categories | AMCMS_cat |
| highscores | AMCMS_highscores |
| challenges | AMCMS_challenges |
| old_pref | AMCMS_pref |
Adds a database table name with a nickname
$name:String - the specified nickname for the sql table
$value:String - the actual sql table name
Boolean - true on success; false otherwise
Determines whether the table is already defined
$name:String - the specified name for the sql table
Boolean - true if it exists; null otherwise
Gets the information value
$name:String - the information name to get
String - the information data
| name | description |
|---|---|
| script_version | the version of the running script |
| arcade_url | the url where aracdem is running |
| uploads_url | url of upload directory |
| cache_url | url of cache directory |
| games_url | url of game media directory |
| games_imgs_url | url of game images directory |
| admin_url | url of admin panel |
| mod_url | url of jcustom mod area |
| mod_plugin_url | url of jcustom mod plugins |
| arcade_path | the absolute path of the arcadem script |
| uploads_path | the absolute path for uploads |
| cache_path | the absolute path for cache files |
| games_path | the absolute path for game media files |
| games_imgs_path | the absolute path for game images files |
| admin_path | the absolute path of admin panel |
| mod_path | the absolute path of jcustom mod |
| mod_plugin_path | the absolute path of jcustom mod plugins |
| current_theme | the currently selected theme name |
| theme_url | the url of the selected theme |
| theme_path | the absolute path of the selected theme |
| arcade_title | the specified arcade title |
| html_title | the HTML title to use for the current page |
| html_meta_desc | the HTML meta description to use for the current page |
| html_meta_tags | the HTML meta tags to use for the current page |
Gets the stored data from a path variable
$location:String - path on how the data is loaded as container name & var name
$use_session:Boolean - whether the data is stored as a $_SESSION variable, else data is temporarily stored on page load session
Mixed - the corresponding data if variable exist; null otherwise
Stores data on a path variable
$location:String - path on how the data is saved as container name & var name
$use_session:Boolean - whether the data is stored as a $_SESSION variable, else data is temporarily stored on page load session
$value:Mixed - the data to be stored
$value:Mixed - the stored data on success; false otherwise
remember_var( "games/my_var", false, "apple" );
echo remember_var( "games/my_var" );
/* output:
apple
*/
Deletes a path or path variable
$location:String - path on how the data is loaded as container name & var name
$use_session:Boolean - whether the data is stored as a $_SESSION variable, else data is temporarily stored on page load session
Boolean - true on success; false otherwise
Gets the corresponding system option value
$name:String - the option name to get, must NOT be sql escaped
Mixed - the option value; null otherwise
Saves a given data value as a system option
$name:String - the option name to add, must NOT be sql escaped
$value:Mixed - the data to save, can be any data type except resource, must NOT be sql escaped
$autoload:Boolean - whether the option should be loaded as initial options on system start
Int - the sql insert ID on success
jc_error - a jc_error corresponding on why insert failed
Note: Option name must not exists as this would return a jc_error. SQL sanitation occurs on the insert method.
Saves an array list of given data values as a system options
$list:Array - list of given data values as system options
Int - sql insert ID on success
jc_error - a jc_error corresponding on why insert failed
Note: The option is added only if the option name does not exists yet. SQL sanitation occurs on the insert method.
$options = array( array( "name"=>"my_var", "value"=>"my_val","autoload"=>true ), array( "name"=>"my_var2","value"=>"another_value","autoload"=>false) ); add_options( $options );
Updates a given data value as a system option
$name:String - the option name to update, must NOT be sql escaped
$value:Mixed - the data to save, can be any data type except resource, must NOT be sql escaped
$autoload:Boolean - whether the option should be loaded as initial options on system start, only applies if option does not exist
Boolean - true on success
jc_error - a jc_error corresponding on why update failed
Updates an array list of given data values as system options
$list:Array - array of options to add
Boolean - true on success
jc_error - a jc_error corresponding on why update failed
Deletes a system option
$name:String - the option name to delete, must NOT be sql escaped
Int - the number of deleted rows on success
jc_error - a jc_error corresponding on why delete failed
Deletes an array list of system options
$list:Array - array of option names to delete
Int - the number of deleted rows on success
jc_error - a jc_error corresponding on why delete failed
Recovers the appropriate message string if designated language file is set else if not, the default message is returned
$path:String - path on how the string is saved as container name & var name
$msg:String - the default message string
String - the appropriate message
Generates an MD5 hash for the session. Useful for enforcing POST securities.
$str:String - the key string
String - the hash value
Adds a data filter for the specified filter name.
$name:String - the filter name
$callback:Callback - a callback that has to recieve the passed data to filter then return it
$priority:Int - [default = 4] the execution priority of the filter (min = 0, max = 9)
$args:Array - [optional] an array of arguments that would be passed along the data
Boolean - true on success
jc_error - a jc_error corresponding why the method failed
function my_filter( $data ){
return str_replace( "a", "e", $data );
}
add_filter( "custom_filter", "my_filter" );
echo apply_filter( "custom_filter", "apple and banana" );
/* output:
epple end benene
*/
Removes an already defined filter for the specified filter name
$name:String - the filter name
$callback:Callback - the callback to recieve the passed data to filter
$priority:Int - [default = 4] the execution priority of the filter (min = 0, max = 9)
Boolean - true on success; otherwise false
Removes all the defined filters for the specified filter name
$name:String - the filter name
Boolean - true on success; otherwise false
Determines whether the speicified filter name has defined filters
$name:String - the filter name
Boolean - true if it has defined filter; otherwise false
Determines whether the specified filter name has the callback defined as one of it's filters
$name:String - the filter name
$callback:Callback - the callback to recieve the passed data to filter
$priority:Int - [default = 4] the execution priority of the filter (min = 0, max = 9)
Boolean - true if the callback is a defined filter; otherwise false
Applies the specified name filters on the data
$name:String - the filter name
&$name:Mixed - the data to filter; passed by reference
Mixed - the filtered data
Gets all the filters & arguments on the specified filter name
$name:String - the filter name
Array - the list of filters and their arguments
Copies all the filters & arguments of a specific filter name to another filter name
$source_name:String - the filter nameto copy from
$dest_name:String - the filter nameto copy to
Boolean - true on success; otherwise false
Adds a listener on a custom event
$name:String - the event name
$callback:Callback - callback to be called when custom event is triggered
$priority:Int - [default = 4] the execution priority of the event (min = 0, max = 9)
Boolean - true on success
jc_error - a jc_error corresponding why the method failed
function my_action(){
echo "beep beep";
}
add_action( "custom_event", "my_action" );
execute_action( "custom_event" );
/* output:
beep beep
*/
Removes the listener on the custom event
$name:String - the event name
$callback:Callback - the callback
$priority:Int - [default = 4] the execution priority of the event (min = 0, max = 9)
Boolean - true on success; otherwise false
Removes all defined listeners on the custom event
$name:String - the event name
Boolean - true on success; otherwise false
Determines whether the custom event name has definedlisteners
$name:String - the event name
Boolean - true if it has defined listeners; otherwise false
Determines whethere the callback defined as a listener of the custom event
$name:String - the event name
$callback:Callback - the callback
$priority:Int - [default = 4] the execution priority of the event (min = 0, max = 9)
Boolean - true if callback is a defined listener; otherwise false
Triggers the custom event
$name:String - the event name
$data:Mixed - [optional] an argument to be passed on each listener callback
Determines if the custom event has already been triggered
$name:String - the event name
Int - the number of times the event has been triggered; otherwise false
Gets all the callback listeners of the custom event
$name:String - the event name
Array - the list of callback listeners
:String -
:String -