Design and Goals

[ppurang]

I rather like the way http://www.html5rocks.com/en/tutorials/eventsource/basics/ shows a blog (pay attention to the ⊕ it ). For comments DISQUS does it good. But instead of hosting comments on DISQUS they'll be hosted on our backend.

One very important detail is the use of html5 semantic markup see http://html5doctor.com/article-archive/ section "HTML5 Semantics" or again http://playground.html5rocks.com/#semantic_markup

Each element should get an anchor to allow fine grained linking within the document.

To support easy editing the json should contain markdown and this markdown could then be translated on the client using JS. see http://www.showdown.im/ or perhaps http://code.google.com/p/pagedown/wiki/PageDown

Once again :

HTML5 semantic markup fluid grid uncluttered markdown rich client (js client driven by webservices)

[ppurang]

{
    "uuid":"8aac796b-e3f4-4e89-8b23-735110f8c3ba",
    "state":"Nascent",
    "created":{
        "time":35255716153154
    },
    "content":{
        "headline":{
            "headline":"First *blog post* ever"
        },
        "sections":[
            {
                "headline":{
                    "headline":"Summary"
                },
                "paragraphs":[
                    {
                        "content":"This journey took a long time. It almost never started and then it had many close calls. This post narrates this story."
                    }
                ]
            },
            {
                "paragraphs":[
                    {
                        "content":"It would have been so easy -- just pick a blogging platform and\n voila one has a blog with a lot of functionality. In case you really want to own it just roll out one of the many blogging suites on your server. But **none** can boast of the pain and joy creating your own software\n        brings with it. The creativity, the decision making, the struggles to implement the vision at the micro and macro level,\n        and other nitty gritties spice up the adventure."
                    }
                ]
            },
            {
                "headline":{
                    "headline":"The need"
                },
                "paragraphs":[
                    {
                        "content":"[Twitter](http://twitter.com) is too terse;\n most journals have more ads then real content;\n a private diary isn't social enough."
                    },
                    {
                        "content":"A good blog is about content, content and content.\n A great or unique writing style makes the difference when content is not a problem.\n        All other things equal a great design and technological schnickschnack give the blog that aura of invincibility."
                    }
            ]
        }
    ]
},"tags":[
    {
        "tag":"blog"
    },
    {
        "tag":"writing"
    }
]}

[jasalguero]

About the object example:

• For the display logic I need to differentiate 2 parts of the post, the summary (or excerpt) and the "rest", will the backend provide that separation?
• What's the purpose of having multiple content objects inside a paragraph? And the headlines?

[ppurang]

Do we need this separation? The front-end always gets the entire content and needs to just use another view for the summary (title + special section called summary). That way we avoid too many round-trips. The only problem arises when the content including comments becomes too large and minified and gzipped json isn't enough. When we see that this is an issue we can design around it. Mobile clients might need this earlier.

Excellent question about the seemingly redundant info in the json structure. The reason is actually an example of implementation details leaking out as a spec. Think scala case classes:

case class Headline(headline: String)

case class Section(headline: Option[Headline] = None, paragraphs: List[Paragraph] = List())

case class Paragraph(content: String)

Where each paragraph is semantically linked to a <p></p> (though I am surprised that paragraphs are treated as an array of contents and not List[paragraph > content] I have to double check that one). I'd like to keep it this way because it helps making the backend more type-safe instead of just using anonymous strings. I hope it doesn't make the JS code harder to write!

[jasalguero]

Still more doubts

• I see your point of putting all the content in the same response, but it has the counterbalance that you have to load all the content before being able to show a preview. And the full content may be long and content external resources, right? Is all a trade off. An alternative would be loading only the previews to render the page and as soon as is finished start loading in the background the full content of each post.
• The structure of the text is defining the structure of the class?
• How is the post writing supposed to work? It will be a Text Area that then the server will split into the corresponding sections? Or structured already in the sections,paragraphs and headlines?
• What is the use of headline in the client side? (H1 tag??)
• I was checking Markdown and the support for images seems quite limited, cannot define position or size, (and no support for video/audio), have to take that into account. In case we need an alternative we can consider using directly HTML code, there are a few implementations of editors -> https://github.com/xing/wysihtml5/