The Log
The Log
Each time myCred gives or takes points from a user on your website, the transaction is logged in a dedicated table that myCred installs in your database. Besides serving as a record of the transaction that you might show to your users for accountability, the log is also used to enforce limits or to reward e.g. badges.
Depending on your setup, the log is saved under the id prefix_mycred_log. If you are using multisite and not using the Central Log feature, each site gets its own log table. You can change the log ID using the MYCRED_LOG_TABLE constant.
No Log Entry = No points
As a rule of thumb, throughout myCred, any feature that provides you with the option to set a log entry template, template can not be empty! myCred will decline all transactions that do not have a log entry for accountability. So if you have setup a feature to give/take points and nothing is happening, you should always start by checking and making sure the log entry template (if there is one) is not empty!
Structure
Besides the textual representation of the log entry, which describes why points were taken / given, myCred also logs a few additional sets of data with each entry. These extra details are used not just to tie the log entry to a particular user but also to add support for Dynamic Log Entries and information to help enforce limits.
Figure 1. Log column structure.
| Column Name | Type | Description | Example Usage |
|---|---|---|---|
id
|
int |
ID Unique identifier for each log entry. Auto incremented by your database to prevent duplicate ids. Mainly used to identify a specific log entry. |
- |
ref
|
string |
Reference The reference identifies the event that triggered this log entry. myCred uses a large range of unique references to help identify particular events. References are lowercase and use underscores instead of empty spaces. Note that myCred uses santize_key for reference sanitizations. References are also descriptive to help quickly identify the event e.g. |
Badges myCRED Badges are based on a users points history and when you setup a badge, you select the reference for which the badge is awarded. This is what the badge-on looks for when calculating if a user gets a badge or not. |
ref_id
|
int |
Reference ID While the reference helps us identify the event, the reference ID allows us to further specify our search. As only integers can be used as a reference ID, it is usually used to store object IDs, e.g. the Post ID for which a user got points for getting published. |
Hooks Hooks use the reference ID to make sure points are only awarded once per unique event e.g. points for publishing a content. If the content is unpublished then re-published the hook will not payout as there will be a log entry with that posts ID as reference ID. |
user_id
|
int |
User Identification This is used to reference which user the log entry belongs to. |
Get Users History The mycred_history shortcode can be set to show log entries for a particular user instead of everyones. In that case, the user_id is used to filter results. |
creds
|
int or float |
The Points A positive value for point gains and a negative value for point loses. This column supports an integer or floats, depending on your point setup. If you set to use decimals then values here are floats (stored as DOUBLE). |
Total Balance Used to calculate a users total balance in conjunction with |
ctype
|
string |
The Point Type Key Identifies what point type was used. The default point type key is |
Multiple Point Type History When using multiple point types and viewing your Log in the admin area, each separate log shows results from the same log but filtered accordingly to the point type. |
time
|
int |
Time Unix timestamp of the log entry insertion or the event triggering the entry insertion. |
Hook Limits Used to help calcualte the number of times a user has gained / lost points in a specific instance to make sure they are not over a set limit based on a timeframe. |
entry
|
string |
Log Description The entry contains the description of the log entry that is shown to users and to admins in the admin area. Can contain html all though I recommend using template tags. |
Everything Unless an administrator edits a users balance without adding a log entry, every single event uses this to insert some sort of information. |
data
|
string |
Additional Information Not visible anywhere, this column is generally used to store extra information for events, usually in a form of a serialized array. |
Hooks Hooks that support template tags in the log entry uses this column to store the type of template tags that are supported and can be used when the log entry is rendered. |
* You can use the MYCRED_DEFAULT_KEY constant to change the default point type. It must be used before the database is installed in order for its value to be set in the database as the default. If not, it will default to mycred_default.
myCred does not allow log entries of zero points! Zero points are interpreted by myCred as “feature is disabled” and will refuse to save the log entry.
While you can add zero point entries via e.g. the $wpdb class, the functions myCred provides for adding log entries will require that you provide a reference, point amount, user ID, and log entry.
Showing the Log
By default, myCred only shows the log in the wp-admin area of your website. Users can access their own history in the wp-admin area under the “Profile” menu but for front-end access, the mycred_history shortcode or the Balance widget must be used.
Administration
Administrators and “Points Editors” can access the myCred log in the admin area. myCred will create a unique log page for each point type you have set up and will only show log entries for that particular point type. There is no admin screen where you can see all log entries no matter the point type.
As of version 1.6, administrators can edit log entries while as of version 1.7, the reference and amount can also be changed.
Dynamic Log Entries
Dynamic Log Entries allows you to always show the current title of for example a post that a user received points for. DLEs are an optional feature where you use Template Tags to represent details about the post/user / comment the log entry is connected to. These template tags are replaced with their current value each time a user views the log entry. This is particularly useful if you need to reference titles/links that are always current.
As an example, let’s say you want to give your users points for publishing content. In the log entry, we want to show the title and a link to the post that the points were given for. If we were to hardcode the title and URL into the log entry, the URL would become useless if the post later changes the title or URL. The log entry would still point to the old title and link. Using template tags, you eliminate this since the title and URL will always be shown as they currently are.
Again, DLEs are optional. If you prefer to use more generic language that does not need template tags, you are free to do so.
| Type | Description |
|---|---|
| General | General template tags, e.g. Singular or plural format of the point type names etc. |
| Post | Post related template tags, e.g. Post Title, Post Title with link etc. |
| Comment | Comment related template tags, e.g. Comment ID, Comment post title or link etc. |
| User | User related template tags, e.g. Username, Username with profile link etc. |
| Amount | Amount related template tags, e.g. show points formatted or unformatted. |
