Questions about creating a new browser theme

[fuzzlesnuz]

For the better part of a year now, I have wanted to try my hand at making some themes for Pale Moon. However, every time I want to get something properly started, I end up reconsidering, due to what appears to a very, very long road full of headaches, gotchas, and lost time. The public resources I could find for creating new addon themes are either outdated or undocumented. I was hoping to find some kind of centralized, thorough documentation on the resources, tools, and workflow for creating and maintain themes for the current PM release, a la MSDN style, but this kind of information seems to only exist in the minds of Lootyhoof and FranklinDM. So, I am making this post to hopefully get some answers to a few key questions.

Poking around in existing themes has yielded some surprises. Stratum 1.7.1 has ~16000 lines of CSS. Aero Moon 2.8.0 has ~19000 lines of CSS. Fox 2 The Moon has 4.8.0 has ~20000 lines of CSS. This seems a bit... insane, since these themes primarily alter a subset of chrome://browser/content and the common control styles, while only lightly touching or completing ignoring other bulky things like about:addons or about:permissions. I find it hard to believe that 600KB of CSS is needed to merely style the primary tabbed browser interface, and, indeed, Lootyhoof's outdated guide seems to indicate as such, wherein the very first step is to extract the browser's default styles and build on top of that. This leads to the conclusion that addon themes are required to style many parts of the browser that the browser already has styles for, even though the theme only wants to modify a specific subset of the UI.

