Awful is an iOS app that's Better Than Safari for browsing the Something Awful Forums. Its story is told in its thread (and its older thread (and its first thread)).
This app is not endorsed by Something Awful.
- Clone the repository:
git clone --recursive https://github.com/Awful/Awful.app Awful-app
- Open Xcode project and build away:
open Awful-app/Awful.xcworkspace
Debug builds, beta builds, and release builds each appear as separate apps (they have different bundle identifiers and display names). For development, choose the Awful Beta
scheme, and an app called Awful Debug
will be run in the iOS Simulator and on your device.
There are no required dependencies for building Awful; all third-party libraries are included, and files generated by other utilities are included in the repository.
There are optional dependencies for building Awful. You only need them if you're working on the relevant part of the app. Once a dependency is installed, simply build the Xcode project and the relevant files will be regenerated.
- CocoaPods manages Objective-C library dependencies. If you're updating, adding, or removing a dependency, please install CocoaPods.
- Even if you add a dependency directly to the Xcode project, you need to run
pod install
to update the acknowledgements section in the Settings screen. Licenses are added from theVendor
directory, either as aLICENSE.txt
file or a properly-formatted comment atop a.h
file.
- Even if you add a dependency directly to the Xcode project, you need to run
- LESS helps us write CSS. If you're modifying the themes for displaying posts (these are files like
posts-view*.less
), please install LESS:- Install homebrew.
- Open Terminal and install node:
brew install node
(prependsudo
to avoid permissions errors). - In Terminal, install less:
npm install less -g
(prependsudo
to avoid permissions errors).
- mogenerator makes Objective-C classes from our Core Data model. If you're modifying the Core Data model (aka
Model.xcdatamodeld
), please install mogenerator.
There are unit tests for the HTML parsing, to help us find problems when markup changes, running continuously via Travis CI.
To build for beta testing, change the scheme to "Awful Beta".
To build for the App Store, change the scheme to "Awful App Store".
Either way, select "iOS Device", then in the Product
menu, choose Archive
.
If you want to use Crashlytics for reporting crashes, create a file called api_keys
, in the root folder of the repository, that looks something like this:
CRASHLYTICS_API_KEY abc123abc123abc123
You can help! Head over to Awful's thread and tell us about any issues you're having. Send in some lovingly crafted thread tags. Or fork the code and send pull requests. Once a pull request is accepted, you get the commit bit!
If you're curious about anything at all, stop by the thread and say hi.
The HTTP client connects to the Something Awful Forums and parses its contents, saving those contents as entities in a Core Data store. Various screens show the forums, threads, posts, private messages, and users saved to the Core Data store.
Awful's Core Data store is a cache of content from the Forums. Any user info specific to the app is stored in user defaults. The Core Data store may be (and can be, since it's stored in the application's Caches directory) deleted at any time.
Awful's posts view is fully customizable using CSS. There's a default theme, as well as themes for specific forums such as YOSPOS and FYAD. Users can include their own custom themes by adding specially-named CSS files to the application Documents directory; more info. Internally, we use LESS to generate our CSS, so if you are editing built-in themes please edit the .less
files. (LESS installation instructions are above.)
The rest of Awful's screens support much more limited theming for the "dark mode" setting. The color schemes are set in AwfulTheme; there is no way to override them.
Diabolik900 and The Dave have fashioned Awful with its own set of thread tags that look great on the iPhone and the iPad. They're distributed with the app. New thread tags can also appear in Awful without us having to send an update through the App Store. This is done by hosting the icons via GitHub Pages.
To add a new thread tag you just made:
- Add it to the thread tags repository and push.
- In the awfulapp.com repository, update the
Thread Tags
submodule and push. - In this (Awful.app) repository, update the
Resources/Thread Tags
submodule and push.
The posts view uses zepto.js (the default build) and some custom JavaScript, which get concatenated into Resources/JavaScript/combined.js
during the Xcode build.
Awful is loosely compatible with iOS 5. That means:
- It shouldn't crash. Use the version category on UIDevice or feature detection to run code on certain versions of iOS.
- It should be usable. A toolbar has the wrong background? Not a big deal. The toolbar doesn't appear at all? We'll fix that.
- Polyfills/shims are great! (e.g. PSTCollectionView provides UICollectionView on iOS 5.)
That said, if a compelling new feature requires iOS 6, and no polyfill is available, it's probably worth requiring iOS 6. So don't be afraid of suggesting/implementing such a feature!
Creative Commons Attribution-NonCommercial-ShareAlike 3.0 United States License
Awful development is led by pokeyman aka Nolan Waite.
Awful includes contributions from: