User:Kit Lywait/WikiBhasha - Customizations and Extensibility Guide

This document describes the customization and extensibility points of WikiBhasha. Intended audience is developers who want to tweak WikiBhasha to add features and to modify current behavior. Many of these extensions are customizations are based on JSON and javascript. Good knowledge of JSON and Javascript are required for making correct changes.

Extending or customizing workflow steps

The current UI shows 3 steps with various panes in each step. The number of steps and what is displayed in each pane can be customized or extended by changing the specification in the file WikiBhasha/js/core/configurations.js. Steps (number, order, text etc), and panes with each step are declared in JSON format in file WikiBhasha/js/core/configurations.js.
Below is example content for current UI with three pane workflow:

// describes the configuration for application workflow steps.

wikiBhasha.configurations.defaultWorkFlow = {

   //configuration for each step that is part of application workflow
   steps: {
       step1: {
           //display order of the given step from left to right
           displayOrder: 0,
           //name of the step displayed on the button
           buttonText: "Collect",
           //tooltip text to be displayed when user mouse hovers on button
           buttonTooltipText: "Collect content from multiple resource articles",
           //class names of button when button is in normal or active states
           buttonStyleNormal: "wbCollectNormal",
           buttonStyleActive: "wbCollectActive",
           //configuration of panes display data
           panesData: [
           //configuration for left hand side(LHS) pane
                       {
                       //assign one of the pane available in 'wb.paneManagement'
                       pane: "#wbSourceOriginalArticlePane",
                       //format of the title to be displayed as pane title
                       title: "{sourceArticleTitle} ({sourceLanguage}, read only)",
                       //default title to be displayed
                       defaultTitle: "English Article (Original, read only)",
                       //theme style to be applied on pane title bar
                       titleBarThemeStyle: "wbLightYellowTitleBar"
                   },
           //configuration for right hand side(RHS) pane
                       {
                       pane: "#wbSourceTranslatedArticlePane",
                       title: "{sourceArticleTitle} ({sourceLanguage}->{targetLanguage}, editable)",
                       defaultTitle: "English Article (Translated, editable)",
                       //is pane data editable or not
                       isContentEditable: true,
                       titleBarThemeStyle: "wbLightYellowTitleBar"
                   }
                   ]
       },
       step2: {
           displayOrder: 1,
           buttonText: "Compose",
           buttonTooltipText: "Compose all the collected content to the target article",
           buttonStyleNormal: "wbComposeNormal",
           buttonStyleActive: "wbComposeActive",
           panesData: [
                       { pane: "#wbSourceTranslatedArticlePane", title: "{sourceArticleTitle} ({sourceLanguage}->{targetLanguage}, corrected & read only)", defaultTitle: "English Article (Translated, read only)", isContentEditable: false, titleBarThemeStyle: "wbLightYellowTitleBar" },
                       { pane: "#wbTargetContentPane", title: "{targetArticleTitle} ({targetLanguage}, editable)", defaultTitle: "Target Language Article (editable)", isContentEditable: true, titleBarThemeStyle: "wbLightBlueTitleBar" }

           //Following describes various future enhancements that can be implemented to 
           //populate the different types of data for panes.            
           /*
           //To set some HTML text into the pane we can think of supporting following format

{html:"

This is some test content

"},

           //To set some data from external API call then we can think of supporting following format
           //Example:
           //This API should support "callback" mechanism with JSON format
           {api:"http://fr.wikipedia.org/w/api.php?&action=query&titles=Microsoft&rvprop=content&prop=revisions&redirects=1&format=json",
           //callback function to handle the JSON data returned by JSONP api
           callback:function(data) {
           var pages = data.query.pages;
           for(var i in pages) {                                        
           return pages[i].revisions[0]["*"];   
           }                       
           }
           }*/
           ]
       },
       step3: {
           displayOrder: 2,
           buttonText: "Publish",
           buttonTooltipText: "Publish the composed article content to Wikipedia",
           buttonStyleNormal: "wbPublishNormal",
           buttonStyleActive: "wbPublishActive",
           panesData: [
                       { pane: "#wbTargetArticleComposeDiv", title: "{targetArticleTitle} ({targetLanguage}, editable)", defaultTitle: "Target Language Wikipedia Edit Page", isEditable: false }
                   ]
       }
   },

   //default configurations of application workflow
   config: {
       //default step to load on application launch
       currentStep: 0,        

       // Describes behavior when target language article is loaded as one of sourcing articles for building content.
       // Target language article can be loaded on source pane by clicking on target language results in search results
       // or by clicking links on target language article.
       onTargetLanguageContentLoadAsResourcePage: {
           defaultStep: 1,
           invalidSteps: { 0: true },
           newPaneTitles: { "#wbSourceTranslatedArticlePane": "{sourceArticleTitle} ({targetLanguage}, read only)" }
       },

       // Describes behavior when source language article is loaded as one of sourcing articles for building content. 
       onSourceLanguageContentLoadAsResourcePage: {
           defaultStep: 0
       },

       // Describes which are all the steps that need to be considered to enable links for a translated source article content        
       onSourceArticleTranslatedContentLinksClicked: {
           stepsToConsider: { 1: true },
           //which language to target for searching the clicked link title
           languageCodeToChoose: "targetLanguageCode" //Possible values: 'sourceLanguageCode' OR 'targetLanguageCode'
       },

       // Describes which are all the steps that need to be prevented from navigation while translation is going on.
       // this applies only to new articles for better usability
       preventNavigationToStepsDuringTranslationForNewArticle: {
           stepsToPrevent: { 2: true }
       },

       //When the user invokes WikiBhasha from a target language article for which there is no corresponding article 
       //in source language, we would like to load WikiBhasha in step 2 as we don’t have anything to show in step1. 
       //The below code portion defines this behavior.
       onSourceArticleAbsence: {
           defaultStep: 1
       }
   },
   //array to hold the steps data
   stepsArray: []

};

