From 2bc9be676d37deb3d1a28932ad82027bde244214 Mon Sep 17 00:00:00 2001 From: Sibi Prabakaran Date: Fri, 20 Dec 2024 10:37:18 +0530 Subject: [PATCH] Finish till chapter 5 --- .../asciidoc/shakespearean-templates.asciidoc | 32 ++++++++-------- book/asciidoc/widgets.asciidoc | 38 +++++++++---------- 2 files changed, 34 insertions(+), 36 deletions(-) diff --git a/book/asciidoc/shakespearean-templates.asciidoc b/book/asciidoc/shakespearean-templates.asciidoc index 7771cb7d..a452462c 100644 --- a/book/asciidoc/shakespearean-templates.asciidoc +++ b/book/asciidoc/shakespearean-templates.asciidoc @@ -1,7 +1,7 @@ == Shakespearean Templates Yesod uses the Shakespearean family of template languages as its standard -approach to HTML, CSS and Javascript creation. This language family shares some +approach to HTML, CSS and JavaScript creation. This language family shares some common syntax, as well as overarching principles: * As little interference to the underlying language as possible, while @@ -28,7 +28,7 @@ Julius is for Javascript, and Cassius and Lucius are both for CSS. Hamlet and Cassius are both whitespace-sensitive formats, using indentation to denote nesting. By contrast, Lucius is a superset of CSS, keeping CSS's braces for denoting nesting. Julius is a simple passthrough language for producing -Javascript; the only added feature is variable interpolation. +JavaScript; the only added feature is variable interpolation. NOTE: Cassius is in fact just an alternate syntax for Lucius. They both use the same processing engine underneath, but Cassius files have indentation converted @@ -84,7 +84,7 @@ section.blog background-image: url(@{MyBackgroundR}) ---- -==== Julius (Javascript) +==== Julius (JavaScript) String interpolation works slightly differently in Julius. This is important from a security standpoint — all interpolated values are valid JSON by default @@ -121,7 +121,7 @@ name. It might look like this:

Hello, my name is #{name} ---- - + NOTE: +#{...}+ is how we do variable interpolation in Shakespeare. What should happen to +name+, and what should its datatype be? A naive approach @@ -189,11 +189,11 @@ _http://example.com/display/time_ displays the current time. And let's say we want to link from the homepage to the time. I can think of three different ways of constructing the URL: -. As a relative link: _../display/time_ +. As a relative link: _../display/time_ -. As an absolute link, without a domain: _/display/time_ +. As an absolute link, without a domain: _/display/time_ -. As an absolute link, with a domain: _http://example.com/display/time_ +. As an absolute link, with a domain: _http://example.com/display/time_ There are problems with each approach: the first will break if either URL changes. Also, it's not suitable for all use cases; RSS and Atom feeds, for @@ -230,7 +230,7 @@ renderMyRoute :: MyRoute -> Text renderMyRoute Home = "http://example.com/profile/home" renderMyRoute Time = "http://example.com/display/time" ---- - + [NOTE] ==== URL rendering functions are actually a bit more complicated than this. They @@ -273,7 +273,7 @@ this would translate roughly into the Haskell code: All Shakespearean languages share the same interpolation syntax, and are able to utilize type-safe URLs. They differ in the syntax specific for their target -language (HTML, CSS, or Javascript). Let's explore each language in turn. +language (HTML, CSS, or JavaScript). Let's explore each language in turn. ==== Hamlet Syntax @@ -635,7 +635,7 @@ $doctype 5

All done. ---- - + NOTE: There is an older and still supported syntax: three exclamation points (+!!!+). You may still see this in code out there. We have no plans to remove support for this, but in general find the +$doctype+ approach easier to read. @@ -653,7 +653,7 @@ in a few more features. * You can declare variables in your templates. * A set of CSS properties can be created as a mixin, and reused in multiple - declarations. + declarations. Starting with the second point: let's say you want to have some special styling for some tags within your +article+. In plain ol' CSS, you'd have to write: @@ -743,12 +743,12 @@ simple example: ==== Julius Syntax Julius is the simplest of the languages discussed here. In fact, some might -even say it's really just Javascript. Julius allows the three forms of +even say it's really just JavaScript. Julius allows the three forms of interpolation we've mentioned so far, and otherwise applies no transformations to your content. NOTE: If you use Julius with the scaffolded Yesod site, you may notice that -your Javascript is automatically minified. This is not a feature of Julius; +your JavaScript is automatically minified. This is not a feature of Julius; instead, Yesod uses the hjsmin package to minify Julius output. === Calling Shakespeare @@ -873,7 +873,7 @@ There are a few changes: * We use a different set of functions, prefixed with an "s". So the quasiquoter is +shamlet+ and the external file function is +shamletFile+. How we - pronounce those is still up for debate. + pronounce this is still up for debate. * No URL interpolation is allowed. Doing so will result in a compile-time error. @@ -920,7 +920,7 @@ $doctype 5

_{Apples count} ---- - + This kind of a template now needs some way to turn those values into HTML. So just like type-safe URLs, we pass in a render function. To represent this, we @@ -981,7 +981,7 @@ main = putStrLn $ renderHtml === Other Shakespeare -In addition to HTML, CSS and Javascript helpers, there is also some more +In addition to HTML, CSS and JavaScript helpers, there is also some more general-purpose Shakespeare available. shakespeare-text provides a simple way to create interpolated strings, much like people are accustomed to in scripting languages like Ruby and Python. This package's utility is definitely not diff --git a/book/asciidoc/widgets.asciidoc b/book/asciidoc/widgets.asciidoc index 997c2a76..808602dc 100644 --- a/book/asciidoc/widgets.asciidoc +++ b/book/asciidoc/widgets.asciidoc @@ -1,14 +1,14 @@ == Widgets One of the challenges in web development is that we have to coordinate three -different client-side technologies: HTML, CSS and Javascript. Worse still, we +different client-side technologies: HTML, CSS and JavaScript. Worse still, we have to place these components in different locations on the page: CSS in a -style tag in the head, Javascript in a script tag before the closing body tag, and HTML in the -body. And never mind if you want to put your CSS and Javascript in separate +style tag in the head, JavaScript in a script tag before the closing body tag, and HTML in the +body. And never mind if you want to put your CSS and JavaScript in separate files! In practice, this works out fairly nicely when building a single page, because -we can separate our structure (HTML), style (CSS) and logic (Javascript). But +we can separate our structure (HTML), style (CSS) and logic (JavaScript). But when we want to build modular pieces of code that can be easily composed, it can be a headache to coordinate all three pieces separately. Widgets are Yesod's solution to the problem. They also help with the issue of including @@ -118,7 +118,7 @@ page. In particular: * External stylesheets * External Javascript * CSS declarations -* Javascript code +* JavaScript code * Arbitrary ++ content * Arbitrary ++ content @@ -148,7 +148,7 @@ style code appear in a separate file. The scaffolded site provides this for you automatically. But what if you want to add some ++ tags, which need to appear in -the head? Or if you want some Javascript to appear in the body instead of the +the head? Or if you want some JavaScript to appear in the body instead of the head? For these purposes, Yesod provides two additional type classes: +ToWidgetHead+ and +ToWidgetBody+. These work exactly as they seem they should. One example use case for this is to have fine-grained control of where your +