From a15dd2a411e0d00fa0bb0de60a169f71febd5c64 Mon Sep 17 00:00:00 2001
From: Jeremy Mikola <jmikola@gmail.com>
Date: Mon, 16 Apr 2012 12:45:10 -0400
Subject: [PATCH] [Listener] Revise is_indexable_callback documentation

---
 README.md | 28 ++++++++++++++++++++--------
 1 file changed, 20 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
index 739b533..66379dc 100644
--- a/README.md
+++ b/README.md
@@ -479,18 +479,30 @@ You can also choose to only listen for some of the events:
 
 ### Checking an entity method for listener
 
-If you use listeners to update your index, you may need to validate your entities before you put them to the
-index (e.g. is the entity public). You can do this with the is_indexable_callback config param.
+If you use listeners to update your index, you may need to validate your
+entities before you index them (e.g. only index "public" entities). Typically,
+you'll want the listener to be consistent with the provider's query criteria.
+This may be achieved by using the `is_indexable_callback` config parameter:
 
                         persistence:
                             listener:
-                            is_indexable_callback: "isPublic"
+                                is_indexable_callback: "isPublic"
 
-This is optional, but if you set the is_indexable_callback and the entity has a method with the specified name, your
-entities will go into the index only if the method returns true. If you update an entity and the update
-listener is active, it will check the method again, and if it returns true, the entity will be removed from
-the index. If it returns true, it will be updated in the index of course. Delete listener disregards the
-is_indexable_callback.
+If `is_indexable_callback` is a string and the entity has a method with the
+specified name, the listener will only index entities for which the method
+returns `true`. Additionally, you may provide a service and method name pair:
+
+                        persistence:
+                            listener:
+                                is_indexable_callback: [ "%custom_service_id%", "isIndexable" ]
+
+In this case, the callback will be the `isIndexable()` method on the specified
+service. This allows you to do more complex validation (e.g. ACL checks).
+
+As you might expect, new entities will only be indexed if the callback returns
+`true`. Additionally, modified entities will be updated or removed from the
+index depending on whether the callback returns `true` or `false`, respectively.
+The delete listener disregards the callback.
 
 > **Propel** doesn't support this feature yet.