Difference between revisions of "Extension:MGet"

From Mario Fan Games Galaxy Wiki
m (Version Log: new version, well, there will be soon anyway)
Line 1: Line 1:
{{Notice|You might notice some discrepancies between results displayed through this extension on the wiki and those on the forums. This is being looked into.}}<br />{{Message
 
|colour=#0000dd
 
|image=File:Blue!box.gif
 
|title=Under Development
 
|description=This extension is heavily under development and drastic changes could take place at any point in the near future. Information shown is therefore liable to frequent change.}}
 
 
MFGG User Get is a Mediawiki extension written by [[Kyori]] and [[Char]]. It adds several magic words that are used to automatically update user information on the MFGG Wiki using data from the [[MFGG Forums]].
 
MFGG User Get is a Mediawiki extension written by [[Kyori]] and [[Char]]. It adds several magic words that are used to automatically update user information on the MFGG Wiki using data from the [[MFGG Forums]].
  
These magic words are used in the new MFGGer template, so it is no longer necessary to specify, or update, the badges or groups that a user currently has.
+
These magic words are used in the new MFGGer template, so it is no longer necessary to specify, or update, the badges or groups (or various other data) that a user currently has.
 +
 
 +
==Data==
 +
The data that the extension pulls from the forums consists of:
 +
*Username
 +
*Mainsite ID
 +
*Groups
 +
*Rank
 +
*Badges
 +
*Flag
 +
*Gender
 +
*Age
 +
*Location
 +
*Occupation
 +
*Interests
 +
*Website
 +
*Whether the user has certain IM clients
  
 
==Usage==
 
