StoryArchitecture

From GeeklogWiki
Jump to: navigation, search

The main thing to understand with the Story "Rewrite" in 1.5.0 is the States a story may be in and how they interact with each other. I'd do a State Transition Network, but, no suitable diagramming tool to hand.

Essentially, a Story (or any piece of textual content by extension) has four main states and a few minor "transitional" states:

  • Display

The Display state is the one that is rendered. All that is needed to be done with an element of a story in Display state is to echo it to the page. It is safe to do so. It is clean and secure and HTML friendly. If there was a BBCode postmode, it would be bold for example. Autotags have been replaced, plaintext links made clickable. All ready to go.

  • Edit

The edit state is the one that is rendered in the edit controls. It just needs to be echo'd into a textarea tag or value attribute. It contains nothing but the edit version of a piece of text. (If there was a BBCode postmode, it would be [b]bold[/b], if HTML it would be <b>bold<b>). Autotags have not been replaced. Plaintext links are back to just text urls.

  • Database

The state that is in the database.

  • Rest

This is the native state of the class. There is very little work to do to move to display state. Really, only Autotags.

The sub-modes are:

  • Post

The result of an edit form being sent back by a $_POST operation. Stories should only be in this state for the briefest of moments.


The following must be true at all times:

addslashes(Rest) === Database stripslashes(Database) === Rest

The Rest state must be AS CLOSE TO Display as possible. Only real time critical changes (Autotags) and non-reversible operations (none so far) must be required to move to the Display state. Essentially, for plaintext and html:

PLG_Autotags(Rest) === Display

The move from Edit to Rest must be reversible. Always. i.e. EditMode(Rest) === Edit and LoadFromRequest(Post) === Rest

Also The following must be true: LoadFromDatabase(Database) === LoadFromRequest(Post)

The idea being that the LoadFromRequest operation and the LoadFromDatabase operations happen as soon as data comes in from POST or database and moves to the Rest state it should be trivial to move it to Display state. Ideally, nothing should need doing, autotags is an exception. Autotags exist to provide up to the second information, and thus must be parsed on render. The work should be done in LoadFromRequest (possibly heavy duty processing to provide safe html markup that can be reversed) and EditElements which reverses that work and escapes for display in the edit fields.

Currently, there are two postmodes HTML (including advanced editor) and plaintext. Plaintext escapes all HTML (no injections or XSS possible at all) and makes links click-able and puts line feeds into place. HTML parses HTML against an allowed list (very minimum risk) and escapes disallowed HTML, leaving it escaped (because that's the right thing to do...).

Postmodes exist to allow formatting of text. Other common options are bbcode and wikitext, which should in my opinion be implemented the same as text and html. They should be responsible for removing security risks and providing required formatting in a safe way.

Personal tools
Namespaces

Variants
Actions
documentation
Tools