Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 141 lines (92 sloc) 4.772 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
a4128af @norman Continued work on docs
authored
21 versioning, 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
29 docs](http://norman.github.com/friendly_id/file.WhatsNew.html) to see what's
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
37
8777f06 @norman Initial commit to 4.0.0
authored
38 ## Rails Quickstart
39
40 gem install friendly_id
41
42 rails new my_app
43
44 cd my_app
45
f5f28ca @norman Update docs, bump version
authored
46 gem "friendly_id", "~> 4.0.0.beta8"
204c477 @norman Bump version, update README
authored
47
8777f06 @norman Initial commit to 4.0.0
authored
48 rails generate scaffold user name:string slug:string
49
50 # edit db/migrate/*_create_users.rb
51 add_index :users, :slug, :unique => true
52
53 rake db:migrate
54
55 # edit app/models/user.rb
56 class User < ActiveRecord::Base
70c8884 @norman has_friendly_id => friendly_id, and accept "use" arg to load modules
authored
57 extend FriendlyId
58 friendly_id :name, :use => :slugged
8777f06 @norman Initial commit to 4.0.0
authored
59 end
60
61 User.create! :name => "Joe Schmoe"
62
63 rails server
64
65 GET http://localhost:3000/users/joe-schmoe
66
aa1fe01 @norman Updated README
authored
67 # If you're adding FriendlyId to an existing app and need
68 # to generate slugs for existing users, do this from the
69 # console, runner, or add a Rake task:
70 User.all.map(&:save)
f68be81 @norman Added link to docs
authored
71
a4128af @norman Continued work on docs
authored
72
ce7eb3c @norman Worked on documentation.
authored
73 ## Benchmarks
74
75 The latest benchmarks for FriendlyId are maintained
76 [here](https://gist.github.com/1129745).
77
78
8777f06 @norman Initial commit to 4.0.0
authored
79 ## Bugs
80
bda2b36 @norman Doc tweaks
authored
81 Please report them on the [Github issue
82 tracker](http://github.com/norman/friendly_id/issues) for this project.
8777f06 @norman Initial commit to 4.0.0
authored
83
84 If you have a bug to report, please include the following information:
85
86 * **Version information for FriendlyId, Rails and Ruby.**
87 * Stack trace and error message.
aa1fe01 @norman Updated README
authored
88 * Any snippets of relevant model, view or controller code that shows how you
8777f06 @norman Initial commit to 4.0.0
authored
89 are using FriendlyId.
90
91 If you are able to, it helps even more if you can fork FriendlyId on Github,
92 and add a test that reproduces the error you are experiencing.
93
aa1fe01 @norman Updated README
authored
94 ## Thanks and Credits
8777f06 @norman Initial commit to 4.0.0
authored
95
bda2b36 @norman Doc tweaks
authored
96 FriendlyId was originally created by Norman Clarke and Adrian Mugnolo, with
97 significant help early in its life by Emilio Tagua. I'm deeply gratful for the
98 generous contributions over the years from [many
8777f06 @norman Initial commit to 4.0.0
authored
99 volunteers](https://github.com/norman/friendly_id/contributors).
100
d261d19 @norman Added note on Slugged
authored
101 Part of the inspiration to rework FriendlyId came from Darcy Laycock's library
102 [Slugged](https://github.com/Sutto/slugged), which he was inspired to create
103 because of frustrations he experienced while using FriendlyId 3.x. Seeing a
104 smart programmer become frustrated with my code was enough of a kick in the
105 butt to make me want to improve this library significantly.
106
107 Many thanks to him for providing valid, real criticism while still being a cool
108 about it. I definitely recommend you check out his library if for some reason
109 FriendlyId doesn't do it for you.
110
aa1fe01 @norman Updated README
authored
111 Thanks also to Loren Segal and Nick Plante for YARD and the
112 [rubydoc.info](http://rubydoc.info/) website which FriendlyId uses for
113 documentation.
114
ee73161 @norman Added Travis status image
authored
115 Lastly, FriendlyId uses [Travis](http://travis-ci.org/) for continuous
116 integration. It's an excellent, free service created by a whole bunch of [good
117 people](https://github.com/travis-ci) - if you're not already using it, you
118 should be!
119
aa1fe01 @norman Updated README
authored
120 ## License
121
8777f06 @norman Initial commit to 4.0.0
authored
122 Copyright (c) 2008-2011 Norman Clarke, released under the MIT license.
aa1fe01 @norman Updated README
authored
123
124 Permission is hereby granted, free of charge, to any person obtaining a copy of
125 this software and associated documentation files (the "Software"), to deal in
126 the Software without restriction, including without limitation the rights to
127 use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
128 of the Software, and to permit persons to whom the Software is furnished to do
129 so, subject to the following conditions:
130
131 The above copyright notice and this permission notice shall be included in all
132 copies or substantial portions of the Software.
133
134 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
135 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
136 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
137 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
138 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
139 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
140 SOFTWARE.
Something went wrong with that request. Please try again.