Post editor design doc
As an SSE eboard member I would like the ability to add and edit posts so I don't need to coordinate with the website team about what exactly needs to be in the post.
The architecture for this feature could be a new web application possibly written in ruby on rails. Ruby on rails would be good to use since we can integrate easily with the website's markdown engine kramdown to generate html previews of the post, and to validate the syntax of the markdown with the exact markdown engine the website uses.
From the ruby on rails backend we can integrate with the Github API to publish the post. With the Github API we can publish the post using the webmaster's Github account, or if we can have a user authorize themselves with a personal Github account. If we go with the route of having a user authorize themeselves with a personal Github account we can possibility limit the use of this app to only memebers of the msoe-sse Github orginizaion.
When the post gets published this app will open a pull request in the main website's repository. This will give the webmaster a chance to look over the post and to make sure that the post editor application created a valid post.
Using ruby on rails might be intimidating for some members since the framework is very large and includes a lot of components. Some solutions to this would be to disable some parts of the framework such as ActionMailer. We need to disable the ActiveRecord component of rails anyway to not require a database connection. Or we could use a simpler framework we could look at using a framework like sinatra. Sinatra may be simpler but it doesn't use the MVC design pattern. So, from an architecture standpoint it may be better to use ruby on rails depending on the scale of the features we add to the new application.
Above shows a simple mockup of what the authorizaion view could look like. All that we would probably need is a textbox for the username and the password and a login button. An alternative solution could be that we can authorize the app with Github possibly but that would take some investigation.
Above shows a list of what a post list view could look like. It would start initially with all the posts in the site. It we initially start with all the posts in the site there would need to be some investigation into if we need to have a limit of how many posts we can fetch at once. There will be the option to search and an option to choose a search filter such as by author, tiltle, tags, etc.
Above shows a crude mockup of what the view to edits posts could look like. We could have textboxes to enter in basic information such as the title and author of the post. There could be other fields such as tags, and the hero of the post. The text area on the left would be where the user would type in their markdown and the right would display the preview html. Instead of having a button to fetch the preview we would also fetch the preview everytime the user edits the markdown text area. If we wanted to go with an alternative design instead of having two text areas next to each other maybe we could go with a tab view kind of like Github's markdown editor.
AuthorizationController: A controller class handling authorization. The class will contain a GithubService object to authorize a user with Github using the Github API
HomeController: A controller class responsible for the main view of the application after authentication. It will contain a GithubService object to get a list of posts to possibly from the website repository. Also, it will allow a user to add a new post.
PostController: A controller class responsible for editing posts. It will contain a KramdownService object to get a html preview of the user's markdown, edit their markdown into a valid Jekyll post. Also, it will contain a GithubService object to handle publishing the post to the main website repository
KramdownService: A service class handling all operations related to kramdown
GithubSerivce: A service class which is responsible for interacting with the Github API
Design Doc Author: Andy Wojceichowski