Refine, extend or compose
Table of contents
Introduction
Your feature can change another feature in three ways. Compose works through what the other feature already offers, extend adds data or URLs to it, and refine replaces part of it. Pick the first that works, since each step down ties your feature closer to the other and leaves less room for a third.
# hooks.py of your feature, composing with shop
from splent_framework.hooks.template_hooks import register_template_hook
register_template_hook("shop.detail.before_meta", collection_badge)
This fills a slot the base opens. It needs no declaration, and any number of features can do the same.
Choosing one
collections composes and extends at once.| Outcome | Declared in | What it may do | Several at once |
|---|---|---|---|
| Compose | Only the UVL dependency (b => a) |
Fill the base’s slots, call its services, listen to its signals, link to its routes | Yes, without limit |
| Extend | refines and extends |
Add columns and methods to a base model, add routes to its blueprint | Yes, if no two add the same name or URL |
| Refine | refines and overrides |
Replace a template, a service or the base’s callbacks in a slot | No, one refiner per target |
Extend and refine both make your feature a refiner of the base, declared in [tool.splent.refinement]. A refiner loads after its base and is checked against the base’s extension points.
Composing with a feature
Composition is the default. Your feature keeps its own models, routes and templates, and reaches the other one only through what it publishes.
- Hook slots. Register a callback with
register_template_hook. Hooks add up. See Template hooks. - Services.
service_proxy("ShopService")gives you the base’s service, refined or not. - Signals.
connect_signalreacts to what the base emits, without the base knowing who listens. - Registries. A base keeps a registry module and your feature fills it from
init_feature.
import importlib
def init_feature(app):
try:
slots = importlib.import_module("splent_io.splent_feature_reports.slots")
except ImportError:
return # no reports in this product
slots.register_kpi("notes", _l("Notes"), count, home=True)
Wrap the import in try when the other feature is optional. The contract then lists it under features_optional, and the model needs no constraint between the two.
Extending a feature
Extend when the base’s records must carry something new, or its blueprint must answer a new URL.
[tool.splent.refinement]
refines = "splent_feature_shop"
[tool.splent.refinement.extends]
models = [{ target = "Item", mixin = "ItemCollectionMixin" }]
extends.models injects a mixin’s columns and methods into a base model, and your feature owns their migration. extends.routes adds routes to the base’s blueprint. See Refinement.
Several refiners can extend one base, as long as no two add the same attribute or URL, and none reuses a name the base model defines. A method marked @typing.override is the only exception.
Refining a feature
Refine only when something the base does has to be replaced, and the base cannot offer a slot or a setting instead.
overrides.templatesreplaces a template with your copy.overrides.servicesreplaces a service with a class merged from yours and the base’s.overrides.hooksswaps the base’s own callbacks in a slot for yours.
An override is exclusive. Two refiners claiming the same target collide, so keep it in one of them, or declare them incompatible with a UVL constraint such as !(collections & sales).
A template override costs upkeep. Your copy must follow every change the base makes, and it hides every slot the base opens there. Ask the base for a slot first. A slot serves every later feature, and an override serves only yours.
Keeping refinement shallow
- One level. A refiner refines a base that refines nothing. Chains are refused at boot, by
product:validateand by thefeature:refinewizard. - Few targets. Declare only what you replace. Each override is a claim no other refiner can make.
- Additive first. A column, a route or a filled slot leaves room for the next feature.
The same rules run in feature:refine, in product:validate and at boot. Validation lists them.
A full example
collections groups the items of a shop into collections. Asked in order, the three questions sort it out.
- Can it work through what
shopoffers? Its own model, archive and admin screens need nothing fromshop, so they compose. So does what it shows on the shop pages, through the slotsshopopens. - Does it need the data of
shop? Yes. An item must know its collection, socollectionsextendsItemwithcollection_id. - Could
shopopen slots instead of being overridden? Yes, so nothing is overridden.
Page of shop |
Slot | What collections puts there |
|---|---|---|
shop/list.html |
shop.list.title, shop.list.hero, shop.list.content |
A featured collection, or nothing so shop renders its own page |
shop/detail.html |
shop.detail.before_meta |
The item’s collection |
shop/admin/list.html |
shop.admin.list.actions, shop.admin.list.item_meta |
Buttons to its screens, and each item’s collection |
shop/admin/form.html |
shop.admin.form.fields |
The collection selector |
collections claims no template of shop, so another feature can use the same slots, and a change to the shop templates needs nothing from collections.
See also
- Refinement, declaring and writing a refiner
- Template hooks, slots and hook replacement
- Validation, the rules and where they run