stringex 2.8.4 → 2.8.6
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/README.md +162 -0
- data/VERSION +1 -1
- data/lib/stringex/acts_as_url/adapter/base.rb +5 -1
- data/stringex.gemspec +14 -35
- data/test/unit/acts_as_url/adapter/activerecord.rb +1 -1
- data/test/unit/acts_as_url/adapter/mongoid.rb +1 -1
- metadata +7 -9
- data/README.rdoc +0 -150
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 1b26eaa16536e306141877a8ee3f50acdd23d8cb3601fe1830ccf798e7a2b433
|
|
4
|
+
data.tar.gz: 8062ea4ee5667139acb8337fa979d212ab1ef52a69a1303efd302df142c83c8c
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 7179fa45397f05d438470e2ae225e0e4ac03a6f0cf2922af031ca4e7c68bb7be20d8d833bab9f928782687ccc78f5cdac30142a2923941e23441616b948b3041
|
|
7
|
+
data.tar.gz: b42d191422c1340122677106d7360a05ec6c41f30206f577701a276ac253509a3f4553a5f628b383b3aed4fa293e4c0b7498eb0466cc565eeaefe576e9ebba08
|
data/README.md
ADDED
|
@@ -0,0 +1,162 @@
|
|
|
1
|
+
# Stringex [<img src="https://codeclimate.com/github/rsl/stringex.svg" />](https://codeclimate.com/github/rsl/stringex) [<img src="https://travis-ci.org/rsl/stringex.svg?branch=master" alt="Build Status" />](https://travis-ci.org/rsl/stringex) [<img src="https://badge.fury.io/rb/stringex.svg" alt="Gem Version" />](http://badge.fury.io/rb/stringex)
|
|
2
|
+
|
|
3
|
+
Some [hopefully] useful extensions to Ruby's String class. It is made up of three libraries: ActsAsUrl, Unidecoder, and StringExtensions.
|
|
4
|
+
|
|
5
|
+
*NOTE: Stringex 2.0 [and beyond] drops support for Rails 2. If you need support for that version, use 1.5.1 instead.*
|
|
6
|
+
|
|
7
|
+
## ActsAsUrl
|
|
8
|
+
|
|
9
|
+
*NOTE: You can now require 'stringex_lite' instead of 'stringex' and skip loading ActsAsUrl functionality if you don't need it.*
|
|
10
|
+
|
|
11
|
+
This library is designed to create URI-friendly representations of an attribute, for use in generating urls from your attributes. Basic usage is just calling the method:
|
|
12
|
+
|
|
13
|
+
```ruby
|
|
14
|
+
# Inside your model
|
|
15
|
+
acts_as_url :title
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
which will populate the `url` attribute on the object with the converted contents of the `title` attribute. `acts_as_url` takes the following options:
|
|
19
|
+
|
|
20
|
+
| | |
|
|
21
|
+
|---|---|
|
|
22
|
+
| `:url_attribute` | The name of the attribute to use for storing the generated url string. Default is `:url` |
|
|
23
|
+
| `:scope` | The name of model attribute to scope unique urls to. There is no default here. |
|
|
24
|
+
| `:only_when_blank` | If set to true, the url generation will only happen when `:url_attribute` is blank. Default is false (meaning url generation will happen always). |
|
|
25
|
+
| `:sync_url` | If set to true, the url field will be updated when changes are made to the attribute it is based on. Default is false. |
|
|
26
|
+
| `:allow_slash` | If set to true, the url field will not convert slashes. Default is false. |
|
|
27
|
+
| `:allow_duplicates` | If set to true, unique urls will not be enforced. Default is false. *NOTE: This is strongly not recommended if you are routing solely on the generated slug as you will no longer be guaranteed to lookup the expected record based on a duplicate slug.* |
|
|
28
|
+
| `:limit` | If set, will limit length of url generated. Default is nil. |
|
|
29
|
+
| `:truncate_words` | Used with :limit. If set to false, the url will be truncated to the last whole word before the limit was reached. Default is true. |
|
|
30
|
+
| `:blacklist` | List of urls that should not be allowed. Default is `%w{new}` [which avoids confusion on urls like `/documents/new`]. |
|
|
31
|
+
| `:blacklist_policy` | Proc or lambda defining new naming behavior when blacklisted urls are encountered. Default converts `/documents/new` to `/documents/new-document`. |
|
|
32
|
+
|
|
33
|
+
In order to use the generated url attribute, you will probably want to
|
|
34
|
+
override `to_param` like so, in your Model:
|
|
35
|
+
|
|
36
|
+
```ruby
|
|
37
|
+
# Inside your model
|
|
38
|
+
def to_param
|
|
39
|
+
url # or whatever you set :url_attribute to
|
|
40
|
+
end
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
Routing called via named routes like `foo_path(@foo)` will automatically use the url. In your controllers you will need to call
|
|
44
|
+
`Foo.find_by_url(params[:id])` instead of the regular find. Don't look for `params[:url]` unless you set it explicitly in the routing, `to_param` will generate `params[:id]`.
|
|
45
|
+
|
|
46
|
+
Note that if you add `acts_as_url` to an existing model, the `url` database column will initially be blank. To set this column for your existing instances, you can use the `initialize_urls` method. So if your class is `Post`, just say `Post.initialize_urls`.
|
|
47
|
+
|
|
48
|
+
Unlike other permalink solutions, ActsAsUrl doesn't rely on Iconv (which is inconsistent across platforms and doesn't provide great transliteration as is) but instead uses a transliteration scheme (see the code for Unidecoder) which produces much better results for Unicode characters. It also mixes in some custom helpers to translate common characters into a more URI-friendly format rather than just dump them completely. Examples:
|
|
49
|
+
|
|
50
|
+
```ruby
|
|
51
|
+
# A simple prelude
|
|
52
|
+
"simple English".to_url => "simple-english"
|
|
53
|
+
"it's nothing at all".to_url => "its-nothing-at-all"
|
|
54
|
+
"rock & roll".to_url => "rock-and-roll"
|
|
55
|
+
|
|
56
|
+
# Let's show off
|
|
57
|
+
"$12 worth of Ruby power".to_url => "12-dollars-worth-of-ruby-power"
|
|
58
|
+
"10% off if you act now".to_url => "10-percent-off-if-you-act-now"
|
|
59
|
+
|
|
60
|
+
# You dont EVEN wanna rely on Iconv for this next part
|
|
61
|
+
"kick it en Français".to_url => "kick-it-en-francais"
|
|
62
|
+
"rock it Español style".to_url => "rock-it-espanol-style"
|
|
63
|
+
"tell your readers 你好".to_url => "tell-your-readers-ni-hao"
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
Compare those results with the ones produced on my Intel Mac by a leading permalink plugin:
|
|
67
|
+
|
|
68
|
+
```ruby
|
|
69
|
+
"simple English" # => "simple-english"
|
|
70
|
+
"it's nothing at all" # => "it-s-nothing-at-all"
|
|
71
|
+
"rock & roll" # => "rock-roll"
|
|
72
|
+
|
|
73
|
+
"$12 worth of Ruby power" # => "12-worth-of-ruby-power"
|
|
74
|
+
"10% off if you act now" # => "10-off-if-you-act-now"
|
|
75
|
+
|
|
76
|
+
"kick it en Français" # => "kick-it-en-francais"
|
|
77
|
+
"rock it Español style" # => "rock-it-espan-ol-style"
|
|
78
|
+
"tell your readers 你好" # => "tell-your-readers"
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
Not so great, actually.
|
|
82
|
+
|
|
83
|
+
Note: No offense is intended to the author(s) of whatever plugins might produce such results. It's not your faults Iconv sucks.
|
|
84
|
+
|
|
85
|
+
## Unidecoder
|
|
86
|
+
|
|
87
|
+
This library converts Unicode [and accented ASCII] characters to their plain-text ASCII equivalents. This is a port of Perl's Unidecode and provides eminently superior and more reliable results than Iconv. (Seriously, Iconv... A plague on both your houses! [sic])
|
|
88
|
+
|
|
89
|
+
You may require only the unidecoder (and its dependent localization) via
|
|
90
|
+
|
|
91
|
+
```ruby
|
|
92
|
+
require "stringex/unidecoder"
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
You probably won't ever need to run Unidecoder by itself. Thus, you probably would want to add String#to_ascii which wraps all of Unidecoder's functionality, by requiring:
|
|
96
|
+
|
|
97
|
+
```ruby
|
|
98
|
+
require "stringex/core_ext"
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
For anyone interested, details of the implementation can be read about in the original implementation of [Text::Unidecode](http://interglacial.com/~sburke/tpj/as_html/tpj22.html). Extensive examples can be found in the tests.
|
|
102
|
+
|
|
103
|
+
## StringExtensions
|
|
104
|
+
|
|
105
|
+
A small collection of extensions on Ruby's String class. Please see the documentation for StringExtensions module for more information. There's not much to explain about them really.
|
|
106
|
+
|
|
107
|
+
## Localization
|
|
108
|
+
|
|
109
|
+
With Stringex version 2.0 and higher, you can localize the different conversions in Stringex. Read more [here](https://github.com/rsl/stringex/wiki/Localization-of-Stringex-conversions). If you add a new language, please submit a pull request so we can make it available to other users also.
|
|
110
|
+
|
|
111
|
+
## Ruby on Rails Usage
|
|
112
|
+
|
|
113
|
+
When using Stringex with Ruby on Rails, you automatically get built-in translations for miscellaneous characters, HTML entities, and vulgar fractions. You can see Stringex's standard translations [here](https://github.com/rsl/stringex/tree/master/locales).
|
|
114
|
+
|
|
115
|
+
Currently, built-in translations are available for the following languages:
|
|
116
|
+
|
|
117
|
+
* English (en)
|
|
118
|
+
* Danish (da)
|
|
119
|
+
* Swedish (sv)
|
|
120
|
+
* Dutch (nl)
|
|
121
|
+
* German (de)
|
|
122
|
+
* Polish (pl)
|
|
123
|
+
* Portuguese Brazilian (pt-BR)
|
|
124
|
+
* Russian (ru)
|
|
125
|
+
|
|
126
|
+
You can easily add your own or customize the built-in translations - read [here](https://github.com/rsl/stringex/wiki/Localization-of-Stringex-conversions). If you add a new language, please submit a pull request so we can make it available to other users also.
|
|
127
|
+
|
|
128
|
+
If you don't want to use the Stringex built-in translations, you can force Stringex to use English (or another language), regardless what is in your `I18n.locale`. In an initializer, e.g. `config/initializers/stringex.rb`:
|
|
129
|
+
|
|
130
|
+
```ruby
|
|
131
|
+
Stringex::Localization.locale = :en
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
## CanCan Usage Note
|
|
135
|
+
|
|
136
|
+
You'll need to add a `:find_by => :url` to your `load_and_authorize_resource`. Here's an example:
|
|
137
|
+
|
|
138
|
+
```ruby
|
|
139
|
+
load_and_authorize_resource :class => "Whatever", :message => "Not authorized", :find_by => :url
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
## Semantic Versioning
|
|
143
|
+
|
|
144
|
+
This project conforms to [semver](http://semver.org/). As a result of this policy, you can (and should) specify a dependency on this gem using the [Pessimistic Version Constraint](http://guides.rubygems.org/patterns/) with two digits of precision. For example:
|
|
145
|
+
|
|
146
|
+
```ruby
|
|
147
|
+
spec.add_dependency 'stringex', '~> 1.0'
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
This means your project is compatible with licensee 1.0 up until 2.0. You can also set a higher minimum version:
|
|
151
|
+
|
|
152
|
+
```ruby
|
|
153
|
+
spec.add_dependency 'stringex', '~> 1.1'
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
## Thanks & Acknowledgements
|
|
157
|
+
|
|
158
|
+
If it's not obvious, some of the code for ActsAsUrl is based on Rick Olsen's [permalink_fu](http://svn.techno-weenie.net/projects/plugins/permalink_fu/) plugin. Unidecoder is a Ruby port of Sean Burke's [Text::Unidecode](http://interglacial.com/~sburke/tpj/as_html/tpj22.html) module for Perl. And, finally, the bulk of [strip_html_tags](classes/Stringex/StringExtensions.html#M000005) in StringExtensions was stolen from Tobias Lütke's Regex in [Typo](http://typosphere.org/).
|
|
159
|
+
|
|
160
|
+
GIANT thanks to the many contributors who have helped make Stringex better and better: http://github.com/rsl/stringex/contributors
|
|
161
|
+
|
|
162
|
+
Copyright (c) 2008-2018 Lucky Sneaks, released under the MIT license
|
data/VERSION
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
2.8.
|
|
1
|
+
2.8.6
|
|
@@ -70,7 +70,11 @@ module Stringex
|
|
|
70
70
|
end
|
|
71
71
|
|
|
72
72
|
def create_callback
|
|
73
|
-
klass.send
|
|
73
|
+
klass.send(
|
|
74
|
+
klass_callback_method,
|
|
75
|
+
:ensure_unique_url,
|
|
76
|
+
**callback_options
|
|
77
|
+
)
|
|
74
78
|
end
|
|
75
79
|
|
|
76
80
|
def klass_callback_method
|
data/stringex.gemspec
CHANGED
|
@@ -2,26 +2,25 @@
|
|
|
2
2
|
# DO NOT EDIT THIS FILE DIRECTLY
|
|
3
3
|
# Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
|
|
4
4
|
# -*- encoding: utf-8 -*-
|
|
5
|
-
# stub: stringex 2.8.
|
|
5
|
+
# stub: stringex 2.8.6 ruby lib
|
|
6
6
|
|
|
7
7
|
Gem::Specification.new do |s|
|
|
8
8
|
s.name = "stringex".freeze
|
|
9
|
-
s.version = "2.8.
|
|
9
|
+
s.version = "2.8.6"
|
|
10
10
|
|
|
11
11
|
s.required_rubygems_version = Gem::Requirement.new(">= 0".freeze) if s.respond_to? :required_rubygems_version=
|
|
12
12
|
s.require_paths = ["lib".freeze]
|
|
13
13
|
s.authors = ["Russell Norris".freeze]
|
|
14
|
-
s.date = "
|
|
14
|
+
s.date = "2023-04-19"
|
|
15
15
|
s.description = "Some [hopefully] useful extensions to Ruby's String class. Stringex is made up of three libraries: ActsAsUrl [permalink solution with better character translation], Unidecoder [Unicode to ASCII transliteration], and StringExtensions [miscellaneous helper methods for the String class].".freeze
|
|
16
16
|
s.email = "rsl@luckysneaks.com".freeze
|
|
17
17
|
s.extra_rdoc_files = [
|
|
18
|
-
"MIT-LICENSE"
|
|
19
|
-
"README.rdoc"
|
|
18
|
+
"MIT-LICENSE"
|
|
20
19
|
]
|
|
21
20
|
s.files = [
|
|
22
21
|
"Gemfile",
|
|
23
22
|
"MIT-LICENSE",
|
|
24
|
-
"README.
|
|
23
|
+
"README.md",
|
|
25
24
|
"Rakefile",
|
|
26
25
|
"VERSION",
|
|
27
26
|
"init.rb",
|
|
@@ -275,37 +274,17 @@ Gem::Specification.new do |s|
|
|
|
275
274
|
s.homepage = "http://github.com/rsl/stringex".freeze
|
|
276
275
|
s.licenses = ["MIT".freeze]
|
|
277
276
|
s.rdoc_options = ["--main".freeze, "README.rdoc".freeze, "--charset".freeze, "utf-8".freeze, "--line-numbers".freeze]
|
|
278
|
-
s.rubygems_version = "
|
|
277
|
+
s.rubygems_version = "3.4.9".freeze
|
|
279
278
|
s.summary = "Some [hopefully] useful extensions to Ruby's String class".freeze
|
|
280
279
|
|
|
281
|
-
|
|
282
|
-
s.specification_version = 4
|
|
280
|
+
s.specification_version = 4
|
|
283
281
|
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
s.add_development_dependency(%q<i18n>.freeze, ["= 0.7.0"])
|
|
292
|
-
else
|
|
293
|
-
s.add_dependency(%q<jeweler>.freeze, ["= 2.3.7"])
|
|
294
|
-
s.add_dependency(%q<travis-lint>.freeze, ["= 1.7.0"])
|
|
295
|
-
s.add_dependency(%q<RedCloth>.freeze, ["= 4.2.9"])
|
|
296
|
-
s.add_dependency(%q<sqlite3>.freeze, ["= 1.3.10"])
|
|
297
|
-
s.add_dependency(%q<test-unit>.freeze, ["= 3.0.9"])
|
|
298
|
-
s.add_dependency(%q<activerecord>.freeze, ["= 5.1.4"])
|
|
299
|
-
s.add_dependency(%q<i18n>.freeze, ["= 0.7.0"])
|
|
300
|
-
end
|
|
301
|
-
else
|
|
302
|
-
s.add_dependency(%q<jeweler>.freeze, ["= 2.3.7"])
|
|
303
|
-
s.add_dependency(%q<travis-lint>.freeze, ["= 1.7.0"])
|
|
304
|
-
s.add_dependency(%q<RedCloth>.freeze, ["= 4.2.9"])
|
|
305
|
-
s.add_dependency(%q<sqlite3>.freeze, ["= 1.3.10"])
|
|
306
|
-
s.add_dependency(%q<test-unit>.freeze, ["= 3.0.9"])
|
|
307
|
-
s.add_dependency(%q<activerecord>.freeze, ["= 5.1.4"])
|
|
308
|
-
s.add_dependency(%q<i18n>.freeze, ["= 0.7.0"])
|
|
309
|
-
end
|
|
282
|
+
s.add_development_dependency(%q<jeweler>.freeze, ["= 2.3.7"])
|
|
283
|
+
s.add_development_dependency(%q<travis-lint>.freeze, ["= 1.7.0"])
|
|
284
|
+
s.add_development_dependency(%q<RedCloth>.freeze, ["= 4.2.9"])
|
|
285
|
+
s.add_development_dependency(%q<sqlite3>.freeze, ["= 1.3.10"])
|
|
286
|
+
s.add_development_dependency(%q<test-unit>.freeze, ["= 3.0.9"])
|
|
287
|
+
s.add_development_dependency(%q<activerecord>.freeze, ["= 5.1.4"])
|
|
288
|
+
s.add_development_dependency(%q<i18n>.freeze, ["= 0.7.0"])
|
|
310
289
|
end
|
|
311
290
|
|
metadata
CHANGED
|
@@ -1,14 +1,14 @@
|
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
|
2
2
|
name: stringex
|
|
3
3
|
version: !ruby/object:Gem::Version
|
|
4
|
-
version: 2.8.
|
|
4
|
+
version: 2.8.6
|
|
5
5
|
platform: ruby
|
|
6
6
|
authors:
|
|
7
7
|
- Russell Norris
|
|
8
|
-
autorequire:
|
|
8
|
+
autorequire:
|
|
9
9
|
bindir: bin
|
|
10
10
|
cert_chain: []
|
|
11
|
-
date:
|
|
11
|
+
date: 2023-04-19 00:00:00.000000000 Z
|
|
12
12
|
dependencies:
|
|
13
13
|
- !ruby/object:Gem::Dependency
|
|
14
14
|
name: jeweler
|
|
@@ -117,11 +117,10 @@ executables: []
|
|
|
117
117
|
extensions: []
|
|
118
118
|
extra_rdoc_files:
|
|
119
119
|
- MIT-LICENSE
|
|
120
|
-
- README.rdoc
|
|
121
120
|
files:
|
|
122
121
|
- Gemfile
|
|
123
122
|
- MIT-LICENSE
|
|
124
|
-
- README.
|
|
123
|
+
- README.md
|
|
125
124
|
- Rakefile
|
|
126
125
|
- VERSION
|
|
127
126
|
- init.rb
|
|
@@ -375,7 +374,7 @@ homepage: http://github.com/rsl/stringex
|
|
|
375
374
|
licenses:
|
|
376
375
|
- MIT
|
|
377
376
|
metadata: {}
|
|
378
|
-
post_install_message:
|
|
377
|
+
post_install_message:
|
|
379
378
|
rdoc_options:
|
|
380
379
|
- "--main"
|
|
381
380
|
- README.rdoc
|
|
@@ -395,9 +394,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
|
|
|
395
394
|
- !ruby/object:Gem::Version
|
|
396
395
|
version: '0'
|
|
397
396
|
requirements: []
|
|
398
|
-
|
|
399
|
-
|
|
400
|
-
signing_key:
|
|
397
|
+
rubygems_version: 3.4.9
|
|
398
|
+
signing_key:
|
|
401
399
|
specification_version: 4
|
|
402
400
|
summary: Some [hopefully] useful extensions to Ruby's String class
|
|
403
401
|
test_files: []
|
data/README.rdoc
DELETED
|
@@ -1,150 +0,0 @@
|
|
|
1
|
-
= Stringex {<img src="https://codeclimate.com/github/rsl/stringex.png" />}[https://codeclimate.com/github/rsl/stringex] {<img src="https://travis-ci.org/rsl/stringex.png?branch=master" alt="Build Status" />}[https://travis-ci.org/rsl/stringex] {<img src="https://badge.fury.io/rb/stringex.svg" alt="Gem Version" />}[http://badge.fury.io/rb/stringex]
|
|
2
|
-
|
|
3
|
-
Some [hopefully] useful extensions to Ruby's String class. It is made up of three libraries: ActsAsUrl, Unidecoder, and StringExtensions.
|
|
4
|
-
|
|
5
|
-
<em>NOTE: Stringex 2.0 [and beyond] drops support for Rails 2. If you need support for that version, use 1.5.1 instead.</em>
|
|
6
|
-
|
|
7
|
-
== ActsAsUrl
|
|
8
|
-
|
|
9
|
-
<em>NOTE: You can now require 'stringex_lite' instead of 'stringex' and skip loading ActsAsUrl functionality if you don't need it.</em>
|
|
10
|
-
|
|
11
|
-
This library is designed to create URI-friendly representations of an attribute, for use in generating urls from your attributes. Basic usage is just calling the method:
|
|
12
|
-
|
|
13
|
-
# Inside your model
|
|
14
|
-
acts_as_url :title
|
|
15
|
-
|
|
16
|
-
which will populate the <tt>url</tt> attribute on the object with the converted contents of the <tt>title</tt> attribute.
|
|
17
|
-
<tt>acts_as_url</tt> takes the following options:
|
|
18
|
-
|
|
19
|
-
<tt>:url_attribute</tt>:: The name of the attribute to use for storing the generated url string.
|
|
20
|
-
Default is <tt>:url</tt>
|
|
21
|
-
<tt>:scope</tt>:: The name of model attribute to scope unique urls to. There is no default here.
|
|
22
|
-
<tt>:only_when_blank</tt>:: If set to true, the url generation will only happen when <tt>:url_attribute</tt> is
|
|
23
|
-
blank. Default is false (meaning url generation will happen always).
|
|
24
|
-
<tt>:sync_url</tt>:: If set to true, the url field will be updated when changes are made to the
|
|
25
|
-
attribute it is based on. Default is false.
|
|
26
|
-
<tt>:allow_slash</tt>:: If set to true, the url field will not convert slashes. Default is false.
|
|
27
|
-
<tt>:allow_duplicates</tt>:: If set to true, unique urls will not be enforced.
|
|
28
|
-
Default is false. <em>NOTE: This is strongly not recommended
|
|
29
|
-
if you are routing solely on the generated slug as you will no longer
|
|
30
|
-
be guaranteed to lookup the expected record based on a duplicate slug.</em>
|
|
31
|
-
<tt>:limit</tt>:: If set, will limit length of url generated. Default is nil.
|
|
32
|
-
<tt>:truncate_words</tt>:: Used with :limit. If set to false, the url will be truncated to the last
|
|
33
|
-
whole word before the limit was reached. Default is true.
|
|
34
|
-
<tt>:blacklist</tt>:: List of urls that should not be allowed. Default is <tt>%w{new}</tt> [which avoids confusion
|
|
35
|
-
on urls like <tt>/documents/new</tt>].
|
|
36
|
-
<tt>:blacklist_policy</tt>:: Proc or lambda defining new naming behavior when blacklisted urls are encountered.
|
|
37
|
-
Default converts <tt>/documents/new</tt> to <tt>/documents/new-document</tt>.
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
In order to use the generated url attribute, you will probably want to override <tt>to_param</tt> like so, in your Model:
|
|
41
|
-
|
|
42
|
-
# Inside your model
|
|
43
|
-
def to_param
|
|
44
|
-
url # or whatever you set :url_attribute to
|
|
45
|
-
end
|
|
46
|
-
|
|
47
|
-
Routing called via named routes like <tt>foo_path(@foo)</tt> will automatically use the url. In your controllers you will need to call <tt>Foo.find_by_url(params[:id])</tt> instead of the regular find. Don't look for <tt>params[:url]</tt> unless you set it explicitly in the routing, <tt>to_param</tt> will generate <tt>params[:id]</tt>.
|
|
48
|
-
|
|
49
|
-
Note that if you add <tt>acts_as_url</tt> to an existing model, the <tt>url</tt> database column will initially be blank. To set this column for your existing instances, you can use the <tt>initialize_urls</tt> method. So if your class is <tt>Post</tt>, just say <tt>Post.initialize_urls</tt>.
|
|
50
|
-
|
|
51
|
-
Unlike other permalink solutions, ActsAsUrl doesn't rely on Iconv (which is inconsistent across platforms and doesn't provide great transliteration as is) but instead uses a transliteration scheme (see the code for Unidecoder) which produces much better results for Unicode characters. It also mixes in some custom helpers to translate common characters into a more URI-friendly format rather than just dump them completely. Examples:
|
|
52
|
-
|
|
53
|
-
# A simple prelude
|
|
54
|
-
"simple English".to_url => "simple-english"
|
|
55
|
-
"it's nothing at all".to_url => "its-nothing-at-all"
|
|
56
|
-
"rock & roll".to_url => "rock-and-roll"
|
|
57
|
-
|
|
58
|
-
# Let's show off
|
|
59
|
-
"$12 worth of Ruby power".to_url => "12-dollars-worth-of-ruby-power"
|
|
60
|
-
"10% off if you act now".to_url => "10-percent-off-if-you-act-now"
|
|
61
|
-
|
|
62
|
-
# You dont EVEN wanna rely on Iconv for this next part
|
|
63
|
-
"kick it en Français".to_url => "kick-it-en-francais"
|
|
64
|
-
"rock it Español style".to_url => "rock-it-espanol-style"
|
|
65
|
-
"tell your readers 你好".to_url => "tell-your-readers-ni-hao"
|
|
66
|
-
|
|
67
|
-
Compare those results with the ones produced on my Intel Mac by a leading permalink plugin:
|
|
68
|
-
|
|
69
|
-
"simple English" # => "simple-english"
|
|
70
|
-
"it's nothing at all" # => "it-s-nothing-at-all"
|
|
71
|
-
"rock & roll" # => "rock-roll"
|
|
72
|
-
|
|
73
|
-
"$12 worth of Ruby power" # => "12-worth-of-ruby-power"
|
|
74
|
-
"10% off if you act now" # => "10-off-if-you-act-now"
|
|
75
|
-
|
|
76
|
-
"kick it en Français" # => "kick-it-en-francais"
|
|
77
|
-
"rock it Español style" # => "rock-it-espan-ol-style"
|
|
78
|
-
"tell your readers 你好" # => "tell-your-readers"
|
|
79
|
-
|
|
80
|
-
Not so great, actually.
|
|
81
|
-
|
|
82
|
-
Note: No offense is intended to the author[s] of whatever plugins might produce such results. It's not your faults Iconv sucks.
|
|
83
|
-
|
|
84
|
-
== Unidecoder
|
|
85
|
-
|
|
86
|
-
This library converts Unicode [and accented ASCII] characters to their plain-text ASCII equivalents. This is a port of Perl's Unidecode and provides eminently superior and more reliable results than Iconv. (Seriously, Iconv... A plague on both your houses! [sic])
|
|
87
|
-
|
|
88
|
-
You may require only the unidecoder (and its dependent localization) via
|
|
89
|
-
|
|
90
|
-
require "stringex/unidecoder"
|
|
91
|
-
|
|
92
|
-
You probably won't ever need to run Unidecoder by itself. Thus, you probably would want to add String#to_ascii which wraps all of Unidecoder's functionality, by requiring:
|
|
93
|
-
|
|
94
|
-
require "stringex/core_ext"
|
|
95
|
-
|
|
96
|
-
For anyone interested, details of the implementation can be read about in the original implementation of Text::Unidecode[http://interglacial.com/~sburke/tpj/as_html/tpj22.html]. Extensive examples can be found in the tests.
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
== StringExtensions
|
|
100
|
-
|
|
101
|
-
A small collection of extensions on Ruby's String class. Please see the documentation for StringExtensions module for more information. There's not much to explain about them really.
|
|
102
|
-
|
|
103
|
-
== Localization
|
|
104
|
-
|
|
105
|
-
With Stringex version 2.0 and higher, you can localize the different conversions in Stringex. Read more here[https://github.com/rsl/stringex/wiki/Localization-of-Stringex-conversions]. If you add a new language, please submit a pull request so we can make it available to other users also.
|
|
106
|
-
|
|
107
|
-
== Ruby on Rails Usage
|
|
108
|
-
|
|
109
|
-
When using Stringex with Ruby on Rails, you automatically get built-in translations for miscellaneous characters, HTML entities, and vulgar fractions. You can see Stringex's standard translations here[https://github.com/rsl/stringex/tree/master/locales].
|
|
110
|
-
|
|
111
|
-
Currently, built-in translations are available for the following languages:
|
|
112
|
-
|
|
113
|
-
* English (en)
|
|
114
|
-
* Danish (da)
|
|
115
|
-
* Swedish (sv)
|
|
116
|
-
* Dutch (nl)
|
|
117
|
-
* German (de)
|
|
118
|
-
* Polish (pl)
|
|
119
|
-
* Portuguese Brazilian (pt-BR)
|
|
120
|
-
* Russian (ru)
|
|
121
|
-
|
|
122
|
-
You can easily add your own or customize the built-in translations - read here[https://github.com/rsl/stringex/wiki/Localization-of-Stringex-conversions]. If you add a new language, please submit a pull request so we can make it available to other users also.
|
|
123
|
-
|
|
124
|
-
If you don't want to use the Stringex built-in translations, you can force Stringex to use English (or another language), regardless what is in your +I18n.locale+. In an initializer, e.g. +config/initializers/stringex.rb+:
|
|
125
|
-
|
|
126
|
-
Stringex::Localization.locale = :en
|
|
127
|
-
|
|
128
|
-
== CanCan Usage Note
|
|
129
|
-
|
|
130
|
-
You'll need to add a <tt>:find_by => :url</tt> to your <tt>load_and_authorize_resource</tt>. Here's an example:
|
|
131
|
-
|
|
132
|
-
load_and_authorize_resource :class => "Whatever", :message => "Not authorized", :find_by => :url
|
|
133
|
-
|
|
134
|
-
== Semantic Versioning
|
|
135
|
-
|
|
136
|
-
This project conforms to [semver](http://semver.org/). As a result of this policy, you can (and should) specify a dependency on this gem using the [Pessimistic Version Constraint](http://guides.rubygems.org/patterns/) with two digits of precision. For example:
|
|
137
|
-
|
|
138
|
-
spec.add_dependency 'stringex', '~> 1.0'
|
|
139
|
-
|
|
140
|
-
This means your project is compatible with licensee 1.0 up until 2.0. You can also set a higher minimum version:
|
|
141
|
-
|
|
142
|
-
spec.add_dependency 'stringex', '~> 1.1'
|
|
143
|
-
|
|
144
|
-
== Thanks & Acknowledgements
|
|
145
|
-
|
|
146
|
-
If it's not obvious, some of the code for ActsAsUrl is based on Rick Olsen's permalink_fu[http://svn.techno-weenie.net/projects/plugins/permalink_fu/] plugin. Unidecoder is a Ruby port of Sean Burke's Text::Unidecode[http://interglacial.com/~sburke/tpj/as_html/tpj22.html] module for Perl. And, finally, the bulk of strip_html_tags[link:classes/Stringex/StringExtensions.html#M000005] in StringExtensions was stolen from Tobias Lütke's Regex in Typo[http://typosphere.org/].
|
|
147
|
-
|
|
148
|
-
GIANT thanks to the many contributors who have helped make Stringex better and better: http://github.com/rsl/stringex/contributors
|
|
149
|
-
|
|
150
|
-
copyright (c) 2008-2014 Lucky Sneaks, released under the MIT license
|