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

Compose first, extend when you need the base's data, refine last Three questions in order. If the feature can work through the base's slots, services and signals, compose. If it needs a column on the base's model or a route on its blueprint, extend. If the base could open a slot instead, open it and compose. Only otherwise refine, replacing a template, service or hook. Your feature has to change another feature Can it work through what the base offers? its hook slots, its services, its signals Yes no refinement Compose Fills the base's slots, calls its services. Any number can coexist. No Does it need the base's own data or URLs? a column on its model, a route on its blueprint Yes refines + extends Extend Adds a mixin or routes to the base. Names must not clash. No Could the base open a slot for it instead? a hook slot or a setting, as shop does for collections Yes Open the slot in the base then compose No refines + overrides Refine Replaces a template, service or hook of the base. One refiner per target, so keep it rare.
Ask the three questions in order and stop at the first yes. A feature may land on more than one box, as 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_signal reacts 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.templates replaces a template with your copy.
  • overrides.services replaces a service with a class merged from yours and the base’s.
  • overrides.hooks swaps 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:validate and by the feature:refine wizard.
  • 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.

  1. Can it work through what shop offers? Its own model, archive and admin screens need nothing from shop, so they compose. So does what it shows on the shop pages, through the slots shop opens.
  2. Does it need the data of shop? Yes. An item must know its collection, so collections extends Item with collection_id.
  3. Could shop open 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


Back to top

splent. Distributed by an LGPL license v3. Contact us: drorganvidez@us.es