Table of Contents. Preface... xi. 1. Introduction... 1 Type Safety 1 Concise Code 2 Performance 2 Modularity 3 A Solid Foundation 3

Transcription

1 Table of Contents Preface xi Part I. Basics 1. Introduction Type Safety 1 Concise Code 2 Performance 2 Modularity 3 A Solid Foundation 3 2. Haskell Terminology 5 Tools 6 Language Pragmas 7 Overloaded Strings 8 Type Families 9 Template Haskell 10 QuasiQuotes 12 API Documentation 12 Summary Basics Hello, World 13 Routing 14 Handler Function 16 The Foundation 16 iii

2 Running 17 Resources and Type-Safe URLs 17 Non-HTML Responses 19 The Scaffolded Site 19 Development Server 20 Summary Shakespearean Templates Synopsis 21 Hamlet (HTML) 22 Lucius (CSS) 22 Cassius (CSS) 22 Julius (JavaScript) 22 Types 23 Type-Safe URLs 24 Syntax 25 Hamlet Syntax 26 Lucius Syntax 31 Cassius Syntax 33 Julius Syntax 33 Calling Shakespeare 33 Alternative Hamlet Types 35 Other Shakespeare 37 General Recommendations Widgets Synopsis 39 What s in a Widget? 41 Constructing Widgets 42 Combining Widgets 43 Generating IDs 44 whamlet 44 Types 45 Using Widgets 46 Using Handler Functions 48 Summary The Yesod Typeclass Rendering and Parsing URLs 51 joinpath 53 cleanpath 53 defaultlayout 55 iv Table of Contents

3 getmessage 56 Custom Error Pages 57 External CSS and JavaScript 58 Smarter Static Files 59 Authentication/Authorization 60 Some Simple Settings 61 Summary Routing and Handlers Route Syntax 63 Pieces 64 Resource Name 66 Handler Specification 67 Dispatch 68 Return Type 68 Arguments 69 The Handler Functions 70 Application Information 71 Request Information 71 Short-Circuiting 71 Response Headers 72 I/O and Debugging 73 Query String and Hash Fragments 74 Summary Forms Synopsis 77 Kinds of Forms 79 Types 80 Converting 82 Creating AForms 82 Optional Fields 83 Validation 84 More Sophisticated Fields 85 Running Forms 86 i18n 87 Monadic Forms 87 Input Forms 90 Custom Fields 91 Values That Don t Come from the User 93 Summary 95 Table of Contents v

4 9. Sessions clientsession 97 Controlling Sessions 98 Session Operations 99 Messages 100 Ultimate Destination 102 Summary Persistent Synopsis 106 Solving the Boundary Issue 107 Types 108 Code Generation 109 PersistStore 112 Migrations 113 Uniqueness 116 Queries 117 Fetching by ID 117 Fetching by Unique Constraint 118 Select Functions 118 Manipulation 120 Insert 120 Update 122 Delete 123 Attributes 123 Relations 126 A Closer Look at Types 127 More Complicated, More Generic 128 Custom Fields 129 Persistent: Raw SQL 130 Integration with Yesod 132 More Complex SQL 134 Something Besides SQLite 134 Summary Deploying Your Web App Keter 137 Compiling 138 Files to Deploy 138 SSL and Static Files 139 Warp 139 Nginx Configuration 140 vi Table of Contents

5 Server Process 142 Nginx + FastCGI 142 Desktop 143 CGI on Apache 144 FastCGI on lighttpd 144 CGI on lighttpd 145 Part II. Advanced 12. RESTful Content Request Methods 149 Representations 150 JSON Conveniences 152 New Data Types 154 Other Request Headers 158 Summary Yesod s Monads Monad Transformers 159 The Three Transformers 160 Example: Database-Driven Navbar 161 Example: Request Information 163 Performance and Error Messages 165 Adding a New Monad Transformer 166 Summary Authentication and Authorization Overview 171 Authenticate Me Authorization 180 Summary Scaffolding and the Site Template How to Scaffold 183 File Structure 184 Cabal File 184 Routes and Entities 185 Foundation and Application Modules 185 Import 186 Handler Modules 187 Table of Contents vii

6 widgetfile 187 defaultlayout 188 Static Files 188 Summary Internationalization Synopsis 191 Overview 193 Message Files 194 Specifying Types 195 RenderMessage typeclass 195 Interpolation 196 Phrases, Not Words Creating a Subsite Hello, World Understanding a Request Handlers 203 Layers 204 Content 205 Short-Circuit Responses 206 Dispatch 206 towaiapp, towaiappplain, and warp 207 Generated Code 208 Complete Code 212 Summary SQL Joins Multiauthor Blog 215 Database Queries in Widgets 217 Joins 218 Esqueleto 219 Streaming 220 Summary Yesod for Haskellers Hello, Warp 225 What About Yesod? 230 The HandlerT Monad Transformer 232 (To)Content, (To)TypedContent 235 HasContentType and Representations 236 viii Table of Contents

7 Convenience warp Function 238 Writing Handlers 238 Getting Request Parameters 238 Short-Circuiting 239 Streaming 239 Dynamic Parameters 241 Routing with Template Haskell 242 LiteApp 244 Shakespeare 245 The URL Rendering Function 247 Widgets 247 Details We Won t Cover 248 Part III. Examples 21. Initializing Data in the Foundation Data Type Step 1: Define Your Foundation 252 Step 2: Use the Foundation 252 Step 3: Create the Foundation Value 252 Summary Blog: i18n, Authentication, Authorization, and Database Wiki: Markdown, Chat Subsite, Event Source Subsite: Data 265 Subsite: Handlers 266 Subsite: Widget 269 Master Site: Data 271 Master Site: Instances 272 Master Site: Wiki Handlers 273 Master Site: Running 274 Summary JSON Web Service Server 277 Client Case Study: Sphinx-Based Search Sphinx Setup 281 Basic Yesod Setup 282 Searching 285 Table of Contents ix

