ESCObservable

KO | EN

gitlite — search

#javascript #php #python #cms #hacktoberfest #android #ansible #golang #nodejs #metadata #visualization #docker

★ 58 Open GitHub ↗

iOS eventing framework

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

ESCObservable
=============

A framework that implements the Observer pattern.

Advantages over using NSNotificationCenter:

* No need to remove observers on dealloc (ESCObservable uses weak references)
* Observers have a clearly defined list of possible events (defined in a protocol)
* Each event has a clearly defined list of parameters
* Send primitive types or nil as parameters
* Easy to test using mock objects

Using ESCObservable
=============

Project Setup
-------------
ESCObservable can be imported as a subproject in Xcode or as a .framework.  The .framework can be built using the ```Build Framework``` target.

In the build settings under ```Other Linker Flags``` add ```-ObjC``` and ```-all_load```.

Declare Events
-------------

Events are declared in one or more protocols.

```
// An example of a protocol that might be used
@protocol ExampleObjectObserver
@optional // all methods will be treated as optional by ESCObservable regardless of the @optional keyword

- (void)eventWithNoParameters;
- (void)eventWithObjectParameter:(NSString *)string primitiveParameter:(NSInteger)integer;

@end
```

Notifying Observers
-------------

To send events you must declare what protocol(s) declare the methods you will event on (typically in -init).  To post events just call the method on your escNotifier.

```
// ExampleObject.h
@interface ExampleObject : NSObject<ESCObservable>

@end
```

```
// ExampleObject.m
@interface ESCTestObservable()<ESCObservableInternal>

@end

@implementation ESCTestObservable

- (id)init {
	if (self = [super init]) {
		[self escRegisterObserverProtocol:@protocol(ExampleObjectObserver)];
	}
	return self;
}

- (void)sendExampleEvents {
	// send event to all observers
	[self.escNotifier eventWithNoParameters];

// send event with parameters to all observers
	[self.escNotifier eventWithObjectParameter:@"The Answer" primitiveParameter:42];
}

@end
```

Observing
-------------

### Option 1 - ```-escAddObserver:```

Adding an observer using -escAddObserver: will register the object to receive all events.  If the object does not implement a method on the protocol, it will simply not be called (no crashes for unimplemented methods).

```
// ExampleObserver1.m

- (instancetype)initWithExampleObject:(ExampleObject *)exampleObject {
	if (self = [super init]) {
		[exampleObject escAddObserver:self];
	}
	return self;
}

- (void)eventWithNoParameters {
	// do stuff based on the eventWithNoParameters event
}

- (void)eventWithObjectParameter:(NSString *)string primitiveParameter:(NSInteger)integer {
	// do stuff based on the eventWithObjectParameter:primitiveParameter: event
}
```

### Option 2 - ```-escAddObserver:forSelector:``` and ```-escAddObserver:forSelector:forwardingToSelector```

Adding an observer using ```-escAddObserver:forSelector:``` or ```-escAddObserver:forSelector:forwardingToSelector``` will register the object to receive only the specified event.  If the latter is used, the forwardingToSelector will be called when the event occurs.  If using forwardToSelector, the method signatures must match.

```
// ExampleObserver2.m

- (instancetype)initWithExampleObject:(ExampleObject *)exampleObject {
	if (self = [super init]) {
		[exampleObject escAddObserver:self forSelector:@selector(eventWithNoParameters)];
		[exampleObject escAddObserver:self forSelector:@selector(eventWithObjectParameter:primitiveParameter:) forwardToSelector:@selector(forwardingExampleWithString:integer:)];
	}
	return self;
}

- (void)eventWithNoParameters {
	// do stuff based on the eventWithNoParameters event
}

- (void)forwardingExampleWithString:(NSString *)string integer:(NSInteger)integer {
	// do stuff based on the eventWithObjectParameter:primitiveParameter: event
}
```

ESCObservable

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README