Permalink
Browse files

latest docs

git-svn-id: https://svn.codehaus.org/grails-plugins/grails-searchable/trunk@45437 832c1c66-4827-0410-8465-ccb17913cd09
  • Loading branch information...
maurice
maurice committed Nov 29, 2008
1 parent ea37db8 commit 95c6faf5d96a140abd65f56de53cbb5f6b390be6
View

Large diffs are not rendered by default.

Oops, something went wrong.
@@ -0,0 +1,46 @@
+MAKING A RELEASE
+
+* Update plugin version numbers in searchable and searchable14 projects
+
+* Perform full test in searchable/trunk with:
+
+ ant
+
+This runs the unit, functional and integration tests.
+
+This needs to be done for at least the current production version of
+Grails and preferably the one before and current development versions,
+and both searchable and searchable14 projects.
+
+There should be no failing tests and the ant build should complete.
+
+* Update wiki docs
+
+This can be done either by editing the docs in src/docs/wiki and
+uploading them to grails.org, or by updating them on grails.org and
+then downloading them to src/docs/wiki.
+
+In particular rememeber to add something to the "Searchable Plugin -
+Releases" page.
+
+The sync-docs tool can be used for upload/download, see
+tools/sync-docs/README.txt.
+
+ groovy tools/sync-docs/scripts/get -server=www.grails.org -dir=src/doc/wiki -username=maurice -password=xxx -startPage='Searchable Plugin' -match='^Searchable Plugin.+$'
+
+Commit wiki docs.
+
+* Using Grails 1.1 and in searchable/trunk, run
+
+ grails release-plugin
+
+* Using Grails 1.0.x and in searchable14/trunk, run
+
+ grails release-plugin
+
+* Add a news item on grails.org
+
+* Announce the new version at user@grails.codehaus.org
+
+* Go to JIRA and set that version as released
+
@@ -0,0 +1,116 @@
+h1. Analyzers
+
+In order to make your data searchable it is typically _analyzed_.
+
+When text is analyzed using Lucene's @StandardAnalyzer@, for example,
+white-space and other irrelevant characters (eg punctation) are
+discarded, as are un-interesting words (eg, 'and', 'or', etc) and the
+remaining words are lower-cased. The input text is effectively
+normalized for the search index.
+
+Additionally when you search with a query string, that too is
+analyzed. This process means that the terms you search on are
+normalized in the same way as the terms in the index.
+
+Lucene includes many analyzers out of the box and you can also provide
+your own.
+
+h2. What we get with Compass
+
+Compass acts as a registry of Analyzers, each identified by a name.
+
+Compass provides two analyzers: @"default"@ which is used for indexing
+and @"search"@ which is used for searching (analyzing query strings).
+
+They are both instances of Lucenes @StandardAnalyzer@ (or equivalent).
+
+You can re-define both of these or define additional analyzers with
+new names.
+
+h2. Defining Analyzer implementations
+
+You can define an analyzer with Compass settings and (since 0.5.1) as
+Spring beans.
+
+h3. Compass settings
+
+The [Compass settings|http://www.compass-project.org/docs/2.1.0/reference/html/core-settings.html#core-configuration-searchengineanalyzers]
+can either be defined in the plugin's [configuration|Searchable Plugin - Configuration] or in a [native Compass configuration file|Searchable Plugin - Configuration].
+
+h3. Spring beans
+
+If you define a Spring bean in @resources.xml@ or @resources.groovy@
+that is an instance of @org.apache.lucene.analysis.Analyzer@ then it wil be
+automatically registered with Compass using the Spring bean name as it's name.
+
+This allows you to inject your analyzer with other Spring beans and
+configuration, eg
+
+{code}
+htmlAnalyzer(MyHtmlAnalyzer) {
+ context = someContext
+ includeMeta = true
+}
+{code}
+
+defines an analyzer called @"htmlAnalyzer"@, while
+
+{code}
+'default'(StandardAnalyzer, new HashSet()) // there are now no stop words
+{code}
+
+re-defines the @"default"@ analyzer so that it has no stop-words (and
+will not discard 'and', 'or', etc).
+
+h2. Using Analyzers
+
+h3. Indexing
+
+For indexing purposes you define the analyzer in the mapping, either at the class level
+
+{code}
+class Book {
+ static searchable = {
+ analyzer 'bookAnalyzer'
+ }
+ String title
+}
+{code}
+
+and/or at the property level
+
+{code}
+class Book {
+ static searchable = {
+ title analyzer: 'bookTitleAnalyzer'
+ }
+ String title
+}
+{code}
+
+Property-level analyzers override class-level analyzers just for that property.
+
+Note you can also use native Compass [XML|Searchable Plugin - Mapping - Compass XML] or [annotations|Searchable Plugin - Mapping - Compass annotations] to map with custom analyzers.
+
+h3. Searching
+
+You can say which analyzer you want to use on a per-query basis
+
+{code}
+def sr = Song.search("only the lonely", analyzer: 'songLyricsAnalyzer')
+{code}
+
+or with the [plugin's configuration|Searchable Plugin - Configuration]
+you can choose a search analyzer for all search queries (unless
+overriden on a per-query basis).
+
+{code}
+ defaultMethodOptions = [
+ search: [reload: false, escape: false, offset: 0, max: 10, defaultOperator: "and", analyzer: 'myAnalyzer'],
+ suggestQuery: [userFriendly: true]
+ ]
+{code}
+
+You could also simply redefine the @"search"@ analyzer to achieve the
+same effect.
+
@@ -29,6 +29,10 @@ With this file you can configure such things as
See the docs in the [config file itself|https://svn.codehaus.org/grails-plugins/grails-searchable/trunk/src/conf/Searchable.groovy] for more.
+h2. Spring beans
+
+Since 0.5.1, custom [analyzers|Searchable Plugin - Analyzers] and [converters|Searchable Plugin - Converters] can be defoned as Spring beans.
+
h2. Native Compass XML config
Since 0.4 the plugin also looks for a native Compass XML configuration file at the root of the classpath called *@compass.cfg.xml@*. If this file is present, Compass is configured with the settings defined in it, in addition to any that may be defined by the plugin's own *@Searchable.groovy@*.
@@ -0,0 +1,69 @@
+h1. Converters
+
+In order to transform your objects and their properties into
+searchable text, and from data stored in the index back into objects,
+Compass has the notion of _converters_.
+
+Compass acts as a registry of converters, each identified by name.
+
+Compass includes many converters itself, some responsible for
+converting entire class instances and some for individual properties.
+
+Additionally the plugin includes a custom converter itself which
+supports @Map<String, String>@ class property types, since Grails
+supports this as a persistent class property type.
+
+h2. Defining Converter implementations
+
+You can define a converter with Compass settings and (since 0.5.1) as
+Spring beans.
+
+h3. Compass settings
+
+The [Compass settings|http://www.compass-project.org/docs/2.1.0/reference/html/core-settings.html#config-converter]
+can either be defined in the plugin's [configuration|Searchable Plugin - Configuration] or in a [native Compass configuration file|Searchable Plugin - Configuration].
+
+h3. Spring beans
+
+If you define a Spring bean in @resources.xml@ or @resources.groovy@
+that is an instance of @org.compass.core.converter.Converter@ then it wil be
+automatically registered with Compass using the Spring bean name as it's name.
+
+This allows you to inject your analyzer with other Spring beans and
+configuration, eg
+
+{code}
+htmlConverter(MyHtmlConverter) {
+ context = someContext
+ includeMeta = true
+}
+{code}
+
+defines a converter called @"htmlConverter"@.
+
+h2. Using Converters
+
+Converters are defined in the class mapping, either at either at the class level
+
+{code}
+class Book {
+ static searchable = {
+ converter 'bookConverter'
+ }
+ String title
+}
+{code}
+
+and/or at the property level
+
+{code}
+class Book {
+ static searchable = {
+ title converter: 'bookTitleConverter'
+ }
+ String title
+}
+{code}
+
+Note you can also use native Compass [XML|Searchable Plugin - Mapping - Compass XML] or [annotations|Searchable Plugin - Mapping - Compass annotations] to map with custom converters.
+
@@ -1,5 +1,13 @@
h1. Releases
+h2. 0.5.1
+
+This release fixes some bugs and includes new features. It is a recommended upgrade for all users.
+
+It has been tested with Grails 1.0.3, 1.0.4 and 1.1-beta1.
+
+JIRA release notes are [here|http://jira.codehaus.org/secure/ReleaseNote.jspa?projectId=11450&styleName=Html&version=14751]
+
h2. 0.5
This release includes several bug fixes, adds few new search
@@ -62,7 +62,7 @@ Here it is in action in the Searchable Plugin's own search results page, @grails
</g:if>
<g:else>
<g:paginate controller="searchable" action="index" params="[q: params.q]"
- total="${searchResult.total}" prev="< previous" next="next >"/>
+ total="${searchResult.total}" prev="< previous" next="next >"/>
</g:else>
</g:if>
{code}
@@ -36,7 +36,7 @@ def searchResult = Song.search("summer winds", withHighlighter: songHighlighter)
assert searchResult.highlights
assert searchResult.highlights.size() == searchResult.results.size()
-assert (searchResult.highlights[0].indexOf("<b>summer</b>") > -1 &&
+assert (searchResult.highlights[0].indexOf("<b>summer</b>") > -1 &&
searchResult.highlights[0].indexOf("<b>winds</b>") > -1)
{code}
@@ -26,34 +26,40 @@ h2. Features
h2. Table of Contents
# [Quick start|Searchable Plugin - Quick start] \
-# [Mapping|Searchable Plugin - Mapping] \
-## [Class Mapping|Searchable Plugin - Mapping - Class Mapping] \
-## [Class Property Mapping|Searchable Plugin - Mapping - Class Property Mapping] \
-## [Compass annotations|Searchable Plugin - Mapping - Compass annotations] \
-## [Compass XML|Searchable Plugin - Mapping - Compass XML] \
-## [Compass concepts|Searchable Plugin - Mapping - Compass concepts] \
-## [Conventions|Searchable Plugin - Mapping - Conventions] \
-## [Mapping DSL|Searchable Plugin - Mapping - Mapping DSL] \
-## [Not All Properties|Searchable Plugin - Mapping - Not All Properties] \
-## [Searchable Property|Searchable Plugin - Mapping - Searchable Property] \
# [SearchableController and view|Searchable Plugin - SearchableController and view] \
# [Searching|Searchable Plugin - Searching] \
+## [Query strings|Searchable Plugin - Searching - String Queries] \
## [Query Builder|Searchable Plugin - Searching - Query Builder] \
## [Sorting|Searchable Plugin - Searching - Sorting] \
+# [Mapping|Searchable Plugin - Mapping] \
+## [Not All Properties|Searchable Plugin - Mapping - Not All Properties] \
+## [Conventions|Searchable Plugin - Mapping - Conventions] \
+## [Compass concepts|Searchable Plugin - Mapping - Compass concepts] \
+## [Mapping DSL|Searchable Plugin - Mapping - Mapping DSL] \
+## [Class Property Mapping|Searchable Plugin - Mapping - Class Property Mapping] \
+## [Searchable Id|Searchable Plugin - Mapping - Searchable Id] \
+## [Searchable Property|Searchable Plugin - Mapping - Searchable Property] \
+## [Searchable Reference|Searchable Plugin - Mapping - Searchable Reference] \
+## [Searchable Component|Searchable Plugin - Mapping - Searchable Component] \
+## [Class Mapping|Searchable Plugin - Mapping - Class Mapping] \
+## [Compass annotations|Searchable Plugin - Mapping - Compass annotations] \
+## [Compass XML|Searchable Plugin - Mapping - Compass XML] \
# [Managing the index|Searchable Plugin - Managing the index] \
# [Configuration|Searchable Plugin - Configuration] \
+# [Analyzers|Searchable Plugin - Analyzers] \
+# [Converters|Searchable Plugin - Converters] \
# [Debugging|Searchable Plugin - Debugging] \
# [FAQ|Searchable Plugin - FAQ] \
# Methods \
+## [search|Searchable Plugin - Methods - search] \
+## [countHits|Searchable Plugin - Methods - countHits] \
## [moreLikeThis|Searchable Plugin - Methods - moreLikeThis] \
+## [suggestQuery|Searchable Plugin - Methods - suggestQuery] \
+## [termFreqs|Searchable Plugin - Methods - termFreqs]
## [index|Searchable Plugin - Methods - index] \
## [unindex|Searchable Plugin - Methods - unindex] \
## [reindex|Searchable Plugin - Methods - reindex] \
## [rebuildSpellingSuggestions|Searchable Plugin - Methods - rebuildSpellingSuggestions] \
## [startMirroring|Searchable Plugin - Methods - startMirroring] \
## [stopMirroring|Searchable Plugin - Methods - stopMirroring] \
-## [search|Searchable Plugin - Methods - search] \
-## [countHits|Searchable Plugin - Methods - countHits] \
-## [suggestQuery|Searchable Plugin - Methods - suggestQuery] \
-## [termFreqs|Searchable Plugin - Methods - termFreqs]
# [Releases|Searchable Plugin - Releases]
@@ -222,7 +222,7 @@ class Get {
start = resp.indexOf('>', start) + 1
def end = resp.indexOf('</textarea>')
def text = resp.substring(start, end)
- text.replaceAll('&quot;', '"')
+ text.replaceAll('&quot;', '"').replaceAll('&amp;', '&')
}
def getHash(String text) {
@@ -71,18 +71,21 @@ class Put {
if (exists) {
def resp = getPageResponse(client, pageName)
version = findMessageWithin(resp, '<input type="hidden" name="version" value="', '" />')
- hash = getHash(getPageText(resp))
+ def pageText = getPageText(resp, pageName)
+ hash = getHash(pageText)
}
// is it different?
def doUpload = true
if (exists) {
- doUpload = hash != getHash(text)
+ def newHash = getHash(text)
+ doUpload = hash != newHash
+// println "${hash}\n${newHash}\n$doUpload"
}
if (!doUpload) {
return
}
- println "Checking \"${pageName}\" (at ${server + "/save/" + URLEncoder.encode(pageName)})"
+// println "Uploading \"${pageName}\" (at ${server + "/save/" + URLEncoder.encode(pageName)})"
def post = classLoader.loadClass('org.apache.http.client.methods.HttpPost').newInstance(server + "/save/" + URLEncoder.encode(pageName))
post.setEntity(classLoader.loadClass('org.apache.http.entity.StringEntity').newInstance("version=${version}&title=${URLEncoder.encode(pageName)}&body=${URLEncoder.encode(text)}" as String))
post.setHeader('Content-Type', 'application/x-www-form-urlencoded')
@@ -100,7 +103,8 @@ class Put {
def pageExists(client, pageName) {
def get = classLoader.loadClass('org.apache.http.client.methods.HttpGet').newInstance(server + "/" + URLEncoder.encode(pageName))
def resp = responseToText(client.execute(get))
- !resp.contains("NOT_FOUND")
+ //println resp
+ !resp.contains("NOT_FOUND") && !resp.contains("HTTP Status 404")
}
def getPageResponse(client, pageName) {
@@ -141,11 +145,11 @@ class Put {
os.toString()
}
- def getPageText(String resp) {
+ def getPageText(String resp, String pageName) {
def start = resp.indexOf('<textarea ')
if (start == -1) {
println "No wiki content found on page ${pageName}"
- return
+ return null
}
start = resp.indexOf('>', start) + 1
def end = resp.indexOf('</textarea>')

0 comments on commit 95c6faf

Please sign in to comment.