You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This chapter describes how to add images, stylesheets, JavaScripts, and other static assets.
13
+
14
+
Earlier in this manual, we have seen how to create views, and how to use file and image fields.
15
+
These are all dynamic, however, and often we just want to ship with a static image, icon, CSS or JavaScript file.
16
+
For this, we need to register static resources.
13
17
14
-
Earlier in this manual, we have seen how to create views, and how to use
15
-
file and image fields. These are all dynamic, however, and often we just
16
-
want to ship with a static image/icon, CSS or JavaScript file. For this,
17
-
we need to register static resources.
18
18
19
19
## Registering a static resource directory
20
20
21
-
The easiest way to manage static resources is to create a
22
-
`static` resource directory in your Dexterity project using the ZCML resourceDirectory directive.
21
+
The easiest way to manage static resources is to create a `static` resource directory in your Dexterity project using the ZCML `resourceDirectory` directive.
23
22
24
-
Registration of the resource directory is done using the
25
-
`<browser:resourceDirectory />` ZCML directive. This requires two
26
-
attributes: `name` is the name that appears after the
27
-
`++resource++` namespace; `directory` is a relative path to the
28
-
directory containing resources.
23
+
Registration of the resource directory is done using the `<browser:resourceDirectory />` ZCML directive.
24
+
This requires two attributes.
25
+
`name` is the name that appears after the `++resource++` namespace
26
+
`directory` is a relative path to the directory containing resources.
29
27
30
-
It's conventional to use "static" for the directory name and the dotted name of your package for the resource name.
31
-
You would use this zcml to register it:
28
+
It's conventional to use `static` for the directory name, and the dotted name of your package for the resource name.
29
+
You would use this ZCML to register it.
32
30
33
31
```xml
34
32
<browser:resourceDirectory
35
33
name="example.conference"
36
34
directory="static" />
37
35
```
38
36
39
-
Then, if a "static" resource directory in the `example.conference` package
40
-
contains a file called `conference.css`, it will be accessible on a URL
41
-
like `http://<server>/site/++resource++example.conference/conference.css.`
42
-
The resource name is the same as the package name wherein the `resources`
43
-
directory appears.
37
+
Then, if a "static" resource directory in the `example.conference` package contains a file called {file}`conference.css`, it will be accessible on a URL, such as `https://<server>/site/++resource++example.conference/conference.css`.
38
+
The resource name is the same as the package name wherein the `resources` directory appears.
39
+
44
40
45
41
## Importing CSS and JavaScript files in templates
46
42
47
-
One common use of static resources is to add a static CSS or JavaScript
48
-
file to a specific template. We can do this by filling the `style_slot`
49
-
or `javascript_slot` in Plone’s `main_template` in our own view
50
-
template and using an appropriate resource link.
43
+
One common use of static resources is to add a static CSS or JavaScript file to a specific template.
44
+
We can do this by filling the `style_slot` or `javascript_slot` in Plone's `main_template` in our own view template and using an appropriate resource link.
51
45
52
-
For example, we could add the following near the top of
53
-
`presenter_templates/view.pt`:
46
+
For example, we could add the following near the top of {file}`presenter_templates/view.pt`.
54
47
55
-
```html
48
+
```xml
56
49
<head>
57
50
<metal:blockfill-slot="style_slot">
58
51
<linkrel="stylesheet"type="text/css"
@@ -63,35 +56,24 @@ For example, we could add the following near the top of
63
56
</head>
64
57
```
65
58
66
-
:::{note}
67
-
Always create the resource URL relative to the navigation root as shown
68
-
here, so that the URL is the same for all content objects using this
69
-
view. This allows for efficient resource caching.
70
-
:::
71
-
72
-
## Registering resources with Plone’s resource registries
73
-
74
-
Sometimes it is more appropriate to register a stylesheet with Plone’s
75
-
`portal_css` registry (or a JavaScript file with
76
-
`portal_javascripts`), rather than add the registration on a
77
-
per-template basis. This ensures that the resource is available
78
-
site-wide.
79
-
80
-
:::{note}
81
-
It may seem wasteful to include a resource that is not be used on all
82
-
pages in the global registry. Remember, however, that `portal_css` and
83
-
`portal_javascripts` will merge and compress resources, and set caching
84
-
headers such that browsers and caching proxies can cache resources well.
85
-
It is often more effective to have one slightly larger file that caches
86
-
well, than to have a variable number of files that may need to be loaded
87
-
at different times.
88
-
:::
89
-
90
-
To add a static resource file, you can use the GenericSetup
91
-
`cssregistry.xml` or `jsregistry.xml` import steps in the
92
-
`profiles/default` directory. For example, an import step to add the
93
-
`conference.css` file site-wide may involve a `cssregistry.xml` file
94
-
that looks like this:
59
+
```{note}
60
+
Always create the resource URL relative to the navigation root as shown here, so that the URL is the same for all content objects using this view.
61
+
This allows for efficient resource caching.
62
+
```
63
+
64
+
65
+
## Registering resources with Plone's resource registries
66
+
67
+
Sometimes it is more appropriate to register a stylesheet with Plone's `portal_css` registry (or a JavaScript file with `portal_javascripts`), rather than add the registration on a per-template basis.
68
+
This ensures that the resource is available site-wide.
69
+
70
+
```{note}
71
+
It may seem wasteful to include a resource that is not be used on all pages in the global registry.
72
+
Remember, however, that `portal_css` and `portal_javascripts` will merge and compress resources, and set caching headers such that browsers and caching proxies can cache resources well.
73
+
It is often more effective to have one slightly larger file that caches well, than to have a variable number of files that may need to be loaded at different times.
74
+
```
75
+
76
+
To add a static resource file, you can use the GenericSetup {file}`cssregistry.xml` or {file}`jsregistry.xml` import steps in the `profiles/default` directory. For example, an import step to add the {file}`conference.css` file site-wide may involve a {file}`cssregistry.xml` file such as the following.
95
77
96
78
```xml
97
79
<?xml version="1.0"?>
@@ -103,8 +85,7 @@ that looks like this:
103
85
</object>
104
86
```
105
87
106
-
Similarly, a JavaScript resource could be imported with a
107
-
`jsregistry.xml` like:
88
+
Similarly, a JavaScript resource could be imported with a {file}`jsregistry.xml` file such as the following.
108
89
109
90
```xml
110
91
<?xml version="1.0"?>
@@ -115,26 +96,24 @@ Similarly, a JavaScript resource could be imported with a
115
96
</object>
116
97
```
117
98
99
+
118
100
## Image resources
119
101
120
-
Images can be added to resource directories just like any other type of
121
-
resource. To use the image in a view, you can construct an `<img />` tag
122
-
like this:
102
+
Images can be added to resource directories just like any other type of resource.
103
+
To use the image in a view, you can construct an `<img />` tag as follows.
Finally, to use an image resource as the icon for a content type, simply
134
-
list it in the FTI under the `content_icon` property. For example, in
135
-
`profiles/default/types/example.conference.presenter.xml`, we can use
136
-
the following line, presuming we have a `presenter.gif` in the `example.conference` resource
137
-
directory:
115
+
Finally, to use an image resource as the icon for a content type, simply list it in the FTI under the `content_icon` property.
116
+
For example, in {file}`profiles/default/types/example.conference.presenter.xml`, we can use the following line, presuming we have a {file}`presenter.gif` in the `example.conference` resource directory.
0 commit comments