Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 147 lines (97 sloc) 5.196 kb
8777f06 @norman Initial commit to 4.0.0
authored
1 # FriendlyId
2
f4fe0cd @laserlemon Add dependency status via Gemnasium to README
laserlemon authored
3 [![Build Status](http://travis-ci.org/norman/friendly_id.png)](http://travis-ci.org/norman/friendly_id) [![Dependency Status](https://gemnasium.com/norman/friendly_id.png)](https://gemnasium.com/norman/friendly_id)
ee73161 @norman Added Travis status image
authored
4
8777f06 @norman Initial commit to 4.0.0
authored
5 FriendlyId is the "Swiss Army bulldozer" of slugging and permalink plugins for
e4045ab @norman Small doc tweaks.
authored
6 Ruby on Rails. It allows you to create pretty URLs and work with human-friendly
a4128af @norman Continued work on docs
authored
7 strings as if they were numeric ids for Active Record models.
8777f06 @norman Initial commit to 4.0.0
authored
8
e4045ab @norman Small doc tweaks.
authored
9 Using FriendlyId, it's easy to make your application use URLs like:
8777f06 @norman Initial commit to 4.0.0
authored
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
e4045ab @norman Small doc tweaks.
authored
23 FriendlyId is compatible with Active Record **3.0** and higher.
8777f06 @norman Initial commit to 4.0.0
authored
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
f4cd421 @norman Prepped final 4.0.0 release
authored
49 gem "friendly_id", "~> 4.0.0"
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
e4045ab @norman Small doc tweaks.
authored
54 add_index :users, :slug, unique: true
8777f06 @norman Initial commit to 4.0.0
authored
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
e4045ab @norman Small doc tweaks.
authored
61 friendly_id :name, use: :slugged
8777f06 @norman Initial commit to 4.0.0
authored
62 end
63
e4045ab @norman Small doc tweaks.
authored
64 User.create! name: "Joe Schmoe"
8777f06 @norman Initial commit to 4.0.0
authored
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…
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.**
e4045ab @norman Small doc tweaks.
authored
90 * Full stack trace and error message (if you have them).
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
e4045ab @norman Small doc tweaks.
authored
97 For more info on how to report bugs, please see [this
98 article](http://yourbugreportneedsmore.info/).
99
aa1fe01 @norman Updated README
authored
100 ## Thanks and Credits
8777f06 @norman Initial commit to 4.0.0
authored
101
bda2b36 @norman Doc tweaks
authored
102 FriendlyId was originally created by Norman Clarke and Adrian Mugnolo, with
103 significant help early in its life by Emilio Tagua. I'm deeply gratful for the
104 generous contributions over the years from [many
8777f06 @norman Initial commit to 4.0.0
authored
105 volunteers](https://github.com/norman/friendly_id/contributors).
106
d261d19 @norman Added note on Slugged
authored
107 Part of the inspiration to rework FriendlyId came from Darcy Laycock's library
108 [Slugged](https://github.com/Sutto/slugged), which he was inspired to create
109 because of frustrations he experienced while using FriendlyId 3.x. Seeing a
110 smart programmer become frustrated with my code was enough of a kick in the
e4045ab @norman Small doc tweaks.
authored
111 butt to make me want to significantly improve this library.
d261d19 @norman Added note on Slugged
authored
112
113 Many thanks to him for providing valid, real criticism while still being a cool
114 about it. I definitely recommend you check out his library if for some reason
115 FriendlyId doesn't do it for you.
116
aa1fe01 @norman Updated README
authored
117 Thanks also to Loren Segal and Nick Plante for YARD and the
118 [rubydoc.info](http://rubydoc.info/) website which FriendlyId uses for
119 documentation.
120
ee73161 @norman Added Travis status image
authored
121 Lastly, FriendlyId uses [Travis](http://travis-ci.org/) for continuous
122 integration. It's an excellent, free service created by a whole bunch of [good
123 people](https://github.com/travis-ci) - if you're not already using it, you
124 should be!
125
aa1fe01 @norman Updated README
authored
126 ## License
127
8777f06 @norman Initial commit to 4.0.0
authored
128 Copyright (c) 2008-2011 Norman Clarke, released under the MIT license.
aa1fe01 @norman Updated README
authored
129
130 Permission is hereby granted, free of charge, to any person obtaining a copy of
131 this software and associated documentation files (the "Software"), to deal in
132 the Software without restriction, including without limitation the rights to
133 use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
134 of the Software, and to permit persons to whom the Software is furnished to do
135 so, subject to the following conditions:
136
137 The above copyright notice and this permission notice shall be included in all
138 copies or substantial portions of the Software.
139
140 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
141 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
142 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
143 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
144 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
145 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
146 SOFTWARE.
Something went wrong with that request. Please try again.