Revision: 3821
Author: jasvir
Date: Wed Oct 21 00:17:27 2009
Log: Cleaning up documentation
* removed obsolete content from the wiki
* consolidated repeated text from different pages
* added a page on debugging
* added a floating sidebar
http://code.google.com/p/google-caja/source/detail?r=3821
Added:
/wiki/Containers.wiki
/wiki/Debugging.wiki
/wiki/Motivation.wiki
Modified:
/wiki/CajaCajole.wiki
/wiki/ContributingCode.wiki
/wiki/GettingStarted.wiki
/wiki/RunningCaja.wiki
/wiki/TableOfContents.wiki
=======================================
--- /dev/null
+++ /wiki/Containers.wiki Wed Oct 21 00:17:27 2009
@@ -0,0 +1,12 @@
+#summary Containers using Caja
+
+= Containers using Caja =
+ * [http://developer.yahoo.com/yap/ Yahoo Application Platform]
+ All YAP gadgets are cajoled
+ * [http://m.www.yahoo.com/ New Yahoo home page]
+ All home page gadgets are cajoled in expanded view
+ * [http://code.google.com/p/support/wiki/WikiSyntax#Gadgets Gadgets in
Google Code Wiki]
+ Wiki authors can force untrusted gadgets they embed in their page to
be cajoled with the `caja=1` attribute setting
+ * [http://www.google.com/ig iGoogle] and [http://www.orkut.com Orkut]
+ Gadget authors can protect themselves from accidental XSS errors by
requiring the caja feature with `<Require feature="caja" />`
+ * [http://incubator.apache.org/shindig/ Shindig] reference implementation
of OpenSocial
=======================================
--- /dev/null
+++ /wiki/Debugging.wiki Wed Oct 21 00:17:27 2009
@@ -0,0 +1,121 @@
+#summary How to debug Caja applications
+
+Caja performs a server-side translation of your HTML, CSS and
+JavaScript. It also includes some client-side runtime support.
+
+= Compile-time errors =
+
+Caja compile time errors include information about what errors
+occured, the url of the offending content as well as a line number and
+offset.
+
+For example, suppose you try to cajole the following piece of code: {{{
+<script>
+var top;
+with(top) { location = "http://www.evil.com"; }
+</script>
+}}}
+
+You get the following messages:
+{{{
+LINT http://www.example.com/index.html:3+48: Semicolon inserted:
+ERROR http://www.example.com/index.html:3+1 - 50: "with" blocks are not
allowed:
+}}}
+
+The first message is of type `LINT`. These do not stop the
+compilation from proceeding and producing output but inform you of
+choices the cajoler has made about how to recover from a possible
+problem in the input. In this case, the cajoler has inserted a
+semicolon on Line 3, Column 48. According to the JavaScript
+specification, it is not an error to leave out semicolons at the end
+of the line. However, under some circumstances you may be surprised
+about where JavaScript thinks a semicolon should go.
+
+The second message is of type `ERROR`. These do not stop the
+compilation from proceeding to discover more context around the error
+but the cajoler will not be able to produce usable output. In this
+case, the cajoler has come across a `with` block on Line 3, starting
+at Column 1 and continuing to Column 50. `with`statements modify
+dynamic scope and are often misunderstood and a common source of
+errors. They are disallowed in Caja. To correct this error, you must
+rewrite this block of code to avoid the `with` statement.
+
+Here are some types of messages you may see:
+ * `LOG` info about the internal progress of the Cajoler
+ * `LINT`/`WARNING` a possible problem in an input source file
+ * `CRITICAL_WARNING` a serious problem but cajoler can still produce
usable output
+ * `ERROR`/`FATAL_ERROR` cajoler cannot produce usable output
+
+= Run-time errors =
+
+Some types of errors in your program won't get discovered until
+runtime. On browsers that support a console, runtime errors are
+logged to the console configued by the container.
+
+For example, suppose you try to cajole and run the following piece of
code: {{{
+<script>
+top.location = "http://www.evil.com";;
+</script>
+}}}
+
+You will see no compile errors, however, your browser page will
+probably not redirect as you expect. In your JavaScript console, you
+get the following message:
+
+{{{
+http://www.example.com/index.html:2: Result of expression 'top'
[undefined] is not an object.
+}}}
+
+This error means on Line 2, the code was expecting the expression
+`top` to be an `Object` but it turned out to be undefined. This
+happens because by default cajoled code is not granted access to _any_
+browser object other than the DOM. As a result variables such as
+`window`, `top` and `navigator` which you may expect to be defined
+when you are running JavaScript in a browser will all be undefined.
+
+Here's another trivial piece of code with an error: {{{
+<script>
+ function apply(func, val) {
+ return func(val);
+ }
+ apply(1, alert);
+</script>
+}}}
+
+As you would expect in your JavaScript console, you get the following
message:
+{{{
+http://www.example.com/index.html:2: expected function instead of number:1
+}}}
+
+Caja checks that if you try to call an object as a function, that it
+is in fact a function and that the gadget is allowed to call it before
+it is called.
+
+Some containers and browsers may not provide you with adequate
+information about the error messages your application generates. If
+you are able to narrow the problematic section of your code, you can
+may be able to get more detailed error messages by testing snippets on
+our testbeds([http://www.cajadores.com/demos/testbed/ 1]
+[http://caja.appspot.com 2]).
+
+= Advanced Debugging =
+
+With larger and more sophisticated applications, it is helpful to
+delve deeper into the cajoled code to understand why a cajoled
+application is misbehaving.
+
+Here are some tips that you may find helpful:
+
+* [http://www.squarefree.com/shell/shell.html SquareFree Shell] provides a
very useful [https://www.squarefree.com/bookmarklets/webdevel.html
bookmarklet] which you can load in the same frame as a cajoled
application. In the shell, you can access what a cajoled gadget perceives
its global scope to be as follows: {{{
+ var gadgetGlobal = ___.getNewModuleHandler().getImports().outers;
+}}}
+
+* You can test if some property of an object is readable, settable or
callable by the gadget with `___.canRead(obj, property)`, `___.canSet(obj,
property)` and `___.canCall(obj, property)` respectively.
+
+* Other [InternalProperties internal properties] can also help identify
why a cajoled program behaves differently from an uncajoled one
+
+* By default, many containers will minify cajoled output for efficient
delivery. This is not ideal for debugging. If possible, request debug mode
from the container or use the testbed for debugging.
+
+* If you are using Firefox, install the Firebug extension. Caja dumps
useful logs and stack traces in the console.
+
+* If the container has made the `alert` function or the `console.log`
functions available, they provide very useful feedback.
=======================================
--- /dev/null
+++ /wiki/Motivation.wiki Wed Oct 21 00:17:27 2009
@@ -0,0 +1,24 @@
+#summary Why use Caja?
+
+= Motivation =
+
+Some websites embed code in `iframes`, and pass user data between
+them. The use of these sites has thus far been limited to teenagers
+and others who are comfortable with some aspects of their lives being
+very public. The same development model -- where one company
+provides a general storage layer for data, and third parties provide
+custom interfaces and extensions - has not been extended to
+systems that deal with valuable data.
+
+This development model is promising, though. Large software companies
+have to target their user-interface efforts at a mythical average
+user; the high costs of researching and understanding the needs of
+niches of users means that user interfaces tend to suffer from the
+"lowest common denominator" effect. But there are many developers who
+understand niche markets, and know how to write custom user interfaces
+and workflows.
+
+If we can safely embed third-party user interfaces and workflows into
+generic backends, we can encourage a market for embedded applications
+that will make the web experience much richer. Caja aims to allow that
+safe embedding.
=======================================
--- /wiki/CajaCajole.wiki Tue Jun 3 23:45:18 2008
+++ /wiki/CajaCajole.wiki Wed Oct 21 00:17:27 2009
@@ -1,13 +1,5 @@
#summary "Cajoling" is what we call the process of turning Caja input into
JavaScript.
-=Decide what you want to cajole=
-
-Caja turns a piece of Web content -- roughly, a snippet of HTML, CSS
and !JavaScript that you would see within the `body` tag of an HTML page --
into a Caja _module_. This module is represented as a single !JavaScript
_module function_ that can be run within a Caja container. (The module
function builds the supplied HTML and CSS dynamically.) Caja supports two
input formats:
-
-*!OpenSocial.* Caja accepts an [http://code.google.com/apis/opensocial/
OpenSocial] [http://code.google.com/apis/gadgets/docs/spec.html gadget],
producing as its output a similar gadget with a single `script` tag
containing the module function.
-
-*Plain HTML.* When given a bare snippet of HTML content (including CSS,
and !JavaScript `script` tags), Caja will produce a single !JavaScript file
containing the module function.
-
=Obtain a Caja build=
To cajole your input, first build Caja from source.
=======================================
--- /wiki/ContributingCode.wiki Mon Oct 27 11:49:47 2008
+++ /wiki/ContributingCode.wiki Wed Oct 21 00:17:27 2009
@@ -106,3 +106,10 @@
* `diffstats` - number of lines added/changed/removed
* `files` - files changed in svn. Pipeable to xargs
* `filetypes` - sets `svn:mime-type` of modified files based on file
suffix
+
+= Legal =
+
+See also the Contributor Licence Agreement (either the
+[http://code.google.com/legal/individual-cla-v1.0.html individual CLA]
+or the [http://code.google.com/legal/corporate-cla-v1.0.html corporate
+CLA]).
=======================================
--- /wiki/GettingStarted.wiki Fri Feb 20 03:06:25 2009
+++ /wiki/GettingStarted.wiki Wed Oct 21 00:17:27 2009
@@ -1,10 +1,42 @@
-#summary Resources for new users or users-to-be of Caja
-#labels Phase-Deploy,Featured
-
-= Resource For New Users =
-
- * [RunningCaja Downloading and building Caja].
- * [CajaCajole Running Caja from the command line].
- * [NewNewCodeReview Contributing code] - see also the Contributor Licence
Agreement (either the
[http://code.google.com/legal/individual-cla-v1.0.html individual CLA] or
the [http://code.google.com/legal/corporate-cla-v1.0.html corporate CLA]).
- * [CajaHostingModules Writing containers].
- * [LibraryTaming Taming libraries].
+#summary Resources for end-users using caja
+
+=How do I use Caja? =
+
+Caja turns a piece of Web content -- roughly, a snippet of HTML, CSS
+and !JavaScript that you would see within the `body` tag of an HTML
+page -- into a Caja _module_. This module is represented as a single
+!JavaScript _module function_ that can be run within a Caja container.
+
+Caja is currently used both for securing gadgets and plain webpages.
+
+= Caja for Gadgets =
+
+In practice, the most common place you may need to write in Caja is
+when creating Opensocial gadgets. Some opensocial containers (such as
+YAP, Shindig, iGoogle, Code Wiki and Orkut) support Caja.
+
+To turn on caja, you require the caja feature with `<Require
feature="caja" />`.
+
+For example, here is a trivial Hello World OpenSocial gadget:
+
+{{{
+<?xml version="1.0" encoding="UTF-8"?>
+<Module>
+ <ModulePrefs title="Hello World Gadget">
+ <Require feature="caja"/>
+ </ModulePrefs>
+ <Content type="html">
+ <![CDATA[
+ <div id="message"></div>
+ <script type="text/javascript">
+ document.getElementById('message').innerHTML = "Hello World";
+ </script>
+ ]]>
+ </Content>
+</Module>
+}}}
+
+You can run this gadget by loading it in an opensocial container such as
Code Wiki as follows:
+{{{
+<wiki:gadget url="http://example.com/gadget.xml"; height="200" border="0" />
+}}}
=======================================
--- /wiki/RunningCaja.wiki Fri Feb 20 02:49:50 2009
+++ /wiki/RunningCaja.wiki Wed Oct 21 00:17:27 2009
@@ -11,9 +11,8 @@
* The [http://subversion.tigris.org/project_packages.html subversion]
version manager
* The [http://ant.apache.org/manual/install.html Apache Ant] build
system.
* The
[http://sourceforge.net/project/showfiles.php?group_id=15278&package_id=12472
JUnit] testing framework. Just drop {{{junit.jar}}} in the
{{{$ANT_HOME/lib}}} directory you set up for Ant.
- * [http://code.google.com/p/gvn gvn].
-
-If you intend to contribute patches to Caja (and we would love you to do
that, see ContributingCode for how), you need to sign a Contributor Licence
Agreement (either the
[http://code.google.com/legal/individual-cla-v1.0.html individual CLA] or
the [http://code.google.com/legal/corporate-cla-v1.0.html corporate CLA],
depending on your situation). Note that patches are accepted at the
discretion of the development team. Membership of the development team will
be offered to those who consistently make positive contributions.
+
+If you intend to contribute patches to Caja (and we would love you to do
that, see [ContributingCode] for how), you need to sign a Contributor
Licence Agreement (either the
[http://code.google.com/legal/individual-cla-v1.0.html individual CLA] or
the [http://code.google.com/legal/corporate-cla-v1.0.html corporate CLA],
depending on your situation). Note that patches are accepted at the
discretion of the development team. Membership of the development team will
be offered to those who consistently make positive contributions.
== Building Caja via Ant ===
@@ -113,12 +112,6 @@
{{{
$ ./tools/myvn eclipse
}}}
-
-You may have to create {{{~/.gvn/config}}} containing:
-
-`username=`_`your code.google.com user name`_
-
-before this works.
From inside eclipse, import the project from the File -> Import ->
Existing Project into Workspace option. Select the Caja checkout directory
as the root directory and import the project.
@@ -159,8 +152,6 @@
|
+--tests : test files and resources
}}}
-
-
== Other Resources ==
=======================================
--- /wiki/TableOfContents.wiki Tue Oct 20 15:41:17 2009
+++ /wiki/TableOfContents.wiki Wed Oct 21 00:17:27 2009
@@ -1,12 +1,11 @@
#summary documentation outline for docreader
#sidebar TableOfContents
* End-user's Guide
- * [Motivation Motivation]
- * [AttackVectors]
- * [CapabilityUseCases]
* [GettingStarted Getting Started]
* [Debugging]
- * [InternalProperties]
+ * [Motivation]
+ * [AttackVectors Types of attacks]
+ * [CapabilityUseCases Capabilities in Web applications]
* Language spec
* [CajaOverview]
* [SimpleSubset]
@@ -25,10 +24,9 @@
* [Performance]
* [PipelineConfiguration]
* Developer's Guide
- * [CajaCajole]
+ * [RunningCaja]
* [ContributingCode]
* [DebuggingShindig]
- * [RunningCaja]
* [RunningJQueryTests]
* [RunningPrototypeTests]
* [InternalProperties]
@@ -46,13 +44,14 @@
* [InnocentCodeRewriter]
* [UncaughtExceptionHandling]
* [OutputChecks]
+ * [InternalProperties]
* Releases
* [CajaVersions]
* Community
* External articles about caja
- * Containers that use caja
+ * [Containers Containers that use caja]
* Mailing lists
* [Ideas Ideas and feature requests]
* [RefactoringToolFeatureRequests]
* [CajaLexicon Glossary of common terms]
- * [http://code.google.com/p/google-caja/w/list List of all wiki pages]
+ * [http://code.google.com/p/google-caja/w/list All wiki pages]
