Home

Awesome

EBPhotoPages

”A photo gallery can become a pretty complex component of an app very quickly. The EBPhotoPages project demonstrates how a developer could use the State Pattern to control the behavior of an interface with numerous features. This pattern grants the ability to create new behaviors for a custom implementation of the EBPhotoPages photo gallery without having to modify or understand much of the original source code. The goal was to design a photo gallery class that would smoothly support whatever use cases would be required in the future.”

Alt text|Alt text Alt text Alt text|Alt text Alt text|Alt text Alt text

What is this?

EBPhotoPages is a photo gallery library for displaying pages of photos and their meta data in a scrollview. Users are able to zoom photos in and out, as well as create, edit or delete comments and tags, share or delete a photo, and report inappropriate photos. All photos and content are loaded asynchronously. User permissions for a photo are controlled through a delegate protocol. No graphic files are required for the gallery as icons are drawn in code.

The library was designed using a state pattern to control the behavior of the gallery, so that other developers can easily modify or add new states without having to understand too much of the original code.

Quick Feature list:

How do I use it?

  1. Add the QuartzCore.framework, CoreGraphics.framework and AVFoundation.framework to your project.

  2. Add the EBPhotoPagesController folder from this repo to your app.

  3. Implement the EBPhotoPagesDataSource(required) and EBPhotoPagesDelegate(optional) protocols in an object(s) you plan to use as the datasource and delegate for your EBPhotoPagesController instance.

  4. Then, initialize and present the photoPagesController:

EBPhotoPagesController *photoPagesController = [[EBPhotoPagesController alloc] 
                                               initWithDataSource:aDataSource delegate:aDelegate];

[self presentViewController:photoPagesController animated:YES completion:nil];

How do I customize this?

The EBPhotoPagesFactory class is meant to be the one-stop shop for all UI objects. This class is responsible for instantiaing UI Elements and returning them to the EBPhotoPagesController. If you wish to customize the look of your photo gallery implementation, this is the first place you should check for whatever you want to customize. Some other UI elements are not yet created by this class, but the plan is to eventually move them into it.

By subclassing this class and overriding relevant methods, you can control how the UI objects will look before they get sent back to the EBPhotoPagesController to be used.

If you are going to create a custom EBPhotoPagesFactory subclass, you will have to init your EBPhotoPagesController with one of the init methods that lets you pass an EBPhotoPagesFactory instance, such as this one:

- (id)initWithDataSource:(id<EBPhotoPagesDataSource>)dataSource 
                delegate:(id<EBPhotoPagesDelegate>)aDelegate 
       photoPagesFactory:(EBPhotoPagesFactory *)factory 
            photoAtIndex:(NSInteger)index
<!--- Remove comments when carthage support is ready Carthage ------- Carthage is the simplest way to include frameworks in your Cocoa applications. Learn more at https://github.com/Carthage/Carthage To use the latest version of this library, add this to your Cartfile. ``` # Use the latest version github "EddyBorja/EBPhotoPages" ``` -->

How do State Objects work in EBPhotoPages?

At any given time, the photo gallery has a state object assigned as its current state, when a user event is received, the photo gallery’s state object takes responsibility for how the photo gallery should respond.

By convention, state objects are decoupled from each other. This means they are completely unaware of other state objects, and they also hold no data of their own. You can freely create and destroy them without fear (or guilt…).

When a state object decides it’s time to transition to a new state, it simply calls upon a method within the photo gallery that replaces the current state object with a new instance of the next state object.

To create a new custom State for your implementation of the photo gallery, you should do two things:

  1. Create a new state object that is a subclass of the EBPhotoPagesState object, and override the methods you’re interested in. (example: EBPhotoPagesCoolNewState)

  2. Create a category of the EBPhotoPages that contains the method(s) for your custom transitions. The purpose of a transition method is usually to set the “currentState” object of the EBPhotoPagesController to a new instance of your new custom state. (example: -(void)transitionToCoolNewState;)

  3. Decide how the user will reach this new custom state. If there is a special button in the interface that takes the user to this state when tapped, then make sure the EBPhotoPages calls your new transition method for that user event. If you are injecting this custom state somewhere in between the default state machine flow (the normal default behavior of the EBPhotoPagesController), then this may require a bit more overriding of existing classes so that your new state is reached instead of the original ones.

  4. Don’t forget to implement some way for a user to exit your custom state and go back to a default idle browsing state!

Tell me more about the features.

What are some things to consider when implementing EBPhotoPages?

How can I help?

Although this library has a lot of features and over 5,000 lines of code, there’s still some challenges to solve. Feel free to improve on the library and submit pull requests. In particular, these areas need some attention:

Any issues or bugs?

Got a License?

EBPhotoPages uses the MIT License:

Copyright (c) 2014 Eddy Borja

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Who made this?

EBPhotoPages and its components were created by Eddy Borja.

iPhone PSD Template by Mikael Eidenberg.

These days I'm unable to continue working on this project due to other obligations, but I'm always open to pull requests.

Contributors can always be found here.

What else?

Be sure to check out these other libraries:

MLPSpotlight<br /> UIColor+MLPFlatColors<br /> MLPAccessoryBadge<br /> MLPAutoCompleteTextField<br />