diff options
Diffstat (limited to 'browser/components/storybook/docs/README.xul-and-html.stories.md')
| -rw-r--r-- | browser/components/storybook/docs/README.xul-and-html.stories.md | 67 |
1 files changed, 67 insertions, 0 deletions
diff --git a/browser/components/storybook/docs/README.xul-and-html.stories.md b/browser/components/storybook/docs/README.xul-and-html.stories.md new file mode 100644 index 0000000000..8d2d4cb7bf --- /dev/null +++ b/browser/components/storybook/docs/README.xul-and-html.stories.md @@ -0,0 +1,67 @@ +# XUL and HTML + +This document gives a quick overview of XUL and HTML, especially as it pertains to desktop front-end developers. +As we migrate away from XUL elements to HTML elements where possible, it is important to note the differences between these two technologies. +Additionally it is helpful to know how to use both where needed, as some elements will still need to use XUL. + +## What is XUL + +XUL is an XML-based language for building cross-platform user interfaces and applications, so all the features of XML are available in XUL as well. +This is in contrast to HTML which is intended for developing web pages. +Because of this XUL is oriented towards application artifacts such as windows, scrollbars, and menus instead of pages, headings, links, etc. +These XUL elements are provided to an HTML page without the page having any control over them. + +XUL was and is used to create various UI elements, for example: +- Input controls such as textboxes and checkboxes +- Toolbars with buttons or other content +- Menus on a menu bar or pop up menus +- Tabbed dialogs +- Trees for hierarchical or tabular information + +XUL is a Mozilla-specific technology with many similarities but also many differences to HTML. +These include a different box model (although it is now synthesized in the HTML box model) and the ability to be backed by C++ code. + +## What requires XUL + +While many of the existing XUL elements that make up the browser can be migrated to HTML, there are some elements that require XUL. +These elements tend to be fundamental to the browser such as windows, popups, panels, etc. +Elements that need to emulate OS-specific styling also tend to be XUL elements. +While there are parts of these elements that must be XUL, that does not mean that the component must be entirely implmented in XUL. +For example, we require that a `panel` can be drawn outside of a window's bounds, but then we can have HTML inside of that `panel` element. + +The following is not an exhaustive list of elements that require XUL: +- Browser Window + - https://searchfox.org/mozilla-central/source/xpfe/appshell/nsIXULBrowserWindow.idl +- Popups + - https://searchfox.org/mozilla-central/source/dom/webidl/XULPopupElement.webidl + - https://searchfox.org/mozilla-central/source/layout/xul/nsMenuPopupFrame.cpp + - https://searchfox.org/mozilla-central/source/toolkit/content/widgets/autocomplete-popup.js + - https://searchfox.org/mozilla-central/source/toolkit/content/widgets/menupopup.js +- Panels + - https://searchfox.org/mozilla-central/source/toolkit/content/widgets/panel.js + +## When to use HTML or XUL + +Now that HTML is powerful enough for us to create almost an entire application with it, the need for the features of XUL has diminished. +We now prefer to write HTML components over XUL components since that model is better understood by the web and front-end community. +This also allows us to gain new features of the web in the UI that we write without backporting them to XUL. + +There are some cases where XUL may still be required for non-standard functionality. +Some XUL elements have more functions over similar HTML elements, such as the XUL `<browser>` element compared to the HTML `<iframe>` element. +The XUL `<panel>` can exceed the bounds of its parent document and is useful for dropdowns, menus, and similar situations. +In these situations, it would be appropriate to use XUL elements. +Otherwise, we want to [start replacing XUL elements with HTML elements](https://bugzilla.mozilla.org/show_bug.cgi?id=1563415). +Because of this, new code **should use HTML whenever possible**. + +## Mixing HTML and XUL + +There are a few things you must do in order to use HTML in a XUL file. +First, you must add the following attribute to the `window` tag of the XUL file, or to the outermost HTML element. +`xmlns:html="http://www.w3.org/1999/xhtml`. +Using this allows Firefox (or other applications using Gecko) to distinguish the HTML tags from the XUL ones. +Second, any HTML element used must be prefixed with `html:` otherwise the element will be parsed as a XUL element. +For example, to use a HTML anchor, you would declare it as `<html:a>`. +Third, any tags or attributes you use have to be in lowercase as XML is case-sensitive. + +Please note [you cannot declare XUL in HTML markup](https://searchfox.org/mozilla-central/rev/7a4c08f2c3a895c9dc064734ada320f920250c1f/toolkit/content/tests/widgets/test_panel_list_in_xul_panel.html#35-36). +You can use `document.createXULElement()` to programmatically create a XUL element in chrome privileged documents. |