jdaugherty commented on code in PR #15585: URL: https://github.com/apache/grails-core/pull/15585#discussion_r3150885665
########## grails-doc/src/en/guide/theWebLayer/gsp/layouts.adoc: ########## @@ -20,7 +20,9 @@ under the License. ==== Creating Layouts -This product includes software developed by the OpenSymphony Group (https://github.com/sitemesh). The Sitemesh framework is used to provide 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 uses the https://github.com/sitemesh/sitemesh3[SiteMesh 3] framework as its decorator engine to support view layouts. In Grails 7.2 and later, decoration is performed by a Spring MVC `ViewResolver` rather than a Servlet filter, which improves performance and enables correct support for async controller return types. Review Comment: "This product includes software developed by the OpenSymphony Group (https://github.com/sitemesh)." is a requirement of the sitemesh 2 license. Unless we're going to drop sitemesh 2 in Grails 7.2, we have to leave that line to be compatible with the license. Note: we can move it to a subsection explaining that this is only if grails-layout is used. ########## grails-doc/src/en/guide/upgrading/upgrading72x.adoc: ########## @@ -0,0 +1,96 @@ +//// +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + +https://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied. See the License for the +specific language governing permissions and limitations +under the License. +//// + +=== Upgrade Instructions for Grails 7.1 to Grails 7.2 + +This guide outlines the changes introduced in Grails 7.2 and the steps required to upgrade your application. + +==== 1. SiteMesh 3 Filter-less Integration + +Grails 7.2 upgrades the SiteMesh 3 integration to a *filter-less* architecture. Decoration is now performed by a Spring MVC `ViewResolver` rather than a Servlet filter. This change improves performance, eliminates ordering issues with other filters, and correctly supports async controller return types (`Callable`, `@Async`). + +===== What Changed + +* The `SiteMeshFilter` servlet filter is no longer active. A `NoopSitemeshFilter` placeholder bean is registered under the `sitemesh` name to prevent SiteMesh's auto-configuration from activating the upstream filter-based integration. +* Layout resolution and decoration are now handled by `Sitemesh3LayoutView` (a Spring `View`) and `CaptureAwareContentProcessor`. +* GSP pages populate a `Sitemesh3CapturedPage` at render time via the `grailsLayout` capture tag library. SiteMesh no longer parses the raw HTML response to extract head/body/title. + +===== Required Actions + +For most applications **no changes are required**. The filter-less integration is a drop-in replacement: layouts, `<g:layoutHead>`, `<g:layoutTitle>`, `<g:layoutBody>`, `<g:pageProperty>`, `<g:applyLayout>`, and layout-by-convention all behave identically to the previous release. + +The following SiteMesh 2-era configuration properties are no longer consulted and can be removed from your `application.yml` if present: Review Comment: We still have to support sitemesh 2 so we need to clarify that this is only if sitemesh3 is being used. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
