docs: Update documentation (#405)

- Fix many broken links - Set correct code block syntax - Add locale param to select, timeZoneSelect, localeSelect and datePicker tags
grails · Dec 21, 2023 · ce92d7d · ce92d7d
1 parent 8d45ef0
commit ce92d7d
Show file tree

Hide file tree

Showing 94 changed files with 413 additions and 390 deletions.
diff --git a/build.gradle b/build.gradle
@@ -99,6 +99,17 @@ subprojects {
 apply from: "${commonBuild}/common-docs.gradle"
 apply from: "${commonBuild}/common-publishing.gradle"
 
+tasks.named('publishGuide') {
+    // Override value defined in grails/grails-common-build/common-docs.gradle
+    it.properties['commandLineRef'] = "https://docs.grails.org/$grailsVersion/ref/Command%20Line"
+    it.properties['controllersRef'] = "https://docs.grails.org/$grailsVersion/ref/Controllers"
+    it.properties['grailsapi']      = "https://docs.grails.org/$grailsVersion/api/"
+    it.properties['grailsdocs']     = "https://docs.grails.org/$grailsVersion/"
+    it.properties['groovyapi']      = "https://docs.groovy-lang.org/$groovyVersion/html/gapi/"
+    it.properties['groovyjdk']      = "https://docs.groovy-lang.org/$groovyVersion/html/groovy-jdk/"
+    it.properties['javase']         = 'https://docs.oracle.com/en/java/javase/11/docs/api/'
+}
+
 boolean isNonStable(String version) {
     version ==~ /(?i).+(-|\.?)(b|M|RC|Dev)\d?.*/ ||
             ['alpha', 'beta', 'milestone', 'rc', 'cr', 'm', 'preview', 'b', 'ea'].any { qualifier ->

diff --git a/src/main/docs/guide/GSPBasics.adoc b/src/main/docs/guide/GSPBasics.adoc
@@ -2,7 +2,7 @@ In the next view sections we'll go through the basics of GSP and what is availab
 
 GSP supports the usage of `<% %>` scriptlet blocks to embed Groovy code (again this is discouraged):
 
-[source,xml]
+[,xml]
 ----
 <html>
    <body>
@@ -13,7 +13,7 @@ GSP supports the usage of `<% %>` scriptlet blocks to embed Groovy code (again t
 
 You can also use the `<%= %>` syntax to output values:
 
-[source,xml]
+[,xml]
 ----
 <html>
    <body>
@@ -24,7 +24,7 @@ You can also use the `<%= %>` syntax to output values:
 
 GSP also supports JSP-style server-side comments (which are not rendered in the HTML response) as the following example demonstrates:
 
-[source,xml]
+[,xml]
 ----
 <html>
    <body>
@@ -34,4 +34,4 @@ GSP also supports JSP-style server-side comments (which are not rendered in the
 </html>
 ----
 
-WARNING: Embedding data received from user input has the risk of making your application vulnerable to an Cross Site Scripting (XSS) attack. Please read the documentation on link:security.html#xssPrevention[XSS prevention] for information on how to prevent XSS attacks.
+WARNING: Embedding data received from user input has the risk of making your application vulnerable to an Cross Site Scripting (XSS) attack. Please read the documentation on {grailsdocs}guide/security.html#xssPrevention[XSS prevention] for information on how to prevent XSS attacks.
diff --git a/src/main/docs/guide/GSPBasics/expressions.adoc b/src/main/docs/guide/GSPBasics/expressions.adoc
@@ -11,4 +11,4 @@ In GSP the `<%= %>` syntax introduced earlier is rarely used due to the support
 
 However, unlike JSP EL you can have any Groovy expression within the `${..}` block.
 
-WARNING: Embedding data received from user input has the risk of making your application vulnerable to an Cross Site Scripting (XSS) attack. Please read the documentation on link:security.html#xssPrevention[XSS prevention] for information on how to prevent XSS attacks.
+WARNING: Embedding data received from user input has the risk of making your application vulnerable to a Cross Site Scripting (XSS) attack. Please read the documentation on {grailsdocs}guide/security.html#xssPrevention[XSS prevention] for information on how to prevent XSS attacks.
diff --git a/src/main/docs/guide/GSPBasics/logicAndIteration.adoc b/src/main/docs/guide/GSPBasics/logicAndIteration.adoc
@@ -1,6 +1,6 @@
 Using the `<% %>` syntax you can embed loops and so on using this syntax:
 
-[source,xml]
+[,xml]
 ----
 <html>
    <body>
@@ -13,7 +13,7 @@ Using the `<% %>` syntax you can embed loops and so on using this syntax:
 
 As well as logical branching:
 
-[source,xml]
+[,xml]
 ----
 <html>
    <body>

diff --git a/src/main/docs/guide/GSPBasics/pageDirectives.adoc b/src/main/docs/guide/GSPBasics/pageDirectives.adoc
@@ -1,15 +1,15 @@
 GSP also supports a few JSP-style page directives.
 
-The import directive lets you import classes into the page. However, it is rarely needed due to Groovy's default imports and <<tags,GSP Tags>>:
+The import directive lets you import classes into the page. However, it is rarely needed due to Groovy's default imports and xref:tags.adoc[GSP Tags]:
 
-[source,xml]
+[,xml]
 ----
 <%@ page import="java.awt.*" %>
 ----
 
 GSP also supports the contentType directive:
 
-[source,xml]
+[,xml]
 ----
 <%@ page contentType="application/json" %>
 ----

diff --git a/src/main/docs/guide/GSPBasics/variablesAndScopes.adoc b/src/main/docs/guide/GSPBasics/variablesAndScopes.adoc
@@ -1,26 +1,26 @@
 Within the `<% %>` brackets you can declare variables:
 
-[source,xml]
+[,]
 ----
 <% now = new Date() %>
 ----
 
 and then access those variables later in the page:
 
-[source,xml]
+[,]
 ----
 <%=now%>
 ----
 
 Within the scope of a GSP there are a number of pre-defined variables, including:
 
-* `application` - The http://docs.oracle.com/javaee/1.4/api/javax/servlet/ServletContext.html[javax.servlet.ServletContext] instance
-* `applicationContext` The Spring http://docs.spring.io/spring/docs/current/javadoc-api/org/springframework/context/ApplicationContext.html[ApplicationContext] instance
-* `flash` - The link:{controllersRef}/flash.html[flash] object
-* `grailsApplication` - The http://docs.grails.org/latest/api/grails/core/GrailsApplication.html[GrailsApplication] instance
+* `application` - The {javaee}javax/servlet/ServletContext.html[javax.servlet.ServletContext] instance
+* `applicationContext` The Spring {springapi}org/springframework/context/ApplicationContext.html[ApplicationContext] instance
+* `flash` - The {controllersRef}/flash.html[flash] object
+* `grailsApplication` - The {grailsapi}grails/core/GrailsApplication.html[GrailsApplication] instance
 * `out` - The response writer for writing to the output stream
-* `params` - The link:{controllersRef}/params.html[params] object for retrieving request parameters
-* `request` - The http://docs.oracle.com/javaee/1.4/api/javax/servlet/http/HttpServletRequest.html[HttpServletRequest] instance
-* `response` - The http://docs.oracle.com/javaee/1.4/api/javax/servlet/http/HttpServletResponse.html[HttpServletResponse] instance
-* `session` - The http://docs.oracle.com/javaee/1.4/api/javax/servlet/http/HttpSession.html[HttpSession] instance
-* `webRequest` - The http://docs.grails.org/latest/api/org/grails/web/servlet/mvc/GrailsWebRequest.html[GrailsWebRequest] instance
+* `params` - The {controllersRef}/params.html[params] object for retrieving request parameters
+* `request` - The {javaee}javax/servlet/http/HttpServletRequest.html[HttpServletRequest] instance
+* `response` - The {javaee}javax/servlet/http/HttpServletResponse.html[HttpServletResponse] instance
+* `session` - The {javaee}javax/servlet/http/HttpSession.html[HttpSession] instance
+* `webRequest` - The {grailsapi}org/grails/web/servlet/mvc/GrailsWebRequest.html[GrailsWebRequest] instance
diff --git a/src/main/docs/guide/introduction.adoc b/src/main/docs/guide/introduction.adoc
@@ -6,22 +6,22 @@ GSP was previously part of Grails core, but since version 3.3 it is an independe
 .build.gradle
 ----
 dependencies {
-    ...
+    //...
     implementation "org.grails.plugins:gsp:{version}"
 }
 ----
 
-In addition for production compilation you should apply the `grails-gsp` Gradle plugin:
+In addition, for production compilation you should apply the `grails-gsp` Gradle plugin:
 
-[source,groovy,subs="attributes"]
+[source,groovy]
 .build.gradle
 ----
-apply plugin:"org.grails.grails-gsp"
+apply plugin: "org.grails.grails-gsp"
 ----
 
-GSPs themselves live in the `grails-app/views` directory and are typically rendered automatically (by convention) or with the link:{controllersRef}/render.html[render] method such as:
+GSPs themselves live in the `grails-app/views` directory and are typically rendered automatically (by convention) or with the {controllersRef}/render.html[render] method such as:
 
-[source,java]
+[source,groovy]
 ----
 render(view: "index")
 ----
@@ -32,7 +32,7 @@ NOTE: Although it is possible to have Groovy logic embedded in your GSP and doin
 
 A GSP typically has a "model" which is a set of variables that are used for view rendering. The model is passed to the GSP view from a controller. For example consider the following controller action:
 
-[source,java]
+[source,groovy]
 ----
 def show() {
     [book: Book.get(params.id)]
@@ -41,9 +41,9 @@ def show() {
 
 This action will look up a `Book` instance and create a model that contains a key called `book`. This key can then be referenced within the GSP view using the name `book`:
 
-[source,groovy]
+[source,gsp]
 ----
 ${book.title}
 ----
 
-WARNING: Embedding data received from user input has the risk of making your application vulnerable to an Cross Site Scripting (XSS) attack. Please read the documentation on link:https://docs.grails.org/latest/guide/security.html#xssPrevention[XSS prevention] for information on how to prevent XSS attacks.
+WARNING: Embedding data received from user input has the risk of making your application vulnerable to a Cross Site Scripting (XSS) attack. Please read the documentation on {grailsdocs}guide/security.html#xssPrevention[XSS prevention] for information on how to prevent XSS attacks.
diff --git a/src/main/docs/guide/layouts.adoc b/src/main/docs/guide/layouts.adoc
@@ -2,7 +2,7 @@
 ==== Creating Layouts
 
 
-Grails leverages http://sitemesh.org[Sitemesh], a decorator engine, to support view layouts. Layouts are located in the `grails-app/views/layouts` directory. A typical layout can be seen below:
+Grails leverages https://github.com/sitemesh[Sitemesh], a decorator engine, to support view layouts. Layouts are located in the `grails-app/views/layouts` directory. A typical layout can be seen below:
 
 [source,xml]
 ----
@@ -20,13 +20,13 @@ Grails leverages http://sitemesh.org[Sitemesh], a decorator engine, to support v
 </html>
 ----
 
-The key elements are the link:../ref/Tags/layoutHead.html[layoutHead], link:../ref/Tags/layoutTitle.html[layoutTitle] and link:../ref/Tags/layoutBody.html[layoutBody] tag invocations:
+The key elements are the xref:../ref/Tags/layoutHead.adoc[layoutHead], xref:../ref/Tags/layoutTitle.adoc[layoutTitle] and xref:../ref/Tags/layoutBody.adoc[layoutBody] tag invocations:
 
 * `layoutTitle` - outputs the target page's title
 * `layoutHead` - outputs the target page's head tag contents
 * `layoutBody` - outputs the target page's body tag contents
 
-The previous example also demonstrates the link:../ref/Tags/pageProperty.html[pageProperty] tag which can be used to inspect and return aspects of the target page.
+The previous example also demonstrates the xref:../ref/Tags/pageProperty.adoc[pageProperty] tag which can be used to inspect and return aspects of the target page.
 
 
 ==== Triggering Layouts
@@ -45,7 +45,7 @@ There are a few ways to trigger a layout. The simplest is to add a meta tag to t
 </html>
 ----
 
-In this case a layout called `grails-app/views/layouts/main.gsp` will be used to layout the page. If we were to use the layout from the previous section the output would resemble this:
+In this case a layout called `grails-app/views/layouts/main.gsp` will be used to lay out the page. If we were to use the layout from the previous section the output would resemble this:
 
 [source,xml]
 ----
@@ -68,23 +68,23 @@ In this case a layout called `grails-app/views/layouts/main.gsp` will be used to
 
 Another way to specify a layout is to specify the name of the layout by assigning a value to the "layout" property in a controller. For example, if you have a controller such as:
 
-[source,java]
+[source,groovy]
 ----
 class BookController {
     static layout = 'customer'
 
-    def list() { ... }
+    def list() { /*...*/ }
 }
 ----
 
-You can create a layout called `grails-app/views/layouts/customer.gsp` which will be applied to all views that the `BookController` delegates to.  The value of the "layout" property may contain a directory structure relative to the `grails-app/views/layouts/` directory.  For example:
+You can create a layout called `grails-app/views/layouts/customer.gsp` which will be applied to all views that the `BookController` delegates to.  The value of the `layout` property may contain a directory structure relative to the `grails-app/views/layouts/` directory.  For example:
 
-[source,java]
+[source,groovy]
 ----
 class BookController {
     static layout = 'custom/customer'
 
-    def list() { ... }
+    def list() { /*...*/ }
 }
 ----
 
@@ -96,26 +96,27 @@ Views rendered from that controller would be decorated with the `grails-app/view
 
 Another way to associate layouts is to use "layout by convention". For example, if you have this controller:
 
-[source,java]
+[source,groovy]
 ----
 class BookController {
-    def list() { ... }
+    def list() { /*...*/ }
 }
 ----
 
 You can create a layout called `grails-app/views/layouts/book.gsp`, which will be applied to all views that the `BookController` delegates to.
 
 Alternatively, you can create a layout called `grails-app/views/layouts/book/list.gsp` which will only be applied to the `list` action within the `BookController`.
 
-If you have both the above mentioned layouts in place the layout specific to the action will take precedence when the list action is executed.
+If you have both the above-mentioned layouts in place the layout specific to the action will take precedence when the list action is executed.
 
-If a layout may not be located using any of those conventions, the convention of last resort is to look for the application default layout which
-is `grails-app/views/layouts/application.gsp`.  The name of the application default layout may be changed by defining a property
-in `grails-app/conf/application.groovy` as follows:
+If a layout is not located using any of those conventions, the convention of last resort is to look for the application default layout which
+is `grails-app/views/layouts/application.gsp`.  The name of the application default layout may be changed by defining the property `grails.sitemesh.default.layout`
+in the application configuration as follows:
 
-[source,java]
+[source,yaml]
+.grails-app/conf/application.yml
 ----
-grails.sitemesh.default.layout = 'myLayoutName'
+grails.sitemesh.default.layout: myLayoutName
 ----
 
 With that property in place, the application default layout will be `grails-app/views/layouts/myLayoutName.gsp`.
@@ -124,15 +125,15 @@ With that property in place, the application default layout will be `grails-app/
 ==== Inline Layouts
 
 
-Grails' also supports Sitemesh's concept of inline layouts with the link:../ref/Tags/applyLayout.html[applyLayout] tag. This can be used to apply a layout to a template, URL or arbitrary section of content. This lets you even further modularize your view structure by "decorating" your template includes.
+Grails' also supports Sitemesh's concept of inline layouts with the xref:../ref/Tags/applyLayout.adoc[applyLayout] tag. This can be used to apply a layout to a template, URL or arbitrary section of content. This lets you even further modularize your view structure by "decorating" your template includes.
 
 Some examples of usage can be seen below:
 
-[source,xml]
+[,xml]
 ----
 <g:applyLayout name="myLayout" template="bookTemplate" collection="${books}" />
 
-<g:applyLayout name="myLayout" url="http://www.google.com" />
+<g:applyLayout name="myLayout" url="https://www.google.com" />
 
 <g:applyLayout name="myLayout">
 The content to apply a layout to
@@ -143,14 +144,14 @@ The content to apply a layout to
 ==== Server-Side Includes
 
 
-While the link:../ref/Tags/applyLayout.html[applyLayout] tag is useful for applying layouts to external content, if you simply want to include external content in the current page you use the link:../ref/Tags/include.html[include] tag:
+While the xref:../ref/Tags/applyLayout.adoc[applyLayout] tag is useful for applying layouts to external content, if you simply want to include external content in the current page you use the xref:../ref/Tags/include.adoc[include] tag:
 
 [source,xml]
 ----
 <g:include controller="book" action="list" />
 ----
 
-You can even combine the link:../ref/Tags/include.html[include] tag and the link:../ref/Tags/applyLayout.html[applyLayout] tag for added flexibility:
+You can even combine the xref:../ref/Tags/include.adoc[include] tag and the xref:../ref/Tags/applyLayout.adoc[applyLayout] tag for added flexibility:
 
 [source,xml]
 ----
@@ -159,11 +160,11 @@ You can even combine the link:../ref/Tags/include.html[include] tag and the link
 </g:applyLayout>
 ----
 
-Finally, you can also call the link:../ref/Tags/include.html[include] tag from a controller or tag library as a method:
+Finally, you can also call the xref:../ref/Tags/include.adoc[include] tag from a controller or tag library as a method:
 
-[source,java]
+[source,groovy]
 ----
 def content = include(controller:"book", action:"list")
 ----
 
-The resulting content will be provided via the return value of the link:../ref/Tags/include.html[include] tag.
+The resulting content will be provided via the return value of the xref:../ref/Tags/include.adoc[include] tag.
Original file line number	Diff line number	Diff line change
Expand Up		@@ -11,4 +11,4 @@ In GSP the `<%= %>` syntax introduced earlier is rarely used due to the support

		However, unlike JSP EL you can have any Groovy expression within the `${..}` block.

		WARNING: Embedding data received from user input has the risk of making your application vulnerable to an Cross Site Scripting (XSS) attack. Please read the documentation on link:security.html#xssPrevention[XSS prevention] for information on how to prevent XSS attacks.
		WARNING: Embedding data received from user input has the risk of making your application vulnerable to a Cross Site Scripting (XSS) attack. Please read the documentation on {grailsdocs}guide/security.html#xssPrevention[XSS prevention] for information on how to prevent XSS attacks.