Wikipédia:LiveRC/Documentation/Extensions/en

LiveRC

Documentation

ToDo

Sources

Extensions

Traductions

Newsletter

Discussion

Introduction

Since version 0.4.2, LiveRC source code provides hooks to add extensions. Theses hooks allow external functions to be executed in some points of the process, modifying the way that LiveRC is running.

Existing hooks

There are now (version 1.0.5 ^m) 36 hooks. They are named following the point where the functions they contain are to be executed.

See the lixt to the right.

Some hooks have special particularities :

• functions executed through "BeforeRC" must return a value true. If one of them do not, the RC request is aborted. This can be used to do another request instead.
• functions executed through "AfterRC" have an array parameter, witch contain the id attribute of the added line (tag <tr> ) and all infos about the RC line (state, title, user, warnings, etc...). Note : this element may not exist as it can have been deleted before the hook.
  • Example :

function MyFunc(Args){
  var ElementTrId = Args.id;
  var rcInfos = Args.rc;
}
LiveRC_AddHook("AfterRC", MyFunc);

• functions executed through a post-preview hook ("AfterPreview?????") had an array parameter. This array is equal to the data variable, avaiable after the request success. So it contain all necessary variables for the preview display. Their name and number depends on the preview type that the hook is targeting.
  • Example :

function MyFunc(Args){
  var PageName = Args.page;  
  var User = Args.user;
  var Url = Args.url;
}
LiveRC_AddHook("AfterPreviewArticle", MyFunc);

Syntax

To add a function in a hook, the syntax is :

LiveRC_AddHook("type", func);

• "type" : hook type, one of the values above.
• func : the function to be executed by the hook.

To prevent extension displaying errors on other pages than LiveRC page, it is necessary to test it. The easiest way is to test the existence of the global variable that contain all hooks, lrcHooks. The right syntax is :

if (typeof(lrcHooks)!="undefined") {
    LiveRC_AddHook("type", func);
}

Theses extensions have to be added in User:<YOUR-NAME>/LiveRCparam.js. They can be written directly in it or added through an importScript() or an importScriptURI() function.

Usefull variables and functions

• lrcExtensions : list of extensions that can be added to LiveRC through the customization panel. To add an extension in this list, you must ask to a sysop and/or on LiveRC talk page.
• lrcIcons : array that contain all icons. It is possible to add some.
• lrcTexts : array containing all texts. It is possible to add new entries on this array or to create a new array for text variable of the extension
• lrcParamDesc : array that containt descriptions for other variables. If some variables of the extension are customizable through the LiveRC customization panel variable, their description can be added here. Nota : if the description is not added, the default description will be "<VariableName>", just like unset mediawiki system messages.
• LiveRC_addNeededMessages(MessageName) : function that permit to add a system messages needed by LiveRC. If an extension needs a system message that is not in that list, it is necessary to add it, in order to permit LiveRC to do a request to get its value. Example :

LiveRC_addNeededMessages("MessageName");

• LiveRC_ManageParams_Fill(OptionArray, ArrayName, FunctionName, AddButton) : this function permit to add an array variable to the customization panel. That will create a new tab. Must be used with "AfterFillParamPanel" hook.
  • OptionArray = Array name;
  • ArrayName = Array name, between guillemets;
  • FunctionName = function used to set the variable (if AddButton is true) or a variable item (if AddButton is false or not set) (optionnel, set to false to define the variable or the item directly)
  • AddButton = true if the variable needs (+) or (-) links, to add or delete items (like in tag or warn templates).
  • Example :

function AddParamToVariableThree(item, value){
  VariableThree[item] = value;
}
function AddParamToVariableFour(value){
  VariableFour = value;
}
LiveRC_AddHook("AfterFillParamPanel", function(){
    LiveRC_ManageParams_Fill(VariableOne, "VariableOne");
    LiveRC_ManageParams_Fill(VariableTwo, "VariableTwo", false, true);
    LiveRC_ManageParams_Fill(VariableThree, "VariableThree", "AddParamToVariableThree");
    LiveRC_ManageParams_Fill(VariableFour, "VariableFour", "AddParamToVariableFour", true);
});

• LiveRC_ManageParams_CreateNewListMenu(menuname, buttons, columns) : this function permit to add a new tab to the customization panel. This function return the <ul> where things that can be enumerated. Can be used with the "AfterCreateParamPanel" hook. IMPORTANT : this tab will not be taken in account when saving params in standards tabs. A specific function must be created to do so.
  • menuname = codename of the tab. A new item in the variable lrcParamDesc can be set to give the text of the tab and the title of this particular panel.
  • buttons = control buttons to be added at the beginning of the panel (save params, close panel, etc...). LiveRC expect a "node" object
  • columns = number of columns of the <ul> containing the panel list (to add after)
  • Example :

LiveRC_AddHook("AfterCreateParamPanel", function(){
    var Button = document.createElement('input');
    Button.type = "button";
    Button.value = "My button";
    var MyNewMenu = LiveRC_ManageParams_CreateNewListMenu("MySpecialMenu", Button, 2);
    MyNewMenu.innerHTML = "<li>My Menu Content</li>";
});
lrcParamDesc["DescMySpecialMenu_short"] = "My new menu";
lrcParamDesc["DescMySpecialMenu"] = "My new menu description";