diff options
Diffstat (limited to 'files/id/archive/mozilla')
7 files changed, 634 insertions, 0 deletions
diff --git a/files/id/archive/mozilla/index.html b/files/id/archive/mozilla/index.html new file mode 100644 index 0000000000..132253aacf --- /dev/null +++ b/files/id/archive/mozilla/index.html @@ -0,0 +1,8 @@ +--- +title: Archived Mozilla and build documentation +slug: Archive/Mozilla +translation_of: Archive/Mozilla +--- +<p>In progress. These articles are archived, obsolete documents about Mozilla, Gecko, and the process of building Mozilla projects.</p> + +<p>{{SubpagesWithSummaries}}</p> diff --git a/files/id/archive/mozilla/xul/index.html b/files/id/archive/mozilla/xul/index.html new file mode 100644 index 0000000000..17aa6ed66c --- /dev/null +++ b/files/id/archive/mozilla/xul/index.html @@ -0,0 +1,84 @@ +--- +title: XUL +slug: Archive/Mozilla/XUL +tags: + - NeedsTranslation + - TopicStub + - XUL +translation_of: Archive/Mozilla/XUL +--- +<div class="callout-box"><strong><a href="/en-US/docs/XUL_Tutorial" title="en-US/docs/XUL_Tutorial">XUL Tutorial</a></strong><br> +A guided tutorial that will help you get started with XUL, originally from XULPlanet.</div> + +<div> +<p><strong>XUL</strong> (XML User Interface Language) is Mozilla's <a href="/en-US/docs/XML" title="en-US/docs/XML">XML</a>-based language for building user interfaces of applications like Firefox. The term XUL is sometimes used to refer to the whole <a href="/en-US/docs/The_Mozilla_platform" title="/en-US/docs/The_Mozilla_platform">Mozilla platform</a> (e.g. XUL applications are applications using XUL and other components of the platform).</p> + +<p><a href="/en-US/docs/XUL_controls" title="en-US/docs/XUL_controls">XUL Controls</a> lists some of the common controls provided by XUL.</p> +</div> + +<table class="topicpage-table"> + <tbody> + <tr> + <td> + <h2 class="Documentation" id="Documentation">Documentation</h2> + + <dl> + <dt><strong><a href="/en-US/docs/XUL_Tutorial" title="en-US/docs/XUL_Tutorial">XUL Tutorial</a></strong></dt> + <dd>A guided tutorial that will help you get started with XUL, originally from XULPlanet.</dd> + <dt><a href="/en-US/docs/XUL_Reference" title="en-US/docs/XUL_Reference">XUL Reference</a></dt> + <dd>XUL elements, attributes, properties, methods, and event handlers.</dd> + <dt><a href="/en-US/docs/XUL_controls" title="en-US/docs/XUL_controls">XUL Controls</a></dt> + <dd>A quick list of all of the available XUL controls.</dd> + <dt><a href="/en-US/docs/The_Joy_of_XUL" title="en-US/docs/The_Joy_of_XUL">The Joy of XUL</a></dt> + <dd>Describes the key features and components of XUL.</dd> + <dt><a href="/en-US/docs/XUL/PopupGuide" title="en-US/docs/XUL/PopupGuide">Menus and Popups Guide</a></dt> + <dd>A guide on using menus and popup panels.</dd> + <dt><a href="/en-US/docs/XUL/Template_Guide" title="en-US/docs/XUL/Template_Guide">Template Guide</a></dt> + <dd>A detailed guide on XUL templates, which is a means of generating content from a datasource.</dd> + <dt><a href="/en-US/docs/DragDrop/Drag_and_Drop" title="Drag and Drop">Drag and Drop</a></dt> + <dd>How to perform drag and drop operations.</dd> + </dl> + + <dl> + <dt>XUL Periodic Table</dt> + <dd>This collection of XUL demos was available as a <a href="/en-US/docs/" title="/en-US/docs/">web page</a>, but can no longer be viwed in Firefox since support for <a href="/en-US/docs/Remote_XUL" title="/en-US/docs/Remote_XUL">Remote XUL</a> was disabled. There is a XULRunner application containing the XUL Periodic Table which can be opened with Gecko based browsers. <a href="https://github.com/matthewkastor/XULRunner-Examples" title="https://github.com/matthewkastor/XULRunner-Examples">You can get it here</a>. See: <a href="/en-US/docs/XULRunner_tips#Using_Firefox_3_to_run_XULRunner_applications" title="/en-US/docs/XULRunner_tips#Using_Firefox_3_to_run_XULRunner_applications">XULRunner_tips#Using_Firefox_3_to_run_XULRunner_applications</a> for instructions on running XULRunner apps in Firefox.</dd> + <dt>Changes to XUL</dt> + <dd>New XUL features and changes to existing features are included in the <a href="/en-US/docs/Mozilla/Firefox/Releases" title="/en-US/docs/Mozilla/Firefox/Releases">Firefox developer release notes</a>.</dd> + </dl> + + <p><span class="alllinks"><a href="/en-US/docs/tag/XUL" title="tag/XUL">View All...</a></span></p> + </td> + <td> + <h2 class="Community" id="Community">Community</h2> + + <ul> + <li>View Mozilla forums...{{ DiscussionList("dev-tech-xul", "mozilla.dev.tech.xul") }}</li> + <li><a class="link-irc" href="irc://irc.mozilla.org/xul">#xul on irc.mozilla.org</a></li> + </ul> + + <h2 class="Tools" id="Tools">Tools</h2> + + <ul> + <li><a class="external" href="/en-US/docs/XUL_Explorer" title="en-US/docs/XUL_Explorer">XUL Explorer</a> (a lightweight XUL IDE)</li> + <li><a href="https://github.com/matthewkastor/XULExplorer" title="https://github.com/matthewkastor/XULExplorer">XULExplorer</a> (Patched version of XUL explorer)</li> + <li><a class="external" href="http://ted.mielczarek.org/code/mozilla/extensiondev/">Extension developer's extension</a> (featuring a Live XUL Editor)</li> + <li><a class="external" href="http://forum.addonsmirror.net/index.php?showtopic=751" title="http://forum.addonsmirror.net/index.php?showtopic=751">XULRef sidebar</a></li> + <li><a class="external" href="http://www.getfirebug.com/">Firebug</a></li> + <li><a href="/en-US/docs/DOM_Inspector" title="en-US/docs/DOM_Inspector">DOM Inspector</a></li> + <li><a class="external" href="http://www.spket.com/">Spket IDE</a>, IDE for XUL/XBL</li> + <li><a class="external" href="http://www.amplesdk.com" title="http://www.amplesdk.com/">Ample SDK</a>, (Cross-browser XUL renderer in JavaScript/HTML)</li> + </ul> + + <p><span class="alllinks"><a href="/en-US/docs/tag/tools" title="tag/tools">View All...</a></span></p> + + <h2 class="Related_Topics" id="Related_Topics">Related Topics</h2> + + <ul> + <li><a href="/en-US/docs/JavaScript" title="en-US/docs/JavaScript">JavaScript</a>, <a href="/en-US/docs/XBL" title="en-US/docs/XBL">XBL</a>, <a href="/en-US/docs/CSS" title="en-US/docs/CSS">CSS</a>, <a href="/en-US/docs/RDF" title="en-US/docs/RDF">RDF</a>, <a href="/en-US/docs/Extensions" title="en-US/docs/Extensions">Extensions</a>, <a href="/en-US/docs/XULRunner" title="en-US/docs/XULRunner">XULRunner</a></li> + </ul> + </td> + </tr> + </tbody> +</table> + +<p> </p> diff --git a/files/id/archive/mozilla/xul/international_characters_in_xul_javascript/index.html b/files/id/archive/mozilla/xul/international_characters_in_xul_javascript/index.html new file mode 100644 index 0000000000..d3ddd60359 --- /dev/null +++ b/files/id/archive/mozilla/xul/international_characters_in_xul_javascript/index.html @@ -0,0 +1,23 @@ +--- +title: International characters in XUL JavaScript +slug: Archive/Mozilla/XUL/International_characters_in_XUL_JavaScript +translation_of: Archive/Mozilla/XUL/International_characters_in_XUL_JavaScript +--- +<h3 id="Introduction" name="Introduction">Introduction</h3> +<p><a href="/en-US/docs/Gecko" title="en/Gecko">Gecko</a> 1.8, as used in <a href="/en-US/docs/Firefox_1.5_for_developers" title="en/Firefox_1.5_for_developers">Firefox 1.5</a> and other applications, added support for non-ASCII characters in <a href="/en-US/docs/JavaScript" title="en/JavaScript">JavaScript</a> files loaded from <a href="/en-US/docs/XUL" title="en/XUL">XUL</a> files.</p> +<p>This means that such script files can use any character from virtually any language of the world. For example, they can contain a line:</p> +<pre class="eval">var text = "Ein schönes Beispiel eines mehrsprachigen Textes: 日本語"; +</pre> +<p>This mixes German and Japanese characters.</p> +<p>Earlier versions always interpreted JS files loaded from XUL as <a class="external" href="http://en.wikipedia.org/wiki/ISO_8859-1#Code_table">ISO-8859-1</a> (Latin-1), in both local and remote cases. Unicode escapes, <a href="#Cross-version_compatibility">as discussed below</a>, have always worked.</p> +<h3 id="How_the_character_encoding_is_determined_in_Gecko_1.8_and_later" name="How_the_character_encoding_is_determined_in_Gecko_1.8_and_later">How the character encoding is determined in Gecko 1.8 and later</h3> +<p>When the JavaScript file is loaded from a <code>chrome://</code> URL, a <a href="/en-US/docs/Byte_Order_Mark" title="en/Byte_Order_Mark">Byte Order Mark</a> ({{todo}})({{ interwiki('wikipedia', 'Byte_Order_Mark', 'BOM') }}) is used to determine the character encoding of the script. Otherwise, the character encoding will be the same as the one used by the XUL file (which can be specified using an <code>encoding</code> attribute in the <code><?xml?></code> tag). By default this will use UTF-8, which can represent virtually all characters in the world.</p> +<p>If the script file is loaded via HTTP, the HTTP header can contain a character encoding declaration as part of the <code>Content-Type</code> header, for example:</p> +<pre class="eval">Content-Type: application/javascript; charset=UTF-8 +</pre> +<p>If no charset parameter is specified, the same rules as above apply.</p> +<h3 id="Cross-version_compatibility" name="Cross-version_compatibility">Cross-version compatibility</h3> +<p>If you want the same code to work in both Gecko 1.8 and earlier versions, you must limit yourself to ASCII. However, you can use <a href="/en-US/docs/Core_JavaScript_1.5_Guide/Unicode#Unicode_Escape_Sequences" title="en/Core_JavaScript_1.5_Guide/Unicode#Unicode_Escape_Sequences">unicode escapes</a> – the earlier example rewritten using them would be:</p> +<pre class="eval">var text = "Ein sch\u00F6nes Beispiel eines mehrsprachigen Textes: \u65E5\u672C\u8A9E"; +</pre> +<p>An alternative might be to use property files via {{interface("nsIStringBundle")}} or the <a href="/en-US/docs/XUL_Tutorial/Property_Files" title="en/XUL_Tutorial/Property_Files">XUL <stringbundle> element</a>; this would allow for localization of the XUL. This can not be done in XUL files loaded from the web, only in privileged code, e.g. in <a href="/en-US/docs/Extensions" title="en/Extensions">extensions</a>.</p> diff --git a/files/id/archive/mozilla/xul/school_tutorial/index.html b/files/id/archive/mozilla/xul/school_tutorial/index.html new file mode 100644 index 0000000000..4ae723e85a --- /dev/null +++ b/files/id/archive/mozilla/xul/school_tutorial/index.html @@ -0,0 +1,59 @@ +--- +title: XUL School Tutorial +slug: Archive/Mozilla/XUL/School_tutorial +tags: + - Add-ons + - Extensions + - NeedsTranslation + - References + - TopicStub + - Tutorials + - XUL +translation_of: Archive/Add-ons/Overlay_Extensions/XUL_School +--- +<p>XUL School is a comprehensive add-on development tutorial, focusing on Firefox extension development. It is recommended that you read through all of it at least once. While Firefox changes rapidly, the content in this tutorial should be up to date and valid.</p> +<dl> + <dt>Introduction</dt> + <dd><ul> + <li><a href="/en-US/docs/XUL/School_tutorial/Introduction" title="XUL/School_tutorial/Introduction">Introduction</a></li> + <li><a href="/en-US/docs/XUL/School_tutorial/Getting_Started_with_Firefox_Extensions" title="XUL/School_tutorial/Getting Started with Firefox Extensions">Getting Started with Firefox Extensions</a></li> + <li><a href="/en-US/docs/XUL/School_tutorial/The_Essentials_of_an_Extension" title="XUL/School_tutorial/The Essentials of an Extension">The Essentials of an Extension</a></li> + <li><a href="/en-US/docs/XUL/School_tutorial/Setting_Up_a_Development_Environment" title="XUL/School_tutorial/Setting Up a Development Environment">Setting Up a Development Environment</a></li> + <li><a href="/en-US/docs/XUL/School_tutorial/JavaScript_Object_Management" title="XUL/School_tutorial/JavaScript Object Management">JavaScript Object Management</a></li> + </ul></dd> + <dt>Basic functionality</dt> + <dd><ul> + <li><a href="/en-US/docs/XUL/School_tutorial/Adding_menus_and_submenus" title="XUL/School_tutorial/Adding menus and submenus">Adding menus and submenus</a></li> + <li><a href="/en-US/docs/XUL/School_tutorial/Adding_Toolbars_and_Toolbar_Buttons" title="XUL/School_tutorial/Adding Toolbars and Toolbar Buttons">Adding Toolbars and Toolbar Buttons</a></li> + <li><a href="/en-US/docs/XUL/School_tutorial/Adding_Events_and_Commands" title="XUL/School_tutorial/Adding Events and Commands">Adding events and commands</a></li> + <li><a href="/en-US/docs/XUL/School_tutorial/Adding_windows_and_dialogs" title="XUL/School_tutorial/Adding windows and dialogs">Adding windows and dialogs</a></li> + <li><a href="/en-US/docs/XUL/School_tutorial/Adding_sidebars" title="XUL/School_tutorial/Adding sidebars">Adding sidebars</a></li> + <li><a href="/en-US/docs/XUL/School_tutorial/User_Notifications_and_Alerts" title="XUL/School_tutorial/User Notifications and Alerts">User notifications and alerts</a></li> + </ul></dd> + <dt>Intermediate functionality</dt> + <dd><ul> + <li><a href="/en-US/docs/XUL/School_tutorial/Intercepting_Page_Loads" title="XUL/School_tutorial/Intercepting Page Loads">Intercepting page loads</a></li> + <li><a href="/en-US/docs/XUL/School_tutorial/Connecting_to_Remote_Content" title="XUL/School_tutorial/Connecting to Remote Content">Connecting to Remote Content</a></li> + <li><a href="/en-US/docs/XUL/School_tutorial/Handling_Preferences" title="XUL/School_tutorial/Handling Preferences">Handling preferences</a></li> + <li><a href="/en-US/docs/XUL/School_tutorial/Local_Storage" title="XUL/School_tutorial/Local Storage">Local Storage</a></li> + </ul></dd> + <dt>Advanced topics</dt> + <dd><ul> + <li><a href="/en-US/docs/XUL/School_tutorial/The_Box_Model" title="XUL/School_tutorial/The Box Model">The Box Model</a></li> + <li><a href="/en-US/docs/XUL/School_tutorial/XPCOM_Objects" title="XUL/School_tutorial/XPCOM Objects">XPCOM Objects</a></li> + <li><a href="/en-US/docs/XUL/School_tutorial/Observer_Notifications" title="XUL/School_tutorial/Observer Notifications">Observer Notifications</a></li> + <li><a href="/en-US/docs/XUL/School_tutorial/Custom_XUL_Elements_with_XBL" title="XUL/School_tutorial/Custom XUL Elements with XBL">Custom XUL Elements with XBL</a></li> + <li><a href="/en-US/docs/XUL/School_tutorial/Mozilla_Documentation_Roadmap" title="XUL/School_tutorial/Mozilla Documentation Roadmap">Mozilla Documentation Roadmap</a></li> + <li><a href="/en-US/docs/XUL/School_tutorial/Useful_Mozilla_Community_Sites" title="XUL/School_tutorial/Useful Mozilla Community Sites">Useful Mozilla Community Sites</a></li> + </ul></dd> + <dt>Appendices</dt> + <dd><ul> + <li><a href="/en-US/docs/XUL/School_tutorial/Appendix_A:_Add-on_Performance" title="XUL/School_tutorial/Appendix A: Add-on Performance">Appendix A: Add-on Performance</a></li> + <li><a href="/en-US/docs/XUL/School_tutorial/Appendix_B:_Install_and_Uninstall_Scripts" title="XUL/School_tutorial/Appendix B: Install and Uninstall Scripts">Appendix B: Install and Uninstall Scripts</a></li> + <li><a href="/en-US/docs/XUL/School_tutorial/Appendix_C:_Avoid_using_eval_in_Add-ons" title="XUL/School_tutorial/Appendix C: Avoid using eval in Add-ons">Appendix C: Avoiding using eval in Add-ons</a></li> + <li><a href="/en-US/docs/XUL/School_tutorial/Appendix_D:_Loading_Scripts" title="XUL/School_tutorial/Appendix D: Loading Scripts">Appendix D: Loading Scripts</a></li> + <li><a href="/en-US/docs/XUL/School_tutorial/DOM_Building_and_HTML_Insertion" title="XUL/School_tutorial/Appendix E: DOM Building and HTML Insertion">Appendix E: DOM Building and HTML Insertion</a></li> + <li><a href="/en-US/docs/XUL/School_tutorial/Appendix_F:_Monitoring_DOM_changes" title="XUL/School_tutorial/Appendix F: Monitoring DOM changes">Appendix F: Monitoring DOM changes</a></li> + </ul></dd> +</dl> +<p>The XUL School project was developed by <a href="http://appcoast.com/" title="http://appcoast.com/">Appcoast</a> (formerly Glaxstar). The project is now published here following its <a href="/Project:Copyrights" title="https://developer.mozilla.org/Project:Copyrights">sharing licenses</a>. Its contents have been modified from the original source as necessary.</p> diff --git a/files/id/archive/mozilla/xul/school_tutorial/perkenalan/index.html b/files/id/archive/mozilla/xul/school_tutorial/perkenalan/index.html new file mode 100644 index 0000000000..5ce760d1be --- /dev/null +++ b/files/id/archive/mozilla/xul/school_tutorial/perkenalan/index.html @@ -0,0 +1,32 @@ +--- +title: Perkenalan +slug: Archive/Mozilla/XUL/School_tutorial/Perkenalan +translation_of: Archive/Add-ons/Overlay_Extensions/XUL_School/Introduction +--- +<div> + {{Next("XUL_School/Getting_Started_with_Firefox_Extensions")}}</div> +<p><span id="result_box" lang="id"><span title="Welcome to the XUL School Tutorial!">Selamat datang di Tutorial Sekolah XUL !</span></span></p> +<p><span id="result_box" lang="id"><span title="This tutorial is meant to be the stepping stone that will turn you into a professional Firefox extension developer in no time.">Tutorial ini dimaksudkan untuk menjadi batu loncatan yang akan mengubah Anda menjadi seorang pengembang ekstensi Firefox profesional dalam waktu singkat . </span><span title="We have poured years of XUL experience into it, providing many solutions for problems extension developers commonly run into.">Kami telah dituangkan tahun pengalaman XUL ke dalamnya , menyediakan banyak solusi untuk masalah pengembang ekstensi pada umumnya.</span></span></p> +<p>XUL School was created by <a href="http://appcoast.com/" title="http://appcoast.com/">Appcoast</a> (formerly Glaxstar), one of the few companies dedicated to building high-quality Firefox extensions. A team of over a dozen XUL developers conformed Glaxstar at the time this tutorial was created, and the combined experiences of years creating Firefox extensions are reflected here.</p> +<p>With this tutorial you'll learn how to develop Firefox extensions. You'll learn how to quickly do the most common tasks in extension development, comparing several different approaches to solve them. In most cases we'll provide code samples that you can easily copy and adapt to your needs, as well as some working example extensions. The tutorial aims to be as brief as possible, often falling back on Mozilla documentation for more detailed information. You can think of it as a quick guide to the expansive world that is the Mozilla platform. Most links in this documentation are meant to be clicked and read.</p> +<p>We'll start with a brief introduction to some key concepts, in case you're not familiar with Mozilla and Firefox.</p> +<h2 id="Mozilla_and_Firefox">Mozilla and Firefox</h2> +<p>The term <a href="http://en.wikipedia.org/wiki/Mozilla" title="http://en.wikipedia.org/wiki/Mozilla">Mozilla</a> can be used to refer to several concepts: the Mozilla project, the <a href="http://en.wikipedia.org/wiki/Mozilla_Foundation" title="http://en.wikipedia.org/wiki/Mozilla_Foundation">Mozilla Foundation</a>, the <a href="http://en.wikipedia.org/wiki/Mozilla_Corporation" title="http://en.wikipedia.org/wiki/Mozilla_Corporation">Mozilla Corporation</a> and the old <a href="http://en.wikipedia.org/wiki/Mozilla_Application_Suite" title="http://en.wikipedia.org/wiki/Mozilla_Application_Suite">Mozilla browser</a>. Even Firefox is sometimes referred to as "Mozilla". If you're unfamiliar with these terms, it's good that you take some time and learn a little about Mozilla. This will help you understand the culture that surrounds the Mozilla community.</p> +<p>Mozilla has spawned several <a href="http://www.mozilla.org/projects/" title="http://www.mozilla.org/projects/">products and projects</a>, the most notable being the Mozilla Firefox web browser. Firefox is one of the most successful open source projects in history, combining the openness, standards-compliance and sophistication of open source with the focus on user experience and powerful outreach more commonly seen in less open companies.</p> +<p>Version 1.0 of Firefox was released in November 2004, version 2.0 in October 2006, and version 3.0 in June 2008. This tutorial was written after Firefox 3 was released, and has been updated with time. While most of it should still work for creating extensions Firefox 3 (and even Firefox 2), it is strongly recommended that you aim to support modern Firefox versions, to encourage users to stay up to date with security fixes. A release that is more than 6 months old is likely vulnerable to published security bugs.</p> +<p>Firefox and other Mozilla applications can be seen as composed of two different parts: a user interface layer that is distinct for each project, and a common platform on top of which the interface layer is built. The user interface is built with technology known as <a href="/en-US/docs/XUL" title="XUL">XUL</a>, and the platform is known as <a href="/en-US/docs/XULRunner" title="XULRunner">XULRunner</a>.</p> +<h2 id="XUL">XUL</h2> +<p><a href="/en-US/docs/XUL" title="XUL">XUL</a> (pronounced "zool") is one of many technologies used for creating Mozilla-based products and extensions. It is only one part of the development landscape, but given that it's practically exclusive to Mozilla, it tends to be used to identify all Mozilla-related development. You'll sometimes read terms like "XUL applications" and "XUL extensions", but rarely will they refer to projects that are exclusively built with XUL. It usually means that the projects were built using Mozilla technologies. Even this project, called XUL School, covers several other technologies such as JavaScript, CSS, XBL and XPCOM.</p> +<h2 id="XULRunner">XULRunner</h2> +<p><a href="/en-US/docs/XULRunner" title="XULRunner">XULRunner</a> includes the <a href="/en-US/docs/Gecko" title="Gecko">Gecko rendering engine</a>, the <a href="/en-US/docs/Necko" title="Necko">Necko networking library</a>, and several other components that provide OS-independent file management, accessibility, and localization, among others. It is this very powerful platform that has allowed such a fast growth of the development community surrounding Mozilla and Firefox.</p> +<p>XULRunner is available in binary form at the <a href="/en-US/docs/XULRunner" title="XULRunner">XULRunner</a> page, and it is the base for several projects, such as Songbird, Miro and Eudora. There's a very comprehensive list of XULRunner applications in the <a href="/en-US/docs/XULRunner_Hall_of_Fame" title="XULRunner Hall of Fame">XULRunner Hall of Fame</a>.</p> +<h3 id="Gecko">Gecko</h3> +<p>The <a href="/en-US/docs/Gecko" title="Gecko">Gecko engine</a> is the part of Firefox used to render web pages and its own user interface. You can identify the level of compatibility of web standards in <a href="http://en.wikipedia.org/wiki/List_of_web_browsers#Gecko-based_browsers" title="http://en.wikipedia.org/wiki/List_of_web_browsers#Gecko-based_browsers">Gecko-based browsers</a> looking at their <a href="http://en.wikipedia.org/wiki/User_agent" title="http://en.wikipedia.org/wiki/User_agent">User Agent</a> string, which should include the Gecko version. Gecko versions are somewhat independent from Firefox versions, and you can see a mapping of Firefox versions and Gecko versions at the <a href="/en-US/docs/Gecko" title="Gecko">Gecko page</a>. The User Agent String for Firefox at the time of this writing (in US English, Mac OS X) is:</p> +<p>Mozilla/5.0 (Macintosh; Intel Mac OS X 10.7; rv:<strong>7.0.1</strong>) Gecko/20100101 Firefox/7.0.1</p> +<p>The highlighted section is the Gecko version: 7.0.1. You can read and copy the user agent string of any Firefox window, choosing "Help > Troubleshooting Information" from the main menu.</p> +<h2 id="On_to_the_Tutorial">On to the Tutorial</h2> +<p>With the basic concepts out of the way, we can now get right into extension development. You are probably still wondering what exactly is an extension, what can it do, and how can you make them. Well, this whole tutorial is devoted to explaining that to you.</p> +<p>Welcome to the world of extension development. Now let's get to it.</p> +<div> + {{Next("XUL_School/Getting_Started_with_Firefox_Extensions")}}</div> +<p><small>This tutorial was kindly donated to Mozilla by Appcoast.</small></p> diff --git a/files/id/archive/mozilla/xul/school_tutorial/the_essentials_of_an_extension/index.html b/files/id/archive/mozilla/xul/school_tutorial/the_essentials_of_an_extension/index.html new file mode 100644 index 0000000000..9fa34889f3 --- /dev/null +++ b/files/id/archive/mozilla/xul/school_tutorial/the_essentials_of_an_extension/index.html @@ -0,0 +1,344 @@ +--- +title: The Essentials of an Extension +slug: Archive/Mozilla/XUL/School_tutorial/The_Essentials_of_an_Extension +translation_of: Archive/Add-ons/Overlay_Extensions/XUL_School/The_Essentials_of_an_Extension +--- +<p>{{ PreviousNext("XUL_School/Getting_Started_with_Firefox_Extensions", "XUL_School/Setting_Up_a_Development_Environment") }}</p> +<h2 id="The_install.rdf_File">The install.rdf File</h2> +<p>In the last section we looked at the contents of the Hello World extension. Now we'll look into its files and code, starting with the <em>install.rdf</em> file. You can open it with any text editor.</p> +<p>The file is formatted in a special flavor of XML called <a class="external" href="http://en.wikipedia.org/wiki/Resource_Description_Framework">RDF</a>. RDF used to be the central storage mechanism for Firefox, but it is now being replaced for a simpler database system. We'll discuss both of these storage systems further ahead in the tutorial.</p> +<p>Now let's look at the important parts of the file.</p> +<div class="code panel" style="border-width: 1px;"> + <div class="codeContent panelContent"> + <pre class="code-java"><em:id>helloworld@xulschool.com</em:id></pre> + </div> +</div> +<p>This is the unique identifier for the extension. Firefox needs this to distinguish your extension from other extensions, so it is required that you have an ID that is unique.</p> +<p>There are two accepted standards for add-on ids. One is the email-like format in the Hello World example, which should be something like <span style="color: #0000ff;"><em><project-name>@<yourdomain></em></span>. The other standard practice is to use a generated <a class="external" href="http://en.wikipedia.org/wiki/Uuid">UUID</a> string, which is extremely unlikely to be duplicated. Unix-based systems have a command line tool called <em>uuidgen</em> that generates UUIDs. There are also downloadable tools for all platforms that generate them. The enclosing brackets are just notation, and they're just common practice. As long as your id has some uniqueness to it, it's OK to use either form.</p> +<div class="code panel" style="border-width: 1px;"> + <div class="codeContent panelContent"> + <pre class="code-java"><em:name>XUL School Hello World</em:name> +<em:description>Welcome to XUL School!</em:description> +<em:version>0.1</em:version> +<em:creator>Appcoast</em:creator> +<span class="code-comment"><em:homepageURL>https://developer.mozilla.org/en/XUL_School</em:homepageURL></span></pre> + </div> +</div> +<p>This is the data that is displayed before and after the extension is installed, that you can see in the Add-ons Manager. There are many other tags that can be added, for contributors and translators. The <a href="/en/Install_Manifests" title="en/Install Manifests">full specification</a> of the install.rdf file has all the details.</p> +<p>Since extensions can be translated to multiple languages, it is often necessary to translate the extension's description, or even its name. A localized description and name can be added with the following code:</p> +<div class="code panel" style="border-width: 1px;"> + <div class="codeContent panelContent"> + <pre class="code-java"><em:localized> + <Description> + <em:locale>es-ES</em:locale> + <em:name>XUL School Hola Mundo</em:name> + <em:description>Bienvenido a XUL School!</em:description> + </Description> +</em:localized></pre> + </div> +</div> +<p>The <em>es-ES</em> locale string indicates that this is the Spanish (es) localization for Spain (ES). You can add as many <em><em:localized></em> sections as you need. For Firefox 2, localizing this file is a <a href="/en/Localizing_extension_descriptions#Localizing_before_Gecko_1.9" title="en/Localizing extension descriptions#Localizing before Gecko 1.9">little more complicated</a>. We'll discuss localization further ahead in this section.</p> +<div class="code panel" style="border-width: 1px;"> + <div class="codeContent panelContent"> + <pre class="code-java"><em:type>2</em:type></pre> + </div> +</div> +<p>This specifies that the add-on being installed is an extension. You can read about different possible types in the <a href="/en/Install_Manifests#type" title="en/Install Manifests#type">install.rdf specification</a>.</p> +<div class="code panel" style="border-width: 1px;"> + <div class="codeContent panelContent"> + <pre class="code-java"><em:targetApplication> + <Description> + <em:id>{ec8030f7-c20a-464f-9b0e-13a3a9e97384}</em:id> + <em:minVersion>4.0</em:minVersion> + <em:maxVersion>10.*</em:maxVersion> + </Description> +</em:targetApplication> +</pre> + </div> +</div> +<p>This node specifies the target application and target versions for the extension, specifically Firefox, from version 4 up to version 10. The UUID is Firefox's unique ID. Other Mozilla and Mozilla-based applications such as Thunderbird and Seamonkey have their own. You can have an extension that works on multiple applications and versions. For example, if you create a Firefox extension, it would normally take little effort to port it to SeaMonkey, which has very similar features and UI.</p> +<p>The min and max version specify the version range in which the extension can be installed. Here's more about the <a href="/en/Toolkit_version_format" title="en/Toolkit version format">version format</a>. If the application or version range don't match, you won't be allowed to install the extension, or the extension will be installed in a disabled state. Users can disable version checks through preferences or installing add-ons like the <a class="link-https" href="https://addons.mozilla.org/en-US/firefox/addon/15003" title="https://addons.mozilla.org/en-US/firefox/addon/15003">Add-on Compatibility Reporter</a>. Beginning with Firefox 11, add-ons will default to compatible and Firefox will mostly ignore the version range. Testing your add-ons with every Firefox version is always recommended, though.</p> +<p>This is the information Firefox and other Mozilla applications need to install an add-on. Any errors or missing information will cause the installation process to fail, or the extension to be installed in a disabled state.</p> +<h2 id="The_chrome.manifest_File">The chrome.manifest File</h2> +<blockquote> + <p><span style="color: #0000ff;">Chrome is the set of user interface elements of the application window that are outside of a window's content area.</span> Toolbars, menu bars, progress bars, and window title bars are all examples of elements that are typically part of the chrome.</p> +</blockquote> +<p>Taken from <a href="/en/Chrome_Registration" title="en/Chrome Registration">Chrome Registration</a>.</p> +<p>In other words, the chrome is everything you see in Firefox. All Firefox windows can be seen as having two parts: (1) the chrome and (2) possibly a content area, like the one that displays web pages in a Firefox tab. Windows like the Downloads window are pure chrome. Most of the code for an extension resides in the chrome folder, just like in the Hello World example.</p> +<p>As we saw in the directory structure of the unpacked extension, the chrome is composed of 3 sections: <span style="color: #0000ff;">content</span>, <span style="color: #0000ff;">locale</span> and <span style="color: #0000ff;">skin</span>. The 3 are necessary for most extensions. If we open the <em>chrome.manifest</em> file (again, any text editor will do), we see that the same 3 sections are mentioned:</p> +<div class="code panel" style="border-width: 1px;"> + <div class="codeContent panelContent"> + <pre class="code-java">content xulschoolhello content/ +skin xulschoolhello classic/1.0 skin/ +locale xulschoolhello en-US locale/en-US/ +</pre> + </div> +</div> +<p><span style="color: #0000ff;">The <em>chrome.manifest</em> file tells Firefox where to look for chrome files.</span> The text is spaced to look like a table, but that is not necessary. The parser ignores repeated spaces.</p> +<p>The first word in a line tells Firefox what it is that is being declared (content, skin, locale, or others mentioned later on). The second is the package name, which we will explain shortly.</p> +<p>Skin and locale packages have a third value to specify what locale or what skin they are extending. There can be multiple skin and locale entries relating to different skins and locales. The most common case is having one skin entry for the global skin, <em>classic/1.0</em>, and multiple locale entries, one for each translation. Finally, the location is specified.</p> +<p>There are some additional options that can be included in the entries of a <em>chrome.manifest</em> file. They are documented in the <a href="/en/Chrome_Registration" title="en/Chrome Registration">Chrome Registration</a> page. Notably, we can have entries that are OS-specific. This is important because the appearance of the browser is very different for each operating system. If our extension needed to look differently on different systems, we could change the manifest file so that it looks like this:</p> +<div class="code panel" style="border-width: 1px;"> + <div class="codeContent panelContent"> + <pre class="code-java">content xulschoolhello content/ +skin xulschoolhello classic/1.0 skin/unix/ +skin xulschoolhello classic/1.0 skin/mac/ os=Darwin +skin xulschoolhello classic/1.0 skin/win/ os=WinNT +locale xulschoolhello en-US locale/en-US/ +</pre> + </div> +</div> +<p>This way we can have separate skins for Windows, Mac OS X, and Linux (plus other unix-like systems), each defined in a separate directory. Since most other systems are Unix-based, the "unix" skin is the default, with no flags.</p> +<h2 id="The_Chrome">The Chrome</h2> +<p>As mentioned earlier, the chrome is composed of 3 sections: content, locale and skin. The content is the most important section, holding user interface (XUL) and script (JS) files. The skin section has the files that define most of the look and feel of the UI (using CSS and images, just like web pages). Finally, the locale section holds all text used in the extension, in DTD and properties files. This division allows other developers to create themes that replace skins, and translators to create localizations in different languages, all of this without having to change your extension or your code. This gives Firefox extensions a great deal of flexibility.</p> +<p>Chrome files are accessed through the chrome protocol. This is what a chrome URI looks like:</p> +<div class="code panel" style="border-width: 1px;"> + <div class="codeContent panelContent"> + <pre class="code-java">chrome:<span class="code-comment">//packagename/section/path/to/file</span></pre> + </div> +</div> +<p>So, for instance, if I want to access the file <em>browserOverlay.xul </em>in the extension, the chrome URI would be <em><a class="external" rel="freelink">chrome://xulschoolhello/content/browserOverlay.xul</a></em>.</p> +<p>If you have too many files in the content and you want to organize them in subdirectories, there's nothing you need to change in <em>chrome.manifest</em>, all you need is to add the right path after <em>content</em> in the URI.</p> +<p>Skin and locale files work in the same way, and you don't need to specify skin names or locale names. So, to access the DTD file in the Hello World extension, the chrome path is <em><a class="external" rel="freelink">chrome://xulschoolhello/locale/browserOverlay.dtd</a></em>. Firefox knows what locale to look for.</p> +<p>Here's an interesting experiment. Open a new Firefox tab, type <em><a class="external" rel="freelink">chrome://mozapps/content/downloads/downloads.xul</a></em> on your location bar and press ENTER. Surprised? You just opened the Downloads window in a Firefox tab! You can access any chrome file by just typing its URI in the location bar. This can come in handy if you want to inspect script files that are part of Firefox, other extensions, or your own. Most of these files are opened as text files, with the exception of XUL files, which are executed and displayed like you would normally see them on a window.</p> +<h3 id="Content">Content</h3> +<p>There are 2 files in the content directory. Let's look at the XUL file first.</p> +<p><a href="/en/XUL" title="en/XUL">XUL</a> files are XML files that define the user interface elements in Firefox and Firefox extensions. XUL was inspired by HTML, so you'll see many similarities between the two. However, XUL is also an improvement over HTML, having learned from many of the mistakes made during the evolution of HTML. XUL allows you to create richer and more interactive interfaces than the ones you can create with HTML, or at least XUL makes it easier.</p> +<p>XUL files usually define one of two things: windows or overlays. The file you opened before, <em>downloads.xul</em>, has the code that defines the Downloads window. The XUL file included in the Hello World extension is an overlay. An overlay extends an existing window, adding new elements to it or replacing some of the elements in it. The line that we skipped in the <em>chrome.manifest</em> file states that this XUL file is an overlay for the main browser window:</p> +<div class="code panel" style="border-width: 1px;"> + <div class="codeContent panelContent"> + <pre class="code-java">overlay chrome:<span class="code-comment">//browser/content/browser.xul chrome://xulschoolhello/content/browserOverlay.xul</span></pre> + </div> +</div> +<p>With this line, Firefox knows that it needs to take the contents of <em>browserOverlay.xul</em> and overlay it on the main browser window, <em>browser.xul</em>. You can declare overlays for any window or dialog in Firefox, but overlaying the main browser window is the most common case by far.</p> +<p>Now let's look at the contents of our XUL file. We'll skip the first few lines because they relate to skin and locale, and we'll cover them later.</p> +<div class="code panel" style="border-width: 1px;"> + <div class="codeContent panelContent"> + <pre class="code-java"><overlay id="xulschoolhello-browser-overlay" + xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul"></pre> + </div> +</div> +<p>The root element in the file is an <em>overlay</em>. Other XUL documents use the <em>window</em> or <em>dialog</em> tag. The element has a unique id, which you should have on most elements in your XUL. The second attribute is the namespace, which is something you should always define in your XUL root element. It says that this node and all child nodes are XUL. You only need to change namespace declarations when you mix different types of content in the same document, such as XUL with HTML or SVG.</p> +<div class="panel" style="border-width: 1px;"> + <div class="panelContent"> + <div class="note"> + You may have noticed the naming we use on several places, such as the id <em>xulschoolhello-browser-overlay</em>. This is the namespacing standard that we use to avoid conflicts with Firefox and other extensions, as well as making some development tasks easier. We namespace all ids and style classes in overlay elements because they will be mixed with other elements in the main browser window. If we used generic ids like <em>container</em> or <em>input</em>, they will likely conflict with ids used within Firefox, or with ids from other extension overlays. Using namespaces minimizes compatibility problems with other extensions. We use camel casing for file names, and all lower case with dashes for element ids and CSS style class names, but you're free to use your own system.</div> + </div> +</div> +<div class="code panel" style="border-width: 1px;"> + <div class="codeContent panelContent"> + <pre class="code-java"><script type=<span class="code-quote">"application/x-javascript"</span> + src=<span class="code-quote">"chrome:<span class="code-comment">//xulschoolhello/content/browserOverlay.js"</span> /></span></pre> + </div> +</div> +<p>Just like in HTML, this includes a JavaScript script file. You can have as many <em>script</em> elements in a XUL document as you need. We'll look into its code later.</p> +<div class="panel" style="border-width: 1px;"> + <div class="panelContent"> + <div class="note"> + You also probably noticed how we format our code, and wonder about the rules we follow. Our general rule on line length is not having lines longer than 80 characters. This feels very restrictive, specially with XML files, but the number was chosen to allow pretty much any text editor to handle these files easily. Even old command line editors work well with files that cut their lines at 80 characters. The tabulation is very straightforward: 2 blank space indents. We never use actual tab characters, with the exception of Makefiles, which will be covered later on. Most of our coding standards are based on Mozilla's or other known and used standards.</div> + </div> +</div> +<p> We'll skip some code that is covered in the locale section, moving on to the most important part of the content:</p> +<div class="code panel" style="border-width: 1px;"> + <div class="codeContent panelContent"> + <pre class="code-java"><menubar id="main-menubar"> + <menu id="xulschoolhello-hello-menu" label="&xulschoolhello.hello.label;" + accesskey="&xulschoolhello.helloMenu.accesskey;" insertafter="helpMenu"> + <menupopup> + <menuitem id="xulschoolhello-hello-menu-item" + label="&xulschoolhello.hello.label;" + accesskey="&xulschoolhello.helloItem.accesskey;" + oncommand="XULSchoolChrome.BrowserOverlay.sayHello(event);" /> + </menupopup> + </menu> +</menubar> + +<vbox id="appmenuSecondaryPane"> + <menu id="xulschoolhello-hello-menu-2" label="&xulschoolhello.hello.label;" + accesskey="&xulschoolhello.helloMenu.accesskey;" + insertafter="appmenu_addons"> + <menupopup> + <menuitem id="xulschoolhello-hello-menu-item-2" + label="&xulschoolhello.hello.label;" + accesskey="&xulschoolhello.helloItem.accesskey;" + oncommand="XULSchoolChrome.BrowserOverlay.sayHello(event);" /> + </menupopup> + </menu> +</vbox> +</pre> + </div> +</div> +<p>This is the code that adds the <em>Hello World</em> menu to the browser window.</p> +<p>There are two similar code blocks, because in modern versions of Firefox, particularly on Windows, a single Firefox menu button is presented, with simplified menu options, rather than an extensive menu bar. The second code block covers the common menu button case; the first code block covers all other cases. Check <em>Menu Bar </em>under the <em>Options </em>menu of the menu button to toggle display of the classic menu on Windows and some Linux distributions.</p> +<p>In order to write this code, we needed some knowledge of the XUL code in <em>browser.xul</em>. We needed to know that the id of the right pane in the unified menu is <em>appmenuSecondaryPane</em>. We're adding a menu of our own, and telling Firefox to add it in that pane, right after the Add-ons item. That's the purpose of the attribute:</p> +<div class="code panel" style="border-width: 1px;"> + <div class="codeContent panelContent"> + <pre class="code-java">insertafter=<span class="code-quote">"appmenu_addons"</span> +</pre> + </div> +</div> +<p><em>appmenu_addons</em> is the id of the menu element that corresponds to the Add-ons menu item in the main menu. We'll see later how we can find out things like the ids of browser elements, but for now let's look at the elements that compose the Hello World menu.</p> +<p>For the classic menu, we added the Hello World menu right in the "root" of the menu so that it would be very easy for you to spot it, but this is not a recommended practice. Imagine if all extensions added menus to the top menu; having a few extensions would make it look like an airplane dashboard, full of knobs and switches. In the case of the unified menu, things are a little more difficult due to lack of options. If your menu item fits in the Web Developer section, it is recommended that you add it there. Otherwise, the root menu might be your only recourse.</p> +<p>One recommended location for menus in the classic menu vase is under the <em>Tools</em> menu, so the code should really look like this:</p> +<div class="code panel" style="border-width: 1px;"> + <div class="codeContent panelContent"> + <pre class="code-java"><menupopup id=<span class="code-quote">"menu_ToolsPopup"</span>> + <menu id=<span class="code-quote">"xulschoolhello-hello-menu"</span> label=<span class="code-quote">"&</span><span class="code-quote">xulschoolhello</span><span class="code-quote">.hello.label;"</span> + accesskey=<span class="code-quote">"&</span><span class="code-quote">xulschoolhello</span><span class="code-quote">.helloMenu.accesskey;"</span> + insertbefore=<span class="code-quote">"</span>devToolsEndSeparator<span class="code-quote">"</span>> + <menupopup> + <menuitem id=<span class="code-quote">"</span><span class="code-quote">xulschoolhello</span><span class="code-quote">-hello-menu-item" + </span> label=<span class="code-quote">"&</span><span class="code-quote">xulschoolhello</span><span class="code-quote">.hello.label;"</span> + accesskey=<span class="code-quote">"&</span><span class="code-quote">xulschoolhello</span><span class="code-quote">.helloItem.accesskey;"</span> + oncommand=<span class="code-quote">"XULSchoolChrome.BrowserOverlay.sayHello(event);"</span> /> + </menupopup> + </menu> +</menupopup> +</pre> + </div> +</div> +<p>We're overlaying the menu that is deeper into the XUL tree, but it doesn't matter because all we need is the id of the element we want to overlay. In this case it is the <a href="/en/XUL/menupopup" title="en/XUL/menupopup">menupopup</a> element that's inside of the Tools <a href="/en/XUL/menu" title="en/XUL/menu">menu</a> element. The <em>insertbefore</em> attribute tells Firefox to add the menu at the bottom of the dev tools section, above its end separator. We'll discuss more about menus later on in the tutorial.</p> +<p>Now let's look at the actual code:</p> +<div class="code panel" style="border-width: 1px;"> + <div class="codeContent panelContent"> + <pre class="code-java">oncommand=<span class="code-quote">"XULSchoolChrome.BrowserOverlay.sayHello(event);"</span> +</pre> + </div> +</div> +<p>This attribute defines an event handler. The <em>command</em> event is the most frequently used in Firefox, since it corresponds to the main action for most UI elements. The value of the attribute is JavaScript code that invokes a function. This function is defined in the JS file that was included with the <em>script</em> tag. The JS function will be called once the user clicks on the menu item in the Hello World menu. All event handlers define a special object named <em>event</em>, which is usually good to pass as an argument to the function. Event handlers are explained in greater depth further ahead.</p> +<p>Now let's look at the JavaScript file and see what's going on when the event is fired.</p> +<div class="code panel" style="border-width: 1px;"> + <div class="codeContent panelContent"> + <pre class="brush: js">/** + * XULSchoolChrome namespace. + */ +if ("undefined" == typeof(XULSchoolChrome)) { + var XULSchoolChrome = {}; +};</pre> + </div> +</div> +<p>The <em>XULSchoolChrome</em> namespace is defined. All objects and variables we define in this JavaScript are global, meaning that scripts in Firefox and other extensions can see them and interact with them. This also means that if we define an object called <em>MenuHandler</em> or some other generic name, it's likely going to conflict with an existing object. What we do here is define a single global object: <em>XULSchoolChrome</em>. Now we know that all of our objects are inside this object, which is unlikely to be duplicated or overwritten by other extensions.</p> +<p>You can read more about the <a href="/en/JavaScript/Reference/Operators/typeof" title="en/Core JavaScript 1.5 Reference/Operators/Special Operators/typeof Operator"><span class="external">typeof operator</span></a>. If you're unfamiliar with JavaScript or this particular syntax, initializing an object as <em>{}</em> is the equivalent of initializing it to <em>new Object()</em>.</p> +<div class="code panel" style="border-width: 1px;"> + <div class="codeContent panelContent"> + <pre class="brush: js">/** + * Controls the browser overlay <span class="code-keyword">for</span> the Hello World extension. + */ +XULSchoolChrome.BrowserOverlay = {</pre> + </div> +</div> +<p>Finally, <em>BrowserOverlay</em> is our object. Naming and referencing objects in such a long and verbose manner can feel uncomfortable at first, but it's worth the cost.</p> +<div class="panel" style="border-width: 1px;"> + <div class="panelContent"> + <div class="note"> + We use <a class="external" href="http://java.sun.com/j2se/javadoc/writingdoccomments/index.html">Javadoc</a> style comments on all namespaces, objects and object members. This is a similar standard to the one used in Mozilla code, and some tools can generate documentation automatically from Javadoc.</div> + </div> +</div> +<div class="code panel" style="border-width: 1px;"> + <div class="codeContent panelContent"> + <pre class="brush: js">sayHello : function(aEvent) { + let stringBundle = document.getElementById("xulschoolhello-string-bundle"); + let message = stringBundle.getString("xulschoolhello.greeting.label"); + + window.alert(message); +}</pre> + </div> +</div> +<p>And, finally, this is our function declaration. Three lines of code are all we need for it to work. The first line in the body of the function declares a variable that will hold the <a href="/en/XUL/stringbundle" title="en/XUL/stringBundle">stringbundle</a> element defined in the overlay. The variable is declared using <em>let,</em> which is similar to <em>var</em> but with more restricted scope. Here you can read more about <a href="/en/JavaScript/Reference/Statements/let" title="let"><span class="external">let declarations</span>.</a></p> +<p>Just like in regular JS, we can use the <a href="/en/DOM" title="en/DOM"><span class="external">DOM</span></a> (Document Object Model) in order to manipulate the XUL document. First we get a reference of the <a href="/en/XUL/stringbundle" title="en/XUL/stringbundle"><span class="external">stringbundle element</span></a> in the document. This is a special element that allows us to obtain localized strings dynamically, by only providing a "key" that identifies the string. This is what we do on the second line. We call the <a href="/en/XUL/stringbundle#m-getString" title="en/XUL/stringbundle#m-getString">getString method</a> of the bundle element and get the localized message to be displayed. We then call the <a href="/en/DOM/window.alert" title="en/DOM/window.alert">window.alert</a> function with the message, just like we would do in an HTML document.</p> +<h3 id="Locale">Locale</h3> +<p>There are two types of locale files: DTD and properties, and in this example we use them both. DTD is the most efficient way of showing text in XUL, so you should use it whenever possible. It is somewhat inflexible so it can't be used for dynamically generated text, hence the need for an alternate way of getting localized strings.</p> +<p>Looking back at the menu code, you probably noticed some attributes such as this:</p> +<div class="code panel" style="border-width: 1px;"> + <div class="codeContent panelContent"> + <pre class="code-java">label=<span class="code-quote">"&xulschoolhello.hello.label;"</span> accesskey=<span class="code-quote">"&xulschoolhello.helloItem.accesskey;"</span></pre> + </div> +</div> +<p>These attributes define the text that you see on the menus, and they are string keys that are defined in our DTD file, <em>browserOverlay.dtd</em>. The DTD file was included in the XUL file with the following code:</p> +<div class="code panel" style="border-width: 1px;"> + <div class="codeContent panelContent"> + <pre class="code-java"><!DOCTYPE overlay SYSTEM "chrome://xulschoolhello/locale/browserOverlay.dtd" ></pre> + </div> +</div> +<p>And in the DTD file you can see the association between keys and localized strings:</p> +<div class="code panel" style="border-width: 1px;"> + <div class="codeContent panelContent"> + <pre class="code-java"><!ENTITY xulschoolhello.hello.label <span class="code-quote">"Hello World!"</span>> +<!ENTITY xulschoolhello.helloMenu.accesskey <span class="code-quote">"l"</span>> +<!ENTITY xulschoolhello.helloItem.accesskey <span class="code-quote">"H"</span>></pre> + </div> +</div> +<p>Notice that on the XUL file you enclose the string key with <em>&</em> and <em>;</em> while on the DTD file you only specify the key. You may get weird parsing errors or incorrect localization if you don't get this right.</p> +<p>Access keys are the shortcuts that allow you to quickly navigate a menu using only the keyboard. They are also the only way to navigate a menu for people with accessibility problems, such as partial or total blindness, or physical disabilities that make using a mouse very difficult or impossible. You can easily recognize the access keys on Windows because the letter that corresponds to the access key is underlined, as in the following image:</p> +<div> + <p><img alt="" class="internal" src="../../../../@api/deki/files/4226/=accesskeys.png" style="width: 167px; height: 58px;"></p> +</div> +<p>Most user interface controls have the <em>accesskey</em> attribute, and you should use it. The value of the access key is localized because it should match a letter in the label text. You should also be careful to avoid access key repetition. For example, within a menu or submenu, access keys should not be repeated. In a window you have to be more careful picking access keys because there are usually more controls there. You have to be specially careful when picking access keys on an overlay. In our case, we can't use the letter "H" as an accesskey in the Main menu item, because it would be the same as the access key in the Help menu. Same goes with "W" and the Window menu on Mac OS. So we settled on the letter "l".</p> +<p>DTD strings are resolved and set when the document is being loaded. If you request the <em>label</em> attribute value for the Hello World menu using DOM, you get the localized string, not the string key. You cannot dynamically change an attribute value with a new DTD key, you have to set the new value directly:</p> +<div class="code panel" style="border-width: 1px;"> + <div class="codeContent panelContent"> + <pre class="brush: js">let helloItem = document.getElementById(<span class="code-quote">"xulschoolhello-hello-menu-item"</span>); + +<span class="code-comment">// The alert will say <span class="code-quote">"Hello World!"</span> +</span>alert(helloItem.getAttribute(<span class="code-quote">"label"</span>)); +<span class="code-comment">// Wrong +</span>helloItem.setAttribute(<span class="code-quote">"label"</span>, <span class="code-quote">"&</span><span class="code-quote">xulschoolhello</span><span class="code-quote">.hello2.label;"</span>); +<span class="code-comment">// Better +</span>helloItem.setAttribute(<span class="code-quote">"label"</span>, <span class="code-quote">"Alternate message"</span>); +<span class="code-comment">// Right! +</span>helloItem.setAttribute(<span class="code-quote">"label"</span>, someStringBundle.getString(<span class="code-quote">"</span><span class="code-quote">xulschoolhello</span><span class="code-quote">.hello2.label"</span>));</pre> + </div> +</div> +<p>This is the reason DTD strings are not a solution for all localization cases, and the reason we often need to include string bundles in XUL files:</p> +<div class="code panel" style="border-width: 1px;"> + <div class="codeContent panelContent"> + <pre class="code-java"><stringbundleset id="stringbundleset"> + <stringbundle id="xulschoolhello-string-bundle" + src="chrome://xulschoolhello/locale/browserOverlay.properties" /> +</stringbundleset></pre> + </div> +</div> +<p>The <a href="/en/XUL/stringbundleset" title="en/XUL/stringbundleset">stringbundleset</a> element is just a container for <a href="/en/XUL/stringbundle" title="en/XUL/stringbundle">stringbundle</a> elements. There should only be one per document, which is the reason why we overlay the <em>stringbundleset</em> that is in <em>browser.xul</em>, hence the very generic id. We don't include the <em>insertbefore</em> or <em>insertafter</em> attributes because the ordering of string bundles doesn't make a difference. The element is completely invisible. If you don't include any of those ordering attributes in an overlay element, Firefox will just append your element as the last child of the parent element.</p> +<p>All you need for the string bundle is an id (to be able to fetch the element later) and the chrome path to the properties file. And, of course, you need the properties file:</p> +<div class="code panel" style="border-width: 1px;"> + <div class="codeContent panelContent"> + <pre class="code-java">xulshoolhello.greeting.label = Hi! How are you?</pre> + </div> +</div> +<p>The whitespace around the equals sign is ignored. Just like in <em>install.rdf</em>, comments can be added using the # character at the beginning of the line. Empty lines are ignored as well.</p> +<p>You will often want to include dynamic content as part of localized strings, like when you want to inform the user about some stat related to the extension. For example: "Found 5 words matching the search query". Your first idea would probably be to simply concatenate strings, and have one "Found" property and another "words matching..." property. This is not a good idea. It greatly complicates the work of localizers, and grammar rules on different languages may change the ordering of the sentence entirely. For this reason it's better to use parameters in the properties:</p> +<div class="code panel" style="border-width: 1px;"> + <div class="codeContent panelContent"> + <pre class="code-java">xulshoolhello.search.label = Found %S words matching the search query!</pre> + </div> +</div> +<p>Then you use <a href="/en/XUL/stringbundle#m-getFormattedString" title="en/XUL/stringbundle#m-getFormattedString">getFormattedString</a> instead of <em>getString</em> in order to get the localized string. Thanks to this we don't need to have multiple properties, and life is easier for translators. You can read more about it on the <a href="/en/XUL_Tutorial/Property_Files#Text_Formatting" title="en/XUL Tutorial/Property Files#Text Formatting">Text Formatting section</a> of the XUL Tutorial. Also have a look at the <a href="/en/Localization_and_Plurals" title="en/Localization and Plurals">Plurals and Localization</a> article, that covers a localization feature in Firefox that allows you to further refine this last example to handle different types of plural forms that are also language-dependent.</p> +<h3 id="Skin">Skin</h3> +<p>Styling XUL is very similar to styling HTML. We'll look into some of the differences when we cover the XUL Box Model, and other more advanced topics. There isn't much styling you can do to a minimal menu and a very simple alert message, so the Hello World extension only includes an empty CSS file and the compulsory global skin file:</p> +<div class="code panel" style="border-width: 1px;"> + <div class="codeContent panelContent"> + <pre class="code-java"><?xml-stylesheet type=<span class="code-quote">"text/css"</span> href=<span class="code-quote">"chrome:<span class="code-comment">//global/skin/"</span> ?> +</span><?xml-stylesheet type=<span class="code-quote">"text/css"</span> + href=<span class="code-quote">"chrome:<span class="code-comment">//xulschoolhello/skin/browserOverlay.css"</span> ?></span></pre> + </div> +</div> +<p>The global skin CSS file holds the default styles for all XUL elements and windows. Forgetting to include this file in a XUL window usually leads to interesting and often unwanted results. In our case we don't really need to include it, since we're overlaying the main browser XUL file, and that file already includes this global CSS. At any rate it's better to always include it. This way it's harder to make the mistake of not including it. You can enter the chrome path in the location bar and inspect the file if you're curious.</p> +<p>This covers all of the files in the Hello World extension. Now you should have an idea of the basics involved in extension development, so now we'll jump right in and set up a development environment. But first, a little exercise.</p> +<h2 id="Exercise">Exercise</h2> +<p>Make the following changes to the example extension:</p> +<ul> + <li>Edit the welcome message that is displayed in the alert window.</li> + <li>Move the Hello World menu to the <em>Tools</em> menu, where it belongs.</li> +</ul> +<p>Repackage the XPI. Issue the following command from within the extension root directory on Linux or Mac OS X:</p> +<pre>zip ../xulschoolhello2.xpi **/* +</pre> +<p>On Windows, use a ZIP tool to compress all files and subdirectories within the extension root directory. Name the file with extension <em>.xpi</em></p> +<p>Re-install the XPI. You can just drag the XPI file to the browser and it will be installed locally.</p> +<p>Test it and verify your changes worked. If you run into problems at installation, it's likely that you didn't reproduce the XPI structure correctly, maybe adding unnecessary folders.</p> +<div class="note"> + <strong>Note:</strong> Packaging an extension is really just creating a ZIP archive of the contents of the main folder, then changing the filename extension to <code>.XPI</code>. Do <strong>not</strong> zip the containing folder, just its contents. The <code>content</code> folder, <code>chrome.manifest</code>, <code>install.rdf</code>, and other files and directories should be at the root level of your archive. If you zip the containing folder, your extension will not load.</div> +<p>Note that the <em>Tools </em>menu is hidden by default on Firefox 4 and above, on Windows and some Linux distributions. Check <em>Menu Bar </em>under the <em>Options </em>menu of the Firefox menu button to enable it.</p> +<p>Once you're done, you can look at this reference solution: <a href="/@api/deki/files/5141/=xulschoolhello2.xpi" title="https://developer.mozilla.org/@api/deki/files/5141/=xulschoolhello2.xpi">Hello World 2</a>.</p> +<p>{{ PreviousNext("XUL_School/Getting_Started_with_Firefox_Extensions", "XUL_School/Setting_Up_a_Development_Environment") }}</p> +<p><span style="font-size: small;">This tutorial was kindly donated to Mozilla by Appcoast.</span></p> diff --git a/files/id/archive/mozilla/xulrunner/index.html b/files/id/archive/mozilla/xulrunner/index.html new file mode 100644 index 0000000000..2bc8fd2c15 --- /dev/null +++ b/files/id/archive/mozilla/xulrunner/index.html @@ -0,0 +1,84 @@ +--- +title: XULRunner +slug: Archive/Mozilla/XULRunner +translation_of: Archive/Mozilla/XULRunner +--- +<div class="callout-box"> + <strong><a href="/en-US/docs/Getting_started_with_XULRunner" title="Getting_started_with_XULRunner">Getting Started with XULRunner</a></strong><br> + A short introduction to XULRunner.</div> +<div> + <span class="seoSummary"><strong>XULRunner</strong> is a Mozilla runtime package that can be used to bootstrap <a href="/en-US/docs/XUL" title="XUL">XUL</a>+<a href="/en-US/docs/XPCOM" title="XPCOM">XPCOM</a> applications that are as rich as Firefox and Thunderbird. It provides mechanisms for installing, upgrading, and uninstalling these applications.</span> XULRunner also provides <code>libxul</code>, a solution which allows the embedding of Mozilla technologies in other projects and products.</div> +<table class="topicpage-table"> + <tbody> + <tr> + <td> + <h2 id="Releases" name="Releases">Releases</h2> + <div class="note"> + <p>XULRunner can be <a class="external" href="http://ftp.mozilla.org/pub/mozilla.org/xulrunner/releases/latest" title="http://ftp.mozilla.org/pub/mozilla.org/xulrunner/releases/">downloaded from ftp.mozilla.org</a>. Please read the <a class="internal" href="/en-US/docs/XULRunner_1.9.2_Release_Notes" title="XULRunner 1.9.2 Release Notes">release notes</a> for installation, uninstallation, and other information.</p> + <p>Firefox 3 and later ships with a private XULRunner package, which can run any compatible XULRunner application using the <code>-app</code> switch.</p> + <p><a href="/en-US/docs/XULRunner/Old_Releases" title="XULRunner/Old_Releases">Older builds</a> are also available.</p> + </div> + <h2 id="Overview" name="Overview">Overview</h2> + <ul> + <li>{{ interwiki('wikimo', 'XULRunner', 'Development Plan') }}</li> + <li><a href="/en-US/docs/XULRunner/What_XULRunner_Provides" title="XULRunner/What_XULRunner_Provides">What XULRunner Provides</a></li> + <li><a href="/en-US/docs/XULRunner_FAQ" title="XULRunner_FAQ">XULRunner FAQ</a></li> + <li>Nightly builds: <a class="external" href="http://ftp.mozilla.org/pub/mozilla.org/xulrunner/nightly/latest-trunk/">unstable-trunk</a></li> + </ul> + <h2 class="Documentation" id="Documentation" name="Documentation">Documentation</h2> + <dl> + <dt> + <a href="/en-US/docs/Getting_started_with_XULRunner" title="Getting_started_with_XULRunner">Getting Started with XULRunner</a></dt> + <dd> + Short tutorial on building desktop applications with XULRunner.</dd> + <dt> + <a href="/en-US/docs/XUL_Tutorial" title="XUL Tutorial">XUL Tutorial</a></dt> + <dd> + Once you have a working XULRunner application, use the XUL tutorial to expand it into a fantastic XUL application.</dd> + <dt> + <a href="/en-US/docs/XULRunner_tips" title="XULRunner_tips">XULRunner tips</a></dt> + <dd> + A collection of tips for working with XULRunner.</dd> + <dt> + <a href="/en-US/docs/XULRunner/Deploying_XULRunner_1.8" title="XULRunner/Deploying_XULRunner_1.8">Deploying XULRunner</a></dt> + <dd> + An introduction on how to package your application with XULRunner.</dd> + <dt> + <a href="/en-US/docs/XULRunner_Hall_of_Fame" title="XULRunner_Hall_of_Fame">XULRunner Hall of Fame</a></dt> + <dd> + Tracks all available applications based on XULRunner.</dd> + <dt> + <a href="/en-US/docs/Developer_Guide/Build_Instructions" title="Build_Documentation">Build Documentation</a></dt> + <dd> + Learn how to get the source and build it.</dd> + <dt> + <a href="/en-US/docs/Debugging_a_XULRunner_Application" title="Debugging_a_XULRunner_Application">Debug Documentation</a></dt> + <dd> + Steps to configure Venkman to debug your App</dd> + <dt> + <a class="external" href="http://zenit.senecac.on.ca/wiki/index.php/XULRunner_Guide">XULRunner Guide</a></dt> + <dd> + A fairly complete, but outdated, introduction and tutorial for XULRunner which collates much of the documentation found here.</dd> + </dl> + <p><span class="alllinks"><a href="/en-US/docs/tag/XULRunner" title="tag/XULRunner">View all...</a></span></p> + </td> + <td> + <h2 class="Community" id="Community" name="Community">Community</h2> + <ul> + <li>View Mozilla forums... {{ DiscussionList("dev-platform", "mozilla.dev.platform") }}</li> + <li><a class="link-irc" href="irc://irc.mozilla.org/#xulrunner">#xulrunner on irc.mozilla.org</a></li> + <li><a href="/en-US/docs/XULRunner/Community" title="XULRunner/Community">Other community links...</a></li> + </ul> + <h2 class="Related_Topics" id="Related_Topics" name="Related_Topics">Related topics</h2> + <ul> + <li><a href="/en-US/docs/XUL" title="XUL">XUL</a></li> + </ul> + <h2 id="See_also" name="See_also">See also</h2> + <ul> + <li><a class="external" href="http://www.kodewerx.org/wiki/A_Brief_Introduction_To_XULRunner:_Part_1" title="http://www.kodewerx.org/wiki/A_Brief_Introduction_To_XULRunner:_Part_1">A brief introduction to XULRunner</a></li> + </ul> + </td> + </tr> + </tbody> +</table> +<p> </p> |