Call for contributors: New Theme Development Docs

Discuss application theming and theme development.
User avatar
KLB
Posts: 2282
Joined: December 21st, 2003, 9:25 am
Location: Saco Maine
Contact:

Re: Call for contributors: New Theme Development Docs

Post by KLB »

Patrick,

I've been trying to triage more bugs lately so you can also ping me if you like. I have the necessary permissions to manage bugs and I'm slowly getting better at figuring out how to categorize bugs appropriately. "Bugzilla" is probably the most appropriately named thing in the Mozilla family. It is a real beast to figure out.

I'm good with whatever collaborative editing environment everyone settles on. I can fully appreciate Patrick's concerns about Google's "all your data belongs to us" mentality.
Ken Barbalace - AMO Editor (I focus on reviewing themes)
I maintain Classic Compact, a very compact yet clean Firefox theme.
EnvironmentalChemistry.com (Periodic Table)
User avatar
jorgev
Posts: 53
Joined: May 26th, 2005, 9:54 am
Location: Costa Rica

Re: Call for contributors: New Theme Development Docs

Post by jorgev »

Sorry for the delays. I have the document set up over here. Everyone should be able to view and add comments, but of course I want to give you edit access. Please request edit access and I will grant it to you. I copied pretty much what I had in the Etherpad as initial sections, but feel free to modify them as you think works better. Once we have enough documentation I will ask the MDN people to give it a look and see how to move it to MDN.

Thanks!
Jorge Villalobos
Add-ons Developer Relations Lead, Mozilla
wbamberg
Posts: 3
Joined: December 5th, 2013, 9:22 pm

Re: Call for contributors: New Theme Development Docs

Post by wbamberg »

Hi

I'm a technical writer working at Mozilla, and I'm working on updating the Add-ons info on MDN as MDN is undergoing a design refresh. I think it was my despair about the state of the Themes documentation that prompted Jorge to ask for your help.

The new homepage for all add-ons is https://developer.mozilla.org/en-US/Add-ons. (To see what it will look like in the new design you need to be logged into MDN and have checked the "Beta user" box in your profile.)

In this page I want links for the main add-on types: extensions and themes. The extensions documentation is not too bad, but the themes docs need a lot of updates to be usable. I'd like to split the theme docs at the top level between lightweight themes and complete themes. For lightweight themes, there's a reasonable doc on AMO that I'll link to.

For complete themes, I started with the page at https://developer.mozilla.org/en-US/docs/Themes. I think that in the short term, I'd like to update this page to remove totally obsolete stuff, and move it under the https://developer.mozilla.org/en-US/Add-ons root. In the longer term it could be the home for some of the docs outlined in the etherpad Jorge created.

So I've been going through the Themes documentation at https://developer.mozilla.org/en-US/docs/Themes, trying to get a sense of which articles and links there are hopelessly outdated and should just be removed, and which could be saved and used as a basis for updated documentation.

My guess is that these should just be removed:

* This article for Firefox <3.0:
https://developer.mozilla.org/en-US/doc ... or_Firefox

* The "Theme changes" articles:
https://developer.mozilla.org/en-US/doc ... _Firefox_4
https://developer.mozilla.org/en-US/doc ... irefox_3.5
https://developer.mozilla.org/en-US/doc ... _Firefox_3
https://developer.mozilla.org/en-US/doc ... _Firefox_2
viewtopic.php?t=197434

* This 404:
http://www.melez.com/mykzilla/2009/03/p ... rbird.html

Ultimately I'd like to make this page be just about complete themes, and document lightweight themes separately. At that point I'd relocate and update https://developer.mozilla.org/en-US/doc ... ght_themes.

The other pages under "Documentation" look like they could be useful with some updates, although I'd really be happy to hear any feedback on that.

The "Community" link goes to this forum, which is good. The three extensions listed all seem to work and be useful, but I don't know if there are any that you would find useful to add.

