HUBViewModelBuilder

@protocol HUBViewModelBuilder <HUBJSONCompatibleBuilder>

Protocol defining the public API of a builder that builds view model objects

This builder acts like a mutable model counterpart for HUBViewModel, with the key difference that they are not related by inheritance.

For more information regarding the properties that this builder enables you to set, see the documentation for HUBViewModel.

The status of the builder

  • Whether this builder is currently empty, and does not contain any content

    As soon as any header, body or overlay component model has been added to this builder, it is no longer considered empty

    Declaration

    Objective-C

    @property (readonly, nonatomic) BOOL isEmpty;

  • The number of body component model builders that this builder contains

    Declaration

    Objective-C

    @property (readonly, nonatomic) NSUInteger numberOfBodyComponentModelBuilders;

  • The number of overlay component model builders that this builder contains

    Declaration

    Objective-C

    @property (readonly, nonatomic) NSUInteger numberOfOverlayComponentModelBuilders;

Identifier

  • The identifier that the view should have

    The value of this property doesn’t have any specific format or constraints and doesn’t explicitly need to be unique - but for logging, UI instrumentation and identification purposes, it’s definitely recommended.

    The default value of this property is either a view identifier derived from remote content JSON data or nil.

    Declaration

    Objective-C

    @property (readwrite, copy, nonatomic, nullable) NSString *viewIdentifier;

Navigation bar & header

  • The title that the view should have in the navigation bar

    This property is an alias for navigationItem.title.

    Declaration

    Objective-C

    @property (readwrite, copy, nonatomic, nullable) NSString *navigationBarTitle;

  • The navigation item that the view should use when presented in a UINavigationController

    You can use this navigation item to set what title, bar buttons etc that the view’s navigation bar should contain. Only relevant when the view’s controller is added to a container view controller.

    Declaration

    Objective-C

    @property (readonly, strong, nonatomic)
    UINavigationItem *_Nonnull navigationItem;

  • The builder to use to build a model for the view’s header component

    If you plan to add a header to your view, you use this builder to setup the component that will make up the header. This builder gets lazily created the first time you access this property, and will cause a component-based header to be added to the view. If this property is never accessed, a UINavigationBar-based header will be used instead.

    To remove this view model builder’s header component builder, use -removeHeaderComponentModelBuilder. To check whether a header component model builder currently exists, use headerComponentModelBuilderExists.

    In case no identifier is explicity defined for the returned builder, it will use header as the default.

    Declaration

    Objective-C

    @property (readonly, strong, nonatomic)
    id<HUBComponentModelBuilder> _Nonnull headerComponentModelBuilder;

  • Whether a builder for a model for the view’s header component currently exists

    Since accessing headerCompoentModelBuilder lazily creates a builder, you can use this property to check for the existance of a builder.

    Declaration

    Objective-C

    @property (readonly, nonatomic) BOOL headerComponentModelBuilderExists;

Custom data

  • Any custom data that should be associated with the view model

    You can use this property to pass any information along in the content loading process, into the view model itself. That data may later be used to make decisions in a view’s delegate. It’s useful for simple customization, but for extended use consider making a contribution to the main HUBViewModel API instead, if it’s some piece of data that is considered useful for other API users as well.

    Declaration

    Objective-C

    @property (readwrite, strong, nonatomic, nullable)
    NSDictionary<NSString *, id> *customData;

Checking if component model builders exist

  • Return whether this builder contains a builder for a body component model with a certain identifier

    Declaration

    Objective-C

    - (BOOL)builderExistsForBodyComponentModelWithIdentifier:
    (nonnull NSString *)identifier;

    Parameters

    identifier

    The identifier to look for

  • Return whether this builder contains a builder for an overlay component model with a certain identifier

    Declaration

    Objective-C

    - (BOOL)builderExistsForOverlayComponentModelWithIdentifier:
    (nonnull NSString *)identifier;

    Parameters

    identifier

    The identifier to look for

