book.txt

We chose a license: http://creativecommons.org/license/results-one?license_code=by-nd
License:
This work is licensed under the Creative Commons Attribution-No Derivative Works 3.0 Unported License. 
To view a copy of this license, visit http://creativecommons.org/licenses/by-nd/3.0/ or send a letter to 
Creative Commons, 171 Second Street, Suite 300, San Francisco, California, 94105, USA.



[Decision] Pick an application to build from scratch. 
(Let's see if we can extend these hit all of the sections -Ty)
Here are a few ideas
- Maybe - ToDo tracker (extend to group todo tracker) 
  - Add an API
  - Comet feature, add group editing?
  - AJAX - Fades!!! Moar FAdez!!
  - OpenID works
  - search works
  - tags work

- Maybe - build PocketChangeApp (my simple expense tracker, we can build this and put it up as pocketchangeapp.com, nice -Ty)
  - API would actually be awesome for this
  - Comet would be hard unless you could have like a joint account - this would be awesometown
  - Search works
  - OpenID works
  - tags work

- Maybe - Build LuxTape, a lift implementation of OpenTape
  - trendy!
  - legal issues?
  - comet would make sense
  - 


[Decision] Should we compare and contrast with other frameworks? I don't know many others --Tyler

- Not sure on this. I've done a lot of Struts 1 and some Tapestry in
  the past, but it's getting a little rusty and both frameworks have
  recently added and refined a lot. I have a feeling that comparisons
  are better left to the bloggers...

1. Include a "Lift quick reference card":  (love this idea -Ty)


-------------------- 
IMHO we should start with an introduction that gives a brief overview
of what Lift is trying to solve, how it works and why it does it
well. The first half would explain some basics about it (built on
Scala, incredible template support, clean separation of V and C), and
then the second half would walk the user through running the HelloLift
example just to get something going out of the box. From my
understanding at this point that would involve just three things:
installing Java (if required), installing Maven2, and then downloading
and running the HelloLift project zip. Of those three, I think
installing Maven is probably the most complex - Derek

So you see 2 distinct Sections: Generalized info and intro, and
getting into and building an app? Sounds good to me. -Tyler

Next question is how much should assume about Scala knowledge? - Derek

I think if we assume none, we'll never finish the book.  I would prefer to target
those that are comfortable with Scala.  -Ty
--------------------

===============================
BOOK
===============================

====== Intro Section ======

1. Introduction
  * Welcome to lift
    * What we'd like you to get out of this book
      * By the end of the book you should be able to create and extend any web application you can think of
    * Why another framework?
      * Too much boilerplate in other frameworks (Struts, we're talking about you)
      * Exposure of programming logic in templates makes things difficult (JSP, etc)
      * Scala has higher efficiency in terms of LoC per function point
      * Powerful AJAX, COMET and JS support
    * What we expect you to already know
      * Scala
      * HTTP protocol
      * HTML
      * Javascript 
      * CSS
  * What is lift?
    * Fast, flexible template-based web framework built on Scala
      * Full-featured template system
      * Clean separation of M,V and C
      * Powerful Web 2.0 (AJAX, COMET) support baked in
      * Thriving community of developers
    * Brief overview of Scala
      * OO/FP Hybird
      * Compiles to JVM Bytecode
      * Made by the good people who brought us generics
      * You get a new powerful language with access to all of Java's libs
  * Let's try out HelloLift
    * Prerequisites
      * Java 1.5 or newer (Scala is not required directly since Maven will pull it down)
      * Maven 2 - include a very brief synopsis on Maven. Anything more detailed should point to the Maven site or go in an appendix
      * Some sort of programming editor is recommended: mention emacs, Eclipse, NetBeans, JEdit, etc.
    * Download the HelloLift project and unzip it
    * "mvn jetty:run"
    * Profit! - let's hope :)
    * Cursory examination of:
      * Index template (shows surround and snippet)
      * Default template
      * Hello snippet
    * Optionally install the JavaRebel Scala plugin from zeroturnaround

2. Getting to know Maven and Project layout (based on HelloLift example)

- I think this should be a small, but self-contained section with
  enough info so that someone who wanted to do "standard" things with
  Maven wouldn't need to go digging around on the site. In other
  words, enough info on maven in this book to handle all of the
  examples we use in the book.

  * What is maven
    * Comprehensive project and build management
    * Structured project layout (conventions)
    * Dependency management
    * Automated testing and packaging
    * Automated reporting
  * Archetypes: project "templates"
  * Directory layout
    * Scala-specific stuff
    * web content
    * resources
  * Introducing the POM
    * Project info (author, date, version, etc)
    * Repo definitions
    * Dependencies
    * Special build targets

====== General Topics ======

3. Lift Architecture in general
  * Everything handled by LiftFilter
    * Show example config in web.xml
    * Handling in LiftFilter allows fall-through to default handlers for things that Lift doesn't handle (Static content, primarily)
  * Rendering pipeline (This can be high-level right now, with links to detailed info in the advanced section - Derek)
    * Dispatch to proper code
      * dispatch methods in effect?
      * rewrite methods in effect?
      * SiteMap matching and access control
      * template or view matched?
        * recursive processing of template and any snippets contained therein
	* direct processing of view
      * Error handling
    * List of tags that are handled by Lift (stolen from http://liftweb.net/index.php/LiftTags, not sure how up-to-date this is)
      * surround
      * embed
      * comet
      * ignore
      * snippet (and, the alternative lift:<class>.<method>)
      * additional attribute handling in tags (via S.attr)

4. A detailed look at lift user components
  * SiteMap
    * Performs two primary duties: generates the menu for your site (customizable) and performs per-page access control
    * Cover Menu, Loc objects to define paths and superpaths (my term for paths that match anything under them)
    * Support for grouping via LocGroup object
    * <lift:Menu> snippets:
      * <lift:Menu.group group="...">content</...> (http://groups.google.com/group/liftweb/browse_thread/thread/5f18df13cd735c51?hl=en#)
      * <lift:Menu.item name="..."> binding to Loc("...",) (http://groups.google.com/group/liftweb/browse_thread/thread/dbdf6a17b9704c99/30f5168e87161f74?hl=en&lnk=gst&q=new+sitemap%2Fmenu+features)
      * Customizing content and attributes on menus
    * Additional attributes
      * If
      * Unless
      * Test
      * Title
    * Finding the current Loc for a page (RequestState.location)
  * Templates
    * Static xml that may embed or surround other templates, and may embed snippets (reference tag list)
    * well-formed XML
    * Special template-hidden directory not directly accessible
    * Use of prefixed elements to assist with binding in snippets
    * Re-cover how templates are located/dispatched
  * Snippets
    * Chunks of code that generate pieces of a final output page. May themselves generate template code that is interpreted
    * Generic Scala classes (stateless)
    * How to deal with state in snippets
      * RequestVars
      * SessionVars
      * StatefulSnippets
    * Using Helpers.bind. In particular, cover view vs. forms usage
    * Using Helpers.chooseTemplate for nested templates
  * Views
    * Chunks of code intended to generate a complete page
    * Can be shoehorned to process template code via processSurroundAndInclude
    * Re-cover how views are located/dispatched
      * Path-based (/my/view)
      * addDispatchBefore/After
  * What are the use cases for snippets vs. views?

5. Intro to the Mapper package
  * This may be Mapper, or it may be Record depending on whether Record makes the 1.0 cut
  * If it's Mapper, then blurb about all the Mapped* fields

6. AJAX and COMET
  * What is COMET? 
    * Why is Comet Awesome? [example]
      * Push to the browser
        * [Example] following a LiveBlog of a keynote presentation, elememts are pushed to your browser
    * Here's a super simple example - http://wiki.liftweb.net/index.php/CometActor
    * Method for async updates pushed *from server to client*
    * Connection is kept open
      * Streaming
      * Long polling
    * Scalability issues
    * Using COMET in Lift
      * CometActor 
      * Mine Jorge's blog post: http://scala-blogs.org/2007/12/dynamic-web-applications-with-lift-and.html
    * Go through Dynamic chat room example
  * What is AJAX?
    * why is AJAX awesome? [example]
    * Method for async updates pulled from the client without a full page reload
    * Relies heavily on javascript and XML
    * Javascript client-side events (button push, timer, etc) trigger requests "behind the scenes" 
    * Web 2.0 built on this
    * Using AJAX in Lift
      * Allows you to bind Javascript events (AJAX) to form elements, links, etc
    * Go through example HelloDarwin AJAX example

7. Deployment
  - Ask the list what they are deploying with. Generally it shouldn't
    be an issue where they deploy since Lift is essentially
    self-contained. We can go into specifics for special cases, I
    suppose
    -!! jetty is required for continuations

  * Basic deployment via Jetty
    * Brief overview of Jetty
      * Capabilities
      * Configuration
      * SSL
    * How jetty is configured in maven for testing
      * Changing the default port (8080)
    * Tips and tricks
  * Deployment in Tomcat
    * Packaging options (pom dependency scope)
  * Deployment in JBoss
  * Deployment in GlassFish
  * putting nginx out front???

====== Advanced Topics ======

8. Detailed request/response handling info (should cover how Actors are used, too)
  1. Request hits LiftFilter
  2. LiftFilter executes each item in LiftRules.early. This would allow you to do advance processing of the HttpRequest
  3. Rewrites occur per the LiftRules.rewriteTable (set up via LiftRules.addRewriteBefore/After)
  4. LiftFilter determines whether the request should be handled by Lift or if it should be chained. If the processing fails it's automatically chained
  5. Processing takes place via the LiftFilter's internal LiftServlet instance
  6. If Lift is running in Jetty, any continuations are invoked (explain a little about Jetty continuations here...). If continuation exists and returns a response, return
  7. LiftServlet checks LiftRules.statelessDispatchTable and returns if matched (what is this for?)
  8. LiftServlet checks LiftRules.dispatchTable (set up via LiftRules.addDispatchBefore/After) and if dispatches match it dispatches there and returns the result
    * detail dispatch handling
  9. LiftServlet then checks to see if the request starts with LiftRules.cometPath (default "comet_request") and if so, handles the request as a COMET request
    * detail COMET handling path
  10. LiftServlet then checks to see if the request starts with LiftRules.ajaxPath (default "ajax_request") and if so, handles the request as an AJAX request
    * detail AJAX handling
  11. If nothing else has occurred, do normal template processing at this point
    1. Lookup template based on path
    2. Process template recursively (surround, include, etc)
  * Additional topics
    * S.addAround and LoanWrapper
    * How S.attr works in conjunction with XML attributes on snippets, etc and with Rewriting

9. URL Rewriting
  * What is URL rewriting
  * Using LiftRules.addRewriteBefore.After
  * What constitutes a rewrite function?
  * Using the params Map to pass parts of the path back into your code via S.param
  * Example: user-friendly URLs

10. JSON handling
  * What is JSON?
    * Why is JSON awesome?  [example]
    * Technically, just a data format for Javascript (http://www.json.org/)
    * Used as an RPC transfer format
    * Well-suited to AJAX because it's essentially javascript
  * How does Lift support JSON?
    * JsonHandler allows simple wrapping and processing of JSON (AJAX) forms
    * JsonCmd allows matching of submitted JSON
  * Go through example JSON/AJAX submission form. Maybe it would be best to make
    it an extension of one of the other examples?

11. JsCommands
  * Integrated javascript handling without hard-coding it in templates
  * jQuery intro
    * Utility library that makes IE6 less ugly ;)
    * Powerful support for dynamic attributing of elements
    * Based on CSS selectors
  * Talk about Marius JS abstraction

12. AJAX and COMET in depth
- this is probably the place for the Spreadsheet example
- talk about design "patterns" ex. the proper TagCloud example

13. JPA Integration
  * What is JPA?
    * Part of EJB3 spec
    * Evolution of container-managed persistence
    * Simplified model (a lot less XML)
    * Heavy use of annotations, although you can define/override via XML descriptors if you want
    * Available in container and outside of container (Hibernate EM, JPOX, etc)
  * Why use JPA when we have mapper?
    * Usable outside of Lift
    * Easily accessible from Java and Scala
    * Legacy models
    * More flexibility w/large schemas
    * Performance/Caching
  * Intro to JPA
    * JPA archetype in Maven
    * Annotations on Scala classes
    * Using orm.xml to override and define
  * Getting a per-session entity manager
    * RequestVar lifecycle
    * In a container (JTA)
    * User-managed transactions
  * ScalaEntityManager and ScalaQuery
    * Provide Scala-esque access to all EM methods (List vs java.util.List,etc)
    * Implicit defs for conversion from java.util.{Set,List} to Scala counterparts
  * Example app (Library catalog)

14. Using Scala Actors
- this is a broad topic, ask the committor list for opinions


====== Advanced Examples and HOWTOs ======

15. OpenID Integration

16. Lucene/Compass Integration

17. Tagging support
- I have lots of sample code for this

18. Lift Widgets
- let's build one together, Marius' Sparklines

19. Web Services
- Building an API
- REST
====== Appendices ======

A. Lift message handling
- What happens now
- How to Fade them web2.0 stylee!

B. Helpers methods, in particular Can/Empty/Full
  * Can/Empty/Full/Failure
    * Richer alternative to Scala's Option/None/Some
    * openOr examples
    * map examples
    * pass - function with side effects
    * run - function with default
    * Using and/or chaining Failure objects
  * Time/date formatting
  * String formatting and utilities
  * Encryption and hashing
  * List helpers
  * Binding
  * URL modification
  * IO Helpers
  * tryo wrappers

C. I18N and L10N
  * S.?(String)
  * lift:loc tag
  * Proper placement of language resources

D. Logging
  * Configuring built-in log4j
  * Using slf4j instead
  * Query Logger
  * Maybe some recommendations?

E. Mailer
  * Configuring the mailer lib
  * Sending email
  * System.properties

F. Dev tips
  * .props for Dev and Prod
  * JavaRebel
  
XX. Lift Quick Reference card (inside of back cover and facing page)
  * All of the lift template tags
  * Brief overview of the render flow (with cross-refs)



====== Attempts at content ======

Chapter 1: Introduction

* Welcome to Lift!

Welcome to <title>. We've created this book to educate you about Lift,
which we think is a great framework for building compelling web
applications. Lift is designed to make powerful techniques easily
accessible, while keeping the overall framework simple and flexible.
Our goal for this book is that by the end, you'll be able to create
and extend any web application you can think of.

For those of you have experience with other web frameworks such as
Struts, Tapestry, Rails or PHP, you must be asking yourself "Why
another framework? Does Lift really solve problems any differently or
more effectively than the ones I've used before?" Based on our
experience (and of others in the Lift community), the answer is an
emphatic "Yes!" Lift has cherry-picked the best ideas from a number of
other frameworks, while creating some novel ideas of its own. It's
this combination of solid foundation and new techniques that makes
Lift so powerful.

A key aspect of Lift's development is that it's been able to avoid the
mistakes made in the past by other frameworks. A growing trend in web
(and other) frameworks is to reduce or eliminate boilerplate
configuration and code. Lift has sensible defaults for everything,
while making it easy to customize precisely what you need to; no more
and no less. Gone are the days of XML file after XML file providing
*basic configuration* for your application. Instead, a basic Lift app
only requires that you add the LiftFilter to your web.xml and add one
or more lines telling Lift what package your classes sit in []. Lift is
intended to work out of the box, and to make you as efficient and
productive as possible.

One of the key strengths of Lift (IOHO) is the clean separation of
content and logic, based on the bedrock concept of the
Model-View-Controller pattern []. One of the original Java web
application technologies (still used today) is JSP, or Java Server
Pages []. JSP allows you to mix HTML and Java code directly within the
page. While this may have seemed like a good idea at the start, it has
proven to be painful in practice. Putting code in your presentation
layer makes it more difficult to debug and understand what is going on
within a page, and makes it more difficult for the people writing the
HTML portion because the contents aren't valid HTML. While many modern
programming and HTML editors have been modified to accomodate this
mess, proper syntax highlighting and validation don't make up for the
fact that you still have to switch back and forth between one or more
files to follow the page flow. Lift takes the approach that there
should be no code in the presentation layer, but that the presentation
layer has to be flexible enough to accomodate any conceivable uses. To
that end, Lift uses a powerful templating system, a la Wicket[], to
bind user-generated data into the presentation layer. Lift's
templating is built on the XML processing capabilities of the Scala
Language (which we'll cover in more detail later), and allows things
such as nested templates, simple injection of user-generated content,
and advanced data binding capabilities. For those coming from JSP,
Lift's advanced template and XML processing allows you to essentially
write custom tag libraries at a fraction of the cost in time and effort.

* Expections for the reader
We are going to focus on Lift in the book, so we expect that you're comfortable with:
- Scala - http://www.scala-lang.org
- The HTTP Protocol - http://www.ietf.org/rfc/rfc2616.txt
- HTML - http://www.w3.org/MarkUp/Guide/
- JavaScript - http://en.wikipedia.org/wiki/JavaScript, and 
- CSS - http://en.wikipedia.org/wiki/Cascading_Style_Sheets

* What is Lift?
Lift is a fast, flexible template-based web framework built on Scala.  Some of it's notable features are a full-featured template system, a clean separation of Model, View and Controller, powerful AJAX and COMET support baked in and there is also a thriving community of developers.

* Brief overview of Scala
From Scala-lang.org: http://www.scala-lang.org/node/25
[quote]Scala is a general purpose programming language designed to express common programming patterns in a concise, elegant, and type-safe way. It smoothly integrates features of object-oriented and functional languages. It is also fully interoperable with Java.[/quote]
 Scala code Compiles to JVM Bytecode so you get a new powerful language with access to all of Java's libraries.
 [todo] discuss some of the Scala features we use, pattern matching and traits, actors