Awful is an iOS 9 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)).
Development talk usually ends up in the project.log thread, but we're not fussy. There's also a todo list.
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
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. The only submodule is the thread-tags repository, which is not strictly needed for building; if you don't need it, you can leave off the --recursive
part from step one.
There are optional dependencies for building Awful. You only need them if you're working on the relevant part of the app.
- CocoaPods manages dependencies. If you're updating, adding, or removing a dependency, please install CocoaPods.
- Even if you add a dependency directly to the Xcode project, please update
Source/Settings/Acknowledgements.mustache
with the name and license of the dependency. We do not use the CocoaPods-generated acknowledgements.
- Even if you add a dependency directly to the Xcode project, please update
- 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). - Now build the Xcode project and the CSS files will be regenerated.
Awful uses an App Group to communicate and share data with the Smilie Keyboard. Unfortunately, App Group identifiers must be unique, so I can't simply set it up and have everything work. By default, Awful builds without an App Group configured, which means that the Smilie Keyboard won't be able to download new smilies, remember recent smilies, or store favourite smilies. If you like, you can create an App Group in your iOS Developer account, then simply place the identifier in a file called app-group
in the root of the repository. After a build and run, full keyboard functionality should be yours.
There are unit tests for the HTML scraping, to help us find problems when markup changes, running continuously via Travis CI.
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.
Awful is broken down somewhat:
Awful
is the iOS app.AwfulCore
is a framework that does the scraping and networking with the Forums. It's meant to be compatible with both iOS and OS X, but nobody's actually tried on OS X.Smilies
is a framework that downloads smilies and presents them as a keyboard. It's meant to be compatible with both iOS and OS X, but nobody's actually tried on OS X.
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. 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.) Then commit both the modified .less
files and any resulting changes to .css
files, so others don't need LESS to build Awful.
The rest of Awful is themed in a a big plist. If you can't find a theme key you'd like to use, ask and we'll add it!
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.
-
Update the awfulapp.com repository repository per its README.
-
In this (Awful.app) repository, update the
Resources/Thread Tags
submodule and push:cd path/to/awful-app/repo cd Resources/Thread\ Tags git pull origin master cd .. git commit -am "Updated thread tags." git push
The posts view uses zepto.js. Awful uses the Touch module which is not part of a standard build, so a custom build is required. (It also uses the Core, Event, and Ajax modules.)
Awful answers to a couple URL schemes:
awful:
opens Awful directly to various screens. This URL scheme is documented at http://handleopenurl.com and at Launch Center Pro.awful://forums
opens the Forums tab.awful://forums/:forumid
opens the Forums tab to the identified forum.awful://threads/:threadid
opens the first page of the identified thread. For example,awful://threads/3510131
opens Awful's thread.awful://threads/:threadid/pages/:page
opens the given page of the identified thread. For example,awful://threads/3510131/pages/15
opens the fifteenth page of Awful's thread.awful://posts/:postid
opens the identified post's page of its thread and jumps to it. For example,awful://posts/408179339
opens the OP of Awful's thread.awful://bookmarks
opens the Bookmarks tab.awful://messages
opens the Messages tab.awful://messages/:messageid
opens the identified private message. (I guess the idea is to handle a link from one message to another? )awful://settings
opens the Settings tab.awful://users/:userid
opens the identified user's profile. For example,awful://users/106125
opens pokeyman's profile.awful://banlist
opens the Leper's Colony.awful://banlist/:userid
opens the identified user's rap sheet. For example,awful://banlist/106125
opens pokeyman's rap sheet.
awfulhttp:
andawfulhttps:
handle Forums website URLs to any screens that have a correspondingawful:
URL described above.- The idea is you take your
https://forums.somethingawful.com/โฆ
URL, putawful
in front, and now it opens in Awful.
- The idea is you take your
There's an iMessage sticker pack with all the smilies. From a fresh start:
- Save a webarchive of the Forums's showsmilies page in
Smilies/Tests/showsmilies.webarchive
. - Build and run
Smilie Extractor
in the iOS simulator. - Tap the
Stickers
button. - Now run
make stickerscale
in Terminal. - You're done.
Creative Commons Attribution-NonCommercial-ShareAlike 3.0 United States License
Awful development is led by pokeyman aka Nolan Waite.
Awful includes contributions from: