docs/admin/apache_rewrite_tricks.txt

   1 Apache Rewrite Tricks
   2 ---------------------
   3 It is possible to use Apache's Rewrite Module features to perform a number of
   4 useful tricks that can make people's lives much easier.
   5
   6 Short URLs
   7 ~~~~~~~~~~
   8 Making short URLs for common destinations can simplify making printed media as
   9 well as shortening or simplifying what people need to type. These are also easy
  10 to add and require minimal maintenance, and generally can be implemented with a
  11 single line addition to your eg_vhost.conf file.
  12
  13 [source,conf]
  14 ----
  15 # My Account - http://host.ext/myaccount -> My Account Page
  16 RewriteRule ^/myaccount https://%{HTTP_HOST}/eg/opac/myopac/main [R]
  17
  18 # ISBN Search - http://host.ext/search/isbn/<ISBN NUMBER> -> Search Page
  19 RewriteRule ^/search/isbn/(.*) /eg/opac/results?_special=1&qtype=identifier|isbn&query=$1 [R]
  20 ----
  21
  22 Domain Based Content with RewriteMaps
  23 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  24 One creative use of Rewrite features is domain-based configuration in a single
  25 eg_vhost.conf file. Regardless of how many VirtualHost blocks use the
  26 configuration you don't need to duplicate things for minor changes, and can in
  27 fact use wildcard VirtualHost blocks to serve multiple subdomains.
  28
  29 For the wildcard blocks you will want to use a ServerAlias directive, and for
  30 SSL VirtualHost blocks ensure you have a wildcard SSL certificate.
  31
  32 [source,conf]
  33 ----
  34 ServerAlias *.example.com
  35 ----
  36
  37 For actually changing things based on the domain, or subdomain, you can use
  38 RewriteMaps. Each RewriteMap is generally a lookup table of some kind. In the
  39 following examples we will generally use text files, though database lookups
  40 and external programs are also possible.
  41
  42 Note that in the examples below we generally store things in Environment
  43 Variables. From within Template Toolkit templates you can access environment
  44 variables with the ENV object.
  45
  46 .Template Toolkit ENV example, link library name/url if set
  47 [source,html]
  48 ----
  49 [% IF ENV.eglibname && ENV.egliburl %]<a href="[% ENV.egliburl %]">[% ENV.eglibname %]</a>[% END %]
  50 ----
  51
  52 The first lookup to do is a domain to identifier, allowing us to re-use
  53 identifiers for multiple domains. In addition we can also supply a default
  54 identifier, for when the domain isn't present in the lookup table.
  55
  56 .Apache Config
  57 [source,conf]
  58 ----
  59 # This internal map allows us to lowercase our hostname, removing case issues in our lookup table
  60 # If you prefer uppercase you can use "uppercase int:toupper" instead.
  61 RewriteMap lowercase int:tolower
  62 # This provides a hostname lookup
  63 RewriteMap eglibid txt:/openils/conf/libid.txt
  64 # This stores the identifier in a variable (eglibid) for later use
  65 # In this case CONS is the default value for when the lookup table has no entry
  66 RewriteRule . - [E=eglibid:${eglibid:${lowercase:%{HTTP_HOST}}|CONS}]
  67 ----
  68
  69 .Contents of libid.txt File
  70 [source,txt]
  71 ----
  72 # Comments can be included
  73 # Multiple TLDs for Branch 1
  74 branch1.example.com BRANCH1
  75 branch1.example.net BRANCH1
  76 # Branches 2 and 3 don't have alternate TLDs
  77 branch2.example.com BRANCH2
  78 branch3.example.com BRANCH3
  79 ----
  80
  81 Once we have identifiers we can look up other information, when appropriate.
  82 For example, say we want to look up library names and URLs:
  83
  84 .Apache Config
  85 [source,conf]
  86 ----
  87 # Library Name Lookup - Note we provide no default in this case.
  88 RewriteMap eglibname txt:/openils/conf/libname.txt
  89 RewriteRule . - [E=eglibname:${eglibname:%{ENV:eglibid}}]
  90 # Library URL Lookup - Also with no default.
  91 RewriteMap egliburl txt:/openils/conf/liburl.txt
  92 RewriteRule . - [E=egliburl:${egliburl:%{ENV:eglibid}}]
  93 ----
  94
  95 .Contents of libname.txt File
  96 [source,txt]
  97 ----
  98 # Note that we cannot have spaces in the "value", so instead &#32; is used. &nbsp; is also an option.
  99 BRANCH1 Branch&#32;One
 100 BRANCH2 Branch&#32;Two
 101 BRANCH3 Branch&#32;Three
 102 CONS Example&#32;Consortium&#32;Name
 103 ----
 104
 105 .Contents of liburl.txt File
 106 [source,txt]
 107 ----
 108 BRANCH1 http://branch1.example.org
 109 BRANCH2 http://branch2.example.org
 110 BRANCH3 http://branch3.example.org
 111 CONS http://example.org
 112 ----
 113
 114 Or, perhaps set the "physical location" variable for default search/display library:
 115
 116 .Apache Config
 117 [source,conf]
 118 ----
 119 # Lookup "physical location" IDs
 120 RewriteMap eglibphysloc txt:/openils/conf/libphysloc.txt
 121 # Note: physical_loc is a variable used in the TTOPAC and should not be re-named
 122 RewriteRule . - [E=physical_loc:${eglibphysloc:%{ENV:eglibid}}]
 123 ----
 124
 125 .Contents of libphysloc.txt File
 126 [source,txt]
 127 ----
 128 BRANCH1 4
 129 BRANCH2 5
 130 BRANCH3 6
 131 CONS 1
 132 ----
 133
 134 Going further, you could also replace files to be downloaded, such as images or
 135 stylesheets, on the fly:
 136
 137 .Apache Config
 138 [source,conf]
 139 ----
 140 # Check if a file exists based on eglibid and the requested file name
 141 # Say, BRANCH1/opac/images/main_logo.png
 142 RewriteCond %{DOCUMENT_ROOT}/%{ENV:eglibid}%{REQUEST_URI} -f
 143 # Serve up the eglibid version of the file instead
 144 RewriteRule (.*) /%{ENG:eglibid}$1
 145 ----
 146
 147 Note that template files themselves cannot be replaced in that manner.
 148