Description
This tool is a Django application that generates the "Table of contents" of the page on which it is installed. Due to the peculiarity of the Django framework, all generation occurs on the server, that is, the SSR rendering method. This application also creates anchor links to the collected chapters, if the heading have an id attribute.
Instalation and Setting up
Let's start by installing the necessary package, my package. You can download it here, but let's download it from PyPi. Don't forget to install the virtual environment and activate it accordingly.
Now let's set up the project. In the settings.py file, connect the application and the corresponding middleware:
And now, in order for this application to find pages to add "Table of Contents" to, your views will need to return a TemplateResponse object. For example, I have a standard article view that returns an HttpResponse using the render shortcut function:
Instead of the render function, you need to substitute TemplateResponse. Like this:
We are done with setting up and installing the necessary django application. Now, about how and where to insert the "TableOfContent" template.
A usage guide
Choose the required template and the place where your article index will be. I usually insert the article index block at the very beginning. After that, you need to insert a piece of the template like this:
Here, you can see all available template variables that are used to customize and tune the article content block. More about them in the next chapter.
Template context variables for customization
- NO_REF - valid values, True, False. Determines whether an internal anchor link of the chapter will be created. Links will only be created if the id attribute is specified in the corresponding headings.
- LIST_STYLE - valid values, all currently supported by the list-style-type style. Which list icons to use.
- WITH_HEADER_TYPE - valid values, True, False. Determines whether the tag name (h1, h2, h3, h4, h5, h6) will be added before the element.
- WITH_PADDING - valid values, True, False. Determines whether there will be indents
- WITH_TITLE - valid values, any string. If not defined, default value will be used: Table of content
- DISALLOWED_TAGS - allowed values, string containing h1, h2, h3, h4, h5, h6. Determines which headings to include and which not, depending on the tag name.
- DISALLOWED_HEADERS - valid values, string containing any heading content. Determines which headers to include and which not to include, depending on the contents of the header.
- isTableOfContentMiddlewareConnected - to ensure that django-simple-toc is connected properly
CSS classes for additional customization
By default, these styles do nothing, they are for the users of the package. If they want to change the appearance of the block. Here are the classes for styling:
- toc-title
- toc-list-container
- toc-list-item
- toc-list-tag-name
- toc-list-tag-content
How it works
Now that you know how to install and use it, you might want to learn how it works. Well, I wouldn't say it's that complicated, but it's still useful to know what you're installing.
So, I implemented it as a Django app, with a little middleware, or shim between the final rendered template and other middleware. Here's the middleware code:
I override 3 methods. We are not interested in the __init__ and __call__ methods, because this is the minimum code required for this package to be able to work. The only thing I will say is that the __init__ method is executed once when the project is launched, and there you can define common class members for further work.
The process_template_response method is called immediately after a particular view (be it a function-based or a class-based) returns an object of the TemplateResponse class. This is why it was necessary to redesign the article view in the beginning.
In the function itself, we parse the rendered content and find all the heading tags. After that, we go through them and update the context data storage.
There are two templates used by this application, table-of-content.html:
And table-of-content-element.html respectively:
What each variable means, you already know from the first chapters.
Reviews
(0)