Prism/Scripting

2008-01-02T14:58:01Z

Greylurk:

Prism allows for some client-side web application customization. The web application [[Prism/Bundle|bundle]] is allowed to hold a JavaScript file named '''webapp.js''' (called the webapp script). This file will be loaded into the Prism chrome window very much like a Firefox extension is loaded into the browser chrome window.

Prism exposes a simple HostUI object to the webapp script. The HostUI object exposes some utility functions that may be useful to the webapp script. The interface is shown below:
<pre>
/**
* Simple host API exposed to the web application script files.
*/
var HostUI = {
// log a message to the error console
void log(aMsg);

// get a reference to the main content web browser
browser getBrowser();

// show a popup alert message
void showAlert(aImage, aTitle, aMsg);

// access the Sidebar object
object sidebar;
};

var Sidebar = {
// collapse or expand the sidebar
boolean visible;

// sets the web content of the sidebar
void add(aTitle, aURI);
};
</pre>

==HostUI methods==
The methods exposed by the HostUI object allow interaction with the Prism runtime environment.

; void log(aMsg);
: Logs a message to the Prism error console.
; browser getBrowser();
: Returns a reference to the XUL [http://developer.mozilla.org/en/docs/XUL:browser Browser] object which displays the Prism documents
; showAlert(aImage, aTitle, aMsg);
: showAlert provides a thin wrapper around the [http://developer.mozilla.org/en/docs/nsIAlertsService nsIAlertsService.showAlertNotification] XPCOM method.
:; aImage
:: A URL to the image which should be displayed in the notification
:; aTitle
:: The string to be used as the title for the alert
:; aMsg
:: The text of the message to be displayed in the alert

There are also hooks that are called when Prism has loaded and when it is about to exit. You can declare these functions in the webapp script:
<pre>
function startup() {
// called during startup
}

function shutdown() {
// called during shutdown
}
</pre>

Currently, the webapp script also has access to full XPCOM functionality, just like a Firefox extension. This level of functionality is commonly called ''chrome-level'' privileges. It means that the script has a higher level of privilege than scripts in the web content and has access to the file system, clipboard and other parts of the native OS.
<div class="note">In the future, the webapp script may have lower privileges. We are looking into the security aspects of the higher privilege level.</div>

Prism/Bundle

2008-01-02T14:35:10Z

Greylurk:

==WebApp Bundle==
In addition to passing simple command line parameters, [http://wiki.mozilla.org/Prism Prism] can use a zipped bundle package to install a webapp. The bundle can hold additional resources currently limited to:
* Application INI settings
* Application icon
* Script for the application chrome, not the web content

==Installing a Bundle==
When Prism opens a webapp bundle it will unpack it into the '''webapps/{webapp-id}''' folder in your Prism profile. The web application may save other data into this folder. Prism will not overwrite or delete any extra data added to the folder. In fact, Prism saves some extra data itself - a file that holds some persistent UI data called ''localstore.json''.

<div class="note">The webapp must have an ID in order to be installed.</div>

When Prism is launched with a "-webapp [bundle]" command line, the bundle must first be unpacked before the web application is launched. This can slow the overall launch time and the unpacking is redundant if the bundle has been launched previously. This is why the preferred method of launching is to use the "-webapp [webapp-id]" command line, which looks for the previously installed (unpacked) web application in the Prism '''webapps/{webapp-id}''' folder. The web application is then launched without the unpacking overhead.

==HowTo==

Here is a simple way to build a basic web application bundle:

* Create file called webapp.ini that contains something like:
<pre>
[Parameters]
id=unique-app-id@unique-author-id.whatever
uri=http://[the-url-what-you-want-to-connect-to]/
status=yes
location=no
sidebar=no
navigation=no
</pre>
* Zip the file to [whatever].webapp
* Double-click the webapp bundle or use <code>prism -webapp [path-to-webapp]

==Structure==
A bundle can contain the following files. Any other files in the .webapp file will be ignored. After the .webapp file is executed the first time, these files will be unzipped and "cached" to a local directory structure.

; /
: webapp.ini
: webapp.js
: webapp.css
:; winnt
:: webapp.css
:; darwin
:: webapp.css
:; linux
:: webapp.css
: [icon].ico
: [icon].xpm
: [icon].icns

MozillaWiki - User contributions [en]

Prism/Scripting

Prism/Bundle