iOS5's release is just around the corner and along with it will be XCode 4.2. Default projects in XCode 4.2 have ARC enabled, therefore all Nimbus code will cause errors.

We need to have a think on how we are going to support ARC for new projects, and still maintain compatibility with previous projects.

Disabling ARC is an option, however I'm sure many (especially new) developers will want ARC on.

Does anybody have any thoughts on this?

Three20's message controller is fairly useful, even in the presence of the native mail interface because it allows you to customize every aspect of the controller.

Some points of note in transitioning this controller:

• We are no longer going to have any base view controller bullshit going on like Three20 has. TTMessageController should inherit from UIViewController, plain and simple.
• The controller is already fairly well documented, but the docs need to be updated with the new doxygen style in order for the docs to be consistent with the rest of Nimbus. This means adding a brief sentence describing each method and property, grouping similar methods, and writing concise, explanatory documentation about when to use the controller and how it should be used.
• I'm not entirely convinced that all of the controller's public methods need to be public, so some auditing here would be helpful.
• The TTMessageField objects are scantily documented. I'm not even entirely sure how these objects work together myself. It would be great to document how each of these fields are used together and how to build custom fields. That being said, it's possible that there is a simpler solution for this as well.

How difficult will this be?

This should be a fairly straightforward port from Three20. Most of the work will be in cleaning up the documentation and providing examples and sample applications.

Nimbus Navigation Design Document

Version 1.0 - Last updated September 1st, 2011 at 10:29PM EST.

The goal with Nimbus navigation is to provide a powerful navigation feature that complements UIKit's existing navigation functionality. This includes iOS 5's Storyboards as well as pre-iOS 5 standard UINavigationController and modal controller presentation.

Design Considerations

This feature will complement the existing UIKit functionality by providing a thin, optional layer on top of UIKit. The goal is to allow a developer to use the navigator when they want to, and to use their own navigation logic when they don't. This means that we do not want deep integration with UIKit components. For example, we won't provide any UIViewController subclasses that implement navigation functionality like Three20 does. A developer should be completely able to slowly integrate the navigator into an existing project if they so desire. Imagine defining a single route and using it within an app that is otherwise completely custom navigation.

The Routing Interfaces

Nimbus Navigation will model directly off of Three20's navigation system by using URLs to map to view controllers and mapping objects to URLs. The routing functionality itself will be implemented using SOCKit.

The routing interface will look roughly like the following:

/**
 * A routing map maintains a mapping of routes from paths to view controllers and objects to paths.
 *
 * All routes are processed using SOCKit to gather parameter information from the paths. Each
 * navigator object (TODO: Name of the object here) instance has an instance of a NIRoutingMap.
 */
@interface NIRoutingMap : NSObject

#pragma mark Controller Routing

/**
 * Add a route from the given path to the given view controller.
 *
 * ## What happens when the navigator opens a path mapped with this method:
 *
 * A view controller will be created and initialized with the initWithNibName:bundle: method.
 * If willNavigateWithPatternParameters:queryParameters: is implemented on the controller then
 * it will be called.
 *
 * Any parameters matched in the path pattern will be passed to
 * willNavigateWithPatternParameters:queryParameters: on the view controller.
 *
 * If you require more explicit access to parameters then you may wish to consider using
 * fromPath:toViewController:withWillNavigateSelector: instead. Using an explicit selector is a
 * recommended means of using the compiler to enforce parameter types and type safety.
 *
 *      @param path  A path that may specify certain parameters that will be matched and sent to
 *                   willNavigateWithPatternParameters:queryParameters:. See the routing parameters
 *                   section of the navigation documentation (TODO: Add link here).
 *      @param viewController  The view controller that will be instantiated and presented when the
 *                             path is opened in the navigator.
 */
- (void)fromPath:(NSString *)path toViewController:(Class)viewController;

/**
 * Add a route from the given path to the given view controller.
 *
 * ## What happens when the navigator opens a path mapped with this method:
 *
 * A view controller will be created and initialized with the initWithNibName:bundle: method.
 * If willNavigateWithPatternParameters:queryParameters: is implemented on the controller then
 * it will be called. The willNavigateSelector will then be called.
 *
 * Any parameters matched in the path pattern will be passed to
 * willNavigateWithPatternParameters:queryParameters: on the view controller.
 *
 *      @param path  A path that may specify certain parameters that will be matched and sent to
 *                   willNavigateWithPatternParameters:queryParameters:. See the routing parameters
 *                   section of the navigation documentation (TODO: Add link here).
 *      @param viewController  The view controller that will be instantiated and presented when the
 *                             path is opened in the navigator.
 *      @param willNavigateSelector  A selector that should have at least as many arguments as
 *                                   there are parameters in the path pattern. One additional
 *                                   argument may provided which accepts an NSDictionary of
 *                                   NSArrays of query parameter values.
 */