I'd really appreciate any feedback on this plan, or on the usefulness of any of the documentation I've pointed to.

Thanks!

Will
User avatar
patrickjdempsey
Posts: 23686
Joined: October 23rd, 2008, 11:43 am
Location: Asheville NC
Contact:

Re: Call for contributors: New Theme Development Docs

Post by patrickjdempsey »

It looks like you have a decent handle on it. I did notice the links to those extensions are broken... old old AMO links. Other notes:

- The "Building a Theme" and "Theme Packaging" links both have a bunch of out-of-date information... the /communicator/ skin for instance hasn't been needed for themes for ages. Also, preview.png is not used anymore.

- For the install manifest stuff, a link to AMO's usable version numbers page would be good: https://addons.mozilla.org/en-US/firefo ... pversions/

- The very first example of something to edit in the Building a Theme doc is the statusbar text. Since that doesn't exist anymore that makes a terrible example. ;)

A few other things that really need to be well documented somewhere:

- A graphic showing the current default theme package structure. YATT is out of date and I don't know if ShareBird is going to fix it. You are welcome to use that graphic I posted earlier for this.

- The fact that individual skins are *optional* and the Default Theme's code will be used for anything left out. There are many Themers who never touch mozapps at all and some who hardly look in global. Having skins in your theme that you don't ever update is a recipe for breakage, and is why themes are often plagued with broken addons manager or missing controls in HTML5 video.

- An official reference on how to detect the OS theme using media queries. mcdavis put together a nice chart here: viewtopic.php?p=10474841#p10474841 but the fact that Mozilla doesn't have a reference on this is kind of sad. For instance, I finally figured out how to detect Windows Aero Basic theme: viewtopic.php?p=13233539#p13233539

- Instructions on how to do multi-platform or multi-version support with low overhead. A Themer can shove fast-moving parts of the browser such as Devtools into a compatibility skin so that he can support older versions (ESR), the current version, and Nightly. ShareBird has documented how to do that here: viewtopic.php?f=18&t=906535 Ideally, Mozilla would put this crazy stuff into it's own skin and we wouldn't even have to bother supporting it.

- In addition to the above, it's been a long time since I saw a really good run-down of the requirements for building a cross-platform theme, listing differences between OSX, Windows, and Linux themes. A few things that come to mind are the fact that the colors ThreeDShadow ThreeDDarkShadow which Mozilla is fond of in the Windows theme break really horribly on OSX and Linux. Line colors should be created using transparencies of back and white instead, like "rgba(0,0,0,.3)" and "rgba(256,256,256,.5)". In Linux-land, there are known issues like you cannot use the color -moz-menuhover... but it is required for getting the correct color for menu hovers in Windows Vista+ ... the solution is to use highlight for your baseline and only use -moz-menuhover when you detect Aero (using the above media queries). There is also a bug where you cannot have drop shadows or shading on the arrowpanel popups in Linux.

- Thanks to Kris Maglione and mcdavis, there are actually some GREAT tools available for testing themes. This is something that never existed prior to Firefox 4.0. I'm not sure how up-to-date any of this is because I haven't tested any of this in over a year.

Kris's tool is I believe was created to aid in allowing AMO reviewers unfamiliar with Themes to do a review... it's not deeply thorough, but it's got the basics:
https://addons.mozilla.org/en-us/firefo ... heme-test/

mcdavis has several Remote XUL pages for testing all kinds of stuff... they go VERY deep. It would be nice to get these all documented, heck as an XUL reference for n00b Firefox developers (so they don't go building custom elements when they don't need to!) these would be fantastic: viewtopic.php?f=18&t=1932839
They require Remote XUL Manager: https://addons.mozilla.org/en-US/firefo ... l-manager/
Tip of the day: If it has "toolbar" in the name, it's crap.
What my avatar is about: https://addons.mozilla.org/en-US/seamonkey/addon/sea-fox/
User avatar
patrickjdempsey
Posts: 23686
Joined: October 23rd, 2008, 11:43 am
Location: Asheville NC
Contact:

