|
2 | 2 |
|
3 | 3 | [](https://travis-ci.org/fabioalmeida/LabelConfigurator) |
4 | 4 | [](http://cocoapods.org/pods/LabelConfigurator) |
| 5 | +[](https://github.com/Carthage/Carthage) |
5 | 6 | [](http://cocoapods.org/pods/LabelConfigurator) |
6 | 7 | [](http://cocoapods.org/pods/LabelConfigurator) |
7 | 8 |
|
8 | | -## Example |
9 | 9 |
|
10 | | -To run the example project, clone the repo, and run `pod install` from the Example directory first. |
| 10 | +LabelConfigurator is a compact library for iOS designed to help configuring [UILabels](https://developer.apple.com/documentation/uikit/uilabel) without the usual burden of setting all the text attributes in several steps, specially when we have substrings with different attributes. |
| 11 | + |
| 12 | +It was created using a [Builder Pattern](https://en.wikipedia.org/wiki/Builder_pattern) to allow adding several attributes to a single label, but just setting all them at once when needed. The interface itself is very easy and straightforward, making this library adoption super fast. For more detailed examples please check the [Usage](#usage) section. |
| 13 | + |
11 | 14 |
|
12 | 15 | ## Requirements |
13 | 16 |
|
| 17 | +The minimum requirements needed to use `LabelConfigurator` are: |
| 18 | +- iOS 9.0 |
| 19 | +- Xcode 8 |
| 20 | +- Obj-C and Swift compatible |
| 21 | + |
| 22 | + |
14 | 23 | ## Installation |
15 | 24 |
|
16 | | -LabelConfigurator is available through [CocoaPods](http://cocoapods.org). To install |
17 | | -it, simply add the following line to your Podfile: |
| 25 | +### CocoaPods |
| 26 | + |
| 27 | +You can use [CocoaPods](http://cocoapods.org) to add `LabelConfigurator` to your project. To install it, simply specify it in your **Podfile**: |
18 | 28 |
|
19 | 29 | ```ruby |
20 | | -pod 'LabelConfigurator' |
| 30 | +source 'https://github.com/CocoaPods/Specs.git' |
| 31 | +platform :ios, '9.0' |
| 32 | +use_frameworks! |
| 33 | + |
| 34 | +target 'TargetName' do |
| 35 | + pod 'LabelConfigurator', '~> 0.2.0' |
| 36 | +end |
| 37 | +``` |
| 38 | + |
| 39 | +After specifying the new dependency on the Podfile, just run `pod install` to make sure you install the latest version of the library. |
| 40 | + |
| 41 | + |
| 42 | +### Carthage |
| 43 | + |
| 44 | +[Carthage](https://github.com/Carthage/Carthage) is a decentralized dependency manager that builds your dependencies and provides you with binary frameworks. |
| 45 | + |
| 46 | +To integrate `LabelConfigurator` into your Xcode project using Carthage, specify it in your `Cartfile`: |
| 47 | + |
| 48 | +```ogdl |
| 49 | +github "fabioameida/LabelConfigurator" ~> 0.2.0 |
| 50 | +``` |
| 51 | + |
| 52 | +Run `carthage update` to build the framework and drag the built `LabelConfigurator.framework` into your Xcode project. |
| 53 | + |
| 54 | + |
| 55 | +## Usage |
| 56 | + |
| 57 | +To import the library to your project just add the following line to your Swift file: |
| 58 | + |
| 59 | +```swift |
| 60 | +import LabelConfigurator |
| 61 | +``` |
| 62 | + |
| 63 | +If you want to make a really simple [UIFont](https://developer.apple.com/documentation/uikit/uifont) and text color to your label, just add the following code: |
| 64 | + |
| 65 | +```swift |
| 66 | +self.myLabel.setLabelText("Some text") |
| 67 | + .set(font: UIFont.boldSystemFont(ofSize: 14)) |
| 68 | + .set(textColor: .blue) |
| 69 | + .configure() |
21 | 70 | ``` |
22 | 71 |
|
| 72 | +Please notice two important aspects about the previous code: |
| 73 | +1. The first method being called is `setLabelText()`, which returns the `UILabelBuilder` that allows you to add all the needed attributes to the UILabel without any boilerplate code; |
| 74 | +2. After adding all the attributes you just need call `configure()` at the end, which will apply all the defined attributes to the UILabel. |
| 75 | + |
| 76 | +The previous code may look quite similar to the `UIKit` code you write to just change the font and text color. But when it comes to other common cases like setting a custom **Font Tracking** or **Line Spacing**, the case is different because that will imply creating an [NSAttributedString](https://developer.apple.com/documentation/foundation/nsattributedstring). |
| 77 | + |
| 78 | +To achieve this with `LabelConfigurator` you just need to do the following: |
| 79 | + |
| 80 | +```swift |
| 81 | +self.myLabel.setLabelText("Some text \n Other text") |
| 82 | + .set(font: UIFont.boldSystemFont(ofSize: 14)) |
| 83 | + .set(textColor: .blue) |
| 84 | + .set(fontTracking: 4) |
| 85 | + .set(lineSpacing: 10) |
| 86 | + .configure() |
| 87 | +``` |
| 88 | + |
| 89 | +Other common example is adding different text attributes to a substring. Now, you can do it like this: |
| 90 | + |
| 91 | +```swift |
| 92 | +let minimumAmount = "$5" |
| 93 | + |
| 94 | +self.myLabel.setLabelText("Please donate \(minimumAmount) or more!") |
| 95 | + .set(font: UIFont.systemFont(ofSize: 12)) |
| 96 | + .set(textColor: .black) |
| 97 | + .set(font: UIFont.boldSystemFont(ofSize: 13), onSubstring: minimumAmount) |
| 98 | + .set(textColor: .red, onSubstring: minimumAmount) |
| 99 | + .configure() |
| 100 | +``` |
| 101 | + |
| 102 | + |
| 103 | +## Advanced Usage |
| 104 | + |
| 105 | +The most common customisations done on `UILabels` are covered with helper methods to allow you adding attributes as easily as possible as you can see on the previous examples. |
| 106 | + |
| 107 | +However, not all the possibilities are covered (and we want to keep it that way) on `UILabel` attributes and also `NSAttributedString`. |
| 108 | + |
| 109 | +The good this is that you can add your custom attributes you wanted to add to your `NSAttributedString` using two convenience methods to do so: |
| 110 | +- `func set(attribute: String, value: AnyObject, onSubstring substring: String)` |
| 111 | +- `func set(attribute: String, value: AnyObject, onRange range: NSRange)` |
| 112 | + |
| 113 | +For example, if you want to add a strikethrough attribute to a substring on your `UILabel`, you can do as the following |
| 114 | + |
| 115 | +```swift |
| 116 | +let oldPrice = "$350" |
| 117 | +let newPrice = "$299" |
| 118 | + |
| 119 | +self.myLabel.setLabelText("New price \(oldPrice) \(newPrice)") |
| 120 | + .set(font: UIFont.systemFont(ofSize: 12)) |
| 121 | + .set(textColor: .black) |
| 122 | + .set(textColor: .red, onSubstring: newPrice) |
| 123 | + .set(textColor: .lightGray, onSubstring: oldPrice) |
| 124 | + .set(attribute: NSStrikethroughStyleAttributeName, value: NSNumber(value: 1), onSubstring: oldPrice) |
| 125 | + .configure() |
| 126 | +``` |
| 127 | + |
| 128 | +All these examples can be found on the repository "Examples" project. |
| 129 | + |
| 130 | + |
| 131 | + |
23 | 132 | ## Author |
24 | 133 |
|
25 | 134 | If you want to get in touch, reach me on twitter: [@fabioacalmeida](https://twitter.com/fabioacalmeida) |
26 | 135 |
|
27 | 136 |
|
28 | 137 | ## License |
29 | 138 |
|
30 | | -LabelBuilder is available under the MIT license. See the LICENSE file for more info. |
| 139 | +LabelConfigurator is available under the MIT license. See the LICENSE file for more info. |
0 commit comments