Talk:Metadata Block

NOTE: This feature is not released yet. (#1103) This is a draft of some documentation for this feature.

A page titled document-start may be necessary for full details. Other documentation of this feature:

http://code.google.com/chrome/extensions/content_scripts.html

http://www.chromium.org/developers/design-documents/user-scripts

Please note there is a discrepancy between the above two documents whether to use an underscore or a dash, however we are using a dash since this is the syntax for userscripts.

This documentation is based on the test script available here: http://gist.github.com/418707

@run-at

Example:

// @run-at document-start

This indicates when the script should be injected into the page. By default scripts are run at document-end occurring at DOMContentLoaded. Use document-start to start running scripts or apply styles before anything has downloaded. It is useful for preventing the flicker problem.

You may have to attach your own DOMContentLoaded listener to show the finished result or run scripts that depend on page elements being accessible.

GM_addStyle("body{ display: none; }");
document.addEventListener('DOMContentLoaded', function(){
  //page has fully loaded, run interactive scripts here
  GM_addStyle("body{ display: block; }");
}, true);

To detect if your script is currently running at document-start in a document-start compatible version of greasemonkey use the following logic:

//document.body is null at document-start
var ranAtDocumentStart = document.body == null;
if(ranAtDocumentStart){
  //document-start compatible greasemonkey
}else{
  //legacy DOMContentLoaded greasemonkey
}

A typical use of document-start involves using GM_addStyle to hide the document body, allowing you to manipulate the page, and then show the result only when the page is loaded and the modifications have been applied. Another use involves listening for the DOMNodeInserted event and reacting as elements are added to the page.

What is the significance of "@" if I do not use it what happens?

Can someone explain to me the reason for the "@" what is the significance of that?

Answer:

Any line that begins with // is a commentary in javascript, and the greasemonkey metadata are put into commentary lines in order for javascript to ignore them. However, greasemonkey needs to be able to identify the metadata from other commentary lines you may put into the script, which is why they use a special character like @.

You could, for instance, want to make the following commentary in your script:

  // include the following line if you want a red background
  document.body.style.backgroundColor = 'red';

Greasemonkey would interpret this as an include command (@include) if they didn't use the @-character to distinguish it from the word "include", which you might write as ordinary text, like in the example above. You are less likely to write @include as normal text.