Дополнения

Добавление заметок

Перевод не завершен. Пожалуйста, помогите перевести эту статью с английского.

Мы будем использовать два объекта для создания заметок: модификатор страницы - чтобы найти элементы, для которых пользователь может оставить заметку и панель для ввода текста заметки.

Селектор модификации страницы

Селектор контент-скриптов

Контент-скрипт для селекторамодификации страницы будет ипользовать jQuery для поиска элементов и манипуляций над ними.

Эго главная задача - обработка "подходящего элемента": это элемент страницы, который подходит для добавления заметки на него. Подходящий элемент будет подсвечен и будет иметь обработчик событий, который будет отправлять сообщения основному коду расширения.

Селектор модификации страницы может быть активирован или деактивирован используя сообщение от основного кода расширения. По-умолчанию он деактивирован:

var matchedElement = null;
var originalBgColor = null;
var active = false;

function resetMatchedElement() {
  if (matchedElement) {
    (matchedElement).css('background-color', originalBgColor);
    (matchedElement).unbind('click.annotator');
  }
}

self.on('message', function onMessage(activation) {
  active = activation;
  if (!active) {
    resetMatchedElement();
  }
});

Данный селектор ожидает вхождения события jQuery mouseenter.

 When a mouseenter event is triggered the selector checks whether the element is eligible for annotation. An element is eligible if it, or one of its ancestors in the DOM tree, has an attribute named "id". The idea here is to make it more likely that the annotator will be able to identify annotated elements correctly later on.

If the page element is eligible for annotation, then the selector highlights that element and binds a click handler to it. The click handler sends a message called show back to the main add-on code. The show message contains: the URL for the page, the ID attribute value, and the text content of the page element.

$('*').mouseenter(function() {
  if (!active || $(this).hasClass('annotated')) {
    return;
  }
  resetMatchedElement();
  ancestor = $(this).closest("[id]");
  matchedElement = $(this).first();
  originalBgColor = $(matchedElement).css('background-color');
  $(matchedElement).css('background-color', 'yellow');
  $(matchedElement).bind('click.annotator', function(event) {
    event.stopPropagation();
    event.preventDefault();
    self.port.emit('show',
      [
        document.location.toString(),
        $(ancestor).attr("id"),
        $(matchedElement).text()
      ]
   );
  });
});

Conversely, the add-on resets the matched element on mouseout:

$('*').mouseout(function() {
  resetMatchedElement();
});

Save this code in a new file called selector.js in your add-on's data directory.

Because this code uses jQuery, you'll need to download that as well, and save it in data.

Updating main.js

Go back to main.js and add the code to create the selector into the main function:

var selector = pageMod.PageMod({
  include: ['*'],
  contentScriptWhen: 'ready',
  contentScriptFile: [data.url('jquery-1.4.2.min.js'),
                      data.url('selector.js')],
  onAttach: function(worker) {
    worker.postMessage(annotatorIsOn);
    selectors.push(worker);
    worker.port.on('show', function(data) {
      console.log(data);
    });
    worker.on('detach', function () {
      detachWorker(this, selectors);
    });
  }
});

Make sure the name you use to load jQuery matches the name of the jQuery version you downloaded.

The page-mod matches all pages, so each time the user loads a page the page-mod emits the attach event, which will call the listener function we've assigned to onAttach. The handler is passed a worker object. Each worker represents a channel of communication between the add-on code and any content scripts running in that particular page context. For a more detailed discussion of the way page-mod uses workers, see the page-mod documentation.

In the attach handler we do three things:

  • send the content script a message with the current activation status
  • add the worker to an array called selectors so we can send it messages later on
  • assign a message handler for messages from this worker. If the message is show we will just log the content for the time being. If the message is detach we remove the worker from the selectors array.

At the top of the file import the page-mod module and declare an array for the workers:

var pageMod = require('sdk/page-mod');
var selectors = [];

Add detachWorker:

function detachWorker(worker, workerArray) {
  var index = workerArray.indexOf(worker);
  if(index != -1) {
    workerArray.splice(index, 1);
  }
}

Edit toggleActivation to notify the workers of a change in activation state:

function activateSelectors() {
  selectors.forEach(
    function (selector) {
      selector.postMessage(annotatorIsOn);
  });
}

function toggleActivation() {
  annotatorIsOn = !annotatorIsOn;
  activateSelectors();
  return annotatorIsOn;
}

We'll be using this URL in all our screenshots. Because cfx run doesn't preserve browsing history, if you want to play along it's worth taking a note of the URL.

Save the file and execute cfx run again. Activate the annotator by clicking the widget and load a page: the screenshot below uses http://blog.mozilla.com/addons/2011/02/04/ overview-amo-review-process/. You should see the highlight appearing when you move the mouse over certain elements:

Click on the highlight and you should see something like this in the console output:

  info: show
  info: http://blog.mozilla.com/addons/2011/02/04/overview-amo-review-process/,
  post-2249,When you submit a new add-on, you will have to choose between 2
  review tracks: Full Review and Preliminary Review.

Annotation Editor Panel

So far we have a page-mod that can highlight elements and send information about them to the main add-on code. Next we will create the editor panel, which enables the user to enter an annotation associated with the selected element.

We will supply the panel's content as an HTML file, and will also supply a content script to execute in the panel's context.

So create a subdirectory under data called editor. This will contain two files: the HTML content, and the content script.

Annotation Editor HTML

The HTML is very simple:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
  <title>Annotation</title>
  <style type="text/css" media="all">
  body {
    font: 100% arial, helvetica, sans-serif;
    background-color: #F5F5F5;
  }
  textarea {
    width: 180px;
    height: 180px;
    margin: 10px;
    padding: 0px;
  }
  </style>

</head>

<body>

<textarea rows='10' cols='20' id='annotation-box'>
</textarea>

</body>

</html>

Save this inside data/editor as annotation-editor.html.

Annotation Editor Content Script

In the corresponding content script we do two things:

  • handle a message from the add-on code by giving the text area focus
  • listen for the return key and when it is pressed, send the contents of the text area to the add-on.

Here's the code:

var textArea = document.getElementById('annotation-box');

textArea.onkeyup = function(event) {
  if (event.keyCode == 13) {
    self.postMessage(textArea.value);
    textArea.value = '';
  }
};

self.on('message', function() {
  var textArea = document.getElementById('annotation-box');
  textArea.value = '';
  textArea.focus();
});

Save this inside data/editor as annotation-editor.js.

Updating main.js Again

Now we'll update main.js again to create the editor and use it.

First, import the panel module:

var panels = require('sdk/panel');

Then add the following code to the main function:

var annotationEditor = panels.Panel({
  width: 220,
  height: 220,
  contentURL: data.url('editor/annotation-editor.html'),
  contentScriptFile: data.url('editor/annotation-editor.js'),
  onMessage: function(annotationText) {
    if (annotationText) {
      console.log(this.annotationAnchor);
      console.log(annotationText);
    }
    annotationEditor.hide();
  },
  onShow: function() {
    this.postMessage('focus');
  }
});

We create the editor panel but don't show it. We will send the editor panel the focus message when it is shown, so it will give the text area focus. When the editor panel sends us its message we log the message and hide the panel.

The only thing left is to link the editor to the selector. So edit the message handler assigned to the selector so that on receiving the show message we assign the content of the message to the panel using a new property "annotationAnchor", and show the panel:

var selector = pageMod.PageMod({
  include: ['*'],
  contentScriptWhen: 'ready',
  contentScriptFile: [data.url('jquery-1.4.2.min.js'),
                      data.url('selector.js')],
  onAttach: function(worker) {
    worker.postMessage(annotatorIsOn);
    selectors.push(worker);
    worker.port.on('show', function(data) {
      annotationEditor.annotationAnchor = data;
      annotationEditor.show();
    });
    worker.on('detach', function () {
      detachWorker(this, selectors);
    });
  }
});

Execute cfx run again, activate the annotator, move your mouse over an element and click the element when it is highlighted. You should see a panel with a text area for a note:

Enter the note and press the return key: you should see console output like this:

  info: http://blog.mozilla.com/addons/2011/02/04/overview-amo-review-process/,
  post-2249,When you submit a new add-on, you will have to choose between 2
  review tracks: Full Review and Preliminary Review.
  info: We should ask for Full Review if possible.

That's a complete annotation, and in the next section we'll deal with storing it.

Метки документа и участники

 Внесли вклад в эту страницу: kestik
 Обновлялась последний раз: kestik,