2 Concepts - Reference Documentation
Authors: Marc Palmer (firstname.lastname@example.org), Luke Daley (email@example.com), Peter N. Steinmetz (firstname.lastname@example.org)
2 ConceptsThe resources framework provides 5 primary functions to a Grails application:
- Bundling of resources into modules with dependency management.
- Processing of resources prior to serving them.
- Tag library to render links to resources in modules.
- Tag library to render links to other resources which are not in modules.
- Service of resources to clients based on appropriate requests.
g:namespace as of Grails 1.4, this more general meaning is important, as different functions of the plugin view resources in different ways. The following sections will provide an overview of how resources are handled by the resource plugin with respect to each of these functions. Please see the other sections of this User Guide for details regarding each of the tags and objects mentioned.
Bundling of Resources into Modules with Dependency Management.In the resources framework, you define resource modules that have a name and contain one or more resources. The modules are declared in separate files named like ModuleResources.groovy (forming a Resources artefact) or in a separate modules block within Config.groovy.The resources can either be local to the application, and declared with the usual map of attributes, such as
file:, or external to the application, with an absolute url containing
Tag Library to Render Links to Resources in Modules.The plugin includes several tags for rendering links to resources that are declared in modules. The resource tag is the primary tag used for this purpose and the uri for a resource can be specified as a combination of attributes, such as directory and file, or a relative uri. The img tag is a specialized tag for rendering links to image files which can be used for images which are declared in modules.
Tag Library to Render Links to Resources Not Declared in Modules.The Resources plugin also provides tags which can be used to render links to resources which are not declared in a module. This function assumes greater importance since Grails 1.4, as the
g:imgtags now call the corresponding tags in the Resources plugin.Resources which haven't been declared in a module fall into two classes, those which are served by the application and those which refer to a resource not served by the application. The former have a context relative URI whereas the latter have an absolute URI, which the plugin defines as a URI that contains the characters
//.The primary tag to render links to either type of resource is the external tag. This tag can take a URI (relative or absolute) or a combination of other attributes to specify the resource, such as directory and file. The img tag may be used with similar arguments to render a link to an image file.
Service of Resources to Clients.A final major function of the Resources plugin is to serve content which is not provided by the dynamic controllers, which serve URIs of the form /controller/action/id. The plugin provides two methods of resolving URIs to serve these non-dynamic, or static, resources.The primary method is by resolving URIs within a specific static URI subspace, normally those URIs under
static/. When such a URI is encountered, the plugin first attempts to determine if the URI corresponds to a resource declared in a module. If it finds one, it serves that. If it cannot find such a resource, it will next examine the file system under webapp and if a file with corresponding path and name is found, it will serve that. In the process of doing so, it will create a copy of the file and process it in the normal manner for a resource of its type, assigning it to a virtual 'adhoc' module.The second method of serving resources is designed to serve resources requested with legacy URIs. These are URIs which are not under the static URI subspace or the form /controller/action/id served by the dynamic controllers. They typically would be generated by a mechanism other than the Resources plugin tags, for example, by older Grails applications. These are referred to as 'ad-hoc' or 'legacy' resources. In order to recognize these URIs, a pattern matching them must be configured, and by default the patterns
*.jswill be processed in this way. When such resources are requested, the client is redirected to a processed copy of the resource which is created in the
/static/URI subspace. This method is not recommended for general use, but only for accomodating legacy URIs.
Use With SecurityWhen the resources plugin is used to serve resources, it is important to understand that resources in the static URI subspace are served without application of security rules by SpringSecurity. This implies that any resources served from the static URI subspace are provided with no security rules applied.
Importantly, this implies that any files accessible in the web-app base directory will be accessible under a corresponding path under <ctx>/static, so be careful which files are available under the web-app base directory.