CaScadeS and Creating a XUL+JS Based Mozilla Extension European Mozilla Developers Meeting 2003 FOSDEM February 08, 2003 Daniel Glazman daniel@glazman.org

1. A few postulates

• Our editor is good but...
• ...Composer is targeting beginners
• Advanced users need more, and need CSS editing
• Available CSS editors on the market are not for beginners
• No CSS editor on the market is sync'ed with Gecko state of art

2. (Personal) Conclusions

• We need a downloadable CSS editor add-on to Mozilla
• We need a CSS editor that even beginners can use

3. Composer

XUL + JS + XBL + CSS
↓
JS API + Command manager
↓
Editor core

4. Extensibility

1. What languages do we need for this?
2. How can we call this CSS editor from Composer ?
   
   

   
   
   

3. How can we package such an add-on?

5. Languages

1. UI: XUL has everything we need
   • Overlays allow us to extend the app
   • XUL itself provides all we need to make a CSS editor's UI
2. core: JS has everything we need
   • Mozilla implements a large part of the CSS Object model
   • Chrome* JS can directly call the editor
   • Gecko interfaces can be used from JS, for instance to save a local file

* Does everyone here understand the word "chrome"?

6. UI

Interaction between Composer and CaScadeS

CaScadeS will live under Tools > CSS Editor menu

From editor.xul:

    <!-- tasks menu filled from tasksOverlay -->
    <menu id="tasksMenu">
      <menupopup id="taskPopup">
        <menuitem id="menu_validate" observes="cmd_validate"/>
        <menuseparator id="sep_validate"/>
      </menupopup>
    </menu>

A new overlay will create the new menu item

7. CaScadeS overlay

<overlay id="cascadesToolbar" 
        xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">


  <script type="application/x-javascript" src="chrome://cascades/content/cascadesOverlay.js"/>

  <menupopup id="taskPopup">
    <menuitem label="&cascadesMenuItem.label;"
              accesskey="&cascadesMenuItem.accesskey;"
              oncommand="openCascadesDialog();"
              insertafter="menu_validate"/>
  </menupopup>
</overlay>

function openCascadesDialog()
{
  window.openDialog("chrome://cascades/content/EdCssProps.xul",
                    "_blank",
                    "chrome,close,modal,titlebar");
  window._content.focus();
}

8. Overlay "registration"

contents.rdf

<?xml version="1.0"?> 
<RDF:RDF xmlns:RDF="http://www.w3.org/1999/02/22-rdf-syntax-ns#" 
            xmlns:chrome="http://www.mozilla.org/rdf/chrome#"> 

  <RDF:Seq about="urn:mozilla:package:root"> 
    <RDF:li resource="urn:mozilla:package:cascades"/> 
  </RDF:Seq> 

  <RDF:Description about="urn:mozilla:package:cascades" 
        chrome:displayName="CaScadeS, the stylesheet editor" 
        chrome:author="Daniel Glazman" 
        chrome:name="cascades"> 
  </RDF:Description>

	<RDF:Seq about="urn:mozilla:overlays">
		<RDF:li resource="chrome://editor/content/editor.xul"/>
	</RDF:Seq>

	<RDF:Seq about="chrome://editor/content/editor.xul">
		<RDF:li>chrome://cascades/content/cascadesOverlay.xul</RDF:li>
	</RDF:Seq>
</RDF:RDF>

8. XUL

http://xulplanet.com/ is your friend

9. JS

• CSS Object Model
  • browse all stylesheets attached to the document
  • create style rules and browse them
  • access the value(s) of individual CSS properties
• Editor core
  • use GetCurrentEditor()
  • create a STYLE or a LINK element
    (that's the only way to create a stylesheet in DOM 2)
  • to notify the editor we changed the document
• Others
  • Necko, to save stylesheets on the local HD
  • FilePicker
  • nsIFontEnumerator

10. L10N

Make it clean, make it localizable!!!

• entities in a *.dtd file
• directory locale/<lang>
• registered by another contents.rdf file

  <?xml version="1.0"?>
  <RDF:RDF xmlns:RDF="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
           xmlns:chrome="http://www.mozilla.org/rdf/chrome#">
  
    <!-- list all the skins being supplied by this package -->
    <RDF:Seq about="urn:mozilla:locale:root">
      <RDF:li resource="urn:mozilla:locale:en-US"/>
    </RDF:Seq>
  
    <!-- locale information -->
    <RDF:Description about="urn:mozilla:locale:en-US">
      <chrome:packages>
        <RDF:Seq about="urn:mozilla:locale:en-US:packages">
          <RDF:li resource="urn:mozilla:locale:en-US:cascades"/>
        </RDF:Seq>
      </chrome:packages>
    </RDF:Description>
  
    <RDF:Description about="urn:mozilla:locale:en-US:cascades"
  	                 chrome:localeVersion="1.3b"/>
  </RDF:RDF>

11. Packaging

An install JS script registers the content and the locale parts.

The XPI file is a zip of the tree:

cascades03.xpi
    cascades/
    cascades/content/
    cascades/content/contents.rdf
    cascades/content/cascadesOverlay.js
    cascades/content/cascadesOverlay.xul
    cascades/content/commonCssProps.js
    cascades/content/compatibility.js
    cascades/content/EdCssProps-utils.js
    cascades/content/EdCssProps.css
    cascades/content/EdCssProps.js
    cascades/content/EdCssProps.xul
    cascades/content/tabsOverlay.xul
    cascades/locale/ 
    cascades/locale/en-US/
    cascades/locale/en-US/contents.rdf
    cascades/locale/en-US/cascadesOverlay.dtd
    cascades/locale/en-US/EdCssProps.dtd
    install.js

11. Make available

Make an install page:

function doneFn (name, result)
{
  if (result != 0 && result != 999)
    alert("The install didn't seem to work, you could maybe try " +
          "a manual install instead.\nFailure code was " + result + ".");
  else
    alert("Installation complete, please restart your browser.");
}

function install(packageName, fileName)
{
  var xpi = new Object();
  xpi[packageName] = fileName;
  InstallTrigger.install(xpi, doneFn);
}

<a href="javascript:install('cascades', 'cascades03.xpi');">Install CaScadeS</a>

12. How it came to life & problems encountered

• I knew almost nothing about XUL and JS when I started.
  • Corollary: I still know almost nothing about it ;-)
• I learned everything about XUL at http://xulplanet.com/
  • but a lot of XUL stuff is poorly or not documented
• I learned everything about XPI Packaging at http://xulplanet.com/
  • folks in #mozilla are very helpful
• I had to look at some other XPIs like Document Inspector to correctly register locale directory
  • Grab other XPIs, unzip them, read them

There is always a first time ;-)

Overall, making such a CSS editor add-on was surprisingly easy and Mozilla is an incredible platform for extensible applications.