HUBComponentModel

@protocol HUBComponentModel <HUBSerializable>

Protocol defining the public API of a model object that is used for a Component in the Hub Framework

You don’t conform to this protocol yourself, instead the Hub Framework will create implementations of it for you based on the data supplied to a HUBComponentModelBuilder or through JSON data.

See also HUBComponent that acts as the controller for a view that renders the data from a HUBComponentModel.

What pieces of data each individual component supports is up to them. It’s also up to the components themselves to control their own rendering of the data contained in a model like this. However, it’s always safe to assign any of the properties in this model, regardless of component implementation. Components that don’t support a certain piece of data (like subtitle or descriptionText for example), will simply choose to ignore those properties.

This protocol defines an immutable component model, for its mutable counterpart; see HUBComponentModelBuilder.

Identifiers

  • The identifier of this model

    Used internally to identify this instance, but may also be used by logging or during debugging to distinguish this set of data from others.

    Declaration

    Objective-C

    @property (readonly, copy, nonatomic) NSString *_Nonnull identifier;

  • The type of component that this model is for

    The Hub Framework supports 3 types of components; header, body & overlay. For more information about the difference between them, see the documentation for HUBViewModel, as well as the content & component programming guides. A component’s children always have the same type as their parent.

    Declaration

    Objective-C

    @property (readonly, nonatomic) HUBComponentType type;

  • The index of the model, either within its parent or within the root list

    Components that use nested models can use this property to determine which child to map a certain model to

    Declaration

    Objective-C

    @property (readonly, nonatomic) NSUInteger index;

  • The identifier of any logical group that the component model belongs to

    You can access the component models in a certain group through the parent’s childrenInGroupWithIdentifier: method.

    Declaration

    Objective-C

    @property (readonly, copy, nonatomic, nullable) NSString *groupIdentifier;

Component

  • The identifier of the component that this model should be rendered using

    The component identifier’s namespace should match the namespace of a registered HUBComponentFactory. If no component can be resolved for this identifier, a fallback one will be used.

    Declaration

    Objective-C

    @property (readonly, copy, nonatomic)
    HUBIdentifier *_Nonnull componentIdentifier;

  • The category of the component that this model should be rendered using

    The Hub Framework uses the value of this property to create a fallback component in case no component could be created by any registered HUBComponentFactory for the model’s componentIdentifier

    Declaration

    Objective-C

    @property (readonly, copy, nonatomic)
    HUBComponentCategory _Nonnull componentCategory;

Text

  • Any title that the component should render

    A title is a component’s most prominent text content. It will usually be rendered using a slightly bigger font.

    Declaration

    Objective-C

    @property (readonly, copy, nonatomic, nullable) NSString *title;

  • Any subtitle that the component should render

    A subtitle is a component’s second most prominent text content. It will usually act as a companion to the title.

    Declaration

    Objective-C

    @property (readonly, copy, nonatomic, nullable) NSString *subtitle;

  • Any accessory title that the component should render

    An accessory title is a supplementary piece of text that is usually used to render metadata or some form of accessory information with less prominance.

    Declaration

    Objective-C

    @property (readonly, copy, nonatomic, nullable) NSString *accessoryTitle;

  • Any description text that the component should render

    A description text is a longer body of text that usually provides more contextual information about the content that the component is rendering.

    Declaration

    Objective-C

    @property (readonly, copy, nonatomic, nullable) NSString *descriptionText;

Images

  • Image data for any main image that the component should render

    A main image is normally the image that has the most visual prominence in the component, but each component is free to determine how this data is used.

    See HUBComponentImageData for more information.

    Declaration

    Objective-C

    @property (readonly, strong, nonatomic, nullable) id<HUBComponentImageData>
    mainImageData;

  • Image data for any background image that the component should render

    A background image is normally renderered behind the rest of the component’s content, but each component is free to determine how this data is used.

    See HUBComponentImageData for more information.

    Declaration

    Objective-C

    @property (readonly, strong, nonatomic, nullable) id<HUBComponentImageData>
    backgroundImageData;

  • Dictionary containing image data objects that describe how to render any custom images for the component

    The keys in this dictionary specify the identifiers of the images, that the component can use to determine their layout.

    For default images, see mainImagedata and backgroundImageData.

    Declaration

    Objective-C

    @property (readonly, strong, nonatomic)
    NSDictionary<NSString *, id<HUBComponentImageData>>
        *_Nonnull customImageData;

  • Any icon that the component should render

    Use the icon object to retrieve an image for a given size. See HUBIcon for more information.

    Declaration

    Objective-C

    @property (readonly, strong, nonatomic, nullable) id<HUBIcon> icon;

Target

  • Any target of a user interaction with the component

    A component’s target contains information about what should happen when a user interacts with it. For example, any URI that should be opened, or any initial view model that should be used for the target view. See HUBComponentTarget for more information.

    Declaration

    Objective-C

    @property (readonly, strong, nonatomic, nullable) id<HUBComponentTarget> target;

Metadata & Customization

  • Any application-specific metadata that should be associated with the component

    Use this for any metadata that is not consumed by the component itself, such as model metadata (music metadata for a music player, photo metadata for a photo editor, for example). For component customization options; use the customData dictionary instead.

    Declaration

    Objective-C

    @property (readonly, strong, nonatomic, nullable)
    NSDictionary<NSString *, id> *metadata;

  • Any data that should be logged alongside interactions or impressions for the component

    The format of this dictionary is completely free form, but since at some point it will end up being serialized, make sure that it only contains serializable values.

    Declaration

    Objective-C

    @property (readonly, strong, nonatomic, nullable)
    NSDictionary<NSString *, id> *loggingData;

  • Any custom data that the component should use

    If a component has some specific customizability options they can be specified here. See the documentation for each HUBComponent implementation for what keys are supported, and for what options. For other types of metadata, such as application-specific model data (music metadata for a music player, photo metadata for a photo editor, for example), that don’t relate to the component itself, use the metadata dictionary.

    Declaration

    Objective-C

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

Hierarchy

  • Any component model that is the parent of this model

    This property contains a back-reference to any component that is above this one in the hierarchy. If this model is for a root component, this property will be nil.

    Declaration

    Objective-C

    @property (readonly, nonatomic, nullable) id<HUBComponentModel> parent;

  • Any component models that are children of this model

    The Hub Framework supports nested components, but it’s up to each HUBComponent implementation to decide what to do with them. For example, when creating a carousel-like component, the children of that component might be the items that the carousel contains.

    Declaration

    Objective-C

    @property (readonly, strong, nonatomic, nullable)
    NSArray<id<HUBComponentModel>> *children;

  • The index path of this component in the HUBComponentModel hierarchy.

    @discussion This is a computed property so shouldn’t be accessed multiple times in the same block.

    Declaration

    Objective-C

    @property (readonly, strong, nonatomic) NSIndexPath *_Nonnull indexPath;

  • Return a child component model for a given index, or nil if an invalid index was supplied

    This method is a convenience API for accessing child component models directly using the children property, since it’s fine to call this method with an index that is not known to be valid (since it will fail gracefully and return nil).

    Declaration

    Objective-C

    - (nullable id<HUBComponentModel>)childAtIndex:(NSUInteger)childIndex;

    Parameters

    childIndex

    The index to return a child component model for

  • Return a child component model that has a certain identifier, or nil if an unknown identifier was given

    Accessing a child component model this way is preferred to iterating over the children array and looking for a model matching an index manually - not only because it’s easier - but also because this method has O(1) complexity.

    Declaration

    Objective-C

    - (nullable id<HUBComponentModel>)childWithIdentifier:
    (nonnull NSString *)identifier;

    Parameters

    identifier

    The identifier of the child to look for

  • Return an array of child component models that belong to certain group

    To put a child component model into a certain group, set its groupIdentifier property either through JSON or when building the model through HUBComponentModelBuilder.

    Declaration

    Objective-C

    - (nullable NSArray<id<HUBComponentModel>> *)childrenInGroupWithIdentifier:
    (nonnull NSString *)groupIdentifier;

    Parameters

    groupIdentifier

    The identifier of the group to return the child component models in