MMMPureLoadable

Objective-C

@protocol MMMPureLoadable <NSObject>

Swift

protocol MMMPureLoadableProtocol : NSObjectProtocol

A protocol for a “read only” view on a loadable object which allows to observe the state but does not allow to sync the contents (i.e. trigger a refresh, upload, etc depending on the context). (It’s similar to the difference between “Promise” in “Deferred” in jQuery.)

Note that there is no explicit “value” property here, the extension of the protocol should specify additional fields (“contents” properties) that together constitute the “value” of the promise.

  • The state of the loadable, such as ‘idle’ or ‘syncing’.

    • The ‘loadable’ prefix allows to have a ‘state’ property for something else in the same object.

    Declaration

    Objective-C

    @property (nonatomic, readonly) MMMLoadableState loadableState;

    Swift

    var loadableState: MMMLoadableState { get }

  • Optional error object describing the failure to sync the loadable.

    The message should be never shown to the user. If different error conditions have to be communicated to the user, then they should be indicated via the code property of the error and the frontend should select appropriate copy based on it; alternatively, there can be an additional property providing more information.

    Declaration

    Objective-C

    @property (nonatomic, readonly, nullable) NSError *error;

    Swift

    var error: (any Error)? { get }

  • YES, if the contents associated with this loadable (a bunch of properties collectively constituting the “value” of the promise, depending on the context) can be used now.

    Note that unlike promises the contents can be available even when the state says the last sync has failed. (It can be the value fetched on a previous sync or the one fetched initially from a cache, etc; it might be not fresh perhaps, but still be available to be displayed in the UI, for example).

    Note that if the state of the loadable is ‘did sync successfully’ then ‘contentsAvailable’ must be YES; the reverse is not true.

    This property can change only together with loadableState.

    TODO: rename to something like ‘ready’ to play better with the cases when a loadable is not about fetching contents but about completion of something.

    Declaration

    Objective-C

    @property (nonatomic, readonly, getter=isContentsAvailable) BOOL contentsAvailable;

    Swift

    var isContentsAvailable: Bool { get }

  • Adds a state change observer for this loadable. You can use this method directly or use MMMLoadableObserver proxy object for more convenient installation and removal.

    Declaration

    Objective-C

    - (void)addObserver:(nonnull id<MMMLoadableObserver>)observer;

    Swift

    func addObserver(_ observer: any MMMLoadableObserverProtocol)

  • Removes the observer installed earlier. Note that forgetting to remove one or trying to remove it more than once is considered a programmer’s error.

    Declaration

    Objective-C

    - (void)removeObserver:(nonnull id<MMMLoadableObserver>)observer;

    Swift

    func removeObserver(_ observer: any MMMLoadableObserverProtocol)