Specifications for Major Milestone 1

TODO:
      - review this document
      - create tickets, and append each atomic item here with appropriate ticket number(s)

Major Milestone 1 is when we first have something that has value other than experience to us: some predefined journals can be released, where users can register, log in, and make their comments to the articles. Articles can be inserted to the journal just by the operator, from cli, or anyhow.

Our goal is to reach this point in not too many months, definitely before christmas...

1. Backend, database

1. articles and comments are stored in xhtml, with one extension: there are <webmore .../> tags in the text.
2. there exists some notion of ACL and rigths management (some table that stores information like (order, entity A, entity B, operation, allowed/disallowed) (SecuritySystem) (#194, #195)
3. articles and comments should be versioned within the database. (Both articles and comments are going to be editable by users. On edit, the text of the article in the database doesn't only get changed, but a new row is created with an increased version number field.
   Technically, since records are usually referenced by their id, on update we need to 1) create a copy of the row to be updated, 2) then change the value and increase version number in the actual row, not the copy. This actually can be arranged with postgres stored procedure/trigger system.) (#148)
4. each version of article/comment has separate set of childern, we call them valid for this version (CommentValidity). (#148, #219)
5. Although the journals shall have a common user base, we should be able to store a set of journals a user wants to be member of. When a user registers through a journal, he becomes the member of just that journal. He can simply add other journals later. (#223, #224)
6. for all articles created and comments made, it should be saved which journal were they originally created for. (#122)

2. Frontend

a) Webmore

0 (Noneh) | 6 (64.0h)

1. Webmore should be stable, we can't get it wrong. It is our big hit. (#103, #134, #135)
2. Webmore commenting (viewing and comment posting) is operational on the frontpage. (#103, #133)
3. Comments are nested (#132)
4. A post can be edited/deleted only by its user and people/groups who has right to do it. (#136)
5. For unallowed people, no edit/delete icons should appear. (#136)
6. If edit/delete icons remain texts (which is okay), they should be internationalized.

b) Comment posting and editing

0 (Noneh) | 4 (36.0h)

1. When the user clicks on a clause, the comment editor box pops up.
2. In that comment editor box, the user can switch back and forth from plain text to fckeditor. (#137)
   • the conversion is done similarly as is implemented by Gergo (todo: ask Gergo, where is this in his code).
   • upon posting, the text goes through some parser with which we can prevent malicious comment posts (e.g. javascript code that tweaks our page, broken xhtml, etc.). We can decide to allow just a subset of xhtml. We need to take care: fckeditor might have some idiotic behaviour (todo: ask Gergo about his experiences with fckeditor, what does it require from input and what does it give?) (#141)
3. The same mechanism (back and forth between plain text and xhtml) should be present when editing comments. (#142)
4. Important: check the <webmore .../> tags upon commit.
   • for a brand new comment, drop all those tags (#229)
   • when comment editing, drop every <webmore.../> tag that didn't exist before editing, and include all the missing ones at the end of the text. (See EditingWebmoredText.) (#230)
5. For comments that are not valid (their parent has a version that they are not valid for) there should be a 3rd icon at the top-right: [accept parent's edit]. Just for owners though. (CommentValidity) (#221)
6. Invalid comments should sign it with red border color in the expanded state. (See CommentValidity.) (#220)
7. Invalid comments should have some icon in the top right toolbar in expanded mode with which the reader can see the last version of the parent for which the comment was valid. (#242)
8. Comment posting should be initiable by users currently not logged in. When the click commit, they should get an interface to register/log in, and finally to get their comments made. (#131)

c) Internationalization

The system should contain some internationalization framework. The template fragments should be fillable with translateable content, and we should be able to create translations for hungarian. On the long run, we need to have some web interface for this, so our users can make their own translations. (#232, #233)

d) Initial data, domains, journal frontpages

1. A newly created blog, named XY should be available at XY.ourdomain, where ourdomain is anything we have, the blog creator should decide. (right now, alapos.hu, mukk.hu, thiblo.com). Should the blog creator not select anything, the default is thiblo.com. (#225)
2. Certain blog creators (right now, nobody, just us, since it may be a commercial option) should have the possibility to set an external domain name to their blogs. When an external domain name is set to a blog, then every internal link pointing to that blog should use the external domain. (#222)
3. alapos.hu should be the external domain of alapos.thiblo.com (#226)
4. thiblo.com should be the external domain of thiblo.thiblo.com (#226)
5. In released form, the url thiblo.com/blog/something should not be available at all, blogs should be available strictly just by subdomains. The system may have some "debug" switch, which may switches on the /blog/ links. (#225)
6. When we release this, then we'd like
   1. import initial data on the production system
   2. clear test articles and test comments There should be some script that does that clearing, while I think it is a good idea not to fork initial-data again.
7. We'd like to have 4 blogs in the initial data which are going to be operational upon first release: alapos.hu, mukk.hu, thiblo.com. (#231)
8. Wireframing should be somehow factored out, and the three journals should be created in initial data in a state when I can give it to Johanna, and say here: you tweak the design, edit and commit initial data of these blogs, until it gets final.
9. It would also be wonderful if we could create some basic blogs, with totally basic blog-design, on the fly after release. I don't say it should be a public interface, but I'd like to have my own blog, szamonkert-politikum.alapos.hu, and that would be nice if I could somehow create it. These casually created blogs can be totally basic, even need of psql usage is acceptable to create them. Definitely no gui for this, just some ./bin/create-trivial-blog --domain alapos.hu szamonkert-politikum style thing... (#213)

e) alapos frontpage

It is basically OK as it is now. It is important that we (me, Johanna) are able to edit its templates on the run --- even if need to use some command line client. (E.g: we want three blocks instead of just 2, or something like that). Also, we need to be able to fill the orange box. (#213)

1. The top right corner should contain the "sign in", "register", "logout", "account page", "what's this" menus, but only the applicable ones. (#234)

f) mukk.hu and thiblo.com frontpage

Their design should initially be the same as alapos.hu, just they should collect articles tagged with their own tags. We (administrators) should be able to edit their layout with some cli. (#231)

.hu pages should be by default hungarian, thiblo.com english. We should implement language selection later, since that is a really fucked up thing in today's web. (#232, #233)

3. Article page

1 (8.0h) | 2 (11.0h)

If a user clicks on the article, that article opens currently in a clear window with a margin. On the long term, we are going to need to store template id's for journal tags, and use templates (boxrenderers) to show articles too (actually, an article page is just a frontpage like entity with just one really really big article, but maybe other controls on the sidebars).

For the beta though, it is okay to leave it almost as it is:

1. There should be a header that shows the title of the journal we came from, with a link that takes us back. Also, the title of the journal should be shown nicely, and the picture belonging to the article too. (#214)

2. The article showing page should receive the information from the journal that which tag was the tag of the box in which the user clicked on the article. Using this tag information, the article showing page should offer some links to other articles.
   
   Not only articles with this tag, but some articles with this tag first, then other articles from the given journal. Later we need to do some sophisticated algorithm to select similar articles to offer. This is going to be a key thing. (#215)

4. Account page, preferences, notification

1 (3.0h) | 14 (47.0h)

1. Header of account page should show which journal did the user come from, on the right, with big font :), and being a link to the journal. (#117)

2. Account page should have a footer bar with around the same size and color as the header is currently. It should contain links to every journal the user is member of. (#123)

3. Below the footer line, it should embed the help page into itself. (#124)

4. Before release, the possibility of experimenting with the account page appearing in popups would be nice. (#127)

5. Comments management should work. (#120, #121)

6. Account page should be internationalized. (#125)

a) Preferences box

1. There should be two groups of settings in the expanded preferences box: personal data, and notification settings. I don't yet know how exactly to do it visually, use the force, luke. But make it nice. If there is just one page, use some grouping, label the groups, and create margins and paddings and spaces there just like the gnome hig describes how to do it. For example, give the whole thing some padding inside its frame, and put some spacer for the Save button. (#116)

2. In the space on the left of the expanded preferences box, create an icon that mimics the back button of the browser and takes us back to the account page. I call this our back button. (wiki:Specs/MajorMilestone1:pref.png ) (#119)

3. The navigation bar should start with the actual journal we came from, so instead of "Account >> Preferences", it should be "Alapos.hu >> Account >> Preferences". (#117)

4. The links here (navigation bar, header, footer, our back button) should contain an onclick that checks if the data was saved and warn if not, handeling the users choice (cancel, don't mind). (#118)

5. Data fields in the preferences box:
   1. personal settings: Nickname, First name, Last name, Email, OpenID URL (read only, with a question mark to tooltip style popup help).
   2. Notification:

        [ ] Get notified when my comments gets commented
            [ ] Get notified if any descendant of my comments get commented
      

      #114, #115

6. Below the email, the system should sign if it is verified or not. (#75, #227)

7. In the notification part: sign if notifications are not going to be sent because of unconfirmed email. Also, give a button that will resend confirmation mail (in case it is lost). (#228)

b) Comments management box

1. Collapsed state: it should contain a table with rows corresponding to the last 10 comments made by the user. Columns: first few words of comment (not more than 15 chars), date, number of responses.
   
   Clicking on the rows should expand the comment management button in the same state as if the user first expanded it then clicked on the same row.

2. Expanded state: a similar table, but
   1. we have a column with the title of the article, and the fields are wider.
   2. all comments are shown, not just the last 10.
   3. clicking on a row shows the actual expanded comment (in an iframe or a popup). There the comment editing facilities should be alive and well. (Webmore should also work, if possible, but maybe just collapsed webmore comments should be shown, without the possibility of opening them.)
   4. there should be a link for all comments that actually take us to the article in question (using the journal to which we made the particular comment. The same article might flow from journal to journal, but as there is specified in 1.6. we have saved at the time of comment creation which journal were we reading).

5. Registration, login

1 (16.0h) | 4 (33.0h)

1. After talks with Misi we decided not to require email verification, although we make it possible (if the user gives or changes his email, he automatically gets a confirmation letter). However, we send notification mails only to confirmed emails. (#114)

2. The actual e-mail confirmation system (with a link that the user can click and accepted e-mail confirmations) should be developed. (#75)

3. If the user clicks "Register" by hand, he should get the registration page where he can either choose "register with openid" (with a question mark icon that pops up a "wtf is openid", or local registration.
   
   Local registration is a wizard that asks for a nickname, a password, and recognizing letters in a graphical image, and creates an  http://id.thiblo.com/nickname openid for the user.
   
   This wizard must contain appropriate error handling (what if the nickname already exists, or the captcha is failed?). (#216, #223)

4. The initial data should contain the link that leads to this registration.

5. This registration mechanism should be built into the comment posting system, so that somebody can post a comment and then lead through this wizard.
   
   On successful wizard completion, his comment is accepted. (#131)

6. On successful wizard completion, (and possibly after comment commit happened), the user should be presented with an optional link that leads to his account page, preferences box expanded, where he can fill out his email. (#216, #223)

7. Login and logout should be available from alapos frontpage after initial data import.

8. Login window should either appear on a layer, darkening the actual content, or in a clear page, but as a centered, dialog like thing.
   It shouldn't say OpenID, it should say "Nickname (or openid)", and there should be a password box too. If the user types some url there, the password box might be on the fly be hidden.
   If the user typed only a nickname and a password, he should be authenticated with our local openid server with the given password. (#235, #236)

6. Command line interface

2 (24.0h) | 3 (40.0h)

For this beta, without interface to create journals and tags and all that, we should have a simple command line interface with which we can modify design, layout of the pages, and post or delete articles, and delete offensive comments. (#213)

This command line interface need not to be clever and usable by anybody through the net, we ssh into the production server and use it from there.

Operations it needs to provide:

1. export the current layout of a journal to yml (#211)
2. reimport the potentially changed data (for example, the boxrenderer is changed) (#213) without clearing out existing connections in the database (so without getting new id). (#212)
3. export/reimport boxrenderers, css files too (#211)
4. posting an article (given a file name, a title, and a tag) (#213)
5. listing articles, (id, title, current tags) (#213)
6. tagging an article with a given tag (#213)
7. removing a tag from an article (#213)