General Information

Player Table Structure

The player table structure is the structure of the table called jBlacklist which can be found inside all players that have loaded. The table holds information such as a player's blacklists and network message cooldown. If a player has more than one blacklist of the same type, the one with the longest expire date will be loaded.

Table:

[Blacklists]:
    [string blacklistType] = number expireDate (The time when the blacklist expires in epoch time)

[NetCooldown] = number cooldown (The cooldown is stored as the server's total uptime with 0.5 seconds added to it. If the value is higher than CurTime, the player has a cooldown.)

Blacklist Table Structure

The blacklist table structure is the structure of the table which can be found in the blacklist result strcuture.

Table:

string STEAMID (The SteamID of the player which the blacklist belongs to)
string TYPE (The blacklist type)
string REASON (The reason why the blacklist was issued)
string ADMIN (The SteamID of the administrator or CONSOLE if it was issued by the console)
number DATE (The date when the blacklist was issued in epoch time)
number LASTUPDATE (The date when the blacklist was last updated in epoch time)
number TIME (The date when the blacklist expires in epoch time)

Blacklist Result Structure

The blacklist result structure is the structure of the table which will be returned when you use any of the data management functions. If the function would fail to read the requested information, the result will be false and the reason will be the reason of the failure. If the function wouldn't find any of the requested data, the result will be an empty table.

Table:

[number blacklistID]:
    string STEAMID (The SteamID of the player which the blacklist belongs to)
    string TYPE (The blacklist type)
    string REASON (The reason why the blacklist was issued)
    string ADMIN (The SteamID of the administrator or CONSOLE if it was issued by the console)
    number DATE (The date when the blacklist was issued in epoch time)
    number LASTUPDATE (The date when the blacklist was last updated in epoch time)
    number TIME (The date when the blacklist expires in epoch time)

Blacklist Module Structure

The blacklist module structure is the structure of the table that is created inside of custom blacklist modules.

Table:

string Name (The name of the blacklist module)
boolean Enabled (A boolean if the blacklist is enabled or not)
function GetDescription (A function used to get the description of the blacklist type)
function GetBlacklistedPhrase (A function used to get the phrase which says the player did something it was blacklisted from doing)
function OnIssued (A function which will be called when a blacklist of this type is issued)
function OnExpire (A function which will be called when a blacklist of this type expires)

Logging Enumerations

The logging enumerations are global variables that can be used within certain functions.

JBLACKLIST_LOGGINGENUM_ADMIN - Used to log administration events.

JBLACKLIST_LOGGINGENUM_OTHER - Used to log other events.

Notification Enumerations

The notification enumerations are global variables that can be used within certain functions.

JBLACKLIST_NOTIFYENUM_WINDOW - Used to show a notification in a window.

JBLACKLIST_NOTIFYENUM_POPUP - Used to show a notification as a popup in the lower right of the screen.

JBLACKLIST_NOTIFYENUM_CHAT - Used to show a notification in the chat.

Hooks

Misc

Hook:

Hook Name:	jBlacklist_StartedLoading
Returns:	Nothing
Realm:	Shared
Description	This hook will be called when JBlacklist starts up.

Hook Parameters:

This hook has no hook parameters.

Hook Return Values:

This hook has no return values.

Hook:

Hook Name:	jBlacklist_FinishedLoading
Returns:	Nothing
Realm:	Shared
Description	This hook will be called when JBlacklist have finished starting up.

Hook Parameters:

This hook has no hook parameters.

Hook Return Values:

This hook has no return values.

Hook:

Hook Name:	jBlacklist_BlacklistRegistered
Returns:	Nothing
Realm:	Shared
Description	This hook will be called when a blacklist module have been loaded into JBlacklist.

Hook Parameters:

1. moduleTable (table)

- The moduleTable is the table which is created inside custom blacklist modules. (Check blacklist module structure)

Hook Return Values:

This hook has no return values.

Hook:

Hook Name:	jBlacklist_BlacklistsFinishedLoading
Returns:	Nothing
Realm:	Shared
Description	This hook will be called all blacklist modules have been loaded.

Hook Parameters:

This hook has no hook parameters.

Hook Return Values:

This hook has no return values.

Hook:

Hook Name:	jBlacklist_LanguageChanged
Returns:	Nothing
Realm:	Shared
Description	This hook will be called when the language of the addon is changed.

Hook Parameters:

1. languageName (string)

- The languageName is the name of the language that the addon was changed to.

Hook Return Values:

This hook has no return values.

Hook:

Hook Name:	jBlacklist_LanguagesFinishedLoading
Returns:	Nothing
Realm:	Shared
Description	This hook will be called when all language modules have finished loading.

Hook Parameters:

This hook has no hook parameters.

Hook Return Values:

This hook has no return values.

Hook:

Hook Name:	jBlacklist_InitialPlayerLoaded
Returns:	Nothing
Realm:	Server
Description	This hook will be called the first time a player is loaded.

Hook Parameters:

1. ply (player)

- The player whose blacklists was loaded.

Hook Return Values:

This hook has no return values.

Hook:

Hook Name:	jBlacklist_PlayerLoaded
Returns:	Nothing
Realm:	Server
Description	This hook will be called each time a player is loaded/reloaded.

Hook Parameters:

1. ply (player)

- The player whose blacklists was loaded.

Hook Return Values:

This hook has no return values.

Data Management

Hook:

Hook Name:	jBlacklist_DataChange
Returns:	Nothing
Realm:	Client
Description	This hook will be called when a change is made within someones blacklists.

Hook Parameters:

1. targets (table)

- A table with all the SteamIDs of all affected players.

2. adminID (string)

- The SteamID of the administrator who caused the datachange.

Hook Return Values:

This hook has no return values.

Hook:

Hook Name:	jBlacklist_BlacklistIssued
Returns:	Nothing
Realm:	Server
Description	This hook will be called when someone issues one or more blacklists.

Hook Parameters:

1. ply (player)

- The player who issued the blacklists.

2. types (table)

- A table with all the blacklist types as strings.

3. targets (table)

- A table with SteamIDs of all the players that should be blacklisted.

4. blacklistLength (number)

- The length of the blacklists in seconds.

5. reason (string)

- The reason for the blacklists.

6. silent (boolean)

- A boolean if the blacklists were issued silently.

Hook Return Values:

This hook has no return values.

Hook:

Hook Name:	jBlacklist_BlacklistRemoved
Returns:	Nothing
Realm:	Server
Description	This hook will be called when someone removes a blacklist.

Hook Parameters:

1. ply (player)

- The player who removed the blacklist.

2. SteamID (string)

- The SteamID of the player whose blacklist were removed.

3. blacklistID (string)

- The ID of the blacklist that was removed.

Hook Return Values:

This hook has no return values.

Hook:

Hook Name:	jBlacklist_BlacklistModified
Returns:	Nothing
Realm:	Server
Description	This hook will be called when someone modify a blacklist.

Hook Parameters:

1. ply (player)

- The player who modified the blacklist.

2. SteamID (string)

- The SteamID of the player whose blacklist were modified.

3. blacklistID (string)

- The ID of the blacklist that was modified.

4. blacklistTable (table)

- The blacklist table after it has been modified. (Check blacklist table structure for more information.)

Hook Return Values:

This hook has no return values.

Hook:

Hook Name:	jBlacklist_BlacklistsErased
Returns:	Nothing
Realm:	Server
Description	This hook will be called when someone erases all blacklists from someone.

Hook Parameters:

1. ply (player)

- The player who erased the blacklists.

2. SteamID (string)

- The SteamID of the player whose blacklists were erased.

Hook Return Values:

This hook has no return values.

Functions

Misc

Function:

Function Name:	PLAYER:IsBlacklisted( table blacklistTable )
Returns:	boolean isBlacklisted
Realm:	Server
Description:	This function will return a boolean if a player is blacklisted or not.

Function Arguments:

1. blacklistTable (table)

- The blacklistTable is created inside of custom blacklists and is used to identify which blacklist we want to check.

Function Return Values:

1. isBlacklisted (boolean)

- A boolean if the player is blacklisted from the provided blacklist or not. (true = Blacklisted - false = Not Blacklisted)

Function:

Function Name:	jBlacklist.FormatBlacklistTime( number Time)
Returns:	string formattedTime
Realm:	Shared
Description:	This function will return a formatted text of the given time. (Example: 1 hour and 10 minutes)

Function Arguments:

1. Time (number)

- The time in seconds that we want to format.

Function Return Values:

1. formattedString (string)

- The formatted time returned as a string. (Example: 1 hour and 10 minutes)

Function:

Function Name:	jBlacklist.RegisterBL( table blacklistTable )
Returns:	Nothing
Realm:	Shared
Description	This function will load a blacklist-type into the addon.

Function Arguments:

1. blacklistTable (table)

- The table holding all the information for the blacklist-type.

Function Return Values:

This function does not return anything.

Function:

Function Name:	jBlacklist.ShowBlacklistedPopup( player ply, table blacklistTbl )
Returns:	Nothing
Realm:	Shared
Description	This function will display in the lower right corner that the player tried doing something it was blacklisted from doing.

Function Arguments:

1. ply (player)

- The player we want to show the message to.

2. blacklistTable (table)

- The table holding all the information for the blacklist-type.

Function Return Values:

This function does not return anything.

Function:

Function Name:	jBlacklist.Log( string type, string title, string message )
Returns:	Nothing
Realm:	Server
Description	This function is used to log something.

Function Arguments:

1. type (string)

- The logging type. (Check logging enums for more information.)

2. title (string)

- The title of the logging message.

3. message (string)

- The message that we want to log.

Function Return Values:

This function does not return anything.

Configuration

Function:

Function Name:	jBlacklist.Configuration.AddConfig( string identifier, table tbl )
Returns:	Nothing
Realm:	Shared
Description:	This function will add a new configuration option to the configuration menu.

Function Arguments:

1. identifier (string)

- The identifier for the configuration-option and will be used to get it's value, etc.

2. tbl (table)

- The tbl will contain information about the configuration-option. (Check configtable structure)

Function Return Values:

This function does not return anything.

Function:

Function Name:	jBlacklist.Configuration.AddUserconfig( string identifier, table tbl )
Returns:	Nothing
Realm:	Shared
Description:	This function will add a new configuration option to the configuration menu for usergroups.

Function Arguments:

1. identifier (string)

- The identifier for the configuration-option and will be used to get it's value, etc.

2. tbl (table)

- The tbl will contain information about the configuration-option. (Check usergroups-configtable structure)

Function Return Values:

This function does not return anything.

Function:

Function Name:	jBlacklist.Configuration.GetConfigValue( string identifier )
Returns:	value configValue
Realm:	Shared
Description:	This function is used to get the configuration-value from a configuration-option.

Function Arguments:

1. identifier (string)

- The identifier for the configuration-option we want to get.

Function Return Values:

1. configValue (value)

- The requested configuration-value. (Datatype depends on how it was registered)

Function:

Function Name:	jBlacklist.Configuration.GetUsergroupConfigValue( player ply, string identifier )
Returns:	value configValue
Realm:	Shared
Description:	This function is used to get the configuration-value from a specific player depending on it's usergroup.

Function Arguments:

1. identifier (string)

- The identifier for the configuration-option we want to get.

2. ply (player)

- The player we want to get the configuration-value from.

Function Return Values:

1. configValue (value)

- The requested configuration-value. (Datatype depends on how it was registered)

Language

Function:

Function Name:	jBlacklist.RegisterLang( table lang )
Returns:	Nothing
Realm:	Shared
Description:	This function is used when creating a language to register the language in the addon.

Function Arguments:

1. lang (table)

- The language-table we want to register.

Function Return Values:

This function does not return anything.

Function:

Function Name:	jBlacklist.ChangeLang( string langName )
Returns:	Nothing
Realm:	Shared
Description:	This function is used to change the language of the addon. (Server and client can have different languages)

Function Arguments:

1. langName (string)

- The name of the language we want to change to.

Function Return Values:

This function does not return anything.

User Interaction

Function:

Function Name:	jBlacklist.Notify( number Type, string Message, player ply, boolean silent)
Returns:	Nothing
Realm:	Shared
Description:	This function is used to send a notification to a player.

Function Arguments:

1. Type (number)

- The notification-type we want to use. (Check notification-enums for more information.)

2. Message (string)

- The message we want to show.

3. ply (player)

- The player we want to show the message to. (Only needed serverside) (If left empty serverside, it will be broadcasted to everyone)

4. silent (boolean)

- This argument is optional but will limit the notification to usergroups that can see hidden messages. (Set the ply argument to nil if you want to set this to true and still broadcast it to all clients)

Function Return Values:

This function does not return anything.

Function:

Function Name:	jBlacklist.ConNotify( string Title, string Message )
Returns:	Nothing
Realm:	Shared
Description:	This function will print something to the console.

Function Arguments:

1. Title (string)

- The title we want for the message. (Such as INFO, ALERT, ERROR)

2. Message (string)

- The message we want to show.

Function Return Values:

This function does not return anything.

Function:

Function Name:	jBlacklist.DermaQuery( string subtitle, function confirmFunc, function cancelFunc)
Returns:	Nothing
Realm:	Client
Description:	This function is used to provide the client with a question. The client will then be able to confirm or cancel which then will call the corresponding function.

Function Arguments:

1. subtitle (string)

- The question we want to show to the client.

2. confirmFunc (function)

- The function we want to be called when a player press confirm.

3. cancelFunc (function)

- The function we want to be called when a player press cancel.

Function Return Values:

This function does not return anything.

Function:

Function Name:	jBlacklist.StringRequest( string subtitle, string default, function confirmFunc, function cancelFunc)
Returns:	Nothing
Realm:	Client
Description:	This function is used to provide the client with a question. The client will then be able to enter a text-input or press cancel.

Function Arguments:

1. subtitle (string)

- The question we want to show to the client.

2. default (string)

- The default value for the string-input shown to the player.

3. confirmFunc (function)

- The function we want to be called when a player press confirm. (Parameters: string text)

4. cancelFunc (function)

- The function we want to be called when a player press cancel. (Parameters: string text)

Function Return Values:

This function does not return anything.

Statistics

Function:

Function Name:	jBlacklist.Stats.GetIssued( function callbackFunc )
Returns:	Nothing (Check callbackFunc)
Realm:	Server
Description:	This function will return the total amount of issued blacklists.

Function Arguments:

1. callbackFunc (function)

- This function will be called when the information have been received. (Parameters: number Amount)

Function Return Values:

This function does not return anything. (Check callbackFunc above)

Function:

Function Name:	jBlacklist.Stats.GetRemoved( function callbackFunc )
Returns:	Nothing (Check callbackFunc)
Realm:	Server
Description:	This function will return the total amount of removed blacklists.

Function Arguments:

1. callbackFunc (function)

- This function will be called when the information have been received. (Parameters: number Amount)

Function Return Values:

This function does not return anything. (Check callbackFunc above)

Function:

Function Name:	jBlacklist.Stats.GetCommon( function callbackFunc )
Returns:	Nothing (Check callbackFunc)
Realm:	Server
Description:	This function will return the most common blacklist-type.

Function Arguments:

1. callbackFunc (function)

- This function will be called when the information have been received. (Parameters: string blacklistType)

Function Return Values:

This function does not return anything. (Check callbackFunc above)

Function:

Function Name:	jBlacklist.Stats.GetTop( function callbackFunc )
Returns:	Nothing (Check callbackFunc)
Realm:	Server
Description:	This function will return the SteamID of the player that have issued the most blacklists.

Function Arguments:

1. callbackFunc (function)

- This function will be called when the information have been received. (Parameters: string SteamID)

Function Return Values:

This function does not return anything. (Check callbackFunc above)

Function:

Function Name:	jBlacklist.Stats.GetPlayerStatistics( string steamID, function callbackFunc )
Returns:	Nothing (Check callbackFunc)
Realm:	Server
Description:	This function will return the total amount of blacklists and the most common blacklist from a player.

Function Arguments:

1. steamID (string)

- The steamID of the player we want to get statistics about.

2. callbackFunc (function)

- This function will be called when the information have been received. (Parameters: table result) (Table structure: {string Total, string Common})

Function Return Values:

This function does not return anything. (Check callbackFunc above)

Data Management

Function:

Function Name:	jBlacklist.DataMGT.SteamIDIsValid( string steamID )
Returns:	boolean isValid
Realm:	Server
Description:	This function will return a boolean if a function is valid or not.

Function Arguments:

1. steamID (string)

- The steamID we want to check.

Function Return Values:

1. isValid (boolean)

- The function will return true if the steamID was valid and return false if it was invalid.

Function:

Function Name:	jBlacklist.DataMGT.GetBlacklistTable( string steamID, number ID, function callbackFunc )
Returns:	Nothing (Check callbackFunc)
Realm:	Server
Description:	This function will return a specific blacklist or all blacklists from a player.

Function Arguments:

1. steamID (string)

- The steamID of the player we want to get the blacklists from.

2. ID (number)

- The blacklistID we want to get. (Set to nil to get the whole table.)

3. callbackFunc (function)

- This function will be called when the information have been received. (Parameters: value result, string reason) (Check blacklist result structure)

Function Return Values:

This function does not return anything. (Check callbackFunc above)

Function:

Function Name:	jBlacklist.DataMGT.GetBlacklistPage( string steamID, number page, function callbackFunc )
Returns:	Nothing (Check callbackFunc)
Realm:	Server
Description:	This function will return up to 20 blacklists at once. Starting from page 1 will return the last 20 blacklists.

Function Arguments:

1. steamID (string)

- The steamID of the player we want to get the blacklists from.

2. Page (number)

- The page of blacklists we want to get.

3. callbackFunc (function)

- This function will be called when the information have been received. (Parameters: value result, string reason) (Check blacklist result structure)

Function Return Values:

This function does not return anything. (Check callbackFunc above)

Function:

Function Name:	jBlacklist.DataMGT.AddBlacklist( table targets, table types, string reason, number length, string adminSteamID, function callbackFunc )
Returns:	Nothing (Check callbackFunc)
Realm:	Server
Description:	This function is used to add new blacklist to players.

Function Arguments:

1. targets (table)

- A table with all SteamIDs as strings that we want to add the blacklists to.

2. types (table)

- A table with all blacklist types as strings that we want to blacklist the players from.

3. reason (string)

- The reason for the blacklists.

4. length (number)

- The length of the blacklists in seconds.

5. adminSteamID (string)

- The SteamID of the administrator that issued the blacklists or CONSOLE if it was issued by the console.

6. callbackFunc (function)

- This function will be called when the action have been completed. (Parameters: value result, string reason)

Function Return Values:

This function does not return anything. (Check callbackFunc above)

Function:

Function Name:	jBlacklist.DataMGT.UpdateBlacklist( string SteamID, number blacklistID, table blacklistTable, function callbackFunc)
Returns:	Nothing (Check callbackFunc)
Realm:	Server
Description:	This function is used to modify the reason and length of the blacklist after it has been issued. (You will soon be able to modify the whole blacklist)

Function Arguments:

1. SteamID (string)

- The SteamID of the player whose blacklist we want modify.

2. blacklistID (number)

- The ID of the blacklist that we want to modify.

3. blacklistTable (table)

- The table that holds all the blacklist information. (Check blacklist table structure for more information.)

4. callbackFunc (function)

- This function will be called when the action have been completed. (Parameters: boolean success, string reason)

Function Return Values:

This function does not return anything. (Check callbackFunc above)

Function:

Function Name:	jBlacklist.DataMGT.RemoveBlacklist( string SteamID, number blacklistID, function callbackFunc )
Returns:	Nothing (Check callbackFunc)
Realm:	Server
Description:	This function is used to remove a blacklist from a player.

Function Arguments:

1. SteamID (string)

- The SteamID of the player whose blacklist we want to remove.

2. blacklistID (number)

- The ID of the blacklist that we want to remove.

3. callbackFunc (function)

- This function will be called when the action have been completed. (Parameters: boolean success, string reason) (NOTE: Success will still be true even if the blacklist wasn't found)

Function Return Values:

This function does not return anything. (Check callbackFunc above)

Function:

Function Name:	jBlacklist.DataMGT.EraseBlacklists( string SteamID, function callbackFunc )
Returns:	Nothing (Check callbackFunc)
Realm:	Server
Description:	This function is used to remove all blacklists from a player.

Function Arguments:

1. SteamID (string)

- The SteamID of the player whose blacklists we want to remove.

2. callbackFunc (function)

- This function will be called when the action have been completed. (Parameters: boolean success, string reason) (NOTE: Success will still be true even if no blacklists was found)

Function Return Values:

This function does not return anything. (Check callbackFunc above)

Hook Library

Function:

Function Name:	jBlacklist.AddHook( string eventName, string identifier, function func )
Returns:	Nothing
Realm:	Server
Description	This function works the same as hook.Add but will only add a hook on the server. It also gives the hook priority over other hooks. It should only be used when really necessary when other addons have a chance of breaking the script.

Function Arguments:

1. eventName (string)

- The name of the hook we want to add.

2. identifier (string)

- The identifier for the hook we want to add.

3. func (function)

- The function we want the hook to call.

Function Return Values:

This function does not return anything.

Function:

Function Name:	jBlacklist.RemoveHook( string eventName, string identifier )
Returns:	Nothing
Realm:	Server
Description	This function is used to remove hooks added with jBlacklist.AddHook.

Function Arguments:

1. eventName (string)

- The name of the hook we want to remove.

2. identifier (string)

- The identifier for the hook we want to remove.

Function Return Values:

This function does not return anything.

Function:

Function Name:	jBlacklist.GetHookTable( )
Returns:	table hooksTable
Realm:	Server
Description	This function is used to remove hooks added with jBlacklist.AddHook.

Function Arguments:

This function has no arguments.

Function Return Values:

1. hooksTable (table)

- A table of all hooks with the same structure as hook.GetTable.

SQL

Function:

Function Name:	jBlacklist.SQLQuery( string query, function onSuccess, function onError)
Returns:	Nothing
Realm:	Server
Description	This function is used to send a SQL query to the SQLite or MySQL database depending on what setting the user has. If you want to send different queries for SQLite and MySQL you can use the jBlacklist.UseSQL variable to make an if statement.

Function Arguments:

1. query (string)

- The query that we want to send to the SQLite or MySQL database.

2. onSuccess (function)

- This function will be called if the query is successfully sent to the SQL database. (Parameters: none empty, table result)

3. onError (function)

- This function will be called if the qyery failed. (Parameters: none empty, string error)

Function Return Values:

This function does not return anything.

Function:

Function Name:	jBlacklist.Escape( string value )
Returns:	string escapedValue
Realm:	Server
Description	This function is used to escape a value before it's used inside a query. It will call the corresponding escape function depending on if the addon is using SQLite or MySQL.

Function Arguments:

1. value (string)

- The string that we want to escape.

Function Return Values:

1. escapedString (string)

- The string that was entered as the value argument but escaped.

Developer API

General Information

Player Table Structure

Blacklist Table Structure

Blacklist Result Structure

Blacklist Module Structure

Logging Enumerations

Notification Enumerations

Hooks

Misc

Hook:

Hook Parameters:

Hook Return Values:

Hook:

Hook Parameters:

Hook Return Values:

Hook:

Hook Parameters:

Hook Return Values:

Hook:

Hook Parameters:

Hook Return Values:

Hook:

Hook Parameters:

Hook Return Values:

Hook:

Hook Parameters:

Hook Return Values:

Hook:

Hook Parameters:

Hook Return Values:

Hook:

Hook Parameters:

Hook Return Values:

Data Management

Hook:

Hook Parameters:

Hook Return Values:

Hook:

Hook Parameters:

Hook Return Values:

Hook:

Hook Parameters:

Hook Return Values:

Hook:

Hook Parameters:

Hook Return Values:

Hook:

Hook Parameters:

Hook Return Values:

Functions

Misc

Function:

Function Arguments:

Function Return Values:

Function:

Function Arguments:

Function Return Values:

Function:

Function Arguments:

Function Return Values:

Function:

Function Arguments:

Function Return Values:

Function:

Function Arguments:

Function Return Values:

Configuration

Function:

Function Arguments:

Function Return Values:

Function:

Function Arguments:

Function Return Values:

Function:

Function Arguments:

Function Return Values:

Function:

Function Arguments:

Function Return Values: