#beautify-ios

Beautify enhances Apple's UIKit controls, re-rendering them to give you much more control over their visual appearance.

The beautify-ios framework is part of a much more ambitious project, which will allow live-styling of applications that have been enhanced by the beautify framework. We plan to release this to our beta programme members shortly.

beautify-ios currently supports the following controls; UISwitch, UISlider, UITableViewCell, UINavigationBar, UITextField, UILabel, UIButton and UIImageView, with more to follow …

Contents

• Setup
• A quick introduction
• Usage
  • Building a theme in code
  • Loading a theme from a JSON file
  • Styling Specific Controls
  • Excluding controls
• Licence

##Setup Beautify is available as a CocoaPod.

To add beautify to your project, follow these steps:

• Add pod 'beautify' to your Podfile
• Run pod install
• Open App.xcworkspace
• Add the following to your AppDelegate's didFinishLaunchingWithOptions: method:

[[BYBeautify instance] activate];

You shouldn't notice an immediate change. The default states of the controls have been styled to match the default Apple style. To customise the style, check out the usage section below.

##A quick introduction

You can add the beautify framework to your application with just one line of code. Once added, all the UIKit controls are re-rendered with a style that matches the native look and feel (iOS 6 or iOS 7). The extra rendering capabilities that beautify provides are accessible via a renderer property. For example, an iOS 7 UIButton looks like the following:

When you add beautify to your application, the button will look just the same - that's by design! However, you can now make changes to the style of your button. These can be subtle, as in the following example:

// beautify the app (typically you would do this in the app-delegate)
[[BYBeautify instance] activate];

// set the border and background color
BYBorder* border = [[BYBorder alloc] initWithColor:[UIColor whiteColor] width:0.0 radius:5.0];
[self.button.renderer setBorder:border forState:UIControlStateNormal];
[self.button.renderer setBackgroundColor:[UIColor colorWithRed:0.38 green:0.78 blue:0.44 alpha:1.0]
                                forState:UIControlStateNormal];

The above code changes the buttons background color, and creates a rounded border:

Or, the changes can be radical:

// add a border
BYBorder* border = [[BYBorder alloc] initWithColor:UIColorFromRGB(0xebebed) width:5.0 radius:20.0];
[self.button.renderer setBorder:border forState:UIControlStateNormal];

// set the text style
BYFont* font = [[BYFont alloc] initWithName:@"AvenirNextCondensed-Heavy"];
BYText* text = [[BYText alloc] initWithFont:font color:[UIColor whiteColor]];
[self.button.renderer setTitleStyle:text forState:UIControlStateNormal];

// add a gradient
UIColor* lightGreen = UIColorFromRGB(0xcae284);
UIColor* darkGreen = UIColorFromRGB(0x9bcb53);
BYGradient* gradient = [[BYGradient alloc] initWithStops:@[
    [[BYGradientStop alloc] initWithColor:lightGreen at:0.0f],
    [[BYGradientStop alloc] initWithColor:darkGreen at:1.0f]]];
[self.button.renderer setBackgroundGradient:gradient forState:UIControlStateNormal];

// add inner shadows
UIColor* shadowColor = UIColorFromRGB(0x81a744);
NSArray* shadows = @[
    [[BYShadow alloc] initWithOffset:CGSizeMake(0.0, -2.0) radius:2.0 color:shadowColor],
    [[BYShadow alloc] initWithOffset:CGSizeMake(0.0, 2.0) radius:1.0 color:[UIColor whiteColor]],
    [[BYShadow alloc] initWithOffset:CGSizeMake(0.0, 1.0) radius:2.0 color:shadowColor]
    ];
[self.button.renderer setInnerShadows:shadows forState:UIControlStateNormal];

Beautify adds borders, shadows (inner and outer), gradients (radial and linear) to all the UIKit controls. It also enhances UITextField, adding a highlighted state, and allows you to change the text on a UISwitch control.

The examples above have shown how to change the visual appearance of a single control. It would be quite a lot of work to explicitly style every single control in your application. For that reason beautify has the concept of a theme which is automatically rolled out to every single control in your application. Furthermore, you can encode the theme in JSON format reducing the amount of code you need to write.

##Usage

###Modifying the appearance of controls When you have activated beautify, and want to modify the appearance of your controls, you have three options:

1. Create a global theme in code, which beautify will roll-out to all of your UI controls.
2. Create a global theme in JSON (either manually or on the beautify site), which beautify will roll-out to all of your UI controls.
3. Modify the appearance of controls on a per-control basis, via the renderer property that beautify adds to the controls.

You can also use a combination of these methods, applying a global theme but making appearance changes to individual controls. These three methods are described in more detail below.

####Building a theme in code Start off by instantiating a new BYTheme object. This object contains all of the properties you will need to style your application. The theme has a number of style properties that relate to each of the UIKit controls, you can use these to change the visual appearance as in the example below:

BYTheme *theme = [BYTheme new];
theme.switchStyle.border = [[BYBorder alloc] initWithColor:[UIColor blueColor]
                                                     width:2.0f radius:0.0f];

This would give you a switch with a 2px blue border and an otherwise default appearance.

Once you've built your theme with code, applying it is simple. Just place the following code underneath the activation line in your AppDelegate, which will apply the theme you have just built to all of the controls in the application:

[[BYThemeManager instance] theme];

####Loading a theme from a JSON file

It is also possible to build your theme in JSON and then pass that into the app. The structure of the JSON file should match the structure of a BYTheme object. Color value should be defined as hex strings, 8 character hex strings can also be used to support alpha values, e.g. RRGGBBAA.

To see an example JSON file, take a look at the demoStyle.json file in the demo app bundle.

Once you have constructed a JSON file, simply replace the call to [[BYBeautify instance] activate] in your AppDelegate with the following line:

[[BYBeautify instance] activateWithStyle:@"myJSONStyleFile"];

Note that you don't need to pass in the ".json" part of the file name - that is handled internally.

###Styling specific controls Once you have applied your theme, either through code or with a JSON file, you may find that you want to specify a different style for a subset of the controls in your app.

Let's say you have a lot of buttons in your app but want to emphasise one of them by surrounding it with a red border. All you have to do is use the renderer associated with that button instance, and set its border property for whatever state(s) you want it to appear on.

UIButton *redBorderedButton;

// Set up the button as usual…

BYButtonRenderer *buttonRenderer = redBorderedButton.renderer;
BYBorder *redBorder = [[BYBorder alloc] initWithColor:[UIColor redColor] width:5.0f radius:0];
[buttonRenderer setBorder:redBorder forState:UIControlStateNormal];

And that's it! redBorderedButton will now have a red, 5px border while its state is UIControlStateNormal.

###Excluding controls Sometimes you will want certain controls to be excluded from the beautify rendering and for them to keep their default styling. To do this, simply set the isImmuneToBeautify property on any of your controls to YES. The default value for isImmuneToBeautify is NO for all controls, except UIImageView.

UIImageViews are commonly used as the component parts of other controls and are often frequently used throughout applications. Given how unlikely it would be that you would want to style every single image view in your application, we decided to default the isImmuneToBeautify property to YES for UIImageViews. If you do wish to style a UIImageView, simply set it to NO.

##License beautify-ios uses the Apache v2 license