- (void)fromPath:(NSString *)path toViewController:(Class)viewController withWillNavigateSelector:(SEL)willNavigateSelector;

/**
 * Returns a newly allocated controller that has been prepared for navigation using the
 * NIRoutingDestination protocol and willNavigateSelector, if such a selector was provided, with
 * the given path to provide the parameters.
 *
 *      @param path  A path that is used to 1. determine which controller class to instantiate and
 *                   2. provide the parameters to the NIRoutingDestination protocol and
 *                   willNavigateSelector, if such a selector is provided.
 *      @returns A newly allocated controller that has been prepared for navigation using the
 *               NIRoutingDestination protocol and willNavigateSelector, if such a selector
 *               was provided, with the given path to provide the parameters.
 */
- (id)controllerForPath:(NSString *)path;

#pragma mark Object Routing

/**
 * Add a route from an object class to a pattern string.
 *
 * This route is used by pathForObject: to generate a path for consumption by the navigator.
 *
 *      @param objectClass  The class of object that can be used to generate the given pattern
 *                          string.
 *      @param patternString  A pattern string that contains parameters that match property names
 *                            on the given object.
 */
- (void)fromObjectClass:(Class)objectClass toPatternString:(NSString *)patternString;

/**
 * Returns a path generated using the object's properties if a route exists for the given object's
 * class, nil otherwise.
 *
 *      @param object  The object whose values will be used by the pattern to generate the path.
 *      @returns A path generated using the object's properties if a route exists for the
 *               given object's class, nil otherwise.
 */
- (NSString *)pathForObject:(id)object;

@end

/**
 * A set of methods that can optionally be implemented by a routing destination.
 */
@protocol NIRoutingDestination <NSObject>

@optional

/**
 * Called immediately after the view controller is initialized by the navigator and before it
 * is presented.
 *
 * If a selector is provided with the routing map then this method will be called first and the
 * routing map's selector second.
 *
 * The parameters for this method are dictionaries of arrays of values. Even parameters that
 * only exist once in the pattern or query will be arrays of values. This is so that if any
 * parameter names are duplicated we provide a consistent means of accessing these values. The
 * parameter values will stored in the array in the order that they were defined in the path.
 *
 * jverkoey implementation note: Do not prepare these parameter dictionaries unless we need to.
 *      If it turns out that this is the only method that will use such a representation of
 *      parameters then we should only create them if the destination implements this method.
 *
 * jverkoey design consideration: Three20's url mapping technology forced you to define the
 *      selector for a mapped url in the url path and encouraged the use of initializers to
 *      initialize the view controller. For example, one might define a path in Three20 like so:
 *          @"fb://profile/(initWithUserId:)" => [FBProfileController class].
 *      Nimbus will not be going this route. Instead, Nimbus will encourage the use of auxiliary
 *      methods to receive the path parameters. This will allow devs to use standard controller
 *      initializers. This will have the net effect of not making it feel like Nimbus is taking
 *      over your app, instead allowing devs to graciously add functionality to existing
 *      controllers as they see fit.
 *      In Nimbus the Three20 example used above would look more like this:
 *          @"fb://profile/:userid" => [FBProfileController class] @selector(setUserId:)
 *      A multi-parameter url could look like this:
 *          @"fb://profile/:userid/:initialTab" => [FBProfileController class]
 *                                                 @selector(setUserId:initialTab:)
 *
 *      @param patternParameters  { "pattern parameter name" => NSArray of parameter values }
 *      @param queryParameters    { "query parameter name" => NSArray of query values }
 */
- (void)willNavigateWithPatternParameters:(NSDictionary *)patternParameters queryParameters:(NSDictionary *)queryParameters;

@end

Create generic html parser, that can be used throughout Nimbus and subsequently create a HTML to NSAttributtedString for use in the NIAttributedLabel

Other open source projects that may help:

Cocoanetics / NSAttributedString-Additions-for-HTML zootreeves / Objective-C-HMTL-Parser

Nimbus specifications

