Skip to content

Commit ce92d7d

Browse files
matreimatrei
authored
docs: Update documentation (#405)
- Fix many broken links - Set correct code block syntax - Add locale param to select, timeZoneSelect, localeSelect and datePicker tags
1 parent 8d45ef0 commit ce92d7d

File tree

94 files changed

+413
-390
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

94 files changed

+413
-390
lines changed

‎build.gradle‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -99,6 +99,17 @@ subprojects {
9999
apply from: "${commonBuild}/common-docs.gradle"
100100
apply from: "${commonBuild}/common-publishing.gradle"
101101

102+
tasks.named('publishGuide') {
103+
// Override value defined in grails/grails-common-build/common-docs.gradle
104+
it.properties['commandLineRef'] = "https://docs.grails.org/$grailsVersion/ref/Command%20Line"
105+
it.properties['controllersRef'] = "https://docs.grails.org/$grailsVersion/ref/Controllers"
106+
it.properties['grailsapi'] = "https://docs.grails.org/$grailsVersion/api/"
107+
it.properties['grailsdocs'] = "https://docs.grails.org/$grailsVersion/"
108+
it.properties['groovyapi'] = "https://docs.groovy-lang.org/$groovyVersion/html/gapi/"
109+
it.properties['groovyjdk'] = "https://docs.groovy-lang.org/$groovyVersion/html/groovy-jdk/"
110+
it.properties['javase'] = 'https://docs.oracle.com/en/java/javase/11/docs/api/'
111+
}
112+
102113
boolean isNonStable(String version) {
103114
version ==~ /(?i).+(-|\.?)(b|M|RC|Dev)\d?.*/ ||
104115
['alpha', 'beta', 'milestone', 'rc', 'cr', 'm', 'preview', 'b', 'ea'].any { qualifier ->

‎src/main/docs/guide/GSPBasics.adoc‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@ In the next view sections we'll go through the basics of GSP and what is availab
22

33
GSP supports the usage of `<% %>` scriptlet blocks to embed Groovy code (again this is discouraged):
44

5-
[source,xml]
5+
[,xml]
66
----
77
<html>
88
<body>
@@ -13,7 +13,7 @@ GSP supports the usage of `<% %>` scriptlet blocks to embed Groovy code (again t
1313

1414
You can also use the `<%= %>` syntax to output values:
1515

16-
[source,xml]
16+
[,xml]
1717
----
1818
<html>
1919
<body>
@@ -24,7 +24,7 @@ You can also use the `<%= %>` syntax to output values:
2424

2525
GSP also supports JSP-style server-side comments (which are not rendered in the HTML response) as the following example demonstrates:
2626

27-
[source,xml]
27+
[,xml]
2828
----
2929
<html>
3030
<body>
@@ -34,4 +34,4 @@ GSP also supports JSP-style server-side comments (which are not rendered in the
3434
</html>
3535
----
3636

37-
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.
37+
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.

‎src/main/docs/guide/GSPBasics/expressions.adoc‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,4 +11,4 @@ In GSP the `<%= %>` syntax introduced earlier is rarely used due to the support
1111

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

14-
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.
14+
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.

‎src/main/docs/guide/GSPBasics/logicAndIteration.adoc‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
Using the `<% %>` syntax you can embed loops and so on using this syntax:
22

3-
[source,xml]
3+
[,xml]
44
----
55
<html>
66
<body>
@@ -13,7 +13,7 @@ Using the `<% %>` syntax you can embed loops and so on using this syntax:
1313

1414
As well as logical branching:
1515

16-
[source,xml]
16+
[,xml]
1717
----
1818
<html>
1919
<body>

‎src/main/docs/guide/GSPBasics/pageDirectives.adoc‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,15 @@
11
GSP also supports a few JSP-style page directives.
22

3-
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>>:
3+
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]:
44

5-
[source,xml]
5+
[,xml]
66
----
77
<%@ page import="java.awt.*" %>
88
----
99
1010
GSP also supports the contentType directive:
1111
12-
[source,xml]
12+
[,xml]
1313
----
1414
<%@ page contentType="application/json" %>
1515
----

‎src/main/docs/guide/GSPBasics/variablesAndScopes.adoc‎

Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,26 +1,26 @@
11
Within the `<% %>` brackets you can declare variables:
22

3-
[source,xml]
3+
[,]
44
----
55
<% now = new Date() %>
66
----
77

88
and then access those variables later in the page:
99

10-
[source,xml]
10+
[,]
1111
----
1212
<%=now%>
1313
----
1414

1515
Within the scope of a GSP there are a number of pre-defined variables, including:
1616

17-
* `application` - The http://docs.oracle.com/javaee/1.4/api/javax/servlet/ServletContext.html[javax.servlet.ServletContext] instance
18-
* `applicationContext` The Spring http://docs.spring.io/spring/docs/current/javadoc-api/org/springframework/context/ApplicationContext.html[ApplicationContext] instance
19-
* `flash` - The link:{controllersRef}/flash.html[flash] object
20-
* `grailsApplication` - The http://docs.grails.org/latest/api/grails/core/GrailsApplication.html[GrailsApplication] instance
17+
* `application` - The {javaee}javax/servlet/ServletContext.html[javax.servlet.ServletContext] instance
18+
* `applicationContext` The Spring {springapi}org/springframework/context/ApplicationContext.html[ApplicationContext] instance
19+
* `flash` - The {controllersRef}/flash.html[flash] object
20+
* `grailsApplication` - The {grailsapi}grails/core/GrailsApplication.html[GrailsApplication] instance
2121
* `out` - The response writer for writing to the output stream
22-
* `params` - The link:{controllersRef}/params.html[params] object for retrieving request parameters
23-
* `request` - The http://docs.oracle.com/javaee/1.4/api/javax/servlet/http/HttpServletRequest.html[HttpServletRequest] instance
24-
* `response` - The http://docs.oracle.com/javaee/1.4/api/javax/servlet/http/HttpServletResponse.html[HttpServletResponse] instance
25-
* `session` - The http://docs.oracle.com/javaee/1.4/api/javax/servlet/http/HttpSession.html[HttpSession] instance
26-
* `webRequest` - The http://docs.grails.org/latest/api/org/grails/web/servlet/mvc/GrailsWebRequest.html[GrailsWebRequest] instance
22+
* `params` - The {controllersRef}/params.html[params] object for retrieving request parameters
23+
* `request` - The {javaee}javax/servlet/http/HttpServletRequest.html[HttpServletRequest] instance
24+
* `response` - The {javaee}javax/servlet/http/HttpServletResponse.html[HttpServletResponse] instance
25+
* `session` - The {javaee}javax/servlet/http/HttpSession.html[HttpSession] instance
26+
* `webRequest` - The {grailsapi}org/grails/web/servlet/mvc/GrailsWebRequest.html[GrailsWebRequest] instance

‎src/main/docs/guide/introduction.adoc‎

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -6,22 +6,22 @@ GSP was previously part of Grails core, but since version 3.3 it is an independe
66
.build.gradle
77
----
88
dependencies {
9-
...
9+
//...
1010
implementation "org.grails.plugins:gsp:{version}"
1111
}
1212
----
1313

14-
In addition for production compilation you should apply the `grails-gsp` Gradle plugin:
14+
In addition, for production compilation you should apply the `grails-gsp` Gradle plugin:
1515

16-
[source,groovy,subs="attributes"]
16+
[source,groovy]
1717
.build.gradle
1818
----
19-
apply plugin:"org.grails.grails-gsp"
19+
apply plugin: "org.grails.grails-gsp"
2020
----
2121

22-
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:
22+
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:
2323

24-
[source,java]
24+
[source,groovy]
2525
----
2626
render(view: "index")
2727
----
@@ -32,7 +32,7 @@ NOTE: Although it is possible to have Groovy logic embedded in your GSP and doin
3232

3333
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:
3434

35-
[source,java]
35+
[source,groovy]
3636
----
3737
def show() {
3838
[book: Book.get(params.id)]
@@ -41,9 +41,9 @@ def show() {
4141

4242
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`:
4343

44-
[source,groovy]
44+
[source,gsp]
4545
----
4646
${book.title}
4747
----
4848

49-
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.
49+
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.

‎src/main/docs/guide/layouts.adoc‎

Lines changed: 26 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
==== Creating Layouts
33

44

5-
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:
5+
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:
66

77
[source,xml]
88
----
@@ -20,13 +20,13 @@ Grails leverages http://sitemesh.org[Sitemesh], a decorator engine, to support v
2020
</html>
2121
----
2222

23-
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:
23+
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:
2424

2525
* `layoutTitle` - outputs the target page's title
2626
* `layoutHead` - outputs the target page's head tag contents
2727
* `layoutBody` - outputs the target page's body tag contents
2828

29-
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.
29+
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.
3030

3131

3232
==== 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
4545
</html>
4646
----
4747

48-
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:
48+
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:
4949

5050
[source,xml]
5151
----
@@ -68,23 +68,23 @@ In this case a layout called `grails-app/views/layouts/main.gsp` will be used to
6868

6969
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:
7070

71-
[source,java]
71+
[source,groovy]
7272
----
7373
class BookController {
7474
static layout = 'customer'
7575
76-
def list() { ... }
76+
def list() { /*...*/ }
7777
}
7878
----
7979

80-
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:
80+
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:
8181

82-
[source,java]
82+
[source,groovy]
8383
----
8484
class BookController {
8585
static layout = 'custom/customer'
8686
87-
def list() { ... }
87+
def list() { /*...*/ }
8888
}
8989
----
9090

@@ -96,26 +96,27 @@ Views rendered from that controller would be decorated with the `grails-app/view
9696

9797
Another way to associate layouts is to use "layout by convention". For example, if you have this controller:
9898

99-
[source,java]
99+
[source,groovy]
100100
----
101101
class BookController {
102-
def list() { ... }
102+
def list() { /*...*/ }
103103
}
104104
----
105105

106106
You can create a layout called `grails-app/views/layouts/book.gsp`, which will be applied to all views that the `BookController` delegates to.
107107

108108
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`.
109109

110-
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.
110+
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.
111111

112-
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
113-
is `grails-app/views/layouts/application.gsp`. The name of the application default layout may be changed by defining a property
114-
in `grails-app/conf/application.groovy` as follows:
112+
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
113+
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`
114+
in the application configuration as follows:
115115

116-
[source,java]
116+
[source,yaml]
117+
.grails-app/conf/application.yml
117118
----
118-
grails.sitemesh.default.layout = 'myLayoutName'
119+
grails.sitemesh.default.layout: myLayoutName
119120
----
120121

121122
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/
124125
==== Inline Layouts
125126

126127

127-
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.
128+
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.
128129

129130
Some examples of usage can be seen below:
130131

131-
[source,xml]
132+
[,xml]
132133
----
133134
<g:applyLayout name="myLayout" template="bookTemplate" collection="${books}" />
134135
135-
<g:applyLayout name="myLayout" url="http://www.google.com" />
136+
<g:applyLayout name="myLayout" url="https://www.google.com" />
136137
137138
<g:applyLayout name="myLayout">
138139
The content to apply a layout to
@@ -143,14 +144,14 @@ The content to apply a layout to
143144
==== Server-Side Includes
144145

145146

146-
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:
147+
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:
147148

148149
[source,xml]
149150
----
150151
<g:include controller="book" action="list" />
151152
----
152153

153-
You can even combine the link:../ref/Tags/include.html[include] tag and the link:../ref/Tags/applyLayout.html[applyLayout] tag for added flexibility:
154+
You can even combine the xref:../ref/Tags/include.adoc[include] tag and the xref:../ref/Tags/applyLayout.adoc[applyLayout] tag for added flexibility:
154155

155156
[source,xml]
156157
----
@@ -159,11 +160,11 @@ You can even combine the link:../ref/Tags/include.html[include] tag and the link
159160
</g:applyLayout>
160161
----
161162

162-
Finally, you can also call the link:../ref/Tags/include.html[include] tag from a controller or tag library as a method:
163+
Finally, you can also call the xref:../ref/Tags/include.adoc[include] tag from a controller or tag library as a method:
163164

164-
[source,java]
165+
[source,groovy]
165166
----
166167
def content = include(controller:"book", action:"list")
167168
----
168169

169-
The resulting content will be provided via the return value of the link:../ref/Tags/include.html[include] tag.
170+
The resulting content will be provided via the return value of the xref:../ref/Tags/include.adoc[include] tag.

0 commit comments

Comments
 (0)