Completed initial draft of taglibs chapter

docs/manual/src/docbook/taglibs.xml

@@ -1,36 +1,92 @@
 <chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="taglibs"
     xmlns:xlink="http://www.w3.org/1999/xlink">
-
     <title>JSP Tag Libraries</title>
-    
-    <para>
-        Spring Security has its own taglib which provides basic support for accessing security information
-        and applying security constraints in JSPs.
-    </para>
-    
+    <para> Spring Security has its own taglib which provides basic support for accessing security
+        information and applying security constraints in JSPs. </para>
     <section>
         <title>Declaring the Taglib</title>
         <para>To use any of the tags, you must have the security taglib declared in your JSP:
-        
-<programlisting>
+            <programlisting>
     <![CDATA[<%@ taglib prefix="sec" uri="http://www.springframework.org/security/tags" %>]]>
-</programlisting>        
-        
-        </para>
+</programlisting></para>
     </section>
-    
     <section>
         <title>The <literal>authorize</literal> Tag</title>
-        <para>
-            This tag is used to determine whether its contents should be evaluated or not. In Spring Security
-            3.0, it can be used in two ways <footnote><para>The legacy options from Spring Security 2.0 are also supported,
-            but discouraged.</para></footnote>. The first approach uses a <link xlink:href="el-access-we">web-security expression</link>,
-            specified in the <literal>access</literal> attribute of the tag.
-        </para>
-        
-    </section>
-    
+        <para> This tag is used to determine whether its contents should be evaluated or not. In
+            Spring Security 3.0, it can be used in two ways <footnote>
+                <para>The legacy options from Spring Security 2.0 are also supported, but
+                    discouraged.</para>
+            </footnote>. The first approach uses a <link xlink:href="el-access-we">web-security
+                expression</link>, specified in the <literal>access</literal> attribute of the tag.
+            The expression evaluation will be delegated to the
+                <interfacename>WebSecurityExpressionHandlder</interfacename> defined in the
+            application context (you should have web expressions enabled in your
+                <literal>&lt;http></literal> namespace configuration to make sure this service is
+            available). So, for example, you might
+            have<programlisting>&lt;sec:authorize access="hasRole('supervisor')">
     
+This content will only be visible to users who have
+the "supervisor" authority in their list of &lt;tt>GrantedAuthority&lt;/tt>s.
+
+&lt;/sec:authorize></programlisting></para>
+        <para>A common requirement is to only show a particular link, if the user is actually
+            allowed to click it. How can we determine in advance whether something will be allowed?
+            This tag can also operate in an alternative mode which allows you to define a particular
+            URL as an attribute. If the user is allowed to invoke that URL, then the tag body will
+            be evaluated, otherwise it will be skipped. So you might have something
+            like<programlisting>&lt;sec:authorize url="/admin">
 
+This content will only be visible to users who are authorized to send requests to the "/admin" URL.
 
-</chapter>
+&lt;/sec:authorize></programlisting>To
+            use this tag there must also be an instance of
+                <interfacename>WebInvocationPrivilegeEvaluator</interfacename> in your application
+            context. If you are using the namespace, one will automatically be registered. This is
+            an instance of <classname>DefaultWebInvocationPrivilegeEvaluator</classname>, which
+            creates a dummy web request for the supplied URL and invokes the security interceptor to
+            see whether the request would succeed or fail. This allows you to delegate to the
+            access-control setup you defined using <literal>intercept-url</literal> declarations
+            within the <literal>&lt;http></literal> namespace configuration and saves having to
+            duplicate the information (such as the required roles) within your JSPs. This approach
+            can also be combined with a <literal>method</literal> attribute, supplying the HTTP
+            method, for a more specific match.</para>
+    </section>
+    <section>
+        <title>The <literal>authentication</literal>Tag</title>
+        <para>This tag allows access to the current <interfacename>Authentication</interfacename>
+            object stored in the security context. It renders a property of the object directly in
+            the JSP. So, for example, if the <literal>principal</literal> property of the
+                <interfacename>Authentication</interfacename> is an instance of Spring Security's
+                <interfacename>UserDetails</interfacename> object, then using
+                <literal>&lt;sec:authentication property="principal.username" /></literal> will
+            render the name of the current user.</para>
+        <para>Of course, it isn't necessary to use JSP tags for this kind of thing and some people
+            prefer to keep as little logic as possible in the view. You can access the
+                <interfacename>Authentication</interfacename> object in your MVC controller (by
+            calling <code>SecurityContextHolder.getContext().getAuthentication()</code>) and add the
+            data directly to your model for rendering by the view.</para>
+    </section>
+    <section>
+        <title>The <literal>accesscontrollist</literal> Tag</title>
+        <para>This tag is only valid when used with Spring Security's ACL module. It checks a
+            comma-separated list of required permissions for a specified domain object. If the
+            current user has any of those permissions, then the tag body will be evaluated. If they
+            don't, it will be skipped. An example might
+            be<programlisting>&lt;sec:accesscontrollist hasPermission="1,2" domainObject="someObject">
+
+This will be shown if the user has either of the permissions represented by the values "1" or "2" on the given object.
+
+&lt;/sec:accesscontrollist></programlisting></para>
+        <para>The permissions are passed to the <interfacename>PermissionFactory</interfacename>
+            defined in the application context, converting them to ACL
+                <interfacename>Permission</interfacename> instances, so they may be any format which
+            is supported by the factory - they don't have to be integers, they could be strings like
+                <literal>READ</literal> or <literal>WRITE</literal>. If no
+                <interfacename>PermissionFactory</interfacename> is found, an instance of
+                <classname>DefaultPermissionFactory</classname> will be used. The
+                <interfacename>AclService</interfacename>from the application context will be used
+            to load the <interfacename>Acl</interfacename> instance for the supplied object. The
+                <interfacename>Acl</interfacename> will be invoked with the required permissions to
+            check if any of them are granted.</para>
+    </section>
+</chapter>