Feature name: htmlattributedstring Dependencies: libxml2, core Interfaces:

NSAttributedString* NSAttributedStringFromHTML(NSString* html);

Minimum v1 functionality

Support for the following tags:

<b><strong>
<i><em>
<u>
<a>

Integration with Nimbus CSS

It would be quite beneficial to be able to tie in HTML parsing to the Nimbus CSS feature. This should be accomplished with a bridge header that doesn't require a strict dependency on the css feature. This would allow developers to use htmlattributedstring without pulling in css.

The bridge header would provide the following API:

NSAttributedString* NSAttributedStringFromHTML(NSString* html, NIStylesheet* stylesheet);

Modifications will have to be made to NIStylesheet to allow for fetching of arbitrary CSS selectors. This will allow HTML like <span class="classname"> to fetch the class name from the stylesheet and style the text accordingly.

A general-purpose grid view controller can be used to present information in grid form. A good example of such a controller would be a photo album thumbnail viewer that shows a grid of photos that can be tapped to view the larger photo.

Some thought should be given as to whether a grid view controller should be an implementation of a table view controller or a completely new implementation. There are benefits to implementing a table view controller such as: section headers, the index scrubber, and a well-tested implementation. The benefit of writing a new grid view controller is mostly in simplicity, as there are some features of a table view controller which don't apply very well to a grid view controller (accessory indicators, editing).

Three20's CSS feature has the potential to be an incredibly powerful feature, making it possible to theme and style native applications using CSS. Three20's implementation is tightly bound to the TTStyle framework and this adds far more weight to the framework than is necessary.

Nimbus Stylesheets

A clean Nimbus implementation would port the CSS grammar and parser that were built for Three20 and make it incredibly easy to import css files and then apply them to standard views.

The interface I'm imaging would look something like this:

// Loads a stylesheet from disk and parses it. This would probably be done at
// app initialization. Because this is necessary for styling views, these style sheets
// should always be immediately available.
// If processing the stylesheet takes a lot of time, it may be worth breaking the
// stylesheets up into separate files and loading them on-demand.
NIStylesheet* stylesheet = [NIStyleSheet stylesheetFromFilePath:<path to css file>];

// This method would apply styles to the given view and all of its subviews.
// This is useful if you want to quickly style a controller's view hierarchy on
// viewDidLoad. This method should be *fast*.
[stylesheet applyRecursivelyTo:self.view];

One method of styling could be to use class names to apply styles to a type of view. For example:

/* All toolbar instances would have this style applied */
UIToolbar {
  tint-color: #000099; /* tint the toolbar red */
  translucent: true;
}

/* All network image views will have a white border */
NINetworkImageView {
  border-color: rgba(255, 255, 255, 0.5); /* semi-transparent white border */
  border-width: 1px;
}

Styling Specific View Instances

It's important to be able to target specific views and style them accordingly. Below are just two ways one could explore the implementation for this.

Four-letter IDs

We could also get fancy with ids in a couple of ways. One could use the tag property on all views to define a unique id using the four character id method. For example:

In code:

photoView.tag = 'ppic'; // This photo view is a profile picture.

In CSS:

#ppic {
  background-color: blue;
}

Pros:

• Easy to use (effectively automatic with the applyRecursivelyTo: method)
• Interface builder integration (you can set tags for views very easily)

Cons:

• Restricted to four letter domain for ids.
• Requires use of the tag property.

Manual Style Application

We could provide a method that allows us to pick a style and apply it directly to any view. An example use of this method would probably look something like this:

[stylesheet applyStyleToView:photoView withID:@"photoView"];

Pros:

• Allows full-length names for style IDs.

Cons:

• Requires manual application of style to every view.

Pseudo-Comprehensive List of Nimbus CSS Properties