Retrieving component model builders

  • Return all current body component model builders

    If you just want to check the current number of body component model builders, it’s better to use the numberOfBodyComponentModelBuilders property, as it’s faster.

    Declaration

    Objective-C

    - (nonnull NSArray<id<HUBComponentModelBuilder>> *)
    allBodyComponentModelBuilders;

    Return Value

    All the existing body component model builders, in the order that they were created. Note that any preferredIndex set by the component model builders hasn’t been resolved at this point, so those are not taken into account.

  • Return all current overlay component model builders

    If you just want to check the current number of overlay component model builders, it’s better to use the numberOfOverlayComponentModelBuilders property, as it’s faster.

    Declaration

    Objective-C

    - (nonnull NSArray<id<HUBComponentModelBuilder>> *)
    allOverlayComponentModelBuilders;

    Return Value

    All the existing overlay component model builders, in the order that they were created. Note that any preferredIndex set by the component model builders hasn’t been resolved at this point, so those are not taken into account.

  • Get or create a builder for a body component model with a certain identifier

    Declaration

    Objective-C

    - (nonnull id<HUBComponentModelBuilder>)
builderForBodyComponentModelWithIdentifier:(nonnull NSString *)identifier;

    Parameters

    identifier

    The identifier that the component model should have

    Return Value

    If a body component model builder already exists for the supplied identifier, then it’s returned. Otherwise a new builder is created, which can be used to build a body component model. Since this method lazily creates a builder in case one doesn’t already exist, use the -builderExistsForBodyComponentModelWithIdentifier: API instead if you simply wish to check for the existance of a builder. See HUBComponentModelBuilder for more information.

  • Get or create a builder for an overlay component model with a certain identifier

    Use overlay component model builders to setup any components that will be rendered as overlays for the view, on top of the rest of the view’s content. This can be used to display loading indicators, popups, or other overlay content. Overlays are always rendered at the center of their container view, stacked on top of each other on the z axis. The components indexes (can be controlled by setting preferredIndex on their component model builders) determines the rendering order.

    See HUBComponentModelBuilder for more information.

    Declaration

    Objective-C

    - (nonnull id<HUBComponentModelBuilder>)
builderForOverlayComponentModelWithIdentifier:(nonnull NSString *)identifier;

    Parameters

    identifier

    The identifier that the component model should have

    Return Value

    If an overlay component model builder already exists for the supplied identifier, then it’s returned. Otherwise a new builder is created, which can be used to build an overlay component model. Since this method lazily creates a builder in case one doesn’t already exist, use the -builderExistsForOverlayComponentModelWithIdentifier: API instead if you simply wish to check for the existance of a builder.

  • Enumerate all component model builders contained within this builder

    The enumeration will start with any header component model builder, then move onto body component model builders and finally overlay component model builders. You can use this API either to inspect all the component content of a view model builder, or perform a sequence of operations on them easily.

    Declaration

    Objective-C

    - (void)enumerateAllComponentModelBuildersWithBlock:
    (nonnull BOOL (^)(id<HUBComponentModelBuilder> _Nonnull))block;

    Parameters

    block

    A block used for enumeration, will be passed each component model builder found as an argument, and is expected to return a BOOL indicating whether the enumeration should continue or not. As soon as an enumeration block returns NO, the enumeration will stop.

Removing component model builders

  • Remove any previously created header component model builder

    Removing the header component model builder will cause the view to use a UINavigationBar-based header instead.

    Declaration

    Objective-C

    - (void)removeHeaderComponentModelBuilder;

  • Remove a builder for a body component with a certain identifier

    Declaration

    Objective-C

    - (void)removeBuilderForBodyComponentModelWithIdentifier:
    (nonnull NSString *)identifier;

    Parameters

    identifier

    The identifier of the component model builder to remove

  • Remove a builder for an overlay component with a certain identifier

    Declaration

    Objective-C

    - (void)removeBuilderForOverlayComponentModelWithIdentifier:
    (nonnull NSString *)identifier;

    Parameters

    identifier

    The identifier of the component model builder to remove

  • Remove all component model builders that this builder contains

    All body component model builders, as well as any header component model builder, will be removed.

    Declaration

    Objective-C

    - (void)removeAllComponentModelBuilders;

Manipulate custom data

  • Sets value for key in custom data dictionary associated with the view model

    Declaration

    Objective-C

    - (void)setCustomDataValue:(nullable id)value forKey:(nonnull NSString *)key;

    Parameters

    value

    The value to put into customData. If the value is nil existing value for the key will be deleted from the dictionary.
    key

    The key used in customData to store the value