How to make a plugin for IE7Pro

From IE7Pro WiKi

[edit] Introduction

To make a JavaScript plug-in for IE7Pro, you must:

- Know a little JavaScript of another language programming (JavaScript is easy!)
- Understand the Document Object Model of IE (and others browsers)
- Can using an notepad (such Notepad++ or Notepad.exe)

This tutorial is very easy but demonstrates only the basis features of the plug-ins and can teach you like writing a research papers. Naturally, you can learn more information about the plug-in on the IE7Pro Web Site.

Regards,

FremyCompany

[edit] The common architecture

[edit] The root directory

To start a plug-in, I recommended you to create a directory in the /plugins.

The name of this directory should be the same that the name you'll give to your plug-in, but it's not very important.

[edit] The PLUGIN.JS file

In this directory, put a plugin.js file. The content of all plug-ins should begin with this:

// ==UserScript==
// @name          PluginName (by Author)
// @namespace     http://iescripts.org/
// @description   MoreInfo
// @statussize    Size of the plugin (ie: 16)
// ==/UserScript==

(function() {
    // Localize the URL's path
    function fpath(url) { return "ie7pro://pluginpath/"+url; }
    
    // Content all the PLUGIN API
    var plugin = PRO_plugin(@name);
    
    // Used to know which icon is currently used
    var getIcon = function() {
        return "ie7pro://pluginpath/bg.png";
    }
    // Used to set the icon of the plugin
    function setIcon(url) {
        plugin.setStatusIcon(url);
        getIcon=function() { return url; };
    }
    
    plugin.onpagechange=function (sessID, url, state) {
        if (state==1) {
           // A new page is opened
        }
        if (state==2) {
           // A new page is loaded
        }
    }
})();

[edit] The utility of all the functions

1. fpath (url)

Transform a relative URL to a long URL. IE7Pro do that for you. IE7PRO://pluginpath/ is replaced by the local path of the plug-in's root directory.

2. plugin

See the reference of the PLUGIN API on http://www.iescripts.org/help/pro_plugin.html In addition to the PLUGIN API, some other PRO_ functions are accessible in the code

3. get/setIcon([newUrl])

Get or set the icon of the Plug-in. The recommended size is 16 by 16 pixels.

4. onpagechange(sessID, url, state)

This function is call each time a new page is opened and loaded. You can't interact with the page when the status is set to "opened".

sessID: sessID is very important, that's the identifier of the current tab.

When you want to do something on a tab, you must have a reference to this session's ID.

url: The URL of the page currently opened (can be found without this parameter)

state: The status of the actual page (1: opened; 2: loaded)

In the cycles of live of a page, the onpagecreate event is called two times. Firstly with state = 1 and secondly with state = 2.

Sample of use: Print the URL of the file in the plug-in area

[...]
    plugin.onpagechange=function (sessID, url, state) {
        if (state==1) {
           plugin.setStatusText(url, sessID)
        }
    }
[...]

[edit] How to create a Button Plug-in

[edit] Catch the onclick event

The most of the time, you'll make a clickable plug-in.
To catch when the user click on the plug-in, there's the onclick event

    plugin.onclick = function(sessID, currentUrl) {
        // The user click on the plug-in
    }

Sample of use: Clear the plug-in's area

    plugin.onclick = function(sessID, currentUrl) {
           plugin.setStatusText("", sessID)
    }

[edit] Displaying an image instead of the text

Display a text in the plug-in area is very useful but the most of the time, it's better to display an icon (such the "e"-icon of IE7Pro)

To do this, you must indicate an icon in the header of the file and store this icon in the root directory

// @defaulticon   ie7pro://pluginpath/bg.png

If you want a highlight of your icon when the mouse comes in the plug-in area, you can use this simple code:

    plugin.onmouseenter = function() {
        setIcon(fpath("bg_over.png"))
    }
    plugin.onmouseleave = function() {
        setIcon(fpath("bg.png"))
    }

[edit] How to create a context-menu for the plug-in?