color => [#xxxxxx|#xx|rgba(xx, xx, xx, xx.xx)|rgb(xx, xx, xx)|color-name]
dimension => [xx(px)]
font-size => [xx(pt)]
box-dimensions => [<dimension>|<dimension> <dimension>|<dimension> <dimension> <dimension> <dimension>]

UIView {
  border-color: <color>       {view.layer.borderColor}
  border-width: <dimension>   {view.layer.borderWidth}
  background-color: <color>   {view.backgroundColor}
  border-radius: <dimension>  {view.layer.cornerRadius}
  opacity: xx.xx              {view.layer.opacity}
}

UILabel {
  color: <color>                  {label.textColor}
  font: <font-size> <font-name>   {label.font}
  font-weight: [bold|normal]      {label.font}
  text-shadow: <color> <x-offset> <y-offset> {label.shadowColor label.shadowOffset}
  text-align: [left|right|center] {label.textAlignment}
  line-break-mode: [wrap|character-wrap|clip|head-truncate|tail-truncate|middle-truncate] [label.lineBreakMode]
  number-of-lines: xx             {label.numberOfLines}
  minimum-font-size: <font-size>  {label.minimumFontSize}
  adjusts-font-size: [true|false] {label.adjustsFontSizeToFitWidth}
  baseline-adjustment: [align-baselines|align-centers|none] {label.baselineAdjustment}
}

UILabel:highlighted {
  color: <color> label.highlightedTextColor;
}

UIButton {
  padding: <box-dimensions>; {button.contentEdgeInsets, button.titleEdgeInsets, button.imageEdgeInsets}
  color: <color>        {[button titleColorForState:]}
  text-shadow: <color>  {[button titleShadowColorForState:]}
}

UIButton:[highlighted|disabled|selected] {
  color: <color>        {[button titleColorForState:]}
  text-shadow: <color>  {[button titleShadowColorForState:]}
}

UITableView {
  separator-style: [none|single-line|single-line-etched] {tableView.separatorStyle}
  separator-color: <color> {tableView.separatorColor}
}

First fork of three20's TTWebController with working example Currently no documentation but the basics are working. - Done Will tidy up code and add documentation shortly - Done

Jeff,

I've been hacking at the Photos code, and trying to understand the architecture. I've been swimming in NIToolbarPhotoViewController, and the sample code in NetworkPhotoAlbumViewController and DribbblePhotoAlbumViewController.

My purpose is to build an AlbumViewController that loads image paths from an NSManagedObject, and then pulls the image up from the file system. I might, eventually, make it so that it does either local or network, but I'm not worried about that at the moment.

What I'm finding is that several code chunks in NetworkPhotoAlbumViewController should actually be refactored upwards, either into NIToolbarPhotoViewController, or into a sub-class of that. Aaaaand, actually, I'm beginning to think that a general purpose NIPhotoScrollViewController should be the parent of NIToolbarPhotoViewController, and it should manage all of the work not specific to the toolbar/scrubber work done by NIToolbarPVC.

Some of the work that I think should be in NIPhotoScrollViewController:

1. manage _highQualityImageCache and _thumbnailImageCache;
2. • (NSString _)cacheKeyForPhotoIndex:(NSInteger)photoIndex;
3. NIPhotoAlbumScrollView_ _photoAlbumView;
4. @property (nonatomic, readonly, retain) NIPhotoAlbumScrollView* photoAlbumView;
5. • (void)loadThumbnails; (currently in DribbblePAVC);
6. • (void)loadAlbumInformation; (which would actually be in the data source identified by this new NIPhotoSVC);

Before I get too deep in the weeds here, I'd like your perspective on what I'm proposing. Especially if I'm missing something fundamental. The main reason I'm suggesting all of this is that I'm finding I need some of these pieces, but they're either buried in the example code sited above, or seemingly inappropriately (again, in my opinion!) in NIToolbarPVC. This refactoring, I think, will allow for easier implementation of sub-classes of the photo viewers in the future, as some of the "heavy lifting" would already be handled.

Thoughts?

This is the beginnings of the attributed label. It is by no means finished but provided to track development and any comments.

Currently transforms a regular UILabel and creates an NSAttributedString then draws the text.

Relates to issue: #24

NISegmentedControlFormElement adds a table cell with label and UISegmentedControl. NIDatePickerFormElement adds a table cell with label and date that presents a UIDatePicker once tapped.

On the Add Nimbus to your project wiki page, it says:

If you are using the arc branch the import is slightly different:

    #ifdef __OBJC__
        #import <Foundation/Foundation.h>
        #import <UIKit/UIKit.h>
        #import <QuartzCore/QuartzCore.h>
        // only load nimbus when arc is enabled
        #if __has_feature(objc_arc)
            #import "NimbusCore.h"
            #import "NimbusWebController.h"
        #endif
    #endif

Is that section still relevant? From what I can tell, the arc and master branches are essentially identical.

Corollary - If the documentation has become irrelevant, is it perhaps time to delete the arc branch in order to remove doubt in the minds of new Nimbus users as to which branch to use?