From b160984ae35c6b7a28e1eccbe9e2c2f51ac9573f Mon Sep 17 00:00:00 2001 From: Eric Covener Date: Sat, 21 Apr 2018 15:42:03 +0000 Subject: [PATCH] try to make the mod_filter docs a little more approachable - more consistently refer to the filters declared via the harness as "smart filters" - reinforce that the providers are traditional filters. - drop some info about the optional type parameter - elaborate on examples git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1829713 13f79535-47bb-0310-9956-ffa450edef68 --- docs/manual/mod/mod_filter.xml | 63 +++++++++++++++++++--------------- 1 file changed, 35 insertions(+), 28 deletions(-) diff --git a/docs/manual/mod/mod_filter.xml b/docs/manual/mod/mod_filter.xml index 5d3733319b..5f43b42c10 100644 --- a/docs/manual/mod/mod_filter.xml +++ b/docs/manual/mod/mod_filter.xml @@ -95,16 +95,14 @@
Declare Filters
The FilterDeclare directive - declares a filter, assigning it a name and filter type. Required - only if the filter is not the default type AP_FTYPE_RESOURCE.
- + declares a new smart filter, assigning it a name and optional filter + type.
Register Providers
The FilterProvider directive registers a provider with a filter. The filter may have been declared with FilterDeclare; if not, FilterProvider will implicitly - declare it with the default type AP_FTYPE_RESOURCE. The provider - must have been + declare it. The provider must have been registered with ap_register_output_filter by some module. The final argument to FilterProvider is an expression: the provider will be @@ -152,7 +150,9 @@
Examples
Server side Includes (SSI)
-
A simple case of replacing AddOutputFilterByType +
A simple case replacing AddOutputFilterByType. + This example creates a new smart filter named "SSI" that conditionally leverates + the "INCLUDES" filter from mod_include as a provider. FilterDeclare SSI FilterProvider SSI INCLUDES "%{CONTENT_TYPE} =~ m|^text/html|" @@ -170,18 +170,25 @@ FilterChain SSI
Emulating mod_gzip with mod_deflate
-
Insert INFLATE filter only if "gzip" is NOT in the - Accept-Encoding header. This filter runs with ftype CONTENT_SET. +
This example demonstrates the dynamic properties granted to traditional + filters when a smart filter is constructed around them. A new smart filter + named "gzip" is created that dynamically inserts mod_deflate's + INFLATE filter only if "gzip" is NOT in the Accept-Encoding header. + The gzip smart filter runs with type CONTENT_SET. FilterDeclare gzip CONTENT_SET -FilterProvider gzip inflate "%{req:Accept-Encoding} !~ /gzip/" +FilterProvider gzip INFLATE "%{req:Accept-Encoding} !~ /gzip/" FilterChain gzip
Image Downsampling
-
Suppose we want to downsample all web images, and have filters - for GIF, JPEG and PNG. +
This example demonstrates further abstractions that the smart filtering. + Suppose we want to downsample all web images, and have different + filter providers for manipulating GIF, JPEG and PNG + The configuration defines smart filters "unpack" and "repack" via + the harness that invokes the right underlying filter providers based on + the content type at runtime. FilterProvider unpack jpeg_unpack "%{CONTENT_TYPE} = 'image/jpeg'" FilterProvider unpack gif_unpack "%{CONTENT_TYPE} = 'image/gif'" @@ -297,7 +304,7 @@ being moved to mod_filter in version 2.3.7 FilterDeclare Declare a smart filter -FilterDeclare filter-name [type] +FilterDeclare smart-filter-name [type] server configvirtual host directory.htaccess Options @@ -305,7 +312,7 @@ being moved to mod_filter in version 2.3.7

This directive declares an output filter together with a header or environment variable that will determine runtime - configuration. The first argument is a filter-name + configuration. The first argument is a smart-filter-name for use in FilterProvider, FilterChain and FilterProtocol directives.

@@ -321,7 +328,7 @@ being moved to mod_filter in version 2.3.7 FilterProvider Register a content filter -FilterProvider filter-name provider-name +FilterProvider smart-filter-name provider-name expression server configvirtual host directory.htaccess @@ -350,7 +357,7 @@ for a complete reference and examples. FilterChain Configure the filter chain -FilterChain [+=-@!]filter-name ... +FilterChain [+=-@!]smart-filter-name ... server configvirtual host directory.htaccess Options @@ -362,23 +369,23 @@ for a complete reference and examples. determines what to do:

-
+filter-name
+
+smart-filter-name
Add filter-name to the end of the filter chain
-
@filter-name
-
Insert filter-name at the start of the filter chain
+
@smart-filter-name
+
Insert smart-filter-name at the start of the filter chain
-
-filter-name
-
Remove filter-name from the filter chain
+
-smart-filter-name
+
Remove smart-filter-name from the filter chain
-
=filter-name
-
Empty the filter chain and insert filter-name
+
=smart-filter-name
+
Empty the filter chain and insert smart-filter-name
!
Empty the filter chain
-
filter-name
-
Equivalent to +filter-name
+
smart-filter-name
+
Equivalent to +smart-filter-name
 @@ -386,7 +393,7 @@ for a complete reference and examples. FilterProtocol Deal with correct HTTP protocol handling -FilterProtocol filter-name [provider-name] +FilterProtocol smart-filter-name [provider-name] proto-flags server configvirtual host directory.htaccess @@ -399,9 +406,9 @@ for a complete reference and examples. filter.

There are two forms of this directive. With three arguments, it - applies specifically to a filter-name and a + applies specifically to a smart-filter-name and a provider-name for that filter. - With two arguments it applies to a filter-name whenever the + With two arguments it applies to a smart-filter-name whenever the filter runs any provider.

Flags specified with this directive are merged with the flags @@ -443,7 +450,7 @@ for a complete reference and examples. FilterTrace Get debug/diagnostic information from mod_filter -FilterTrace filter-name level +FilterTrace smart-filter-name level server configvirtual host directory -- 2.40.0