Usage examples in the documentation

[gjost]

I do mostly back-end development. My organization hired somebody to do visual design for a site and they are delivering their work in the form of a set of django-pattern-library templates. Using the documentation site (https://torchbox.github.io/django-pattern-library/) I've been able to install django-pattern-library and I can see their work in /pattern-library/. It looks very nice.

My problem is that it is not obvious how to actually use these pattern templates in my project. I think I figured out that you {% include %} the templates and pass in one or more objects:

{% include "patterns/components/image_block.html" image=img, caption=imgcaption, url=imgurl %}

It's quite possible that this is not what you do and I don't actually understand it!

I found this in the code snippet under the "Document your patterns" section of Usage Tips. The django-pattern-library documentation contains hardly any examples of usage, or maybe it does but it's not obvious that these are different from the examples of writing pattern templates themselves.

I would like to see at least a short example at the bottom of the "Getting Started" page, as well as a more detailed "Using DPL In Your DJango Site" page.

[tbrlpld]

Hi @gjost.

There is nothing special about the "patterns" from a Django perspective. They are really just templates that you use as usual (via {% include %} as you point out).

What pattern library adds is the ability to show the templates without a Django view that passes the context to them (possibly through other templates). Instead of the Django view, you can define the context via the yaml files.

[gjost]

Just this explanation goes a long way towards helping me understand!

It feels to me that there are two audiences for the pattern library. One audience is made up of designers who know Pattern Lab and Django developers who need to support them, and the documentation is written for this first audience. The other audience is Django developers who want to use pattern library templates in their sites, and this is where the documentation is lacking (for me anyway).

I also cross-posted a question (apologies) and @thibaudcolas responded with

Hmm yeah we could use more examples. Do you think it’s a case of having a better online demo, or examples directly in the docs, or showcasing real-world projects using the pattern library?
The goal is to support developers using the same templates in the pattern library and for the project(s), so there is no delta ever. But it’s often convenient to also definite templates that are specific to the pattern library, for example when demoing a component within a specific context (Customizing a single pattern’s surroundings), or just lots of variations of the one component in one place (Multiple template variants).

The online demo links are good at showing how the pattern library works but they did not show me how to use patterns in my project.

I think putting your comment above and @thibaudcolas' together in a paragraph at the bottom of the Getting Started page would have answered most of my questions. A "Using Pattern Templates In Your Project" page with a couple examples would answer the rest of them.