The degree to which the browser's own styling must be duplicated is not consistent. For example, Stratum 1.7.1 and Aero Moon 2.8.0 both include all of the browser's built-in chrome/browser/sync*.css files, which have zero changes to them. But then, only Aero Moon includes chrome/browser/tabview/* files to style that control, while Stratum completely omits the tabview folder. Why are the various sync panel CSS files required to be present in a theme, even though they are not modified at all? Why are styles for tabview allowed to be absent in contrast?

I have also noticed it seems like the granularity of styling is limited to the scope of each control in its entirety. For example, even though some themes are able to omit some files (in order to fall back to the browser's default styles for those controls), the same cannot be said for the content of every CSS file. For example, if a theme wants to change just one class in content/browser/downloads/downloads.css, the theme must include a downloads.css file that includes every declaration block in that file, not just the single declaration block it wants to modify. The worst is probably content/browser/browser.css, which is a monstrous file that tends to contain far more duplicated browser default styles than the theme addon's own styles. Maintaining these nasty css files when the browser updates could be a nightmare, so I want as much separation between the browser's CSS and my CSS as possible.

This leads to two interconnected questions:
■ 1. Where can I find a list of what must be included in a theme and what can be omitted?
■ 2. Is there any way to cleanly and clearly separate the "I have to include the browser's own styles because reasons" styles from the "this is actually part of my theme" styles within the addon structure?
I feel that the answer to both, if it even exists, is likely convoluted by the use of @imports.

Finally, the most important question of all:
■ 3. How can I obtain the browser's own styles in the first place?

Lootyhoof's outdated guide instructs us to extract the browser's own styles from two different omni.ja files, but one of those files doesn't exist in the current Pale Moon (31.1.0). To my knowledge, this guide is the only resource on the planet which explains how to rip Pale Moon's own styles, and it is no longer valid. Just the same, the addons/themes/pm-history page does not include any mention of the disappearance of that omni.ja file or where its contents were moved to. Unfortunately, this means it is just about impossible for a newbie like myself to create a new theme properly, since the very first step is to extract the browser's own styles. Preemptive note: I am not interesting in copying an existing theme, like Aero Moon or Stratum, and working from there. Doing so incurs a needless licensing dependency, heaps of extra work & lost time in undoing the theme you copied just to get back to the browser's natural theme, and is a real sin of all sins to commit when it comes to maintaining your theme once the browser updates, since you have to repeat that backwards process every time. Do not suggest this.

To reiterate, I am making this post because creating a new addon theme for Pale Moon seems like putting together an IKEA bed without the instructions. Your only choice is to go in blind, so everything is needlessly trial and error, and what should take only several hours ends up taking several weeks. I'm hoping there are some answers and resources somewhere that would make this process more sane. I have never created Firefox addons or themes, so I don't know if this convoluted process is just carried over from Firefox (pre-Chromezilla era, ofc). It certainly has that distinct Mozilla feel to it (again, pre-Chromezilla era, ofc).

Thanks in advance to anyone with helpful info to share.

[Lootyhoof]

Themes contain a lot of code as they do, indeed, need to style everything, not just the parts you want to adjust yourself. Indeed, themes often also include considerations for the various different operating systems they can run on, as the various UI toolkits on those platforms do style things slightly differently.

I should definitely update that guide at some point, though, and I'm sorry about that. But it is technically still possible to rip the theme resources from the default theme (which is still the best way to do so, as the source code itself displays those files differently). These days, omni.ja is palemoon.res, which is essentially a zip file with brotli compression. To my knowledge you should be able to at least open this using PeaZip, but from a support perspective doing any actual modification to that file itself is highly unsupported. Be aware though that ripping the default theme files only gives you the styling for your OS only, other platforms may have issues if you just make the theme based on that.

In reality though, it does make sense to copy an existing theme so you do have all the OS-specific styling and other quality of life touches compared to doing it yourself, but that's up to you. In terms of licensing, the vast majority of themes use much the same licensing as the browser itself (i.e. MPL 2.0), so you're of course free to adapt them as you like.

I have myself experimented with doing more minimal themes in the past, and these are still going strong, it just depends what you want. If you want to affect the browser style only and leave the global styling as default, have a look at what I've done with Tangomoon, in particular how I worked with chrome.manifest. In this theme I've not specified a global style, so it uses the default. But I have overridden many icons in that default style instead. An even older (and admittedly underused) method could be to do what I termed an icon theme, which makes more extensive use of those overrides while keeping default theme styling for everything else. The only problem there is that Linux uses a different icon mapping in the default theme, so YMMV (and ultimately is why I did not push this much further, but it is there).

[fuzzlesnuz]

Thanks much for the reply.

...it is technically still possible to rip the theme resources from the default theme (which is still the best way to do so, as the source code itself displays those files differently). These days, omni.ja is palemoon.res, which is essentially a zip file with brotli compression. To my knowledge you should be able to at least open this using PeaZip...

PeaZip, WinRAR, and 7-zip are able to view the filenames inside palemoon.res, but none of them are able to decompress the file contents. I also tried this popular 7-zip fork with many additional supported algorithms, including Brotli, but it also could not decompress the file contents. 7-zip also has this to say about palemoon.res:

It seems like a nonstandard format, which isn't too surprising, since Moonchild probably does not intend for users to be ripping its contents. That does, however, bring us back to square one, which is "how do I even get Pale Moon x.x.x.x's default styles in the first place so I can create a new theme"...

...In reality though, it does make sense to copy an existing theme so you do have all the OS-specific styling and other quality of life touches compared to doing it yourself...

Hmm. I assumed that omni.ja (or palemoon.res) would contain a "complete" image of the browser's default theme, with all OS considerations included, since the official (now outdated, ofc) steps to create a new theme start with ripping said styles from said files. After all, whether they are tucked away inside Pale Moon's program files or more easily available as a download from DMPO, the sane way to start any new theme would be to begin with a complete, 1:1 copy of the browser's default theme.

Something is definitely wrong if the recommendation for creating new themes is to clone an existing theme as a base, especially if the intended new theme has absolutely nothing in common with the existing theme that is based on (and said existing theme has no documentation, to boot). Imagine if Moonchild cloned Chromium in order to make Pale Moon. He would have to 1) un-Chrome-ify it so that he could 2) Firefox-ify it so that he could 3) finally turn it into Pale Moon. Only a fool would do that. Just as the sane way to create a unique, new Firefox fork is to clone Firefox, the sane way to create a unique, new Pale Moon theme is to clone the default theme.

I don't want to make some hack job of an existing theme. I don't want to duct tape something together that mysteriously works without me understanding how or why. It'd be shameful to do that and distribute it to other Pale Moon users. I want to have the information necessary to properly understand the theme creation process - to understand why abc causes def, and why you should do xyz instead of tuv. To be clear, I'm not talking about elementary things like css or graphic design. I'm talking about the the specific constraints, quirks, idiosyncrasies, surprises, and potentially un-intuitive requirements that are part of the Pale Moon (/ maybe Firefox also) theme creation process. Why some files are required, while others are not. Why some things work here, but not there. Explanations of the inconsistencies that simply can never be guessed correctly by an outsider. In a nutshell... documentation.

This leads back to the first two questions in my OP.

■ 1. Where can I find a list of what must be included in a theme and what can be omitted?
■ 2. Is there any way to cleanly and clearly separate the "I have to include the browser's own styles because reasons" styles from the "this is actually part of my theme" styles within the addon structure?

#2 can be written off as a convenience, if need be (....e...h.h.hh.....), but #1 seems like an unavoidable requirement that currently does not exist. At least, not in written form that others can readily view. Lootyhoof and FranklinDM are the living containers of that information.

...I should definitely update that guide at some point, though...

If you do ever get around to that, I would very much like to hear when it's finished.

[Lootyhoof]

PeaZip, WinRAR, and 7-zip are able to view the filenames inside palemoon.res, but none of them are able to decompress the file contents.

Hm, odd. I was sure this worked before, but maybe I was wrong. Anyway, you could try this tool by JustOff to do it instead (requires Python): https://github.com/JustOff/mozjarr/

Hmm. I assumed that omni.ja (or palemoon.res) would contain a "complete" image of the browser's default theme, with all OS considerations included

The palemoon.res for a specific platform only has data for that platform. This has always been the case (and to be fair, something I did not ultimately consider back in 2015, even when it was very much still a thing).

Something is definitely wrong if the recommendation for creating new themes is to clone an existing theme as a base

You...do realise that the default theme is one such theme, yes? ALL themes effectively copy from each other in some way; not to mention the fact that both myself and FranklinDM have contributed stylings back into the default theme at one point or another. It's just that a theme on the add-ons site packages everything nicely instead of having to hunt everything down in the default theme.

Imagine if Moonchild cloned Chromium in order to make Pale Moon.

Wrong analogy. Pale Moon is originally from Firefox; in the same way as themes are from the Pale Moon default theme (and prior to that, the Firefox default theme).

I don't want to make some hack job of an existing theme.

That's entirely your decision, but I mentioned it only as a convenience. If you're just going to spit at anything I suggest, then what do you want from me?

■ 2. Is there any way to cleanly and clearly separate the "I have to include the browser's own styles because reasons" styles from the "this is actually part of my theme" styles within the addon structure?

See my work on Tangomoon, that I already linked. It is exactly what you ask for.

[athenian200]

While I would ask you to be a bit more understanding of the fact that this is essentially a volunteer-maintained project, I definitely sympathize with your frustration.

I believe the way themes actually work, is that any given file inside of a theme XPI essentially overrides a corresponding file in omni.ja (though someone please correct me if I'm wrong). That is, it's just a set of instructions telling the browser to use this file instead of the internally provided one. In theory, I imagine you could override just one or two files, and as long as the manifests were valid, you'd have an XPI that could partially override a default theme. I'm pretty sure you could do that with icons at least, don't know about CSS. But you definitely you can't just include your modifications... you need a whole copy of that file that includes your modifications. EDIT: Well, never mind, I just tried creating a test XPI file with only one file inside it changed, and it did not work out the way I hoped. Not even with icons. It seems like it does require a whole mess of stuff to do anything at all, or it just silently fails. :/ It's apparently more complicated than I thought. The directory structure in the XPI files doesn't even match up with what I would expect. I can't do this myself, and I actually write C++ code for the project. Working with themes is such black magic that I would probably find it easier to modify core components. There seems to be no good reason for the way anything is done with regard to themes other than precedent.

The easiest way to edit the default theme at the moment is actually to self-compile a version of the browser with

Code: Select all

MOZ_CHROME_FILE_FORMAT=flat

in confvars.sh instead of the default. That basically makes it so all the stuff that would normally be compressed down into a single file is just available to edit as normal files. We don't ship the browser that way, of course, because it would make the file size larger. It reveals a lot about why the process works the way it does, though. What XPIs do should, in theory, be absurdly simple (though unfortunately there's a lot of convoluted Mozilla precedent involved that I don't understand complicating it)... it just tells the browser to use a different copy of, say, browser.css than the one shipped with the browser. And themes are essentially just a huge collection of individual file overrides that eventually create enough differences to have a totally different style. That's all the manifests and the files inside an XPI actually do, and it's why you can't just have a file with your modifications and not the rest of the file. The system used is not "smart enough" to know you only want to override part of a file, and the overrides are done on a per-file basis. That aspect of the system was inherited, and we didn't design it from the ground up.

Part of the difficulty in creating proper documentation for the process of creating themes, that this all involves a lot of specialized knowledge, and Mozilla themselves never documented the process well. Only a few people who delved deep into it understood how theming worked even back when it was popular, and documentation was always scarce. Now it's obviously even harder, since a lot of the older documentation is either no longer available, or contains things that are obsolete or misleading anyway.

On top of that, Lootyhoof and FranklinDM have so much of their time taken up maintaining the existing themes to keep up with development, that creating documentation so new people can jump into theming winds up going on the back burner. It's something of a self-perpetuating cycle... they are always swamped with work due to the fact that no one else can do what they do, and they remain swamped in part because no one new can get into theming easily and lighten their load.

[fuzzlesnuz]

...If you're just going to spit at anything I suggest...

If you take it that way, well, ok. I know some people can be really high strung on these forums, but that doesn't mean everyone is a troll. You shared some helpful info, but it didn't answer all my questions, and I explained why. You didn't have a home-run solution for those questions, and that's fine. You don't have to take it personally. Suggestions are just suggestions, they aren't social points, and the essence of problem solving is picking apart everyone's suggestions and creating new ones until there's a consensus. Good problem solving (or just good discussion in general) means going through potentially hundreds of suggestions, and doing it effectively means using strong, clear language because it dispels assumptions about the subject matter. At no point in that process does the other person think you are "spitting" on what they are offering. It's just mundane communication between two humans who can't possibly know exactly what's going on in the other guy's head and have to take what they say at face value. Assume good faith.

...Wrong analogy. Pale Moon is originally from Firefox; in the same way as themes are from the Pale Moon default theme (and prior to that, the Firefox default theme)...

"Pale Moon is originally from Firefox" <-- That was the point of the analogy. Creating Pale Moon was simply a Firefox -> Pale Moon process, not a Chromium -> Firefox -> Pale Moon process. The point was to illustrate what a silly, superfluous step looks like.

...It's just that a theme on the add-ons site packages everything nicely instead of having to hunt everything down in the default theme...

This is part of what I was getting at: having a starting point for creating a new theme that produces a 1:1 match with the browser's default theme when it is installed as-is. The natural choice here, I feel, would be a copy of the default theme. This way, after you have modified the default theme to make it unique, it is far less painful to update your theme. If you were to plot out a dependency graph of your theme, you would only have to reconcile the vertex of your theme, the (now old) Pale Moon default theme it was based on, and the (possibly modified) default Pale Moon theme from the new PM release. If your theme is based on another unique theme (not the default theme), you now have 4 connections to reconcile at that vertex instead of 3, which is geometrically more complex and thus could take a lot more time than it needs to.

See my work on Tangomoon, that I already linked. It is exactly what you ask for.

I did take a cursory look at Tangomoon and it seems to work along the lines I was thinking of, but I don't have to time right now to really dig into it. I see quite a lot going on in chrome.manifest, and I can follow those patterns blindly and maybe get the results I'm looking for, sure. The problem then is that my theme now works in mysterious ways that I don't fully understand. That's what I meant by creating a "hack job" of something. Something you cant really maintain, update, or publish with confidence because you don't fully understand how & why it works. When I do have the time to try and pick apart Tangomoon, I will certainly come back to you with any questions that could come up on how it does the things it does.

...you could try this tool by JustOff to do it instead (requires Python): https://github.com/JustOff/mozjarr/...

This was just the ticket and worked perfectly! Many thanks for sharing that. JustOff to the rescue with his myriad of niche-but-oh-so-important tools.

---

I believe the way themes actually work is... <snip>

Thanks for replying. This is the kind of info I was after regarding the granularity of styling things. It leads into what is probably my biggest question at the moment: Is there list that specifies A) what files absolutely need to be included in the theme (even if no changes are made) and B) what files can be omitted? Going back to my OP, I noticed that, for example, some themes include chrome/browser/tabview/* while others do not, but all themes seem to include content/browser/sync*.css. There is no apparent pattern as to what must be kept versus what can be culled. If I knew which files I could safely omit, then my theme would be leaner and easier to maintain. Worst case scenario, I have the entire default theme stuffed inside my theme, with my modifications riding on top, which is certainly feasible, yeah, but is pretty far from ideal. As for trial-and-error'ing my way through all ~600 files that themes consist of to see what I can cull... well, I just don't think that will do. I am not a developer of Pale Moon, so I have no idea know how to fully the test the browser for hidden, non-obvious issues every time I launch it after intentionally omitting a different file from the theme. A list created by a knowledgeable individual is the only thing I would have confidence in. It doesn't necessarily have to be a pretty list, though. If, for example, there were gratuitous comments somewhere in the Pale Moon source that clearly indicated which files are critical and which ones can be omitted, that would work. If such a thing does exist, though, I'd need someone to point me towards it. The PM source tree is very... big.

Part of the difficulty in creating proper documentation for the process of creating themes, that this all involves a lot of specialized knowledge, and Mozilla themselves never documented the process well. Only a few people who delved deep into it understood how theming worked even back when it was popular, and documentation was always scarce. Now it's obviously even harder, since a lot of the older documentation is either no longer available, or contains things that are obsolete or misleading anyway.

I was worried about how much this potentially played into things. If there wasn't any proper documentation from the Mozilla era (which I can't say is too surprising), then that certainly goes along with why there wouldn't be any documentation for Pale Moon either. In lieu of documentation, it'd be nice to have the default theme available as a template/example somewhere. Regardless, I will try building PM with the parameter you mentioned, though I am a bit apprehensive. There seem to be a good number of posts here from people who have difficulties building PM

On top of that, Lootyhoof and FranklinDM have so much of their time taken up maintaining the existing themes to keep up with development, that creating documentation so new people can jump into theming winds up going on the back burner. It's something of a self-perpetuating cycle... they are always swamped with work due to the fact that no one else can do what they do, and they remain swamped in part because no one new can get into theming easily and lighten their load.

I was starting to get the suspicion that was the case. If creating documentation would be the straw to break the camel's back, then I certainly understand why Lootyhoof, FranklinDM, and Moonchild et al would repeatedly avoid that. But it does just reinforce the self-perpetuating cycle you mentioned...

...be a bit more understanding of the fact that this is essentially a volunteer-maintained project...

I'm not a FOSS guy, but I know some of the woes and dredges of volunteer software. I get it. I know Pale Moon isn't sitting on a million dollar grant, or even endorsed by a group like the EFF (though it should be). But I also know I could miss out on some really valuable info if I go in with the assumption that what I'm looking for doesn't exist. I want to exhaust all the possibilities that the kind of info I'm looking for maybe kinda sorta actually does exist somewhere, anywhere, because I really do want to turn my free time into a theme or two for Pale Moon. And I want it to be done right, with confidence and quality, or else it would be a disservice to the PM community and to myself. I wouldn't be considering that or even typing this if I didn't see a lot of value in PM and its niche little ecosystem.

[FranklinDM]

Going back to my OP, I noticed that, for example, some themes include chrome/browser/tabview/* while others do not, but all themes seem to include content/browser/sync*.css.

The tabview folder contains styling for Tab Groups, which used to be in the browser but was eventually removed and turned into an extension. This isn't required to be included in the theme anymore.

[athenian200]

So, I played around with this and found out something interesting. Apparently you CAN just make a theme as nothing but a series of overrides to the default theme like I thought, but you have to do it in a completely different way to how you would create a full theme.

What was tripping me up was that if you put an entry like the ones Lootyhoof used in his tutorial in your chrome.manifest, you have to include ALL the browser styling for the folder you override. For instance, if you include an entry like:

Code: Select all

skin browser namehere chrome/browser/

Then the browser no longer sees the native styling that would be stored in chrome/browser, and you need EVERYTHING that would normally be in chrome/browser. However, there is another way to do it. I managed to create a theme that only overrides one file, but your chrome.manifest has to be setup in a totally different way to do that. In this case, I created a theme that just overrides the file "Toolbar-glass.png" and my chrome.manifest looks like this.

Code: Select all

skin    browser-test        mytheme	chrome/browser-test/

override chrome://browser/skin/Toolbar-glass.png chrome://browser-test/skin/Toolbar-glass.png

The trick is that you shouldn't use the folders that are used for the browser's default theme when doing this. And you also have to know exactly where the file is normally located via the chrome:// url, and use an override directive to explicitly tell it to use the new file you provided.

So yes, it is in fact possible to override one file at a time this way, but most people just include all of the browser's default styling in their new theme if they want to create a full theme, because it's actually easier. So the minimum number of files you have to include is one (plus all the stuff for install.rdf and chrome.manifest), but the moment you use a folder in your theme that the browser provides for the default theme, you have to provide the entire contents of that folder. So it can be folder-level or file-level, as far as I can tell.

All I can say is, this is not how I would have programmed this. I would have set it up so whatever file you provide gets replaced, and the ones you don't provide fallback to the default theme. In other words, if it were up to me, override styling would work well out of the box for people that just want to change a couple of icons, and full themes would be the ones that took a little more work to setup. This seems kinda backwards, but changing it works now would probably cause a compatibility nightmare...

Anyway, all this is actually much easier if you can see the browser compiled up to use flat files rather than the omni.ja stuff. In fact, when you first compile the browser and before it's packaged, it basically uses flat chrome in the directory you use for test runs. So I'm not used to seeing or dealing with omni.ja or XPIs, what little experience I have playing around with the default theme involves simply editing it directly.

[fuzzlesnuz]

So, I played around with this and found out something interesting.... <snip>

This is great info and is the kind of thing I was looking for to understand the basics of how theme addons actually work. Based on all of it, I get the feeling that themes were not much more than a convenient side-effect of Mozilla's application design methodology. Generic UI system meets generic addon system and bam, suddenly we've got a "theme" ""system"" without any extra work! Mr. Eich sure will be pleased to hear that!

At any rate, thanks and thanks again for taking the time to document this piece of the puzzle. That more or less answers the three questions from my OP and means I can really start experimenting now. If more questions come up, I suppose I'll just put them here in this thread.

...if you can see the browser compiled up to use flat files rather than the omni.ja stuff. In fact, when you first compile the browser and before it's packaged, it basically uses flat chrome in the directory you use for test runs....

Which results in really great paths like palemoon\browser\chrome\browser\content\browser\content.css and palemoon\browser\chrome\browser\content\browser\browser.css

[jobbautista9]

Btw if you need an easy way to look at the browser's chrome without extracting the omni.ja, my add-on Chrome Navigator might help you with that.

[athenian200]

Btw if you need an easy way to look at the browser's chrome without extracting the omni.ja, my add-on Chrome Navigator might help you with that.

Thanks for providing that extension.

That is really awesome for this kind of work, and it provides the exact visual metaphor I wanted to give the OP to describe my understanding of the browser chrome and what themes are doing to it. I actually had trouble figuring out how the chrome URLs lined up with the way things are laid out in the omni.ja, to the point that it took me a whole day to figure out the exact chrome URL I had to override just as a proof of concept to show it could be done. And all I wanted to do was put a yellow stripe on a couple of icons to show myself the change had been applied. Being able to see the browser chrome in real time in a running copy of the browser probably helps tremendously, especially since it also shows the effects of files added in by extensions and such. You can see the current state at a glance, really cool.

What's really cool about this extension is that it makes the "file system" metaphor I had in my brain visually explicit. Because the browser chrome operates sort of like a self-contained "file system" that "mounts" a bunch of real files and folders stored elsewhere onto certain mount points. And when you have an extension/theme "mount" one of it's directories in the same place that the browser puts its styling, you've "unmounted" the directory for the default theme, and "mounted" the version of the directory contained in your theme instead.

Therefore, just like if you were in a Unix system and you unmounted a folder that contained, say, the contents of your CD-ROM drive and mounted your USB stick there instead, you wouldn't be able to look there to see what was on the CD-ROM drive anymore. And any program/script that was still expecting the CD-ROM to be mounted there would have issues if it kept looking there... unless you planned it out and duplicated the whole directory structure of the CD-ROM drive onto the USB stick so that applications can keep doing their thing while you apply your changes to files that obviously couldn't be changed on read-only media. That's why this is all so "hacky," basically.

[fuzzlesnuz]

Alright, so I'm already back with a new question. I'm quickly realizing that my theme will require rearranging existing controls in browser.xul and maybe (but hopefully not) hiding & spoofing some elements with new controls. I'd also like to put some of the theme's UI changes behind user-controlled preferences. And I think that means getting into toolkit/overlay addon territory, which is something I've never worked with before. I've been looking into Classic Theme Restorer to get a feel for what is possible and how it is done, but CTR is massive and is full of some rather hideous javascript, so that's probably not the best addon to pick apart in order to learn this stuff. At any rate, what I'm mainly worried about is overstepping the bounds of what a "theme" addon is allowed to do. That is, how radically can I alter the Pale Moon UI before my addon gets kicked out of the "Themes" category in the Addon Manager and has to go in "Extensions" instead? And, follow up to that: is there any difference between a <em:type>4</em:type> addon and a <em:type>2</em:type> addon aside from A) where it goes in the Addon Manager and B) the fact that only one theme addon can be active at a time? I ask because none of the themes available on APMO re-arrange or re-implement pieces of the UI, which could be policy, precedent, or just coincidence - I don't know which. To be clear, my envisioned theme isn't going to make PM look like your boss's old Win XP work laptop with the monstrous vertical taskbar and 300 control panel menus pinned to the desktop; I just need to rearrange the tabs, toolbars, and back/forward buttons, and maybe put some things in the caption area. It'll still look very much like a certain web browser, so I hope it would still qualify as a "Theme".

[moonbat]

I'd also like to put some of the theme's UI changes behind user-controlled preferences

Noia Moon offers a control panel, you could take a look at how that works.

[athenian200]

Alright, so I'm already back with a new question. I'm quickly realizing that my theme will require rearranging existing controls in browser.xul and maybe (but hopefully not) hiding & spoofing some elements with new controls. I'd also like to put some of the theme's UI changes behind user-controlled preferences. And I think that means getting into toolkit/overlay addon territory, which is something I've never worked with before. I've been looking into Classic Theme Restorer to get a feel for what is possible and how it is done, but CTR is massive and is full of some rather hideous javascript, so that's probably not the best addon to pick apart in order to learn this stuff. At any rate, what I'm mainly worried about is overstepping the bounds of what a "theme" addon is allowed to do. That is, how radically can I alter the Pale Moon UI before my addon gets kicked out of the "Themes" category in the Addon Manager and has to go in "Extensions" instead? And, follow up to that: is there any difference between a <em:type>4</em:type> addon and a <em:type>2</em:type> addon aside from A) where it goes in the Addon Manager and B) the fact that only one theme addon can be active at a time? I ask because none of the themes available on APMO re-arrange or re-implement pieces of the UI, which could be policy, precedent, or just coincidence - I don't know which. To be clear, my envisioned theme isn't going to make PM look like your boss's old Win XP work laptop with the monstrous vertical taskbar and 300 control panel menus pinned to the desktop; I just need to rearrange the tabs, toolbars, and back/forward buttons, and maybe put some things in the caption area. It'll still look very much like a certain web browser, so I hope it would still qualify as a "Theme".

Honestly, I think the distinction between a "theme" and an "extension" is pretty subjective anyway. Obviously themes tend to restyle the browser and extensions tend to add new functionality, but if you're writing something that restyles the browser and changes how things are done... well, it might arguably fit into either category.

I doubt there is any kind of mechanism stopping a theme from modifying any of the files included. I'm thinking that if it's part of the browser chrome, you can always swap in the version from your add-on. Mozilla might have had restrictions traditionally, I don't know, but all I can say is... if modifying browser.xul in your theme works and gets the results you want, I don't see why you shouldn't.

[Goodydino]

Btw if you need an easy way to look at the browser's chrome without extracting the omni.ja, my add-on Chrome Navigator might help you with that.

I can see where files are within the application, but I cannot open them to examine them from the list produced by that extension. Maybe that is because the files are inside the application package?

[athenian200]

I can see where files are within the application, but I cannot open them to examine them from the list produced by that extension. Maybe that is because the files are inside the application package?

In general, extracting the omni.ja is kind of a hack and not really recommended, although people do it, especially in the theming community (mostly for lack of a better alternative). That extension would mostly let you view the browser chrome files within the browser itself... that is, if you copy the chrome URLs into the address bar, you would be able to see the graphics and text files. But that wouldn't be enough to let you pull them out into an external application and modify it.

That's why I said that compiling the browser to use flat files is better if you actually want to make changes... you can pretty much change the files it's actually using and see the effects right away, with the downside that it's not at all obvious how that would line up with an XPI's layout.

[jobbautista9]

I can see where files are within the application, but I cannot open them to examine them from the list produced by that extension. Maybe that is because the files are inside the application package?

Yeah, that's a known issue. The only files that open seamlessly into a view-source window are XUL, DTD, and JavaScript files. The rest will pop-up the application picker. My workaround for that is to just make Pale Moon the default application for files in the jar protocol. They will open in the browser window which is good for images, but not ideal for CSS...

[fuzzlesnuz]

Honestly, I think the distinction between a "theme" and an "extension" is pretty subjective anyway. Obviously themes tend to restyle the browser and extensions tend to add new functionality, but if you're writing something that restyles the browser and changes how things are done... well, it might arguably fit into either category.

I doubt there is any kind of mechanism stopping a theme from modifying any of the files included. I'm thinking that if it's part of the browser chrome, you can always swap in the version from your add-on. Mozilla might have had restrictions traditionally, I don't know, but all I can say is... if modifying browser.xul in your theme works and gets the results you want, I don't see why you shouldn't.

I think I've run into an issue that indicates there actually are some restrictions on addons that classify themselves as "themes" instead of "extensions".

This is easily demonstrated with the XUL School status bar demo addon. Mozilla nuked the download and even UDN does not have it, so you'll need to download it from this lucky random site cacher: https://developer.mozilla.org.cach3.com/en-US/docs/Archive/Creating_a_status_bar_extention#Download_the_sample

Test 1

---

1. Open install.rdf and modify the em:targetApplication to target PM. This isn't strictly necessary, but it's for the sake of consistency with what I am trying to do, which is make a theme for PM that might need to use XUL overlays.
2. Package it, install it, test it.

Looks good.

Also, if we try to browse to the XUL overlay file inside the addon's XPI, we can verify it is in the chrome registry:


Now let's change it from an "extension" to a "theme" and see what happens.

Test 2

---

3. Uninstall the addon and restart Pale Moon. <-- This is very important! If you were to reinstall the addon in-place, then restart, Pale Moon will get confused and you might have 2 themes active at once. The only fix is to uninstall one of the 2 themes, since there is no disable button for themes. On a sidenote, this seems like a place for a potential improvement: properly handle addons that change their <em:type> when they update/reinstall. Corner case, yes, but it'd help when doing contrived tests like these.
4. Modify install.rdf to turn the extension into a theme.
　- Change <em:type> to 4
　- Add new elements that theme addons require:
　　- <em:internalName>status-bar-sample-1</em:internalName>
　　- <em:skinnable>true</em:skinnable>
5. Package it, install it, test it.

Oh no.

If we try to browse to the XUL overlay file inside the addon's XPI, we get this message:


My initial thinking was that maybe theme addons are either A) not allowed to use the content directive in their chrome.manifest or B) they are only allowed to use the skin directive (and other "themes-only" related ones). It might explain why the xul overlay is not in the chrome registry, despite us making zero changes to chrome.manifest.

Test 3

---

To test the previous point, let's register and access the XUL overlay with the skin module instead of the content module.
6. Modify chrome.manifest:
　- Replace the content directive with a skin directive: skin browser-status-bar-sample-1 status-bar-sample-1 chrome/browser/
　- And change the overlay chrome URI to account for that: overlay chrome://browser/content/browser.xul chrome://browser-status-bar-sample-1/skin/status-bar-sample-1.xul
7. Change the XUL overlay file's path on the disk to chrome/browser/status-bar-sample-1.xul to account for the changes we made in chrome.manifest
8. Package it, install it, test it.

Hmm. Still not working.

If we browse to the XUL overlay file inside the addon's XPI, we get this message:

　

---

　
Evidently, there is some mechanism preventing the XUL overlay from being applied when the addon it belongs to is a "theme" and not an "extension". I have no prior XUL experience, though, so I don't know why this would be. I can only guess this is inherited from Firefox and is thus a weird design choice by Mozilla 20 years ago.

This demonstration also begs a similar question: are "extension" addons unable to do certain things that "theme" addons can do? I haven't tested that.

I've attached a zip that includes the demo addon at each stage of the above steps for convenience:

Demo Addon.zip

[athenian200]

I think I've run into an issue that indicates there actually are some restrictions on addons that classify themselves as "themes" instead of "extensions".

I'm sorry my assumptions are not playing out well. I keep expecting the design of this to be somewhat logical and open, because it seems to be on the surface, but the more you dive into it... the more I don't like the design of it. I mean, this basically means that to make a complete theme in some cases that styles something Mozilla decided a "theme" is not allowed to style, you have to make a theme AND a companion extension that styles the other stuff to get the full effect. I do seem to vaguely recall at least one example of that. But it's clear that it's the exact same mechanism in both cases and that there's no good technical reason why an add-on that simply styles everything it intends to style shouldn't work, given the way the underlying system seems to work.

I'm sure there are a lot of fans of the classical Mozilla design who would disagree and defend the restriction as something essential or perhaps offering more security and clarity, but that is just my personal (and perhaps inexperienced/dismissive) opinion on the matter and nothing more. I'm appreciative of the efforts of those willing to work with the limitations and arcane nonsense of this system to provide something cool for our users, though. It's honestly not so much that this system is great, as that more modern replacements don't improve things in the direction of making it easier and more logical, but rather put the binders on even more and just make certain things totally impossible. So the existing system winds up being the best we can get.

I mean, I guess if the restriction is only one way and places more limitations on themes, that at least makes some sense because it prevents something that's "just a theme" from potentially having lasting effects, especially since extensions can cause bigger problems. Hopefully that's how it works...

[fuzzlesnuz]

I'm sorry my assumptions are not playing out well. I keep expecting the design of this to be somewhat logical and open, because it seems to be on the surface, but the more you dive into it... the more I don't like the design of it. I mean, this basically means that to make a complete theme in some cases that styles something Mozilla decided a "theme" is not allowed to style, you have to make a theme AND a companion extension that styles the other stuff to get the full effect. I do seem to vaguely recall at least one example of that. But it's clear that it's the exact same mechanism in both cases and that there's no good technical reason why an add-on that simply styles everything it intends to style shouldn't work, given the way the underlying system seems to work.

I'm sure there are a lot of fans of the classical Mozilla design who would disagree and defend the restriction as something essential or perhaps offering more security and clarity, but that is just my personal (and perhaps inexperienced/dismissive) opinion on the matter and nothing more. I'm appreciative of the efforts of those willing to work with the limitations and arcane nonsense of this system to provide something cool for our users, though. It's honestly not so much that this system is great, as that more modern replacements don't improve things in the direction of making it easier and more logical, but rather put the binders on even more and just make certain things totally impossible. So the existing system winds up being the best we can get.

I mean, I guess if the restriction is only one way and places more limitations on themes, that at least makes some sense because it prevents something that's "just a theme" from potentially having lasting effects, especially since extensions can cause bigger problems. Hopefully that's how it works...

Thanks for the insight. I come from the world of wpf and xaml, so I'm used to things that have a lot more structure and options. The Mozilla Way™ is a big departure from that

The reason I wanted to use an overlay was to be able to style the unified back and forward buttons to the extent required by my theme. The simple, two-element hierarchy of <xul:toolbarbutton><xul:image/><xul:toolbarbutton/> does not offer enough options. I need at least 2 child <xul:image/>s, so I figured I'd use an overlay to add in more elements. It is now evident that this approach would require the user to install two addons, one "theme" and one "extension" in order for things to work correctly. Ultimately, I think I might have to go with this approach, since I want to add an options window for adjusting the theme. Moonbat shared a theme earlier in this thread that follows the extension+theme addon pattern, which I now can guess is due to theme addons not allowing xul overlays.

The other option - and this is what I initially tried - was to use xbl to add the additional <xul:image/> by setting -moz-binding on the relevant element. The Aero Moon theme uses xbl to recreate the dropmarker for the back and forward buttons (the specific xbl used dates all the way back to 2010), so it seems that is there indeed a way for themes to modify the application's DOM with just css+xbl markup. Unfortunately, this did not work when I attempted this approach on the back navigation button.

Here is the default back button hierarchy for reference:


And here is the result of what I tried to do:

For some reason, the original children are gone and only the additional control is added.

The XBL and CSS behind this are very basic and I cant see any reason why either might be invalid.
XBL:

Code: Select all

<?xml version="1.0"?>
<bindings xmlns="http://www.mozilla.org/xbl"
          xmlns:xul="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">
    <binding id="back-button-extra-image">
        <content>
            <children/>
            <xul:image id="extra-controls-back-button-icon2" class="toolbarbutton-icon" />
        </content>
    </binding>
</bindings>

CSS:

Code: Select all

#back-button {
	-moz-binding: url(chrome://xxxxx-browser/skin/UnifiedForwardBack/ExtraControls.xbl#back-button-extra-image);
}

My suspicion is that #back-button already uses a -moz-binding to dynamically populate it with the child controls instead of explicitly defining those child controls. Thus, when my theme addon changes the -moz-binding, the original, dynamically-created child controls are replaced with my dynamically-created child controls. If this is true, then it would seem that the behavior of -moz-binding is inconsistent/context-sensitive. If you bind some XBL to a control with explicitly-defined children, and your XBL includes <children/>, then the elements defined in the XBL will be appended to the host control's existing children. If you bind some XBL to a control that has no explicit children and instead is already bound to some XBL, and your XBL includes <children/>, then the <children/> element is ignored, the new XBL simply overwrites the existing XBL, and thus the original children are lost. If this is indeed true, it is a very annoying limitation.

If someone knowledgeable can clarify the above situation and correct/confirm what I've posited above, that'd be great. And if anyone has any ideas to work around this, that would also be great.