Tutorial : How to make a plugin for IE7Pro

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

Naturally, you can learn more information about the plug-in on the IE7Pro Web Site.

Regards,

FremyCompany

The common architecture

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.

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
  }
  }
  })()

The utility of all the functions

• 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.

• 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

• get/setIcon([newUrl])

Get or set the icon of the Plug-in.

The recommended size is 16 by 16 pixels.

• 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)
  }
  }
[...]

How to create a Button Plug-in

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)
  }

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"))
  }

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")

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)

Interact with the page

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;
  }

Executing JavaScript into the web page

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

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.

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);

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 !';
  }
  }

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)
  }
  }

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

Some useful functions

These functions need evalJS and evalVB functions.

Alert (Message Box)

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

Confirm (True – False)

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

Prompt (String)

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

GetSelection (Text-/ControlRange)

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

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);
  }

$ (GetElementById)

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

Learn more

• http://www.iescripts.org/help
• http://msdn2.microsoft.com/en-us/library/ms533054.aspx
• Google is your friend!

Thanks to Author: FremyCompany