Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 159 lines (114 sloc) 4.604 kB
e31a3c0 @floere + new style documentation
authored
1 ## Integration
2
d242249 @floere + edit links for all the doc sections
authored
3 {.edit}
4 [edit](http://github.com/floere/picky/blob/master/web/source/documentation/_integration.html.md)
5
e31a3c0 @floere + new style documentation
authored
6 How do you integrate Picky in…?
7
8 ### Rails
9
dff7f9a @floere + a start of Rails integration documentation
authored
10 There are basically two basic ways to integrate Picky in Rails:
11
12 * Inside your Rails app
13 * With an external server
14
15 The advantage of the first setup is that you don't need to manage an external server. However, having a separate search server is much cleaner: You don't need to load the indexes on Rails startup as you just leave the search server running separately.
16
17 #### Inside your Rails app
18
19 If you just want a small search engine inside your Rails app, this is the way to go.
20
21 In `config/initializers/picky.rb`, add the following: (lots of comments to help you)
22
23 # Set the Picky logger.
24 #
25 Picky.logger = Picky::Loggers::Silent.new
26 # Picky.logger = Picky::Loggers::Concise.new
27 # Picky.logger = Picky::Loggers::Verbose.new
28
29 # Set up an index and store it in a constant.
30 #
31 BooksIndex = Picky::Index.new :books do
32 # Our keys are usually integers.
33 #
34 key_format :to_i
35 # key_format :to_s # From eg. Redis they are strings.
36 # key_format ... (whatever method needs to be called on
37 # the id of what you are indexing)
38
39 # Some indexing options to start with.
40 # Please see: http://florianhanke.com/picky/documentation.html#tokenizing
41 # on what the options are.
42 #
43 indexing removes_characters: /[^a-z0-9\s\/\-\_\:\"\&\.]/i,
44 stopwords: /\b(and|the|of|it|in|for)\b/i,
45 splits_text_on: /[\s\/\-\_\:\"\&\/]/,
46 rejects_token_if: lambda { |token| token.size < 2 }
47
48 # Define categories on your data.
49 #
50 # They have a lot of options, see:
51 # http://florianhanke.com/picky/documentation.html#indexes-categories
52 #
53 category :title
54 category :subtitle
55 category :author
56 category :isbn,
57 :partial => Picky::Partial::None.new # Only full matches
58 end
59
60 # BookSearch is the search interface
61 # on the books index. More info here:
62 # http://florianhanke.com/picky/documentation.html#search
63 #
64 BookSearch = Picky::Search.new BooksIndex
65
66 # We are explicitly indexing the book data.
67 #
68 Book.all.each { |book| BooksIndex.add book }
69
70 That's already a nice setup. Whenever Rails starts up, this will add all books to the index.
71
72 From anywhere (if you have multiple, call `Picky::Indexes.index` to index all).
73
74 Ok, this sets up the index and the indexing. What about the model?
75
76 In the model, here `app/models/book.rb` add this:
77
78 # Two callbacks.
79 #
80 after_save :picky_index
81 after_destroy :picky_index
82
83 # Updates the Picky index.
84 #
85 def picky_index
86 if destroyed?
87 BooksIndex.remove id
88 else
89 BooksIndex.replace self
90 end
91 end
92
93 I actually recommend to use after_commit since it that would be perfectly correct, but it did not work at the time of writing.
94
95 Now, in the controller, you need to return some results to the user.
96
97 # GET /books/search
98 #
99 def search
100 results = BookSearch.search query, params[:ids] || 20, params[:offset] || 0
101
102 # Render nicely as a partial.
103 #
104 results = results.to_hash
105 results.extend Picky::Convenience
106 results.populate_with Book do |book|
107 render_to_string :partial => "book", :object => book
108 end
109
110 respond_to do |format|
111 format.html do
112 render :text => "Book result ids: #{results.ids.to_s}"
113 end
114 format.json do
115 render :text => results.to_json
116 end
117 end
118 end
119
120 The first line executes the search using query params. You can try this using `curl`:
121
122 curl http://127.0.0.1:4567/books/search?query=test
123
124 The next few lines use the results as a hash, and populate the results with data loaded from the database, rendering a book partial.
125
126 Then, we respond to html with a simple web page, or respond to json with the results.
127
128 As you can see, you can do whatever you want with the results. You could use this in an API, or send simple text to the user, or whatever you want.
129
130 TODO Using the Picky client JavaScript.
131
132 #### External Picky server
133
e31a3c0 @floere + new style documentation
authored
134 TODO
135
dff7f9a @floere + a start of Rails integration documentation
authored
136 #### Advanced Ideas
137
138 TODO Reloading indexes live
139
140 TODO Prepending the current user to filter
141
142 # Prepends the current user filter to
143 # the current query.
144 #
145 query = "user:#{current_user.id} #{params[:query]}"
146
e31a3c0 @floere + new style documentation
authored
147 ### Sinatra
148
149 TODO
150
151 TODO Also mention Padrino.
152
153 ### DRb
154
155 TODO
156
157 ### Ruby Script
158
159 TODO
Something went wrong with that request. Please try again.