Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 144 lines (95 sloc) 4.978 kb
8777f06 @norman Initial commit to 4.0.0
authored
1 # FriendlyId
2
ee73161 @norman Added Travis status image
authored
3 [![Build Status](http://travis-ci.org/norman/friendly_id.png)](http://travis-ci.org/norman/friendly_id)
4
8777f06 @norman Initial commit to 4.0.0
authored
5 FriendlyId is the "Swiss Army bulldozer" of slugging and permalink plugins for
a4128af @norman Continued work on docs
authored
6 Ruby on Rails. It allows you to create pretty URL's and work with human-friendly
7 strings as if they were numeric ids for Active Record models.
8777f06 @norman Initial commit to 4.0.0
authored
8
9 Using FriendlyId, it's easy to make your application use URL's like:
10
11 http://example.com/states/washington
12
13 instead of:
14
15 http://example.com/states/4323454
16
f68be81 @norman Added link to docs
authored
17
8777f06 @norman Initial commit to 4.0.0
authored
18 ## FriendlyId Features
19
20 FriendlyId offers many advanced features, including: slug history and
5453646 @norman i18n now requires locale suffix on all slug columns
authored
21 versioning, i18n, scoped slugs, reserved words, and custom slug generators.
8777f06 @norman Initial commit to 4.0.0
authored
22
23 FriendlyId is compatible with Active Record **3.0** and **3.1**.
24
004d623 @norman Docs tweaks
authored
25 ## Version 4.x
26
f5f28ca @norman Update docs, bump version
authored
27 FriendlyId 4.x introduces many changes incompatible with 3.x. If you're
28 upgrading, please [read the
526c144 @manuelmeurer Fixed doc link
manuelmeurer authored
29 docs](http://rubydoc.info/github/norman/friendly_id/master/file/WhatsNew.md) to see what's
f5f28ca @norman Update docs, bump version
authored
30 new.
004d623 @norman Docs tweaks
authored
31
aa1fe01 @norman Updated README
authored
32 ## Docs
33
ae2ec54 @hectcastro Fixed a small typo in the README.
hectcastro authored
34 The current docs can always be found
aa1fe01 @norman Updated README
authored
35 [here](http://rubydoc.info/github/norman/friendly_id/master/frames).
36
86b0c09 @norman Added generated guide from RDoc
authored
37 The best place to start is with the
82bbce2 @norman Fix Guide URL
authored
38 [Guide](http://rubydoc.info/github/norman/friendly_id/master/file/Guide.rdoc),
86b0c09 @norman Added generated guide from RDoc
authored
39 which compiles the top-level RDocs into one outlined document.
aa1fe01 @norman Updated README
authored
40
8777f06 @norman Initial commit to 4.0.0
authored
41 ## Rails Quickstart
42
43 gem install friendly_id
44
45 rails new my_app
46
47 cd my_app
48
cf42002 @norman Bumped version
authored
49 gem "friendly_id", "~> 4.0.0.beta14"
204c477 @norman Bump version, update README
authored
50
8777f06 @norman Initial commit to 4.0.0
authored
51 rails generate scaffold user name:string slug:string
52
53 # edit db/migrate/*_create_users.rb
54 add_index :users, :slug, :unique => true
55
56 rake db:migrate
57
58 # edit app/models/user.rb
59 class User < ActiveRecord::Base
70c8884 @norman has_friendly_id => friendly_id, and accept "use" arg to load modules
authored
60 extend FriendlyId
61 friendly_id :name, :use => :slugged
8777f06 @norman Initial commit to 4.0.0
authored
62 end
63
64 User.create! :name => "Joe Schmoe"
65
66 rails server
67
68 GET http://localhost:3000/users/joe-schmoe
69
aa1fe01 @norman Updated README
authored
70 # If you're adding FriendlyId to an existing app and need
71 # to generate slugs for existing users, do this from the
72 # console, runner, or add a Rake task:
1be839f @manuelmeurer Use `find_each` instead of `all`, since there might be a lot of users an...
manuelmeurer authored
73 User.find_each(&:save)
f68be81 @norman Added link to docs
authored
74
a4128af @norman Continued work on docs
authored
75
ce7eb3c @norman Worked on documentation.
authored
76 ## Benchmarks
77
78 The latest benchmarks for FriendlyId are maintained
aa40f56 @norman Improve peformance of finds using old friendly_id
authored
79 [here](http://bit.ly/friendly-id-benchmarks).
ce7eb3c @norman Worked on documentation.
authored
80
81
8777f06 @norman Initial commit to 4.0.0
authored
82 ## Bugs
83
bda2b36 @norman Doc tweaks
authored
84 Please report them on the [Github issue
85 tracker](http://github.com/norman/friendly_id/issues) for this project.
8777f06 @norman Initial commit to 4.0.0
authored
86
87 If you have a bug to report, please include the following information:
88
89 * **Version information for FriendlyId, Rails and Ruby.**
90 * Stack trace and error message.
aa1fe01 @norman Updated README
authored
91 * Any snippets of relevant model, view or controller code that shows how you
8777f06 @norman Initial commit to 4.0.0
authored
92 are using FriendlyId.
93
94 If you are able to, it helps even more if you can fork FriendlyId on Github,
95 and add a test that reproduces the error you are experiencing.
96
aa1fe01 @norman Updated README
authored
97 ## Thanks and Credits
8777f06 @norman Initial commit to 4.0.0
authored
98
bda2b36 @norman Doc tweaks
authored
99 FriendlyId was originally created by Norman Clarke and Adrian Mugnolo, with
100 significant help early in its life by Emilio Tagua. I'm deeply gratful for the
101 generous contributions over the years from [many
8777f06 @norman Initial commit to 4.0.0
authored
102 volunteers](https://github.com/norman/friendly_id/contributors).
103
d261d19 @norman Added note on Slugged
authored
104 Part of the inspiration to rework FriendlyId came from Darcy Laycock's library
105 [Slugged](https://github.com/Sutto/slugged), which he was inspired to create
106 because of frustrations he experienced while using FriendlyId 3.x. Seeing a
107 smart programmer become frustrated with my code was enough of a kick in the
108 butt to make me want to improve this library significantly.
109
110 Many thanks to him for providing valid, real criticism while still being a cool
111 about it. I definitely recommend you check out his library if for some reason
112 FriendlyId doesn't do it for you.
113
aa1fe01 @norman Updated README
authored
114 Thanks also to Loren Segal and Nick Plante for YARD and the
115 [rubydoc.info](http://rubydoc.info/) website which FriendlyId uses for
116 documentation.
117
ee73161 @norman Added Travis status image
authored
118 Lastly, FriendlyId uses [Travis](http://travis-ci.org/) for continuous
119 integration. It's an excellent, free service created by a whole bunch of [good
120 people](https://github.com/travis-ci) - if you're not already using it, you
121 should be!
122
aa1fe01 @norman Updated README
authored
123 ## License
124
8777f06 @norman Initial commit to 4.0.0
authored
125 Copyright (c) 2008-2011 Norman Clarke, released under the MIT license.
aa1fe01 @norman Updated README
authored
126
127 Permission is hereby granted, free of charge, to any person obtaining a copy of
128 this software and associated documentation files (the "Software"), to deal in
129 the Software without restriction, including without limitation the rights to
130 use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
131 of the Software, and to permit persons to whom the Software is furnished to do
132 so, subject to the following conditions:
133
134 The above copyright notice and this permission notice shall be included in all
135 copies or substantial portions of the Software.
136
137 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
138 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
139 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
140 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
141 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
142 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
143 SOFTWARE.
Something went wrong with that request. Please try again.