8 Streaming xmlpipe Output 288 Full Code Visitor Counter Single-Process Pub/Sub Foundation Data Type 299 Allocate a Job 300 Fork Our Background Job 300 View Progress 301 Complete Application Environment Variables for Configuration Route Attributes Alternative Approach: Hierarchical Routes 309 Part IV. Appendices A. monad-control B. Web Application Interface C. Settings Types D. http-conduit E. xml-conduit Index x Table of Contents

9 CHAPTER 1 Introduction Since web programming began, people have been trying to make the development process a more pleasant one. As a community, we have continually pushed new techniques in an effort to solve some of the lingering difficulties of security threats, the stateless nature of HTTP, the multiple languages (HTML, CSS, JavaScript) necessary to create a powerful web application, and more. Yesod attempts to ease the web development process by playing to the strengths of the Haskell programming language. Haskell s strong compile-time guarantees of correctness do not encompass only types; referential transparency ensures that we don t have any unintended side effects. Pattern matching on algebraic data types can help guarantee we ve accounted for every possible case. By building upon Haskell, entire classes of bugs disappear. Unfortunately, using Haskell isn t enough. The Web, by its very nature, is not type safe. Even the simplest case of distinguishing between an integer and a string is impossible: all data on the Web is transferred as raw bytes, evading our best efforts at type safety. Every app writer is left with the task of validating all input. I call this problem the boundary issue: however type safe your application is on the inside, every boundary with the outside world still needs to be sanitized. Type Safety This is where Yesod comes in. By using high-level declarative techniques, you can specify the exact input types you are expecting. And the process works the other way as well: by using type-safe URLs, you can make sure that the data you send out is also guaranteed to be well formed. The boundary issue is not just a problem when dealing with the client: the same problem exists when persisting and loading data. Once again, Yesod saves you on the 1

10 boundary by performing the marshaling of data for you. You can specify your entities in a high-level definition and remain blissfully ignorant of the details. Concise Code We all know that there is a lot of boilerplate coding involved in web applications. Wherever possible, Yesod tries to use Haskell s features to save your fingers the work: The forms library reduces the amount of code used for common cases by leveraging the Applicative typeclass. Routes are declared in a very terse format, without sacrificing type safety. Serializing your data to and from a database is handled automatically via code generation. In Yesod, we have two kinds of code generation. To get your project started, we provide a scaffolding tool to set up your file and folder structure. However, most code generation is done at compile time via metaprogramming. This means your generated code will never get stale, as a simple library upgrade will bring all your generated code up to date. But if you prefer to retain more control, and you want to know exactly what your code is doing, you can always run closer to the compiler and write all your code yourself. Performance Haskell s main compiler, the Glasgow Haskell Compiler (GHC), has amazing performance characteristics and is improving all the time. This choice of language by itself gives Yesod a large performance advantage over other offerings. But that s not enough: we need an architecture designed for performance. Our approach to templates is one example: by allowing HTML, CSS, and JavaScript to be analyzed at compile time, Yesod both avoids costly disk I/O at runtime and can optimize the rendering of this code. But the architectural decisions go deeper: we use advanced techniques such as conduits and builders in the underlying libraries to make sure our code runs in constant memory, without exhausting precious file handles and other resources. By offering high-level abstractions, you can get highly compressed and properly cached CSS and JavaScript. Yesod s flagship web server, Warp, is the fastest Haskell web server around. When these two pieces of technology are combined, it produces one of the fastest web application deployment solutions available. 2 Chapter 1: Introduction

11 Modularity Yesod has spawned the creation of dozens of packages, most of which are usable in a context outside of Yesod itself. One of the goals of the project is to contribute back to the community as much as possible; as such, even if you are not planning on using Yesod in your next project, a large portion of this book may still be relevant for your needs. Of course, these libraries have all been designed to integrate well together. Using the Yesod framework should give you a strong feeling of consistency throughout the various APIs. A Solid Foundation I remember once seeing a PHP framework advertising support for UTF-8. This struck me as surprising: you mean having UTF-8 support isn t automatic? In the Haskell world, issues like character encoding are already well addressed and fully supported. In fact, we usually have the opposite problem: there are a number of packages providing powerful and well-designed support for the problem. The Haskell community is constantly pushing the boundaries to find the cleanest, most efficient solutions for each challenge. The downside of such a powerful ecosystem is the complexity of choice. By using Yesod, you will already have most of the tools chosen for you, and you can be guaranteed they work together. And of course, you always have the option of pulling in your own solution. As a real-life example, Yesod and Hamlet (the default templating language) use blaze-builder for textual content generation. This choice was made because blazebuilder provides the fastest interface for generating UTF-8 data. Anyone who wants to use one of the other great libraries out there, such as text, should have no problem dropping it in. Modularity 3

12 Want to read more? You can buy this book at oreilly.com in print and ebook format. Buy 2 books, get the 3rd FREE! Use discount code: OPC10 All orders over $29.95 qualify for free shipping within the US. It s also available at your favorite book retailer, including the ibookstore, the Android Marketplace, and Amazon.com. Spreading the knowledge of innovators oreilly.com