artskydj/noddity-render-dom

Render Noddity posts to the DOM

noddity-render-dom

Render Noddity posts to the DOM

example

var renderDom = require('noddity-render-dom')
var Butler = require('noddity-butler')
var Linkifier = require('noddity-linkifier')
var LevelJs = require('level-js')

var db = new LevelJs('noddity-posts-db')
var butler = new Butler('http://example.com/blogfiles/', db)
var linkifier = new Linkifier('#/myposts/')

var options = {
	butler: butler,
	linkifier: linkifier,
	el: 'body',
	data: {
		config: {
			configProperty: 'configValue'
		},
		arbitraryValue: 'lol'
	}
}

renderDom('post-template.html', options, function (err, setCurrent) {
	setCurrent('my-awesome-post.md', function (err) {
		if (err) throw err // 404
	})
})

api

var renderDom = require('noddity-render-dom')

renderDom(post, options, cb)

• post: a Noddity post object or a post filename
• options: all the other arguments
  • butler: a Noddity Butler
  • linkifier: a Noddity Linkifier
  • el: a selector string of the element to which the Ractive object will be bound. Optional
  • data: any properties on the data object will be made available to the templates. Optional
• cb(err, setCurrent): a function to be called when the first render is finished.

setCurrent(post, [data,] [cb])

setCurrent is a function/event emitter.

Call the function to change the current post to a different post.

• post: a Noddity post object, or a post filename
• data: any properties on the data object will be made available to the templates. Optional
• cb(err): an optional function that is called when the current post is set or a fatal error occurs. Optional

events

• error(err) is emitted on non-fatal errors, e.g. an embedded template not loading
  • err is an Error object

setCurrent('my-post.md', function (err) {
	if (err) throw err // Could not set 'my-post.md' to be the current post
})

setCurrent.on('error', function (err) {
	console.error(err) // Probably an embedded template didn't load
})

values accessible in ractive expressions

• postList: an array of post objects that have dates, ordered by date descending. Metadata is accessible on the object iself without having to use the metadata property
• posts: an object whose keys are the post file names, and whose value is the post object. Right now the keys all have periods . stripped from them due to an issue with Ractive
• removeDots: a function that takes a string as input and returns a version with dots . removed
• current: the file name of the currently displayed post (the one specified in the url). Also a partial of the current post (set by setCurrent()). Can be accessed by doing {{>current}} or {{{html}}}
• metadata: an object of the metadata of the current post. E.g. {{metadata.title}} accesses the title of the current post, even if it is in an embedded template.
• Metadata values of the template are exposed. (Except in the root post, where the current post's metadata is exposed). E.g. {{title}} accesses the title of the current.

ractive expressions example

root.html

<h1>{{title}}</h1>
<article>
	{{>current}}
</article>
Written by {{author}} on {{date.toDateString()}}.

post1.md

title: welcome
date: 2015-10-30
author: Joseph

Hey, thanks for visiting my blog!!!

::embed.md::

embed.md

title: embed

The title is: {{metadata.title}}
My title is: {{title}}

Set root.html to be the root, and post1.md to be the current post:

renderDom('root.html', options, function (err, setCurrent) {
	setCurrent('post1.md', function (err) {
		if (err) throw err // 404
	})
})

End up with something like:

<h1>welcome</h1>
<article>
	Hey thanks for visiting my blog!!!

	The title is: welcome
	My title is: embed
</article>
Written by Joseph on Fri Oct 30 2015

license

VOL

noddity-render-dom's Issues

Browser tests

Run the current tests in the browser.

Preferably it will be automated, so it runs in travis.

Use browserstack?

Support filename input as well as post object

Like TehShrike/noddity-render-static@c5f8f7b

Upgrade noddity modules to use ractive 0.8

I'm considering setting ractive as a git dependency rather than an npm dependency until ractive 0.8.0 is published to npm.

1. Be able to fix/work around warnings
2. Make some things less hacky.
3. However, git deps feel weird.
4. As far as I know, git deps aren't dedupe-able, but idk if that matters. Is ractive being required elsewhere?

/cc @TehShrike

Try to eliminate the warnings that show up in debug mode

Ractive warns that you're referencing partials that don't exist yet.

Right now, the partials don't exist until after we call resetPartial later.

Remove "current" partial, use data's "current"

http://jsfiddle.net/ddzg0uvw/7/

Should update postList on "index changed" event

Should update postList on "index changed" event.

butler.on('index changed', funtion (idk) {
  postList = idk.sort()
})

Limit posts loaded in parallel

Should set the butler option parallelPostRequests to 4.

Depends on TehShrike/noddity-butler#6

Document exposing current metadata

• Wait for a reply here: https://github.com/ArtskydJ/noddity/issues/4
• Update the readme to include details of this commit: d2ccd18
• Push a minor release to npm

Querystring parameters should be exposed

Partially implemented in v2.2.0, but the implementation may need to change...

See TehShrike/noddity#23.

Posts starting with a number probably throw an error

TehShrike/noddity-render-static#7

First load is slow

See if it is waiting for all the posts to load. It shouldn't be, but it might be.

Backwards compatiblity for {{{html}}}

Add "values accessible to ractive expressions" section to the readme

Like https://github.com/TehShrike/noddity-render-static#values-accessible-in-ractive-expressions

Tests

• Copy noddity-render-static tests
• Get the tests passing
• Setup travis
• Write tests for content being updated when posts change. f8af627 Make it pass. 3f82bcd
• Write a test to ensure that all callbacks are called asynchronously. c7dd0f8
• Write tests for data being removed from scope if the metadata changes
• Write tests for content being updated when root post changes.
• Write tests for content being updated when current posts changes.

Pages should still load/render even if there is a Ractive parse error

If you render some markdown like this:

# Sup dawg

{{}
howdy

Ractive throws this error, visible in the console:

ractive.js:3628 Uncaught ParseError: Expected closing delimiter '}}' after reference at line 4 character 6:
<p>{{}
     ^----

This error message should be displayed in the DOM, as the post content. Probably inside a <pre> tag.

Right now it shows up only in the console, and breaks Noddity from running. The url gets updated, but the content never changes, which is pretty bad UX.

Update content when it changes

The content does not update if an underlying post changes.

https://travis-ci.org/ArtskydJ/noddity-render-dom/builds/84028477#L174-L181

Need a test/fix for internal mediawiki style links with double square brackets '[[', ']]'

new Ractive({
    staticDelimiters: [ '{{{{', '}}}}' ],
    staticTripleDelimiters: [ '{{{{{', '}}}}}' ]
})
// or whatever we decide

Investigate usage of partials for embedded templates

We investigated partials a while ago and had an issue with them. Maybe the issue was that we didn't know how to change a partial's template?

Now we know about ractive.setPartial()!

Here is a jsfiddle that utilizes ractive.setPartial(), but I'm not sure it proves a thing. While ractive.setPartial() seems to work fine, we should probably do more testing.

cc @TehShrike

Do butler.refreshPost(post) on setCurrent(post)

Clear unparseable posts from the cache more aggressively

Based on #23 (comment)

Templates/posts that are not parseable should not be cached for nearly as long as the default.

Perhaps they should not be cached at all and should be reloaded on every navigation?

This will require a new cache-clearing method to be exposed by the butler.