Overview of the CCK 0.1 for Firefox
The goal of the first release of Firefox is to produce an XPI file that when installed customizes parts of Firefox equivalent to the Netscape 7 CCK. This document will describe how those customizations are achieved.
Note that for demo purposes, we have created a CCK that customizes the browser as if it were distributed by A9.
This is a preliminary CCK - use at your own risk.
How the CCK is organized
For this version of the CCK, we have provided an
XPI file that can be distributed and
installed with a standard Firefox install. To make CCK customizations, you
will have to unzip this XPI and the cck.jar
file that is contained within it, and then rezip the file for distribution.
Here is how the files are organized:
The cck.xpi
is a ZIP file that is organized
like this:
- cck.xpi
- install.js
- bin\
- browserconfig-cck.properties
- chrome\
- cck.jar
- defaults\
- pref\
- firefox-cck.js
- profile\
- bookmarks.html
- hostperm.1
- pref\
- searchplugins\
The cck.jar
is a ZIP file that is
organized like this:
- cck.jar
- content\
- cck\
- cck-browser-overlay.xul
- cck.css
- cck.dtd
- cck.js
- cck.properties
- contents.rdf
- throbber-anim.gif
- throbber-single.gif
- cck\
- content\
After making the changes referenced in this file, you should rezip the JAR and the XPI exactly as they were originally.
Installing the CCK with Firefox on Windows
Once you have a cck.xpi
, you can modify
Firefox to install the CCK as part of the normal Firefox install on
Windows.
- First, you must obtain 7-zip from
http://www.7-zip.org/. Using 7-Zip,
unpack the files from
Firefox Setup 1.0.X.exe
into a directory. - Copy your
cck.xpi
into this directory. - Edit the file
config.ini
and make the following changes:
Search for [Setup Type0]
. There are two setup types for
Firefox, and we will be adding the CCK to both of them. After the line
C5=Component QFA
, add the line:
C6=Component CCK
Search for [Setup Type1]
. After the line
C6=Component QFA
, add the line:
C7=Component CCK
Search for [Component Langpack]
. We will be adding a new
component after this section for the CCK. Add the following section after
the line FileCount=25
and before the line
[Component QFA]
:
[Component CCK] Description Short=CCK Description Long=Client Customization Kit Archive=cck.xpi Install Size=1 Install Size System=1 Install Size Archive=1 Attributes=SELECTED|INVISIBLE
These attributes ensure that it will always be installed, and the user will not see that it is being installed.
Note you can also change some of the references to Mozilla Firefox in this file to mention your custom edition. For instance, this line will change the name of the folder that is created on the desktop:
Path=[PROGRAMFILESDIR]\Mozilla Firefox
Do NOT change Company Name
,
Product Name
, or ProductNameInternal
as this will
cause Firefox to not function correctly.
You can now test your install by simply running
setup.exe
.
If you want to ship your customized Firefox as a single executable, you can follow the instructions of Creating a Localized Installer. Creating this file is beyond the scope of this document.
If you want a silent install, you can change the line
Run Mode=Normal
to Run Mode=Silent
. Note that
Run Mode=Auto
does not work with Firefox 1.0.x browsers.
Items that can be changed by the CCK
This section details the items that can be changed by the CCK and how to change them.
Company Identifier
This change allows you to specify a company identifier that is included
as part of the browser's user agent string which appears when you open the
Help menu and select About Mozilla Firefox. To make this change, edit the
file firefox-cck.js
and change the following
line:
pref("general.useragent.vendorComment", "CK-A9");
If you do not want the have a company identifier, comment out (//) the
above line in firefox-cck.js
.
Animated logo
These changes allow you to specify the URL that users will go to when they click on the animated logo button, the tooltip that users will see when they mouse over the animated logo button and the animated logo itself.
To change the URL that users will go to when they click on the animated
logo button, edit the file cck.properties
and change the following line:
browser.throbber.url=http://a9.com/
If you do not want to change the URL comment out (//) the following line
from firefox-cck.js
:
pref("browser.throbber.url", "chrome://cck/content/cck.properties");
To change the tooltip that users will see when they mouse over the
animated logo button, edit the file cck.dtd
and change the following line:
<!ENTITY throbber.tooltip "Go to A9">
If you do not want to change the tooltip, comment out the following code
in cck-browser-overlay.xul
:
<!-- <button id="navigator-throbber" tooltiptext="&throbber.tooltip;"/> -->
To change the animated logo, you must create two images, one
corresponding to the logo when it is animated, and one corresponding to the
logo when it is at rest. The animated image must be a GIF, but the at rest
image can be either a PNG or a GIF. These images should be 16x16. You can
use the files throbber-anim.gif
and
throbber-single.gif
as templates. Once you
have created these images, simply replace
throbber-anim.gif
and
throbber-single.gif
with your images. If you
used a PNG for your at rest logo, you must edit the file
cck.css
and change the two occurrences of
throbber-single.gif to throbber-single.png
.
If you do not want to change the animated logo, remove the following line
from cck-browser-overlay.xul
:
<?xml-stylesheet href="chrome://cck/content/cck.css" type="text/css"?>
Help Menu
This change allow you to add an item to the Help Menu which provides a
link to your online customer support page. To make this change, you have to
change two files. First, edit the file cck.dtd
and change the following line to the text you would like displayed on the
help menu item:
<!ENTITY cckHelp.label "A9 Help and FAQs">
You can also change cckHelp.accesskey
in this file to
indicate which character you would like underlined on the menu.
Next, edit the file cck.properties
and change the following
line to the URL you would like the user to go to when they select the menu
item:
cckhelp.url=http://www.a9.com/-/company/help.jsp
If you do not want to add an item to the Help Menu, comment out the
following code in cck-browser-overlay.xul
like this:
<!-- <menupopup id="menu_HelpPopup"> <menuitem label="&cckHelp.label;" position="1" accesskey="&cckHelp.accesskey;" oncommand="openUILink(getCCKLink('cckhelp.url'), event, false, true);" onclick="checkForMiddleClick(this, event);"/> </menupopup> -->
Default Home Page
This change allows you to specify the page that is displayed when users
first start the Mozilla Firefox browser, or when they click the Home
button. To make this change, edit the file
browser-config-cck.properties
and change the
following lines to the Home Page URL:
browser.startup.homepage=http://a9.com/ browser.startup.homepage_reset=http://a9.com/
If you do not want to change the default home page, comment out (//) the
following lines in firefox-cck.js
:
pref("browser.startup.homepage", "resource:/browserconfig-cck.properties"); pref("browser.startup.homepage_reset", "resource:/browserconfig-cck.properties");
Browser Window's Title Bar Text
This change allows you to add text (for example, your company name) that
appears after the page title in the title bar. To make this change, edit
the file cck.dtd
and change the following line:
<!ENTITY mainWindow.titlemodifier "Mozilla Firefox: A9 Edition">
Note that if you are distributing Firefox externally, this text should take the form:
Mozilla Firefox: CompanyName Edition
If you do not want to change the title bar text, comment out the
following code in cck-browser-overlay.xul
like this:
<!-- <window id="main-window" titlemodifier="&mainWindow.titlemodifier;"/> -->
Custom Personal Toolbar and Bookmarks
This change allows you to specify custom Personal Toolbar items,
bookmarks, and bookmark folders. To make this change, you must edit the
file bookmarks.html
. We have provided a
default bookmarks.html
that shows how to do
some basic bookmarks, and you can use these as a template for adding your
bookmarks. It is important when editing this file that you keep the
structure in the file.
Adding a bookmark
All bookmarks take this form in the file:
<DT><A HREF="http://a9.com/">A9.com</A>
Where you put them in the file determines how they appear in the user interface.
Specifying a custom Personal Toolbar item
To specify a custom tool bar items, make the bookmark a child of the folder marked PERSONAL_TOOLBAR_FOLDER:
<DT><H3 PERSONAL_TOOLBAR_FOLDER="true" ID="rdf:#$FvPhC3">Bookmarks Toolbar Folder</H3> <DD>Add bookmarks to this folder to see them displayed on the Bookmarks Toolbar <DL><p> <DT><A HREF="http://a9.com/">A9.com (Personal Toolbar)</A> </DL>
Adding a bookmark folder
Bookmark folders are indicating by using an <H3>
tag
in the bookmark:
<DT><H3>A9 (Folder)</H3>
Popup and XPInstall whitelist
This change allows you specify sites for which popups and/or XPInstalls
are not automatically blocked. To make this change, you must edit the file
hostperm.1
. This file contains a list of
domain names and the default popup and install settings for those domains.
To add your domain, simply change thefollowing line to your domain name:
host popup 1 a9.com
If you want to allow XPInstalls for your domain, you can add the line:
host install 1 example.com
If you add additional lines, note that the separator between the items on a line are tabs.
If you do not want to specify sites that are whitelisted, do not place
hostperm.1
in
CCK.XPI
.
Note that this change only takes effect when a new profile is created, since the changes are in a file that is copied over when a new profile is created.
Custom Search Engine
This change allows you to specify an additional search engine that is available in the Firefox search bar. In order to add a search engine, you must have a search plugin file (SRC) and an image file (GIF, JPG or PNG). More information on these file formats, as well as many prebuilt search plugins can be found at http://mycroft.mozdev.org/.
Once you have a SRC file and an image file, simply place these files into
the searchplugins
directory in
CCK.XPI
and they will be installed as part of
the CCK.
By default, the search plugins are sorted by filename. If you want your
search engine to appear first in the list, add the following preference to
firefox-cck.js
where "Name of Plugin" is the
name specified in the search plugin file:
pref("browser.search.order.1", "Name of Plugin");
Note that by default, Google is the first search item and Yahoo is the second, so if you make yours first, you might want to add these lines as well to ensure consistent order:
pref("browser.search.order.2", "Google"); pref("browser.search.order.3", "Yahoo");