Metadata-Version: 2.4
Name: splent_feature_public
Version: 1.9.0
Author-email: DiversoLab <diversolab@us.es>
License-Expression: LGPL-3.0-or-later
Requires-Python: >=3.13
Description-Content-Type: text/markdown
License-File: COPYING
License-File: COPYING.LESSER
Dynamic: license-file

# splent_feature_public

The public home page of a [SPLENT](https://splent.io) product, served at `/`
(`public.index`) inside the theme's public shell.

The home knows nothing about content features. It draws the product's brand
copy from the `SITE_*` settings, and every feature that has something for the
home contributes it through a template slot. What this feature provides and
requires is listed in the `[tool.splent.contract]` section of
`pyproject.toml`, which `splent feature:contract --write` keeps in sync with
the source.

## Slots

| Slot | What goes in it |
|---|---|
| `home.hero` | The whole hero. Only for a feature that owns the headline moment (an edition, a campaign). When nothing renders, the home draws its own hero from `SITE_*`. |
| `home.section` | Full-width sections (upcoming events, partners, latest posts), in their registered `order`. |
| `home.aside` | A narrower column beside the sections (counters, a call to action). Optional. |
| `layout.sidebar.top` | Filled by this feature with the "Home" entry of the product sidebar. |

```
 no home.aside                    something in home.aside
┌─────────────────────────┐      ┌────────────────┬────────┐
│ home.section            │      │ home.section   │ home.  │
│ home.section            │      │ home.section   │ aside  │
└─────────────────────────┘      └────────────────┴────────┘
                                  under 960px the aside goes
                                  below the sections
```

The home only splits into two columns when some callback of `home.aside`
returns markup, so a hook can decline on its own (return `""`) and the
sections keep the full width. With an aside and no section, the aside takes
the whole width.

A feature fills a slot from its `hooks.py`, as in this one for `home.aside`.

```python
from flask import render_template
from splent_framework.hooks.template_hooks import register_template_hook


def home_counters():
    return render_template("hooks/home_counters.html", total=count_items())


register_template_hook("home.aside", home_counters, order=50)
```

Lower `order` renders first. Each callback renders a self-contained block
(a card, a box). Several of them stack with a gap between them.

The columns are styled by `assets/css/home.css` (classes `home-columns`,
`home-columns__main` and `home-columns__aside`). A skin or a product changes
the split with the `--home-columns` custom property.

```css
.home-columns { --home-columns: minmax(0, 1fr) 20rem; }
```

## Configuration

Declared in `[tool.splent.config]`. A product overrides them in its own
`[tool.splent.config]`.

| Key | Default | What it does |
|---|---|---|
| `PUBLIC_SIDEBAR_HOME_LINK` | `true` | Shows the "Home" entry at the top of the product sidebar. A product whose logo already leads to the home page sets it to `false`. |

```toml
# the product's pyproject.toml
[tool.splent.config]
PUBLIC_SIDEBAR_HOME_LINK = false
```

## Use it in a product

```bash
splent feature:add splent_feature_public
```

## Develop

```bash
splent feature:test splent_feature_public
splent feature:contract splent_feature_public
```
