You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@wookie.apache.org by sc...@apache.org on 2011/05/17 19:07:24 UTC
svn commit: r1104413 -
/incubator/wookie/site/trunk/content/wookie/docs/developer/parser.mdtext
Author: scottbw
Date: Tue May 17 17:07:24 2011
New Revision: 1104413
URL: http://svn.apache.org/viewvc?rev=1104413&view=rev
Log:
Added parser documentation
Added:
incubator/wookie/site/trunk/content/wookie/docs/developer/parser.mdtext (with props)
Added: incubator/wookie/site/trunk/content/wookie/docs/developer/parser.mdtext
URL: http://svn.apache.org/viewvc/incubator/wookie/site/trunk/content/wookie/docs/developer/parser.mdtext?rev=1104413&view=auto
==============================================================================
--- incubator/wookie/site/trunk/content/wookie/docs/developer/parser.mdtext (added)
+++ incubator/wookie/site/trunk/content/wookie/docs/developer/parser.mdtext Tue May 17 17:07:24 2011
@@ -0,0 +1,100 @@
+Title: Using Wookie's W3C Widget Parser in other Applications
+Notice: Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+ .
+ http://www.apache.org/licenses/LICENSE-2.0
+ .
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+The code that Wookie uses to parse and unpack W3C Widgets can also be used in other applications and projects as a standalone library. The parser can be found as a sub-project within the "parser/java/" folder in the main Wookie source tree.
+
+# Building the parser
+To build the parser as a standalone .jar, run `ant publish-local` from within the parser folder; the jar will be saved in `parser/dist`. Dependencies are described in the ivy.xml file that can also be found in the `parser/dist` folder.
+
+# Using the parser
+The parser is invoked using a `W3CWidgetFactory` object. This has a number of configuration properties that can be set, and these are described at the bottom of this page. While most of these are optional, to use the factory to parse .wgt files you MUST supply a valid output directory into which the `W3CWidgetFactory` will unpack the widget.
+
+For example, a simple program to unpack a .wgt file, and write the name of the widget to the console looks like this:
+
+
+ public static void main(String[] args) {
+ File out = new File("out");
+ File zipFile = new File("in/butterfly.wgt");
+
+ W3CWidgetFactory fac = new W3CWidgetFactory();
+ fac.setOutputDirectory(out.getAbsolutePath());
+ fac.setLocalPath("/out");
+ try {
+ W3CWidget widget = fac.parse(zipFile);
+ System.out.println(widget.getLocalName("en"));
+ } catch (BadWidgetZipFileException e) {
+ e.printStackTrace();
+ } catch (BadManifestException e) {
+ e.printStackTrace();
+ }
+ }
+
+#Localized elements
+
+Many of the elements of a W3CWidget object are localized; these elements all implement the `ILocalizedElement` interface. These elements can be processed using the `LocalizationUtils` class, which has methods to process these elements based on lists of preferred locales. E.g., to extract the single most preferred Name element for the "fr" locale:
+
+ INameEntity[] names = widget.getNames().toArray(new INameEntity[fNamesList.size()]);
+ String[] locales = new String[]{"fr"};
+ INameEntity name = (INameEntity)LocalizationUtils.getLocalizedElement(names, locales);
+
+
+`LocalizationUtils` uses icu4j to process elements using appropriate fallback strategies based on language variants and extensions.
+
+#Outputter
+
+As well as a parser, the parser library also has a `WidgetOutputter` class that can be used to export config.xml files that conform to the W3C Widgets: Packaging and Configuration specification.
+
+To export a config.xml for a W3CWidget object as a String :
+
+ W3CWidget widget = myWidget;
+ WidgetOutputter outputter = new WidgetOutputter();
+ outputter.setWidgetFolder("/widgets");
+ String configXml = outputter.outputXMLString(widget);
+
+To export a config.xml to an OutputStream use:
+
+ W3CWidget widget = myWidget;
+ WidgetOutputter outputter = new WidgetOutputter();
+ outputter.setWidgetFolder("/widgets");
+ FileOutputStream out = new FileOutputStream(new File("config.xml"));
+ outputter.outputXML(widget, out);
+
+#Factory properties reference
+
+##outputDirectory
+The directory where the widget will be saved. The factory will expand the widget archive into this directory, using the widget's identifier to generate a directory name and structure in which to place it</dd>
+
+##startPageProcessor
+
+An implementation of the `IStartPageProcessor` interface. Setting this property allows you to inject a class that can pre-process start pages for the widget; for example to inject javascript, tidy up HTML, insert template code etc. If this is not set, no pre-processing is done by the factory.
+
+##locales
+
+The supported locales (as BCP47 language-tags) to be processed for the widget. This determines which start files, icons, and other localized elements will be processed and expanded. This is set to "en" by default
+
+##encodings
+
+The supported encodings to be processed for the widget. This determines which custom encodings will be allowed for start files. This is set to UTF-8 by default.
+
+##localPath
+
+The base URL from which unpacked widgets will be served, e.g. "/myapp/widgets". The URLs of start files will be appended to this base URL to create the widget URL. The default value of this property is "/widgets"
+
+##features
+
+The features supported by the implementation; this should be supplied as IRIs e.g. "http://wave.google.com". The features are matched against features requested by the widget; if the widget requires features that are unsupported, an Exception will be thrown when parsing the widget package. The default value of this property is an empty String array.
Propchange: incubator/wookie/site/trunk/content/wookie/docs/developer/parser.mdtext
------------------------------------------------------------------------------
svn:eol-style = native