StreetSign Developer Documentation¶
This will contain the documentation for developers, either working on StreetSign, or making plugins/other software to work with it.
It’s assumed that you’re reasonably familiar with StreetSign the end user web interface and basic terminology (Post, Feed, Screen, Zone, etc). If not, see the Getting Started
Project Structure Overview¶
The main “everything” is kept in the folder (& python package)
"streetsign_server", which is a WSGI application, and can be treated as
such. Within streetsign_server:
__init__.py¶
The basic app definition, which pulls in everything else that it needs.
models.py¶
All the peewee ORM database models are defined in here. These are fairly smart models, containing as much business logic as makes sense to keep in them.
Full Reference: streetsign_server.models
user_session.py¶
A bunch of helpful functions for dealing with the user session & authentication
stuff. The basics are kept in the User, Group, and UserSession
objects defined in models.py, but the functions here help make life easier
and shorter. The function login(username, password) for example, attempts
to log in with those credentials, and if it can, then it creates the
appropriate UserSession database items, and adds useful items to the
session cookie.
Full Reference: streetsign_server.user_session
views/¶
The views package contains all of the actual “endpoints” of the web application. So the functions which generate the pages you see when you use the web interface, the screen rendering, etc. It is mostly split out into submodules.
Full Reference: streetsign_server.views
logic/¶
The logic package is where more complex logic is being moved to from the views package. Once things start becoming more complex than simply pulling things from the database and rendering it, and the logic is application specific rather than model specific, then it should go in here. There is more logic than really should be in views/, and in general, it should be ported across to here.
Full Reference: streetsign_server.logic
static/¶
The standard Flask static assets folder.
static/lib/¶
Contains external libraries (jQuery, knockout, etc).
static/screens/¶
Is for all the css & javascript used by the front end screen rendering.
static/user_files/¶
Is the default location for uploaded user files. This can be configured to
some degree in the root of the tree config.py.
static/style.css¶
As much as possible, I’ve kept with vanilla twitter bootstrap, as it looks perfectly good enough. Anything application specific is in here. Of course, this is talking only about the web interface, not about the output screen rendering, which doesn’t reference this file at all.
static/main.js¶
All the basic functions which all of the back end needs. Such as rendering “flashed” notices, etc.
static/model_zones.js¶
The screen editor is a reasonably complex beast, and uses the wonderful knockout.js library to keep everything sane. This file contains the zones knockout model, and functions to control it all (creating the preview, etc). This file is not used at all in the output screen rendering. It’s a totally separate kettle of fish.
static/post_times_editor.js¶
The post time restrictions editing is also a bit fiddly, so all the clobber for that is kept in here.
“Lets Minify And Join all the Javascripts!!!”¶
Don’t be silly. This is a local network application, not expecting zillions of concurrent users from around the globe. There is no point whatsoever in adding any complexity like that.
Other files in the root directory¶
Starting with the file layout:
run.py- run the basic development web server, or waitress stand alone- WSGI server.
setup.sh- downloads all needed python packages, including virtualenv,- and installs them into a local virtualenv called, very creatively, .virtualenv. Also initialises the database, if it doesn’t exist. If you totally stuff up the database, then you can simply delete it and run this script again.
database.db - the sqlite database, generated by setup.sh, normally.
db.py - a very simple database shell.
How Post Types work¶
TODO
How External Data Types Work¶
TODO
How the ‘Screens’ Work¶
Full Reference: Screen Design
How Different Libraries are used¶
TODO