To add an entry to the context-menu of the plug-in, you can do this:

    function func(sessID, url) {
        // The use clicked on "DisplayText"
    }
    plugin.registerContextMenu("DisplayText", func)

If you want to add a separator, you can use this code:

    plugin.registerContextMenu("separator")

[edit] How to save / load options

Theses two functions are used to store settings of your application, such languageâ¿¦

// Get the value of "optionName"
var option = PRO_getValue(optionName, valueIfOptionIsNotSetted)

// Set the value of "optionName"
PRO_setValue(optionName, option)

[edit] Interact with the page

[edit] Getting the URL of the page

The URL can be obtained with the url parameter.
But if you want, you can find the URL of the current document without it.

// Get the URL as text-format
function getUrl(sessID) {
     return plugin.getCurrentDocument(sessID).location.href;
}

You can get the URL as URILocation (see MSDN: document.location), too :

// Get the URL as URILocation
function getUri(sessID) {
     return plugin.getCurrentDocument(sessID).location;
}

[edit] Executing JavaScript into the web page

They are two ways to execute JavaScript on the current page.

[edit] With PRO_openInTab

If you have only a short JavaScript to execute (one line), you can simply use the PRO_openInTab, this is easy and you don't pass any parameter to the function

function injectJS(js) {
    PRO_openInTab("javascript:" + js, 0)
}

How does this function work? This is simple, Internet Explorer executes JavaScript if the location of a page is set to "javascript: â¿¦". Here we are opening a javascript: URL in the current tab (parameter 0). Because it's an URL, it can only execute one line of JavaScript.

[edit] With window.execScript

Internet Explorer implements a simple function for evaluating scripts in a window.

function evalJS(js, sessID) {
    var document = plugin.getCurrentDocument(sessID);
    var window = document.parentWindow;
    window.execScript(js);
}

You can also specify the language and execute any VBScript:

function evalVB(vb, sessID) {
    var document = plugin.getCurrentDocument(sessID);
    var window = document.parentWindow;
    window.execScript(vb,"vbscript");
}

You can now execute more than one line of code (\n = new line):

var doSomething=(
  "if (document.getElementById('data')) {\n"+
  "  document.getElementById('data').value='Plugin Actived !'; \n"+
  "}"
);

evalJS(doSomething, sessID);

[edit] Using DOM

Here, we'll do the same thing that the preview code, but directly in the plug-in:

The first thing you must do before is getting the document and the window objects To do this, you need the id of the current session.

function setData(sessID) {
    var document = plugin.getCurrentDocument(sessID);
    var window = document.parentWindow;
    // ...
}

Next to this, you can do as you were in a JavaScript file:

function setData(sessID) {
    var document = plugin.getCurrentDocument(sessID);
    var window = document.parentWindow;
    if (document.getElementById('data')) {
      document.getElementById('data').value='Plugin Actived !';
    }
}

[edit] Using ActiveXObject

Currently, it's not possible to create an instance of an ActiveXObject.
The follow code causes an error:

    plugin.onclick = function(sessID, currentUrl) {
        try {
            var document = plugin.getCurrentDocument(sessID);
            var window = document.parentWindow;
            var activeX = window.ActiveXObject("Msxml2.DOMDocument");
            PRO_openInTab("javascript:alert('"+activeX+"')", 0)
        } catch (ex) {
            PRO_openInTab("javascript:alert('"+ex.message+"')", 0)
        }
    }

[edit] Using popup

Use the plugin.popupWindow function and plugin.onpopupclose event to use popup

Some tips:
1.	Encode your files as ANSI or UNICODE
2.	Start all your files with <!-- saved from url=(0014)about:internet -->
3.	Impose a font for your dialogs by CSS
* { font-family: Tahoma; font-size: 10pt; }
4.	Try to let some with space at bottom of your dialogs for large-font UI
5.	Return a value to onpopupcolose with window.returnValue

[edit] Some useful functions

These functions need evalJS and evalVB functions.

[edit] Alert (Message Box)

function alert(txt, sessID) {
   var document = plugin.getCurrentDocument(sessID);
   var window = document.parentWindow;
   return window.alert(txt);
}

[edit] Confirm (True â¿¿ False)

function confirm(txt, sessID) {
   var document = plugin.getCurrentDocument(sessID);
   var window = document.parentWindow;
   return window.confirm(txt);
}

[edit] Prompt (String)

function propmt(txt, default, sessID) {
   var document = plugin.getCurrentDocument(sessID);
   var window = document.parentWindow;
   return window.prompt(txt, default);
}

[edit] GetSelection (Text-/ControlRange)

function getSelection(sessID) {
   try {
      var document = plugin.getCurrentDocument(sessID);
      return document.selection.createRange();
   } catch (ex) { return null; }
}

[edit] Go (Navigate in the history)

// 0 : Refresh; 1 : Next; -1 : Preview
function go(index, sessID) {
   var document = plugin.getCurrentDocument(sessID);
   var window = document.parentWindow;
   window.history.go(index);
}

[edit] $ (GetElementById)

function $(ID, sessID) {
   var document = plugin.getCurrentDocument(sessID);
   return document.getElementById(ID);
}

[edit] Key Shortcuts

Here's a way to manage key shorcuts for a plugin

   function getInfo(sessID) {
       return {
           "document":plugin.getCurrentDocument(sessID),
           "window":plugin.getCurrentDocument(sessID).parentWindow
       };
   }
   
   function document(sessID) {
       return getInfo(sessID).document;
   }
   
   function window(sessID) {
       return getInfo(sessID).window;
   }

   var keyShortcuts=new Array();
   function keyShortcut(name, chr, ctrl, alt, shif, oncalled) {
       this.name=name;
       this.chr=chr.charCodeAt(0);
       this.ctrl=ctrl;
       this.alt=alt;
       this.shift=shit;
       this.test=function(sessID, e) {
           if (e.chr==this.chr) {
               if(!this.ctrl || e.ctrlKey) {
                   if(!this.alt || e.altKey) {
                       if(!this.shift || e.shiftKey) {
                           this.oncalled(sessID, e)
                       }
                   }
               }
           }
       }
       this.oncalled=(oncalled?oncalled:function(sessID, e) {});
       this.save() {
           PRO_setValue(@name+"_"+this.name+"_keyShortcut",this.chr+"|"+this.ctrl+"|"+this.alt+"|"+this.shift)
       };
       this.load=function() {
           var data = PRO_getValue(@name+"_"+this.name+"_keyShortcut",this.chr+"|"+this.ctrl+"|"+this.alt+"|"+this.shift).split("|");
           if (data.length!=4) { return false; }
           this.chr=parseInt(data[0]);
           this.ctrl=(data[1]=="true");
           this.alt=(data[2]=="true");
           this.shift=(data[3]=="true");
           return true;
       };
       keyShortcuts.push(this);
   }

   function onKeyDown(sessID) {
       var e = window(sessID).event;
       for (var i=0; i<keyShortcuts.length; i++) {
           var ks = keyShortcuts[i];
           ks.test(sessID, e);
       }
   }

   /*
       How to use / Utilisation :
       ===========================
       1) Ajout de la prise en charge dans les documents :
           plugin.onpagechange=function(sessID, url, state) {
               if (state==2) {
                   document(sessID).attachEvent("onkeydown", function() {
                       onKeyDown(sessID);
                   })
               }
           }
       
       2) Création des raccourcis :
           var ksOpenFile = new KeyShortcut(escape("Open a new file..."), "O", true, false, false, function(sessID, e) {
               // When the k.s. is called
           }); ksOpenFile.load();
           
       3) Modifier un raccourci :
           ksOpenFile.chr="N";
           ksOpenFile.ctrl=false;
           ksOpenFile.alt=true;
           ksOpenFile.shift=false;
           ksOpenFile.save();
   */