tutorial.textile in activeldap-4.0.2

- old
+ new
@@ -401,9 +401,33 @@
 If :attribute is unspecified, it defaults to the dn_attribute.
 
 It is also possible to override :attribute and :value by specifying :filter. This
 argument allows the direct specification of a LDAP filter to retrieve objects by.
 
+h5. Using the :filter option
+
+The filter option lets you pass in an LDAP query string.
+For example retrieving all groups with cn which starts with @'dev'@ and has @guid@ == 1:
+
+<pre>
+irb> Group.find(:all, :filter => '(&(cn=dev*)(guid=1))').collect {|group| group.cn}
+=> ["develop"]
+</pre>
+
+It also allows a hash like sintax (sparing you the need to write the query by hand ):
+
+<pre>
+irb> Group.find(:all, :filter => {:cn => 'dev*', :guid => 1 }).collect {|group| group.cn}
+=> ["develop", "developers", "sys", "sysadmin"]
+</pre>
+
+You can build complex queries combining the hash syntax with arrays and @:or@ and @:and@ operators retrieving all users whose name contains 'john' or cn ends with 'smith' or contains 'liz'
+
+<pre>
+irb> User.find(:all, filter: [:or, [:or, { :cn => '*smith', :name => '*john*'} ], { cn: '*liz*' }]).collect(&:cn)
+=> ['john.smith', 'jane.smith', 'john tha ripper', 'liz.taylor', ...]
+</pre>
+
 h4. .search
 
 .search is a class method that is accessible from any subclass of Base, and Base.
 It lets the user perform an arbitrary search against the current LDAP connection
 irrespetive of LDAP mapping data.  This is meant to be useful as a utility method