Re: Call for contributors: New Theme Development Docs

Post by patrickjdempsey »

Another useful extension that I don't think even works anymore is APNG Edit: https://addons.mozilla.org/en-US/firefo ... apng-edit/ I'm not sure what you guys use to build animations anymore. It's also a little strange to see an extension developed by a Mozilla employee that does something pretty useful that hasn't been updated in 4 and a half years.
Tip of the day: If it has "toolbar" in the name, it's crap.
What my avatar is about: https://addons.mozilla.org/en-US/seamonkey/addon/sea-fox/
User avatar
KLB
Posts: 2282
Joined: December 21st, 2003, 9:25 am
Location: Saco Maine
Contact:

Re: Call for contributors: New Theme Development Docs

Post by KLB »

One of the biggest helps would be clear instructions of how to build a theme from the base Firefox theme. This has gotten much more difficult to figure out now that the default theme isn't a stand alone JAR file. In order to build a base theme to start with they need to extract specific folder trees from two different Omni.ja files.

1) From the base install folder for Firefox (e.g. "C:\Program Files (x86)\Mozilla\Firefox\"), users need to copy and rename the omni.ja file to something like "BaseOmni.zip and extract all the files it contains. In the resulting folder they need to drill down to "\chrome\toolkit\skin\classic" and copy the folders (aero, global & mozapps) to the developer's theme folder.

2) From the "browser" folder in the base Firefox install folder (e.g. "C:\Program Files (x86)\Mozilla\Firefox\browser\"), user need to copy and rename that omni.ja file to something like "BrowserOmni.zip" and extract all the files it contains. In the resulting folder they need to drill down to "\chrome\browser\skin\classic" and copy those folders (aero & browser) to the developer's theme folder.

This will give them all of the base theme files they will need to build a new theme. At this point they could create the chrome.manifest and install.rdf they need to have a fully functional theme using all of the default files.

After that the developer can get down to replacing graphics files and modifying the CSS code to their heart's content.

The drawback to my methodology is that it requires constant vigilance to keep the custom theme code synced with Firefox's default theme changes. I'm sure Patrick or one of the others has a good strategy for keeping track of code.

The strategy I'm adopting as of FF29 (I'm starting over from the base theme files for FF29) will be to flag all code that is becoming obsolete with the CSS comment "/* FLAGGED FOR DELETION 2013-12-16 */" where the date is the date the flag was added. As I go back through my code I will delete flags older than three months since I only plan on supporting the current release version of Firefox plus Beta, Aurora and Nightly (to a limited extent).
Ken Barbalace - AMO Editor (I focus on reviewing themes)
I maintain Classic Compact, a very compact yet clean Firefox theme.
EnvironmentalChemistry.com (Periodic Table)
User avatar
Frank Lion
Posts: 21173
Joined: April 23rd, 2004, 6:59 pm
Location: ... The Exorcist....United Kingdom
Contact:

Re: Call for contributors: New Theme Development Docs

Post by Frank Lion »

KLB wrote:This will give them all of the base theme files they will need to build a new theme.

All that will give them is a headache.

At this point they could create the chrome.manifest and install.rdf they need to have a fully functional theme using all of the default files.

A fully functional theme that only works 100% OK on just one version of Firefox and not on the version a few months before or after and even then would break on Linux and Mac.

After that the developer can get down to replacing graphics files and modifying the CSS code to their heart's content.

Their heart's content would be around an hour. Hands up who fancies trying to modify css code written like this? -

Code: Select all