==Usage==
This section explains how to use each individual magic word. To omit an optional parameter, leave the section blank. If you wish to omit all optional parameters (or all after an optional parameter), you do not need to include the unneeded sections at all. For example:
+
This section explains how to use the extension (through the use of the 2 magic words). To omit an optional parameter, leave the section blank.  
<pre><nowiki>{{#badges:43||{{#order:4>2}}}}      //is valid
+
==={{#forumite}}===
{{#badges:43}}                      //as is this
+
This magic word instructs the extension to check for any information that it might have on a particular user, then to make that information available. The syntax is as follows:
{{#badges:43|{{#groupbadges:4=3}}}} //and this</nowiki></pre>
+
<pre><nowiki>{{#forumite: forumid}}</nowiki></pre>
===#groups===
+
Where <code>forumid</code> is the ID of the user on the MFGG forums.
The <code>groups</code> magic word pulls all of the groups that a particular user has. The usage is as follows:
+
 
<pre><nowiki>{{#groups:forum_id|[optional:group_order]|[optional:FLAG]}}</nowiki></pre>
+
If there is no information whatsoever on the user (i.e. the cache has not been updated) then the extension will return <code>"err01"</code>.
====Flags====
+
 
The <code>groups</code> magic word has flags that can be used to specify which groups to return. These are:
+
It should be noted that due to the probable long life of the cache (2-4 hours), information may not be available when you first use the magic word (meaning that there is no information in the cache related to the user ID that you are using). However, you can be confident in the fact that as soon as the cache expires and badges are viewed, all requested information will be updated.
*FIRSTONLY - only returns the group that would have been displayed first in the list.
 
*ALLBUTFIRST - returns all of the groups aside from the group that would have been displayed first in the list.
 
  
The usage for the flags is as follows:
+
==={{#field}}===
<pre><nowiki>{{#groups:756||FIRSTONLY}}</nowiki></pre>
+
This magic word allows the display of various user information which has been previously made available by the <code><nowiki>{{#forumite}}</nowiki></code> magic word. The syntax is as follows:
In this example, only the first group of user 756 would be returned (the list has also not been ordered, due to the omission of the group order parameter).
+
<pre><nowiki>{{#field: fieldname}}</nowiki></pre>
===#badges===
+
Where <code>fieldname</code> is the name of the field that you wish to display.
The <code>badges</code> magic word pulls all of the badges that a particular user has. It has 2 optional parameters, as well as requiring the forum ID of the user.
 
  
The usage for <code>badges</code> is as follows:
+
The names of the available fields are as follows:
<pre><nowiki>{{#badges:forumid|[optional:groupbadges]|[optional:badgeorder]}}</nowiki></pre>
+
<pre>user_id, badges, groups, primary_group, flag, site_id, icq, aim, yim, msnm, jabber, age, website, interests, occupation, location, rank, name, gender, pulled</pre>
There is no need to provide a mainsite ID; if the forum account has been linked with the mainsite, things like submitter badges will be automatically added to the forum badge table.
+
Most of those will be self explanatory, however some will need explaining.
 +
====icq, aim, yim, msnm and jabber====
 +
These do not return the addresses ofr the user on the respective instant messaging network, but instead return either true or false (in actuality, 1 or 0) if the user ''has'' an account on the network in question or not, respectively.
 +
====name====
 +
This is the username of the user in question, not their actual name.
 +
====pulled====
 +
This is either true or false depending on whether the extension has pulled information from the forums about this user or not.
 +
==={{#field}} for arrays===
 +
Some of the variables (badges and groups) that can be shown through the use of this magic word are arrays. This magic word allows a certain amount of flexibility in displaying arrays over displaying non-arrays.
 +
====prefixes and suffixes====
 +
A prefix and a suffix may be affixed to each top-level member of an array. The syntax is as follows:
 +
<pre><nowiki>{{#field:fieldname|prefix|suffix}}</nowiki></pre>
 +
Where <code>prefix</code> and <code>suffix</code> are the specified prefix and suffix.
 +
====delimiters====
 +
Delimiters may be used to separate each member of the array any deeper than top-level. By default, a comma (<code>,</code>) will be used to separate them, but this will likely be confusing for any array with more than 2 dimensions (as any further dimensions become impossible to differentiate between). Multiple delimiters can be specified as such:
 +
<pre><nowiki>{{#field:fieldname|prefix|suffix|delimiter1|delimiter2|delimiter3| ... | delimitern}}</nowiki></pre>
 +
Where <code>delimiter1, delimiter2, etc.</code> are the chosen delimiters for the increasing dimensions of the array.
 +
====An example====
 +
This is an example of how to use this magic word for arrays (code taken from the MFGGer template badge section):
 +
<pre><nowiki>{{#field:badges|{{dd}}Badge{{!}}|{{!}}auto=true{{bb}}|{{!}}}}</nowiki></pre>
 +
Where <code><nowiki>{{dd}}</nowiki></code> and <code><nowiki>{{bb}}</nowiki></code> are templates that return <nowiki>{{</nowiki> and <nowiki>}}</nowiki> respectively, and <code><nowiki>{{!}}</nowiki></code> is a template that returns <nowiki>|</nowiki>. These templates are necessary due to the way that mediawiki handles the parsing of parser functions (like this magic word) and templates. When expanded and inserted back into the above example, it would look like this:
 +
<pre><nowiki>{{#field:badges|{{Badge||}}||}}</nowiki></pre>
 +
Which, when submitted to the parser, would completely confuse it (or at least, there'd be some confusion between what we want from the parser and what we're actually going to get!).
  
It should be noted that due to the probable long life of the cache (2-4 hours), badges may not display when you first use the magic word if there is no information in the cache related to the user ID that you are using. However, you can be confident in the fact that as soon as the cache expires and badges are viewed, all requested badges will be updated.
+
In the example, the following parameters are given to the extension:
 +
*Field name = badges
 +
*Prefix = <code><nowiki>{{dd}}Badge{{!}}</nowiki></code> or <code><nowiki>{{Badge|</nowiki></code> (the beginning of the MFGG Badge template call)
 +
*Suffix = <code><nowiki>{{!}}auto=true{{bb}}</nowiki></code> or <code><nowiki>}}</nowiki></code>  (the end of the badge template call, auto=true tells the Badge template to do a little bit of extra formatting when dealing with parameters that it's passed, to make it easier to change things around without breaking functionality)
 +
*Delimiters = <code><nowiki>{{!}}</nowiki></code> or <code><nowiki>|</nowiki></code> (a wiki pipe character, used to separate parameters in template calls)
  
====#groupbadges====
+
The badge variable returns a 2 dimensional array, so only one delimiter is required. This array consists of a top level filled with "badges", which are, in and of themselves, arrays of 2 variables (the badge ID, and the amount of badges of that type). So when the extension returns this array, it wraps each "badge" in the prefix and suffix (the beginning and end of the Badge template call) then, in between them, it lists the members of the next level down (the ID and amount) separated by the delimiter (the pipe character). An example of a returned set of badges is as follows:
The <code>groupbadges</code> magic word is used to parse a correctly formatted string into an array and then serialize it for use with the <code>badges</code> magic word to add group specific badges to a users badge list. Examples of this are {{Badge|mod}} and {{Badge|sysop}}. The syntax for this magic word is as follows:
+
<pre><nowiki>{{Badge|12|3|auto=true}}{{Badge|5|1|auto=true}}{{Badge|35|10|auto=true}}</nowiki></pre>
<pre>{{#groupbadges:groupid1=badgeid4,groupid2=badgeid15,groupid6=badgeid22=DEFAULTONLY}}</pre>
+
Which would give you...
In this case, if the user was in groupid1 (i.e. a group with the id "groupid1") he would recieve badgeid4, the same case with groupid2 and badgeid15. However, even if the user was in groupid6, if groupid6 is not set as their ''primary'' group, they will not recieve badgeid22. The DEFAULTONLY flag sets the badge to only be available to those members which have the relevant group set as their ''primary'' (or "default") group.
+
{{Badge|31|3|auto=true}}{{Badge|26|1|auto=true}}{{Badge|17|10|auto=true}}
===#order===
+
...when the parser expands the templates.
The <code>order</code> magic word is used to parse a correctly formatted string into an array and then serialize it for use with both the <code>badges</code> and <code>groups</code> magic words to order their results. The syntax is as follows:
 
<pre><nowiki>{{#order: id1 > id2 > id4 > id3}}</nowiki></pre>
 
In this example, if the user had badges/was in groups with IDs id1, id3 and id4; they would be displayed in the order id1, id4, id3. If there were additional badges/groups that were not mentioned using the <code>order</code> keyword, they would be appended to the end of the ordered badges/groups.
 
 
==Method==
 
==Method==
 
When the extension is called, it checks whether the cache has expired (the cache lifetime is specified with <code>$wgMFGGBadgesCacheTime</code>).
 
When the extension is called, it checks whether the cache has expired (the cache lifetime is specified with <code>$wgMFGGBadgesCacheTime</code>).
Line 66: Line 97:
 
$wgMFGGBadgesSecurityCode;
 
$wgMFGGBadgesSecurityCode;
 
</syntaxhighlight>
 
</syntaxhighlight>
 
==CACHE EMPTY==
 
This message will display in place of the group information if the cache has no data on that particular user. It is formatted as following:
 
<pre>CACHE EMPTY
 
1 h 23 m 56 s
 
Time until recache.</pre>
 
In this example, the extension will recache (request all needed information from the forum server, and cache it) in 1 hour, 23 minutes and 56 seconds.
 
  
 
==Version Log==
 
==Version Log==

Revision as of 15:45, 23 August 2010

MFGG User Get is a Mediawiki extension written by Kyori and Char. It adds several magic words that are used to automatically update user information on the MFGG Wiki using data from the MFGG Forums.

These magic words are used in the new MFGGer template, so it is no longer necessary to specify, or update, the badges or groups (or various other data) that a user currently has.

Data

The data that the extension pulls from the forums consists of:

  • Username
  • Mainsite ID
  • Groups
  • Rank
  • Badges
  • Flag
  • Gender
  • Age
  • Location
  • Occupation
  • Interests
  • Website
  • Whether the user has certain IM clients

Usage

This section explains how to use the extension (through the use of the 2 magic words). To omit an optional parameter, leave the section blank.

{{#forumite}}

This magic word instructs the extension to check for any information that it might have on a particular user, then to make that information available. The syntax is as follows:

{{#forumite: forumid}}

Where forumid is the ID of the user on the MFGG forums.

If there is no information whatsoever on the user (i.e. the cache has not been updated) then the extension will return "err01".

It should be noted that due to the probable long life of the cache (2-4 hours), information may not be available when you first use the magic word (meaning that there is no information in the cache related to the user ID that you are using). However, you can be confident in the fact that as soon as the cache expires and badges are viewed, all requested information will be updated.

{{#field}}

This magic word allows the display of various user information which has been previously made available by the {{#forumite}} magic word. The syntax is as follows:

{{#field: fieldname}}

Where fieldname is the name of the field that you wish to display.

The names of the available fields are as follows:

user_id, badges, groups, primary_group, flag, site_id, icq, aim, yim, msnm, jabber, age, website, interests, occupation, location, rank, name, gender, pulled

Most of those will be self explanatory, however some will need explaining.

icq, aim, yim, msnm and jabber

These do not return the addresses ofr the user on the respective instant messaging network, but instead return either true or false (in actuality, 1 or 0) if the user has an account on the network in question or not, respectively.

name

This is the username of the user in question, not their actual name.

pulled

This is either true or false depending on whether the extension has pulled information from the forums about this user or not.

{{#field}} for arrays

Some of the variables (badges and groups) that can be shown through the use of this magic word are arrays. This magic word allows a certain amount of flexibility in displaying arrays over displaying non-arrays.

prefixes and suffixes

A prefix and a suffix may be affixed to each top-level member of an array. The syntax is as follows:

{{#field:fieldname|prefix|suffix}}

Where prefix and suffix are the specified prefix and suffix.

delimiters

Delimiters may be used to separate each member of the array any deeper than top-level. By default, a comma (,) will be used to separate them, but this will likely be confusing for any array with more than 2 dimensions (as any further dimensions become impossible to differentiate between). Multiple delimiters can be specified as such:

{{#field:fieldname|prefix|suffix|delimiter1|delimiter2|delimiter3| ... | delimitern}}

Where delimiter1, delimiter2, etc. are the chosen delimiters for the increasing dimensions of the array.

An example

This is an example of how to use this magic word for arrays (code taken from the MFGGer template badge section):

{{#field:badges|{{dd}}Badge{{!}}|{{!}}auto=true{{bb}}|{{!}}}}

Where {{dd}} and {{bb}} are templates that return {{ and }} respectively, and {{!}} is a template that returns |. These templates are necessary due to the way that mediawiki handles the parsing of parser functions (like this magic word) and templates. When expanded and inserted back into the above example, it would look like this:

{{#field:badges|{{Badge||}}||}}

Which, when submitted to the parser, would completely confuse it (or at least, there'd be some confusion between what we want from the parser and what we're actually going to get!).

In the example, the following parameters are given to the extension:

  • Field name = badges
  • Prefix = {{dd}}Badge{{!}} or {{Badge| (the beginning of the MFGG Badge template call)
  • Suffix = {{!}}auto=true{{bb}} or }} (the end of the badge template call, auto=true tells the Badge template to do a little bit of extra formatting when dealing with parameters that it's passed, to make it easier to change things around without breaking functionality)
  • Delimiters = {{!}} or | (a wiki pipe character, used to separate parameters in template calls)

The badge variable returns a 2 dimensional array, so only one delimiter is required. This array consists of a top level filled with "badges", which are, in and of themselves, arrays of 2 variables (the badge ID, and the amount of badges of that type). So when the extension returns this array, it wraps each "badge" in the prefix and suffix (the beginning and end of the Badge template call) then, in between them, it lists the members of the next level down (the ID and amount) separated by the delimiter (the pipe character). An example of a returned set of badges is as follows:

{{Badge|12|3|auto=true}}{{Badge|5|1|auto=true}}{{Badge|35|10|auto=true}}

Which would give you...

Santa.png
Countersx.gifCounters3.gif
Awards08.png
Dct.png
Countersx.gifCounters1.gifCounters0.gif

...when the parser expands the templates.

Method

When the extension is called, it checks whether the cache has expired (the cache lifetime is specified with $wgMFGGBadgesCacheTime).

  • If the cache hasn't expired, the extension adds the requested user ID to a cached list of user IDs.
  • If the cache has expired, the extension makes a POST request containing an array of the previously cached user IDs to a script in the forum directory, which then queries the database for the information for those users. The script returns the information and the extension caches it in a local file.

The script then sorts through the information (either from the cache or from a request) and finds the requested user information, then returns them in the correct template format.

For badges:

{{Badge|id|count|auto=true}}

For groups:

{{MemberType|id|auto=true}}

Note: auto is set to true so that the templates know to run specific formatting on the results.

Configuration Variables

These are the various settings that can be modified in LocalSettings.php.

# Address of the forum badge get script
$wgMFGGBadgesReadFileAddress;
# Number of seconds that the cache should live for (set to 4 hours (14400 seconds) by default)
$wgMFGGBadgesCacheTime;
# Security code to be provided to the forum script
$wgMFGGBadgesSecurityCode;

Version Log

  • v0.0.1 - Not in general usage due to being just a little bit buggy!
  • v0.1.0 - Badges and groups working.
    • v0.1.1 - Changed "error" message for empty cache to display time to recache.
    • v0.1.2 - Wiki caching disabled for pages using the extension, bug with default groups on Guinea, Char and Kyori articles (not fixed).
  • v0.2.0 - Complete rewrite. Now caches in wiki database instead of in filesystem. Pulls more information from server, and more cleverly calculates needed groups and badges.