Exploring Lift Derek Chen-Becker, Marius Danciu and Tyler Weir October 17, 2012 ii Copyright © 2008, 2009, 2010, 2011 by Derek Chen-Becker, Marius Danciu, David Pollak, and Tyler Weir. This work is licensed under the Creative Commons Attribution-No Derivative Works 3.0 Un- ported License. The home page for Exploring Lift is at http://exploring.liftweb.net. Here you can find up-to-date copies of the text, as well as links to the mailing list, issue tracking, and source code. Contents Contents iii List of Figures xi List of Listings xiii I The Basics1 1 Welcome to Lift! 3 1.1 Why Lift?............................................3 1.2 What You Should Know before Starting..........................5 1.3 Typographical Conventions.................................5 1.4 For More Information about Lift..............................5 1.5 Your First Lift Application..................................6 2 PocketChange 11 2.1 Defining the Model...................................... 12 2.2 Our First Template...................................... 14 2.3 Writing Snippets........................................ 15 2.4 A Little AJAX Spice...................................... 19 2.5 Conclusion........................................... 21 3 Lift Fundamentals 23 3.1 Entry into Lift......................................... 23 3.2 Bootstrap............................................ 24 3.2.1 Class Resolution................................... 24 3.3 A Note on Standard Imports................................. 25 3.4 Lift’s Main Objects...................................... 25 3.4.1 S object......................................... 25 3.4.2 SHtml......................................... 25 3.4.3 LiftRules........................................ 25 3.5 The Rendering Process.................................... 26 3.6 Notices, Warnings, and Error Messages.......................... 26 3.7 URL Rewriting........................................ 26 3.8 Custom Dispatch Functions................................. 28 3.9 HTTP Redirects........................................ 30 3.10 Cookies............................................. 31 iii iv CONTENTS 3.11 Session and Request State.................................. 31 3.12 Conclusion........................................... 34 4 Templates in Lift 35 4.1 Template XML......................................... 35 4.1.1 Locating Template XML............................... 36 4.1.2 Processing Template XML.............................. 36 4.2 Designer-Friendly Templates................................ 38 4.2.1 Determining the Content Element......................... 38 4.2.2 Invoking Snippets Via the Class Attribute..................... 39 4.2.3 Binding via CSS transforms............................. 39 4.3 HTML5 Support........................................ 39 4.4 Views.............................................. 39 4.5 Tags............................................... 41 4.5.1 a............................................ 42 4.5.2 bind.......................................... 42 4.5.3 bind-at......................................... 42 4.5.4 children........................................ 42 4.5.5 comet.......................................... 42 4.5.6 CSS........................................... 43 4.5.7 embed......................................... 43 4.5.8 form.......................................... 44 4.5.9 HTML5........................................ 44 4.5.10 ignore......................................... 44 4.5.11 lazy-load........................................ 44 4.5.12 loc........................................... 44 4.5.13 Menu.......................................... 44 4.5.14 Msgs.......................................... 44 4.5.15 SkipDocType..................................... 44 4.5.16 snippet......................................... 44 4.5.17 surround........................................ 44 4.5.18 tail........................................... 45 4.5.19 TestCond........................................ 45 4.5.20 with-param...................................... 45 4.5.21 with-resource-id................................... 45 4.5.22 VersionInfo...................................... 45 4.5.23 XmlGroup....................................... 45 4.6 Head and Tail Merge..................................... 45 4.7 Binding............................................. 46 5 Snippets 47 5.1 The Snippet Tag........................................ 47 5.2 Snippet Dispatch....................................... 48 5.2.1 Implicit Dispatch Via Reflection.......................... 48 5.2.2 Explicit Dispatch................................... 50 5.2.3 Per-request Remapping............................... 52 5.3 Snippet Methods....................................... 52 5.3.1 Binding Values in Snippets............................. 53 CONTENTS v 5.3.2 CSS Selector Transforms............................... 54 5.3.3 Stateless versus Stateful Snippets.......................... 58 5.3.4 Eager Evaluation................................... 61 5.4 Handling XHTML Attributes in Snippets......................... 62 5.4.1 Direct Manipulation in Code............................ 62 5.4.2 XHTML Attribute Pass-through.......................... 62 6 Forms in Lift 65 6.1 Form Fundamentals..................................... 65 6.2 Attributes for Form Elements................................ 67 6.3 An Overview of Form Elements............................... 67 6.3.1 checkbox........................................ 67 6.3.2 hidden......................................... 68 6.3.3 link........................................... 68 6.3.4 text and password.................................. 69 6.3.5 textarea........................................ 69 6.3.6 submit......................................... 70 6.3.7 multiselect....................................... 70 6.3.8 radio.......................................... 70 6.3.9 select.......................................... 71 6.3.10 selectObj........................................ 71 6.3.11 untrustedSelect.................................... 72 6.4 File Uploads.......................................... 72 7 SiteMap 75 7.1 Basic SiteMap Definition................................... 75 7.1.1 The Link Class.................................... 76 7.1.2 ExtLink......................................... 76 7.1.3 Creating Menu Entries................................ 76 7.1.4 Nested Menus..................................... 77 7.1.5 Setting the Global SiteMap............................. 78 7.2 Customizing Display..................................... 78 7.2.1 Hidden......................................... 78 7.2.2 Controlling the Menu Text.............................. 79 7.2.3 Using <lift:Menu>.................................. 79 7.3 Access Control......................................... 80 7.3.1 If............................................ 81 7.3.2 Unless......................................... 81 7.4 Page-Specific Rendering................................... 81 7.4.1 The Template Parameter............................... 81 7.4.2 The Snippet and LocSnippets Parameters..................... 82 7.4.3 Title........................................... 82 7.5 Miscellaneous Menu Functionality............................. 83 7.5.1 Test........................................... 83 7.5.2 LocGroup....................................... 83 7.6 Writing Your Own Loc.................................... 84 7.6.1 Corresponding Functions.............................. 85 7.6.2 Type Safe Parameters................................. 85 vi CONTENTS 7.6.3 Dynamically Adding Child Menus......................... 87 7.6.4 Binding Your Custom Loc.............................. 87 7.7 Conclusion........................................... 87 8 The Mapper and Record Frameworks 89 8.1 Introduction to Mapper and MetaMapper......................... 89 8.1.1 Adding Mapper to Your Project........................... 90 8.1.2 Setting Up the Database Connection........................ 90 8.1.3 Constructing a Mapper-enabled Class....................... 91 8.1.4 Object Relationships................................. 93 8.1.5 Indexing........................................ 95 8.1.6 Schema Mapping................................... 95 8.1.7 Persistence Operations on an Entity........................ 96 8.1.8 Querying for Entities................................. 98 8.1.9 Comparison QueryParams............................. 98 8.1.10 Control QueryParams................................ 101 8.1.11 Making Joins a Little Friendlier........................... 102 8.2 Utility Functionality..................................... 102 8.2.1 Display Generation.................................. 102 8.2.2 Form Generation................................... 103 8.2.3 Validation....................................... 104 8.2.4 CRUD Support.................................... 106 8.2.5 Lifecycle Callbacks.................................. 106 8.2.6 Base Field Types................................... 107 8.2.7 Defining Custom Field Types in Mapper..................... 109 8.2.8 ProtoUser and MegaProtoUser........................... 112 8.3 Advanced Features...................................... 113 8.3.1 Using Multiple Databases.............................. 113 8.3.2 Database Sharding.................................. 115 8.3.3 SQL-based Queries.................................. 115 8.4 Logging............................................. 117 8.5 Summary........................................... 117 II Advanced Topics 119 9