Guide on UI customisation

abhas commented 3 years ago

I would like to customise the user interface to change colours and fonts and so on. I also want to put each entry / posting into a sort-of "card". I'm not able to figure out where the frontend code might be. It looks like the UI is completely implemented in J Javascript. I also tried searching for the CSS styles that I might be able to adapt to my liking.

Any guidelines on how to customise the UI would be very helpful. Thank you for this wonderful project.

jamesvandyne commented 3 years ago

Thank you for the comment :) Until I have time to properly document this, maybe will help get you started. Let me know if anything is unclear.

The frontend for the blog is written using Django templates, so it's all rendered on the server. They're located in the apps/templates/public directory.

Each post type can be modified by editing the corresponding template in apps/templates/public/entry/. The detail variable can be used to change rendering on a list page vs a detail page.

Tanzawa uses tailwind for the css, so you'll need to replace remove / add class names on the elements within the templates for now.

The easiest way to add a custom style sheet would be to add a head block to public/index.html.

Something like:

{% block "head" %}
<link href="{% static '/custom.css' %}" rel="stylesheet">
{% endblock %}

And then place your custom.css file in the static directory. You may need to restart the server for Django to find it. If you're Tanzawa in production with gunicorn, you'll need to run the manage.py collectstatic to gather the css file.

I'd like to add support for custom themes at some point in the future.

Lastly, while I don't foresee huge changes to the templates soon, when I do modify them you may run into merge conflicts when you update. Probably not an issue yet, but something to be aware of.

MaybeThisIsRu commented 3 years ago

I'd donate to you for a theme decoupling. This is high on my list! :)

jamesvandyne commented 3 years ago

I appreciate the sentiment 😃. It's not money that's preventing me, it's time.

I've been thinking about how to handle theming for Tanzawa properly. It's a big task, but not impossible. There's 2 different ways to think of theming: 1) css only changes theme support, 2) complete theme support (i.e. colors and layout). The move from css only changes wouldn't be much less work than allowing full customization.

Roughly here's what I think would be required:

Extract all mentions of tailwind colors from templates/public (e.g. bg-negroni-700 ) and replace them with a common name – perhaps role based?
Create a record / setting somewhere ( django-admin?) to track the active theme.
Create a custom template loader (or other shim) that will prioritize rendering with the selected theme's public themes.
Set Tanzawa to only include the css of the selected theme.
Document how to make a custom theme.

Theming isn't my top priority, but it's not low either. If anyone is interested helping before I have a chance to get to it, I'm happy to answer questions / provide direction and so forth.

MaybeThisIsRu commented 2 years ago

A yaml or json file that then generates CSS automatically -- meaning the underlying does have to be custom classes -- is something that I think is a good, low-effort step.

Something like:

base:
   background: #fbfbfb
   color: #3d3d3d
buttons:
   color: #3d3d3d
links:
  textDecoration: 1px underline

What are your thoughts on that as a first step? Would that help with making this feature incrementally or be a deterrent?

jamesvandyne commented 2 years ago

@hirusi Oh, I like that idea a lot.

I'm not super familiar with webpack / tailwind (just the minimum to get this running, really). Do you have a feeling of how it could be implemented or what changes would be required?

MaybeThisIsRu commented 2 years ago

Oh! Tailwind! We could just have a guide linked to on creating Tailwind presets. That's a almost-no-effort start on customizing UI. We'd need some docs on how the UI has been thought of.

Layout would be far trickier.

jamesvandyne commented 2 years ago

Started on theme support in https://github.com/jamesvandyne/tanzawa/pull/150 but I am running into errors compiling the css. I think those errors may be a tailwind bug, rather than a configuration issue, but not sure.

jamesvandyne commented 2 years ago

@abhas @hirusi I've merged support for making themes in Tanzawa and documented it here. I'm going to close this issue. If you find theme support lacking or notice any bugs, please do open a new issue or submit a PR. 🙌

jamesvandyne / tanzawa

Guide on UI customisation #83