#nav-bar .toolbarbutton-1:not([disabled]):-moz-any(:hover,[open]) > .toolbarbutton-menubutton-button > .toolbarbutton-icon,
#nav-bar .toolbarbutton-1:not([disabled]):hover > .toolbarbutton-menubutton-dropmarker > .dropmarker-icon,
#nav-bar .toolbarbutton-1:not([disabled]):not([checked]):not([open]):not(:active):hover > .toolbarbutton-icon,
#nav-bar .toolbarbutton-1:not([disabled]):not([checked]):not([open]):not(:active):hover > .toolbarbutton-text,
#nav-bar .toolbarbutton-1:not([disabled]):not([checked]):not([open]):not(:active):hover > .toolbarbutton-badge-container,
window:not([chromehidden~="toolbar"]) #urlbar-container > .toolbarbutton-1:-moz-any([disabled],:not([open]):not([disabled]):not(:active)) > .toolbarbutton-icon {
  background-image: linear-gradient(hsla(0,0%,100%,.6), hsla(0,0%,100%,.1));
  border-color: hsla(210,54%,20%,.15) hsla(210,54%,20%,.2) hsla(210,54%,20%,.25);
  box-shadow: 0 1px hsla(0,0%,100%,.3) inset,
              0 1px hsla(210,54%,20%,.03),
              0 0 2px hsla(210,54%,20%,.1);
}
"The only thing necessary for the triumph of evil, is for good men to do nothing." - Edmund Burke (attrib.)
.
User avatar
KLB
Posts: 2282
Joined: December 21st, 2003, 9:25 am
Location: Saco Maine
Contact:

Re: Call for contributors: New Theme Development Docs

Post by KLB »

I still need testing on OS X, but using the default Australis Windows Aero theme on Linux, I found only one display bug related to combo boxes. It is the same conflict that existed with previous of Firefox.

I have found that once I stabilized my theme as being compatible across all OSes it pretty much stayed compatible with the different OSes without excessive difficulty.

The default code may not be the prettiest stuff in the world to work with, however, it does provide a reliable starting point for someone with zero knowledge of what it takes to build a theme. It is also the starting point I am using to rebuild my theme for FF29.

In my case, starting over gives me a great opportunity to leave dead and obsolete code behind. It also gives me a chance to overcome code structure mistakes I made in previous versions of my theme. This will actually be the fifth time I started work on my theme from the default theme (FF1.5 for personal use, FF2.0, FF3.0, FF4.0 & now FF29).
Ken Barbalace - AMO Editor (I focus on reviewing themes)
I maintain Classic Compact, a very compact yet clean Firefox theme.
EnvironmentalChemistry.com (Periodic Table)
User avatar
patrickjdempsey
Posts: 23686
Joined: October 23rd, 2008, 11:43 am
Location: Asheville NC
Contact:

Re: Call for contributors: New Theme Development Docs

Post by patrickjdempsey »

There's a ton of stuff in the default Windows theme that breaks in Linux: to name two off the top of my head: menu highlights, the edges of door hanger notifications. Also, I believe the Windows default theme still uses ThreeDShadow in a few places which is a pleasant medium grey in most Windows environments and BLACK in Linux and OSX. Last time I looked into it, there were also some pretty serious issues with how scrollbars are handled in the Windows default vs. OSX, but I found a solution for my own themes that merges both methods. None of these are trivial matters that the average first-time themer will be able to figure out just by copying the default theme. What is needed is the same thing that's been needed for a decade now: a solid tutorial theme with all of the cross-compatibility kinks worked out, and for Mozilla to stop landing developmental stuff into the browser.css file.

Structurally, it's currently insane. In Firefox 3.0 days Mozilla actually managed to build a default theme structure that anyone could copy and it would work. Today you have to go hunting in 2 totally different places and then somehow figure out how all of that relates back together. It also doesn't help that Mozilla has basically completely abandoned the entire concept behind XUL and CSS classes and just goes around creating custom buttons all over the place that it takes ages to hunt-down to theme. Although supposedly they are planning on reining in on the currently 20+ different kinds of "closer" buttons... I'll believe it when I see it.
Tip of the day: If it has "toolbar" in the name, it's crap.
What my avatar is about: https://addons.mozilla.org/en-US/seamonkey/addon/sea-fox/
User avatar
Frank Lion
Posts: 21173
Joined: April 23rd, 2004, 6:59 pm
Location: ... The Exorcist....United Kingdom
Contact:

