granicus.if.org Git - apache/blob - docs/manual/mod/mod_example.xml

   1 <?xml version="1.0"?>
   2 <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
   3 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
   4 <!-- $LastChangedRevision$ -->
   5
   6 <!--
   7  Licensed to the Apache Software Foundation (ASF) under one or more
   8  contributor license agreements.  See the NOTICE file distributed with
   9  this work for additional information regarding copyright ownership.
  10  The ASF licenses this file to You under the Apache License, Version 2.0
  11  (the "License"); you may not use this file except in compliance with
  12  the License.  You may obtain a copy of the License at
  13
  14      http://www.apache.org/licenses/LICENSE-2.0
  15
  16  Unless required by applicable law or agreed to in writing, software
  17  distributed under the License is distributed on an "AS IS" BASIS,
  18  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  19  See the License for the specific language governing permissions and
  20  limitations under the License.
  21 -->
  22
  23 <modulesynopsis metafile="mod_example.xml.meta">
  24
  25 <name>mod_example</name>
  26 <description>Illustrates the Apache module API</description>
  27 <status>Experimental</status>
  28 <sourcefile>mod_example.c</sourcefile>
  29 <identifier>example_module</identifier>
  30
  31 <summary>
  32     <p>Some files in the <code>modules/experimental</code> directory
  33     under the Apache distribution directory tree are provided as an
  34     example to those that wish to write modules that use the Apache
  35     API.</p>
  36
  37     <p>The main file is <code>mod_example.c</code>, which
  38     illustrates all the different callback mechanisms and call
  39     syntaxes. By no means does an add-on module need to include
  40     routines for all of the callbacks - quite the contrary!</p>
  41
  42     <p>The example module is an actual working module. If you link
  43     it into your server, enable the "example-handler" handler for a
  44     location, and then browse to that location, you will see a
  45     display of some of the tracing the example module did as the
  46     various callbacks were made.</p>
  47 </summary>
  48
  49 <section id="compiling"><title>Compiling the example module</title>
  50
  51     <p>To include the example module in your server, follow the
  52     steps below:</p>
  53
  54     <ol>
  55       <li>
  56         Run <program>configure</program> with <code>--enable-example</code>
  57         option.</li>
  58
  59       <li>Make the server (run "<code>make</code>").</li>
  60     </ol>
  61
  62     <p>To add another module of your own:</p>
  63
  64     <ol type="A">
  65       <li><code>cp modules/experimental/mod_example.c
  66       modules/new_module/<em>mod_myexample.c</em></code></li>
  67
  68       <li>Modify the file.</li>
  69
  70       <li>Create <code>modules/new_module/config.m4</code>.
  71         <ol>
  72           <li>Add <code>APACHE_MODPATH_INIT(new_module)</code>.</li>
  73           <li>Copy APACHE_MODULE line with "example" from
  74             <code>modules/experimental/config.m4</code>.</li>
  75           <li>Replace the first argument "example" with <em>myexample</em>.</li>
  76           <li>Replace the second argument with brief description of your module.
  77             It will be used in <code>configure --help</code>.</li>
  78           <li>If your module needs additional C compiler flags, linker flags or
  79             libraries, add them to CFLAGS, LDFLAGS and LIBS accordingly.
  80             See other <code>config.m4</code> files in modules directory for
  81             examples.</li>
  82           <li>Add <code>APACHE_MODPATH_FINISH</code>.</li>
  83         </ol>
  84       </li>
  85
  86       <li>Create <code>module/new_module/Makefile.in</code>.
  87       If your module doesn't need special build instructions,
  88       all you need to have in that file is
  89       <code>include $(top_srcdir)/build/special.mk</code>.</li>
  90
  91       <li>Run ./buildconf from the top-level directory.</li>
  92
  93       <li>Build the server with --enable-myexample</li>
  94
  95     </ol>
  96 </section>
  97
  98 <section id="using"><title>Using the <code>mod_example</code> Module</title>
  99
 100     <p>To activate the example module, include a block similar to
 101     the following in your <code>httpd.conf</code> file:</p>
 102 <highlight language="config">
 103 &lt;Location /example-info&gt;
 104    SetHandler example-handler
 105 &lt;/Location&gt;
 106 </highlight>
 107
 108     <p>As an alternative, you can put the following into a <a
 109     href="core.html#accessfilename"><code>.htaccess</code></a> file
 110     and then request the file "test.example" from that location:</p>
 111 <highlight language="config">
 112    AddHandler example-handler .example
 113 </highlight>
 114
 115     <p>After reloading/restarting your server, you should be able
 116     to browse to this location and see the brief display mentioned
 117     earlier.</p>
 118 </section>
 119
 120 <directivesynopsis>
 121 <name>Example</name>
 122 <description>Demonstration directive to illustrate the Apache module
 123 API</description>
 124 <syntax>Example</syntax>
 125 <contextlist><context>server config</context>
 126 <context>virtual host</context><context>directory</context>
 127 <context>.htaccess</context></contextlist>
 128
 129 <usage>
 130     <p>The <directive>Example</directive> directive just sets a demonstration
 131     flag which the example module's content handler displays. It
 132     takes no arguments. If you browse to an URL to which the
 133     example content-handler applies, you will get a display of the
 134     routines within the module and how and in what order they were
 135     called to service the document request. The effect of this
 136     directive one can observe under the point "<code>Example
 137     directive declared here: YES/NO</code>".</p>
 138 </usage>
 139 </directivesynopsis>
 140
 141 </modulesynopsis>