WikiBhasha.workFlow.steps is an object with list of steps defined. Each step provides a displayOrder, buttonText and panesData. PanesData is an array where each element defines a vertically separated pane with content defined in one of below ways:

• Predefined panes: Predefined pane has predefined system behavior. The current defined panes are:

 * #wbSourceOriginalArticlePane: This shows the source article in side-by-side mode in both English and target language. It also works with “visited topics” history tracking.

 * #wbSourceTranslatedArticlePane: This shows source article wikimarkup in highlighted wikimode and rendered wikimode based on “hide wikimarkup” checkbox setting.

 * #wbTargetContentPane: This shows target article wikimarkup in highlighted wikimode and rendered wikimode based on “hide wikimarkup” checkbox setting.

 * #wbTargetArticleComposeDiv: This shows Wikipedia article submit page in an iframe. It also removes menus from left hand side to show clean view of compose area.

• HTML content: Html custom content can be specified in html:<html content> format

• Ajax API with callback: An URL for ajax call can be specified with callback function that does complex processing and returns an array of panes. See the customizations file for an example.

For example, suppose that the community prefers just one step with source view on left side and compose area on right side. The example configuration could look like below:

 step1: {
 buttonText:"this text will not be show as there is only one step",
 panesData: [{pane:"#SourceHybridViewPane", title: "English Wikipedia Article (Translated)", isEditable:false}, 
   {pane:"#ComposePane", title: "Target Language Wikipedia Edit Page", isEditable:true} ]
 }

Extending right click context menu

When user right clicks on some text in WikiBhasha, a context menu is shown with various tools that the user can use to make the translation task easier. By default, scratch pad and community reference tools are shown. The list of tools is customizable and new tools can be added to the list. Below is example of adding bing search as one of options. The options for customization are self-explanatory. This extension is available for change in WikiBhasha/js/core/configurations.js file. // describes configuration for bing search menu item wikiBhasha.configurations.defaultContextMenuItems["bingSearch"] = {

   "itemId":"bingSearch",
   "itemIcon":{ "iconSrc":"http://www.bing.com/s/wlflag.ico", "iconWidth":"16", "iconHeight":"16"},
   "itemText": "Bing Search (Alt+Ctrl+b)",
   "onClick": function() {
       //make sure not to nullify the user selected text
       var selectedText = wbUIHelper.getSelectedText() || wbContextMenuHandler.lastSelectedText;
       window.open("http://www.bing.com/search?q=" + encodeURIComponent(selectedText) );
   },
   "shortCutKey": "Alt+Ctrl+b"

};

Extending Wikipedia template translations with parameters

WikiBhasha will translate templates from source article to target article automatically if there is equivalent template in target article and if there are no parameters used in source article. If this is not the case, a custom template translation can be defined by editing the template configuration file WikiBhasha/js/core/configurations.templateMappers.js. Below is example content from that file: <templateMapBetweenLangPair srcLang="en" tgtLang="hi">\

   <templateMap srcTemplateName="Age in weeks" tgtTemplateName="उमर_सप्ताह_मे">\
       <param srcTemplateParamName="month1" tgtTemplateParamName="महिना1"/>\
       <param srcTemplateParamName="day1" tgtTemplateParamName="दिन1"/>\
       <param srcTemplateParamName="year1" tgtTemplateParamName="साल1"/>\
       <param srcTemplateParamName="month2" tgtTemplateParamName="महिना2"/>\
       <param srcTemplateParamName="day2" tgtTemplateParamName="दिन2"/>\
       <param srcTemplateParamName="year2" tgtTemplateParamName="साल2"/>\
   </templateMap>\

</templateMapBetweenLangPair>\

WikiBhasha. configurations.templateMappers is an object with many template mapper objects. One template mapper object is defined for each source and target language pairs. The from-language and to-language are listed in parameters FromLang and ToLang. The mappers array contains the mapping of template names and also the mapping of parameters. Once a template mapping is provided, WikiBhasha will automatically translate the mapped templates from source article to target article as part of machine translation.