Adding additional data via directives

[scatten...@gmail.com]

Hi,

at the moment I am working on building a photoblog with tinkerer as blogging engine. But while creating my own theme I encountered a (for me at least) pretty tricky problem: on the one hand I would like to add pictures to the post listing on the index.html and on the other hand add galleries to the posts, but so far I was not able to find a way to pass the information about these files from the .rst-file of the post to the index.html and the post.

I tried to add the data to the metadata of the post via a directive I defined in an extension, but I didn't find a list or dictionary within the metadata, in which I could store it.

Is there some place within the post data, I could use to achieve this or would I have to write this myself and possibly create a pull request on github?

Also is there a way to add default directives added to a post while creating it?

Thanks,
Björn

[Vlad Riscutia]

Hi and thanks for your interest in Tinkerer!

> I tried to add the data to the metadata of the post via a directive I defined in an extension, but I didn't find a list or dictionary within the metadata, in which I could store it.

Python is a dynamic language so you should be easily able to add a list or dictionary to the metadata from within your extension without impacting anything else.

> Is there some place within the post data, I could use to achieve this or would I have to write this myself and possibly create a pull request on github?

I suggest you look into creating a stand-alone extension and pulling it to tinkerer-contrib repo. I'm reluctant to pull targeted solutions into tinkerer core and this sounds like something that can be done as a standalone.

> Also is there a way to add default directives added to a post while creating it?

Tinkerer post and pages are based on Jinja templates (under <packagedir>/__templates/post.rst and <pakagedir>/__templates/page.rst). These templates contain the initial set of directives that come with a post (like comments, author etc.). You can override them inside a blog by creating custom post.rst and/or page.rst files and placing them under _templates subdirectory inside your blog root. Tinkerer should pick those up when creating new posts instead.

Hope the above helps. Let me know if you have more questions.

Thank you,

Vlad

[scatten...@gmail.com]

Hi,

thanks for the very helpful answers. Although I was eventually able to figure out the solution to my first problem by myself, I would most probably have searched for a long time to solve the second one.

At the moment I am trying to get a understanding of how all the Jinja template files within the themes play together to create the final blog and at which point I have to change something to get the result I would like to have.

But I also have a new question: Is there a way to either store template files within a extension directory or extensions within a theme directory? Especially the last one would be very handy to create themes, which have a deeper effect on the behaviour of a blog then what is possible with simple Jinja code.

And now back to the code.
Björn

[Vlad Riscutia]

I’ll try to briefly explain how things work:

 

Jinja2 is the template engine, which takes files and renders them by replacing stuff inside {{ }} and interpreting macros inside {% %} (things like for loops and such).

 

Sphinx uses Jinja in such a way that, given a set of html templates comprising a theme and the documentation information, it renders everything as a static website.

 

Also note that Sphinx extensions which render some custom html (for example, the image directive), do not use Jinja2, rather the extension itself spits out html code on render. This might be closer to what you want.

 

Tinkerer uses Jinja in two ways: one, through Sphinx – Tinkerer has a custom set of themes different than Sphinx, so we can have html5 support and a bunch of other neat blog-related things; two – Tinkerer also uses Jinja for post and page templates, so when you create a new post, we actually have a post.rst template and we use Jinja to render it.

 

If you want the post, by default, to contain an additional directive, you can create a custom post.rst template in your blog’s _template subdir so when Tinkerer creates a new post docunment for you, you get the directive auto-included. You can specify this in the documentation, and provide your poist.rst template with the extension, so users consuming your extension can create the same setup.

 

In terms of your extension/directive rendering itself as html, you don’t need to worry about theming, just make sure that the extension itself knows how to render itself as html. An example of that is the readmore extension in tinkerer/ext/readmore.py.

 

In short, if you want your extension to introduce a new directive, say mydirective, then in the implementation of that directive, you have to write the code that renders it as html. Then when Sphinx builds a post containing that directive, it will call the function that will give your directive the chance to render itself as html. Independent of that, you can extend post.rst template to always include the directive, so new posts always contain mydirective upon creation.

 

A change that would require altering themes is more intrusive than that, so I hope you don’t really need it. I’m reserving that for core functionality. Things like post timestamp, author, and tags, which are required by any blog, belong in that category, but not much else.

 

Thank you,

Vlad

--
You received this message because you are subscribed to the Google Groups "tinkerer-dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to tinkerer-dev...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.