Re: Call for contributors: New Theme Development Docs

Post by Frank Lion »

I was visiting the AMO site earlier and saw this -

Seriously, this is a sad state of affairs. 'New Theme Development Docs' required? Really? Certainly recently it would have just been easier to individually Email the people who made the 16 new Firefox themes in the last YEAR?

https://addons.mozilla.org/en-US/firefo ... rt=created

16 in an entire year! Jeeze.
"The only thing necessary for the triumph of evil, is for good men to do nothing." - Edmund Burke (attrib.)
.
User avatar
LoudNoise
New Member
Posts: 39900
Joined: October 18th, 2007, 1:45 pm
Location: Next door to the west

Re: Call for contributors: New Theme Development Docs

Post by LoudNoise »

I am assuming that neither of you are going to compete for the $10.00 phone then?
Post wrangler
"Choose between the Food Select Feature or other Functions. If no food or function is chosen, Toast is the default."
User avatar
patrickjdempsey
Posts: 23686
Joined: October 23rd, 2008, 11:43 am
Location: Asheville NC
Contact:

Re: Call for contributors: New Theme Development Docs

Post by patrickjdempsey »

Frank has built some lovely and flexible Australis-capable themes... but I'm too busy with updating the 15-year-old Modern theme icons for SeaMonkey to bother with mucking through Mozilla's insane web of code.
Tip of the day: If it has "toolbar" in the name, it's crap.
What my avatar is about: https://addons.mozilla.org/en-US/seamonkey/addon/sea-fox/
User avatar
LoudNoise
New Member
Posts: 39900
Joined: October 18th, 2007, 1:45 pm
Location: Next door to the west

Re: Call for contributors: New Theme Development Docs

Post by LoudNoise »

Actually, I am thinking about writing a them (ackkkk).... err, Complete Theme. The folks competing for the honor seem to be thin on the ground and I am dying to know if the phone will work in the First World outside of Germany.
Post wrangler
"Choose between the Food Select Feature or other Functions. If no food or function is chosen, Toast is the default."
User avatar
Frank Lion
Posts: 21173
Joined: April 23rd, 2004, 6:59 pm
Location: ... The Exorcist....United Kingdom
Contact:

Re: Call for contributors: New Theme Development Docs

Post by Frank Lion »

[quote="patrickjdempsey" but I'm too busy with updating the 15-year-old Modern theme icons for SeaMonkey[/quote]
That's coz you're 'hanging it up', as I recall. :)

to bother with mucking through Mozilla's insane web of code.

You know I only had to wade through default seriously just twice doing that lot? First time was right at the start, because the key with that Aust stuff is cracking active tab. Without doing that, you have no theme. There, I just got lucky or was on a roll or something.

The second time, as you'll recall, was breaking conditional Forward and the flexing urlbar stuff (essential for the look I needed) and I was (what you reckon?) 99% successful, but did have a damn headache afterwards and did, for the first time since 2006, need help for that last 1%.

Dreadful, awful coding in that default.
"The only thing necessary for the triumph of evil, is for good men to do nothing." - Edmund Burke (attrib.)
.
User avatar
patrickjdempsey
Posts: 23686
Joined: October 23rd, 2008, 11:43 am
Location: Asheville NC
Contact:

Re: Call for contributors: New Theme Development Docs

Post by patrickjdempsey »

Frank Lion wrote:
patrickjdempsey wrote: but I'm too busy with updating the 15-year-old Modern theme icons for SeaMonkey

That's coz you're 'hanging it up', as I recall. :)


Does product contribution count as "theming"? ;)
Tip of the day: If it has "toolbar" in the name, it's crap.
What my avatar is about: https://addons.mozilla.org/en-US/seamonkey/addon/sea-fox/
Post Reply