Legals Beta 1 Release Notes - [ ] Overall Status - [ ] This document: ben shine's working draft as of 12.2.2006 - [ ] Welcome to the first beta release of OpenLaszlo project "Legals," which is now officially called "Open Laszlo 4.0 Beta 1." - [ ] With this B1 release, we invite developers to start developing against our brand new DHTML and heavily revamped Flash runtimes. There have been four preview releases before this beta, PR1 through PR4, each demonstrating major progress but none stable enough for use as a development platform. You'll need to deal with a few rough edges -- many performance improvements remain, there are still significant bugs, and some features remain incomplete -- but we believe that the level of functionality is high enough that the intrepid early adopter will benefit from trying out this release. We plan a B2 release by the end of 2006 that will be incrementally more stable. We will label the B2 our "Developer's Release," suggesting that with B2 serious development cycles may begin in earnest. The final release of Legals will come in Q1 of 2007. We foresee major focus on performance improvements for B2. The 4.0 release is a major re-architecture of OpenLaszlo to support multiple target runtimes, and includes support for Flash 7 and 8 (and 9 in Flash-8 emulation) along with DHTML. Our DHTML support covers the most popular browsers of the moment: Firefox 1.5 and 2.0, Microsoft Internet Explorer 6 and 7, and Safari 2. Other browsers are not officially supported but seem to work fairly well, including Opera 9 and nightly builds of Webkit. (See below (link) for details on supported browsers.) Legals is very nearly feature complete. All components are at a testable state with just P2 bugs remaining to be addressed. The Laszlo Foundation Classes (LFC) have been completely refactored and heavily modified to support our multi-kernel architecture, differences between supported JavaScript dialects, and the addition of several significant ECMAScript 4 features to the compiler and language support library. The kernel API is fully documented and nearly complete. The reference documentation tools have been revised to support multiple runtimes and ECMAScript 4 syntax. A more detailed description of the changes in this release is to be found below. There are still a variety of missing elements and gotchas. The rest of this document describes these issues in detail. See (link) We are working to provide as many Flash-centric features as possible in DHTML -- preliminary support for is in this release -- but several features familiar to OpenLaszlo developers are not currently scheduled for 4.0B1 at all. These include swf embedding, audio/video embedding, streaming audio/video, persistent connection, and snippets. A working 3.x application will probably not work unmodified in 4.0B1, but, there are well-known techniques for coping with this. Some changes are required to adapt to the new runtime, plus a few changes are necessary to temporarily work around bugs and missing features. JavaScript in browsers is generally more strict than in Flash, so certain common coding practices no longer work or are deprecated in Legals. More information on transitioning from 3.x is available below. - [ ] Read this before using Open Laszlo 4.0 Beta 1 - [ ] Existing 3.x Open Laszlo applications will probably not work immediately with 4.0, but porting should be straightforward. See the section on porting from 3.x for details. - [ ] swf assets will not display in DHTML. Swf assets must be replaced with bitmap images. We recommend png. See below for a png conversion tool. - [ ] The tools for preparing a SOLO (standalone) application are still under development. - [ ] Performance is slower than 3.4.x and it will be improved. The swf runtime for 4.0 is somewhat slower than the swf runtime for 3.4; the DHTML runtime for 4.0 is considerably slower than the swf runtime for 4.0. This release is a feature-complete release, and not a performance-focused release. The following two releases, Beta 2 and 4.0 Official, will focus on performance improvements. - [ ] Post to laszlo-dev@openlaszlo.org with questions and comments. Please report bugs, especially regressions. - [ ] More information - [ ] The rest of this document first describes major changes since 3.3.x and 3.4, and then lists specific issue names and numbers. - [ ] General information about Legals may be found here. www.openlaszlo.org—legals - [ ] The Legals project wiki is here. wiki.openlaszlo.org—Legals_Project_Plan - [ ] A Legals FAQ is available here. wiki.openlaszlo.org—Legals_FAQ - [ ] Build instructions are here (link) - [ ] Nightly builds are here (link) - [ ] Demos are here (link) - [ ] Documentation is here (link) - [ ] Official distributions are available here (link) - [ ] The bug database is available here (link) - [ ] Getting Involved - [ ] (If you would like to get involved in qualifying Legals for these or any other browser, please contact us by visiting www.openlaszlo.org—cfaq.) - [ ] Marquee Demos - [ ] LzPix: a flickr photo browser which looks identical in DHTML and Flash runtimes. (link) - [ ] Calendar: a calendar application which looks nearly identical in DHTML and Flash runitmes. (link) - [ ] Browsers x Runtimes x Operating Systems - [ ] TODO bshine: make this diagram pretty - [ ] Runtime Operating Systems Support Level OL Kernel Notes Flash 7 Windows/Mac A swf version 7r68 or later Flash 8 Windows/Mac A swf incl. Flash9 emulation mode Internet Explorer 6 Windows A dhtml Internet Explorer 7 Windows A dhtml Firefox 1.5 Windows/Mac/Linux A dhtml Firefox 2.0 Windows/Mac/Linux A dhtml Safari 2.0 Mac A dhtml Flash 7 Linux B swf Flash Lite 2 Embedded/Mobile B swf WebKit nightly Mac B dhtml Mozilla nightly Windows/Mac/Linux B dhtml S60WebKit Symbian Series 60 B dhtml Opera 8 Windows/Mac B dhtml Opera 9 Windows/Mac B dhtml Flash 5 Windows/Mac C dhtml no longer supported Flash 6 Windows/Mac C dhtml no longer supported Flash 9 (native) Windows/Mac C support planned in 2007 Flash Lite Embedded/Mobile C based on Flash5; not supported Internet Explorer 5 Windows/Mac C too old; not supported Support Levels A -- Fully supported B -- Not supported, but may work; bugs tracked and contributions accepted C -- Incompatible (doesn't run for a significant technical reason) - [ ] Roadmap (plans for future and related versions) - [ ] 4.0 Beta 2 will be focused on improving performance. - [ ] We are beginning to plan out Osprey, the successor to 4.0, which will provide native Flash 9 support. (Note that 3.x and Legals both support Flash 9 using that player's Flash 8 emulation mode.) And members of the OpenLaszlo community have announced work on two more runtimes: project Orbit, the Sun/Laszlo partnership to produce a J2ME target runtime, and an experimental SVG runtime from OpenLaszlo team member Henry Minsky. - [ ] Another future version is seaswirl, which is components improvements. Seaswirl is not yet scheduled. - [ ] 4.0B1 does not include the Orbit runtime; watch (link) for news on Orbit. - [ ] Feature Status - [ ] Just Works - [ ] The core Open Laszlo functionality works in 4.0B1: views, nodes, resources, layouts, data, components, events, and focus. The three large demos included in this release demonstrate that 4.0B1 is mature enough to support lots of application development. LzPix (link) shows off animated user interfaces, data binding, REST api usage, image scaling, and complex javascript. The Calendar demo shows off data binding and an animated user interface. - [ ] Laszlo Explorer - [ ] Laszlo in Ten Minutes - [ ] Developer's Guide - [ ] Reference Guide - [ ] Examples we like - [ ] Weather - [ ] Amazon - [ ] LzPix - [ ] Calendar - [ ] Tons of Documentation and Examples - [ ] Views and layouts just work - [ ] Components just work. See components sampler (link) - [ ] Data binding and replication - [ ] New Features - [ ] Eliminated compiler flags (TODO ptw) - [ ] autopng - [ ] Automatically load png files instead of swfs if present."It should be explained that Placing a file with the same name in that parent directory overrides the version in the autoPng directory. Just to clarify, the compiler uses the same search path for swf->png. It does not create png from swf automatically. The autopng files are created by an offline process. - [ ] DHTML cannot display swf assets. As a convenience, the server and compiler automatically search for a corresponding png file if a swf file is referenced in the DHTML runtime. To use this mechanism in your own code, create a png file with the same basename as the swf file, and place it in the same directory as the swf resource you want it to replace. - [ ] - [ ] When compiled into a swf runtime, this will still load resources/foo.swf as expected. When compiled into a DHTML runtime, this will try to load resources/foo.png. - [ ] The Open Laszlo distribution also makes use of png replacements for swfs, generated by an offline, batch tool. If resources/foo.png is not present, the server will try to load resources/autoPng/foo.png. The autoPng-generating-tool used by the Open Laszlo developers is not yet documented for re-use. - [ ] Wrapper pages - [ ] Browser detection code in the wrapper pages will issue a warning at startup in non-A-list browsers. - [ ] canvas.versionInfo - [ ] javascript "in" operator: - [ ] iterating through data structures -- (TODO bshine: test this code) this: for (var c in cats) { var cat = cats[c]; Debug.write("I have a cat whose name is ", c); - [ ] iterating across attributes of an object. (TODO bshine: test this code) var obj = new View( ... ); for (var attr in obj) { Debug.write("obj has an attribute ", attr, " with value ", obj[attr]; } - [ ] Runtime Differences - [ ] Taken from the wiki: wiki.openlaszlo.org—Runtime_Differences - [ ] Visual transformations we can't (yet) do in dhtml are: * Rotation - may be possible in Firefox with SVG * Stretching nested subviews - likely possible in Firefox Visual transformations requiring extra runtime resources (IE only): * Opacity that affects subviews * Displaying PNG (and possibly GIF) images with alpha DHTML-specific limitations requiring source-level lzx changes: * Can't set the opacity of a view that contains text - but can set a subview's opacity (IE only) * Stretches only works on leaf views with resources * Rotation - may be possible in Firefox with SVG * Stretching nested subviews - likely possible in Firefox Fonts * DHTML does not support font inclusion. o If an LZX app uses the tag to import a font, and is compile it for DHTML or other target which doesn't support font inclusion, the compiler will give a warning "DHTMLWriter does not support importing fonts." Keyboard events * In DHTML, control, shift and alt are treated as 'modifer' keys. As a result, they are only sent when another key is pressed or a mouse event occurs. The Persistent Connection Manager * In flash, this is a provisional feature with limited support * In DHTML, does not work. - [ ] DHTML in Internet Explorer 6 is problematic, as is well-known by the web development community. Kernel and LFC support for IE6 is the most likely to have bugs. - [ ] Partially Supported - [ ] DrawView only supported in Firefox. It partially works in Safari. - [ ] MP3 playback - [ ] Present but Not Qualified - [ ] Two major feature sets developed for Open Laszlo 3.4 have been merged into the code for 4.0, but not yet qualified in 4.0B1: CSS (Cascading Style Sheets) and Video. - [ ] Video: (TODO jrs) Video support is present in Open Laszlo 3.4, but not tested or qualified in 4.0B1. - [ ] CSS provides a cascading style sheets implementation for styling Open Laszlo views and data. The CSS system has been extensively tested in 3.4, and is useful for compile-time skinning of applications. This is implemented in 3.4 as part of the LFC, and it will require changes to work in the 4.0 LFC implementation. This feature is separate from the DHTML runtime's use of css to set div properties. - [ ] The SVG (Scalable Vector Graphics) runtime is experimental. - [ ] Not yet ported to DHTML runtime - [ ] SOAP, XML-RPC, Java-RPC have not yet been ported to DHTML - [ ] Dropped Features from 3.x - [ ] Rich text editor - [ ] lps/components/extensions/rich-text will not ever work in DHTML. Code that goes into the "extensions" directory is, by definition, runtime-specific. If you want a rich text editor for DHTML, we suggest embedding an existing DHTML text editor such as TinyMCE tinymce.moxiecode.com - [ ] Dropped Demos - [ ] Dashboard - [ ] Architecture and Language Changes - [ ] Porting from 3.x to Legals - [ ] There will be very little change in the Javascript used in script blocks and method definitions in Open Laszlo applications. The main changes to Javascript in support of SWF9 and EcmaScript 4 are in the LFC sources to take advantage of the faster class system in 4.0. This change will automatically be handled for javascript in lzx code. If your code makes fancy use of the class system, it has a potential to break in 4.0, but we're not aware of breakages caused by the class system. - [ ] swf6 is no longer supported. That means applications will not run in Flash Player 6, and that the lzr=swf6 query argument is now an error. - [ ] swf assets won't work in DHTML. To display a swf asset, you'd need the flash player; we're not using the flash player in DHTML, so, swf assets just won't appear. The solution here is to use bitmap assets instead of swf's. The straighforward but painful way to do this is to convert your swf assets to bitmaps. The clever way to do this is to take advantage of the "autoPng" tool and autoPng server feature. - [ ] The straightforward but work-intensive strategy is to only use png's in your lzx application. If you are writing an application from scratch, this is the technique we recommend. - [ ] TBD Providing png alternates for swf assets - [ ] Applications which use drawview will probably not work well in all runtimes yet. It is probably too soon to start porting applications which use drawview. Wait for Beta 2. - [ ] DHTML doesn't support embedding fonts; swf does. If you try to embed a font and compile for dhtml, you'll get a compile warning, and the text will look ugly, or it won't appear at all. - [ ] The flash runtime is permissive about derefrencing a null reference and getting properties on an undefined object. DHTML blows up if you do this.Because it was permitted in swf, lots of code doesn't check for null. All the places that don't check for null need to be tracked down and fixed, both in the LFC, the components, and application code. - [ ] Introducing the Kernel... - [ ] TODO bshine The Layer Cake Diagram! - [ ] The best documentation for the kernel api is at http://wiki.openlaszlo.org/KernelAPIProposal - [ ] What does the kernel refactor mean for application developers? - [ ] The refactoring should be almost transparent to application developers, except for a few changed API's, which this document (the release notes) describes. - [ ] Most application developers build with components and classes, not the LFC API. Most application developers will not have to go near the kernel API's; the kernel API's are primarily for developers who are working on implementing an additional runtime. - [ ] Compiler flags for multiple runtimes - [ ] Wrapper page changes - [ ] The wrapper pages have been substantially changed. There is a new javascript bridge and flash embedding based on dojo.flash www.dojotoolkit.org Related to LPP-2664 update deployment wrappers for legals, LPP-3181, and LPP-3182 - [ ] TODO jrs: please explain this more - [ ] Resource loading changes - [ ] (TODO: insert description from pga here) - [ ] TODO ptw: Differences in the meaning of undefined, null (see lzunit tautologies test) - [ ] TODO ptw: Differences in semantics of boolean comparisons (see lzunit tautologies test) - [ ] TODO ptw: List javascript functions that were not available in 3.3 but are now available in 4.0. - [ ] For LFC Developers: Language changes - [ ] The "class system" underlying the Laszlo Foundation Changes has been extensively redesigned. If you are an Open Laszlo application developer or component developer, you don't need to know about this at all; it is transparent to you. In fact, you can't even get to the new class system unless you're working in the actual LFC code. - [ ] The Laszlo Foundation Classes (LFC) rely quite a bit on the new class system. If you work on the LFC, you will want to understand these changes. If you don't know whether you work on the LFC, you probably don't. - [ ] These new language features have been implemented in the LFC core to support (and extend) Javascript 2 `class` declarations portably. The LFC developer can now write Javascript 2 `class` declarations, rather than creating their classes using Javascript 1 prototypes. The Javascript 2 `interface` declaration is supported, but not enforced (that is, there is no compile or runtime checking that a class actually implements an interface). - [ ] We have extended Javascript 2 to support `mixin` declarations. See [BrachaCook90](http://portal.acm.org/citation.cfm?id=97982&coll=portal&dl=ACM ) for a formal definition of mixins. Informally, mixins are 'interfaces with implementation'. They take the same form as a `class` declaration, but are introduced by the keyword `mixin`. They are added to a class similarly to an interface, but with the keyword `with`. They are allowed to add methods and fields to the class they are mixed in to. They are allowed to override methods in the superclass and other mixins, but note many O-O theorists feel this generality leads to [inscrutable programs.][1] - [ ] Traits , which is the term we used informally when discussing our extension of the language, has a formal definition in O-O theory that side-steps the complexity of mixins and overriding by prohibiting state and overriding in `trait`s. We do not enforce such restrictions, although the designer can impose such a discipline on themselves. - [ ] The new class regime simply allows us to support the LXZ class system and Javascript 2 `class` declarations in a portable fashion across more runtimes. Eventually, we will expose `mixin`s at the LZX API and the application programmer will be able to use that feature to modularize their programs. We feel this will be highly beneficial in the design of UI components which tend to have shared behavior in patterns that single-inheritance subclassing cannot easily describe without a lot of duplicated code. - [ ] multiple_runtimes - [ ] Deployment changes - [ ] We support new query parameters to request lzx applications to be compiled to each runtime. The most interesting new query parameter is lzr=dhtml, which means, compile this application as dhtml. - [ ] We recommend tomcat 5.0.28 or 5.0.30. - [ ] We have not qualified against other servlet containers, but we have heard reports that Glassfish, JBoss, and Tomcat 5.5 all work. - [ ] We include an example of how to configure Tomcat to use gzip compression for serving up javascript; deployers will need to modify their servlet container's configuration to enable javascript compression. setting up your web server to gzip javascript and dhtml might be tricky. The tomcat that ships with this release is not configured to gzip javascript and dhtml. - [ ] Tools Changes - [ ] The tools we use to build, test, and analyze Open Laszlo have matured significantly with the 4.0 Beta 1 Release. We have changed to using Subversion from Perforce, for source control, in order to enable a more open development process. The build is now based on ant 1.6.5, rather than ant 1.5. We have created a new testing tool, lztest, for automated testing, without dropping lzunit, for application- and component-level testing. We have created a suite of benchmarks and benchmark analysis tools. We have created a tool for batch conversion of swf assets to png. - [ ] Changes visible to application builders - [ ] Debugging changes - [ ] The Debug class now supports new methods for formatting and outputting information: Debug.write, Debug.warn, Debug.info, Debug.format. - [ ] We have a brand new DHTML debugger. - [ ] Cool new auto-completion and history. (TODO ptw, please describe.) - [ ] Remote console debugger (TODO henry: can you describe what this does and why?) - [ ] Changes visible to Open Laszlo platform developers (building and developing the platform itself) - [ ] Build requirements - [ ] We support building under Java 1.4 and 1.5. We haven't tried 1.6. We recommend building with Java 1.5. - [ ] We now require Subversion 1.3 or later and ant 1.6.5 or later to build from source. See (wiki) - [ ] Asset conversion tool - [ ] pga: is the autopng tool available, usable, documented for application developers? - [ ] Documentation tools - [ ] The "doctools" have been rewritten in java and XSLT, replacing the python transformation pipeline in 3.4 and earlier. - [ ] New Test Systems - [ ] The test directory does not ship in Open Laszlo distributions, but it is available from subversion with svn.openlaszlo.org—test - [ ] lztest - [ ] lztest is a tool for testing the compiler and the LFC. Tests for it are not included in the distributions, but they are run for each build. lztest allows the same test code to be executed in swf, in dhtml, or from a command line by using the rhino runtime. The command line lztest facilitates automated build testing. - [ ] lzunit has been updated to work in 4.0B1 in the swf runtime and the dhtml runtime. - [ ] megatest - [ ] xmlunit and junit - [ ] JUnit tests exist for some of the compiler and some of the doctools. The doctools also use xmlunit for unit testing. Neither of these are visible to application developers. - [ ] performance analysis - [ ] The test directory for 4.0B1 includes suites of benchmarks to compare runtime performance in different client environments. These tests are in test/lfc/perf, available from subversion but not in the distributions. The performance suite is not yet supported for external users; we recommend using lps/utils/performance/measure.lzx. - [ ] Infrastructure changes (Laszlo Systems processes visible to the outside world) - [ ] Nightly builds - [ ] We run nightly builds of each active development branch, and deploy these builds to labs.openlaszlo.org. The nightly build of "legals" development is at labs.openlaszlo.org—legals-nightly Think of this as "tip-of-trunk" most recent builds. - [ ] Archived source for all 3.4.x builds and 4.0.x builds are tagged in Subversion as svn.openlaszlo.org—builds - [ ] Digging Deeper - [ ] Don't rely on implicit this. - [ ] A common but unreliable lzx practice is to relying on scope to map a variable name to an attribute of the current object. We discourage this practice; you should always explicitly say "this." on the left-hand side of any assignment. - [ ] The compiler can help you find code which reaches into the global scope; compile your application with `lzc -DwarnGlobalAssignments`, the compiler will print a warning for every global assignment that your program makes. If you intend to make a global assignment, you can silence the warning by explicitly using `global.attr =`. - [ ] 'implicit this' is a term we use to describe the behavior of free references in LZX methods and handlers. In LZX classes, the object bound to `this` is implicitly 'in scope' in all methods and handlers, as it is in Java, but not in Javascript. We added this feature to LZX because we felt it led to more intuitive and compact code. - [ ] What this means is that in any method or handler in a class you can refer to the class attributes by name directly, without the prefix `this.`. (Hence the nickname 'implicit this'.) A concrete example: return attr; return this.attr; The two methods will return the same value. NOTE: you should _not_ rely on implicit this on the left-hand side (LHS) of an assignment expression. Consider: attr = 7; this.attr = 7; Because `attr` is not initialized, the implicit method may not find `attr` in the instance and will set the global variable `attr` instead. You should _always_ explicitly use `this.` on the left-hand side of any assignment. - [ ] Developer console is still flash. - [ ] The oft-misinterpreted codename Legals will still be used. (link to cultural reference) - [ ] Tracked Bugs, Issues, Fixes, etc - [ ] known issues from ben - [ ] This distribution may contain unused resources. Expect the Beta 2 and Final release to be much smaller. - [ ] mkratt is building this section Copyright 2006 Laszlo Systems