DevelopersPre-alpha

Creating an addon

How to use sumeru-bp, place an addon on addons_path, generate imports, install and update it.

Overview

Addons live under sumeru_custom_addons/addons/. Scaffold with make new MODULE=… (minimal layout), or explore the pre-shipped engagement_cookbook kitchen-sink demo for every widget and view type. Declare models with sdk.Model tags, list XML in the manifest, run make generate, then make install.

Scaffold vs demo. make new MODULE=my_app creates one model and starter views. engagement_cookbook is already in the repo — use make install MODULES=engagement_cookbook to explore it; do not run make new MODULE=engagement_cookbook over the reference copy.

Scaffold with sumeru-bp

Use the workspace tab for client work. Name flag aliases: -name, -bp, -boilerplate, -blueprint.

workspace · preferred

$cd sumeru_custom_addons$make setup$make new MODULE=my_app$make install MODULES=my_app

$cd sumeru$make setup$make bp NAME=my_app$make generate

Workspace make new runs sumeru-bp then make generate (writes zmodels.go / zrefs.go; custom init.go is regenerated to models-only — put hooks in models/). Use Core make only when scaffolding inside the sumeru repo.

Reference module (kitchen-sink)

Browse the pre-shipped engagement_cookbook demo — six models, all view types, and the full widget set. Click a file in the tree or sidebar. Same layout as sumeru_custom_addons/addons/engagement_cookbook. For a guided tour see Engagements cookbook.

engagement_cookbook reference demo

addons/engagement_cookbook/ tree

addons/engagement_cookbook/
├── 
├── 
├── models/
│   ├── 
│   └── zmodels.go
├── views/
│   ├── 
│   ├── 
│   ├── 
│   ├── 
│   └── 
└── security/
    ├── 
    └──

1{2  "name": "engagement_cookbook",3  "display_name": "Engagements Cookbook",4  "version": "2.0.0",5  "author": "Project Meru",6  "description": "Professional services engagement tutorial: multi-model app, field widgets, view types, module depends, model/view inherit, and event bridges.",7  "depends": ["base", "contacts", "hr", "mail"],8  "application": true,9  "data": [10    "security/security.xml",11    "security/sys.access.csv",12    "data/demo.xml",13    "views/form_view.xml",14    "views/list_view.xml",15    "views/kanban_view.xml",16    "views/search_view.xml",17    "views/graph_view.xml",18    "views/pivot_view.xml",19    "views/calendar_view.xml",20    "views/gantt_view.xml",21    "views/cohort_view.xml",22    "views/event_views.xml",23    "views/place_views.xml",24    "views/tag_views.xml",25    "views/category_views.xml",26    "views/line_views.xml",27    "views/partner_inherit_views.xml",28    "views/actions.xml",29    "views/menus.xml"30  ]31}

1// Code generated by sumeru-import-gen; DO NOT EDIT.2 3package engagement_cookbook4 5import (6	_ "sumeru_custom_addons/addons/engagement_cookbook/models"7)

1package models2 3import (4	"sumeru/core/sdk"5)6 7// EngagementProject is a client engagement / professional services project.8type EngagementProject struct {9	sdk.Model `sumeru:"model=engagement.project"`10 11	Name         sdk.String `sumeru:"required,unique,index,string=Engagement Name"`12	Reference    sdk.String `sumeru:"index,string=Reference"`13	ExternalCode sdk.String `sumeru:"column=external_ref,index,string=External Code"`14	SerialNumber sdk.String `sumeru:"unique,index,string=Serial Number"`15	ShortCode    sdk.String `sumeru:"size=32,string=Short Code"`16	Description  sdk.Text   `sumeru:"string=Description"`17	Notes        sdk.HTML   `sumeru:"string=Internal Notes"`18	Website      sdk.URL    `sumeru:"string=Website"`19 20	Active   sdk.Boolean `sumeru:"string=Active,default=true"`21	Verified sdk.Boolean `sumeru:"string=Verified,default=false"`22	Archived sdk.Boolean `sumeru:"string=Archived,default=false,index"`23 24	Sequence    sdk.Integer `sumeru:"string=Sequence,default=10"`25	Quantity    sdk.Integer `sumeru:"string=Quantity,default=1"`26	ProgressPct sdk.Integer `sumeru:"string=Progress %,default=0,min=0,max=100"`27	Rating      sdk.Integer `sumeru:"string=Rating,min=0,max=5"`28	Amount      sdk.Float   `sumeru:"string=Budget Amount,default=0"`29	Price       sdk.Numeric `sumeru:"string=Price,precision=18,scale=2,default=0"`30	TaxRate     sdk.Numeric `sumeru:"string=Tax Rate,precision=20,scale=8,default=0"`31	Balance     sdk.Numeric `sumeru:"string=Balance,precision=40,scale=18,default=0"`32 33	Subtotal   sdk.Money                  `sumeru:"string=Subtotal,currency=CurrencyID"`34	TaxAmount  sdk.Money                  `sumeru:"string=Tax,currency=CurrencyID"`35	CurrencyID sdk.Many2One[CoreCurrency] `sumeru:"string=Currency"`36// …

1<?xml version="1.0" encoding="utf-8"?>2<sumeru>3    <data>4        <action id="action_engagement_project" type="window" model="engagement.project" name="Engagements"5            view_mode="kanban,list,form,calendar,gantt">6            <help>7                <p class="sum-view-nocontent-smiling-face">8                    Create a client engagement to explore workflow, relations, and every workspace view type.9                </p>10            </help>11        </action>12        <action id="action_engagement_analysis" type="window" model="engagement.project" name="Engagement analysis"13            view_mode="graph,pivot,cohort,list" />14        <action id="action_engagement_deliverable" type="window" model="engagement.deliverable" name="Deliverables"15            view_mode="list,form" />16        <action id="action_engagement_milestone" type="window" model="engagement.milestone" name="Milestones"17            view_mode="calendar,gantt,list,form" />18        <action id="action_engagement_site" type="window" model="engagement.site" name="Client sites"19            view_mode="map,list,form" />20        <action id="action_engagement_tag" type="window" model="engagement.tag" name="Tags"21            view_mode="list,form" />22        <action id="action_engagement_service_line" type="window" model="engagement.service_line" name="Service lines"23            view_mode="list,form" />24        <action id="action_engagement_contacts" type="window" model="core.partner" name="Contacts"25            view_mode="list,form,kanban">26            <help>27                <p>Contacts form shows fields extended via <code>inherit=core.partner</code> from this module.</p>28            </help>29        </action>30        <action id="action_engagement_tutorial" type="window" model="engagement.project" name="Tutorial"31            view_mode="list,form">32            <help>33                <p><strong>Engagements Cookbook</strong> depends on <code>base</code>, <code>contacts</code>, <code>hr</code>, and <code>mail</code>.</p>34                <p>See <code>README.md</code> in this addon for model inherit, view xpath, event hooks, and cross-module relations.</p>35            </help>36// …

1<?xml version="1.0" encoding="utf-8"?>2<sumeru>3    <data>4        <view id="view_engagement_project_form" model="engagement.project" type="form">5            <header>6                <button name="action_confirm" string="Activate" type="object" class="sum_highlight" />7                <button name="action_done" string="Done" type="object" />8                <button name="action_reset_draft" string="Reset to Draft" type="object" />9                <field name="state" widget="statusbar" options="clickable:1" />10            </header>11            <sheet>12                <div class="sum_title">13                    <field name="avatar" widget="image" />14                    <h1>15                        <field name="name" widget="char" placeholder="Title..." />16                    </h1>17                </div>18                <group>19                    <group string="Identity">20                        <field name="reference" widget="default" />21                        <field name="external_code" />22                        <field name="serial_number" />23                        <field name="short_code" />24                        <field name="public_id" readonly="1" />25                        <field name="priority" widget="priority" options="mode:stars,stars:5" />26                        <field name="kind" widget="radio" />27                        <field name="color_code" widget="color" />28                    </group>29                    <group string="Flags">30                        <field name="active" widget="radio" />31                        <field name="verified" widget="boolean" />32                        <field name="archived" widget="boolean_toggle" />33                        <field name="sequence" />34                    </group>35                </group>36// …

1<?xml version="1.0" encoding="utf-8"?>2<sumeru>3    <data>4        <view id="view_engagement_project_list" model="engagement.project" type="list">5            <field name="sequence" widget="handle" />6            <field name="name" />7            <field name="reference" />8            <field name="state" />9            <field name="kind" />10            <field name="priority" widget="priority" options="mode:stars,stars:5" />11            <field name="company_id" />12            <field name="amount" />13            <field name="subtotal" widget="monetary" />14            <field name="date_start" />15            <field name="date_stop" />16            <field name="progress_pct" widget="progressbar" />17            <field name="active" widget="boolean_toggle" />18        </view>19    </data>20</sumeru>

1<?xml version="1.0" encoding="utf-8"?>2<sumeru>3    <data>4        <view id="view_engagement_project_kanban" model="engagement.project" type="kanban"5            default_group_by="state" records_draggable="1">6            <field name="state" />7            <field name="avatar" widget="image" />8            <field name="name" />9            <field name="reference" />10            <field name="priority" widget="priority" options="mode:stars,stars:5" />11            <field name="subtotal" widget="monetary" />12            <field name="active" widget="boolean_toggle" />13        </view>14    </data>15</sumeru>

1<?xml version="1.0" encoding="utf-8"?>2<sumeru>3    <data>4        <menuitem id="menu_engagement_root" name="Engagements Cookbook" sequence="20" web_icon="briefcase" />5 6        <menuitem id="menu_engagement_operations" name="Operations" parent="menu_engagement_root" sequence="10" />7        <menuitem id="menu_engagement_planning" name="Planning" parent="menu_engagement_root" sequence="20" />8        <menuitem id="menu_engagement_analytics" name="Analytics" parent="menu_engagement_root" sequence="30" />9        <menuitem id="menu_engagement_clients" name="Clients" parent="menu_engagement_root" sequence="40" />10        <menuitem id="menu_engagement_configuration" name="Configuration" parent="menu_engagement_root"11            sequence="90" groups="engagement_cookbook.group_engagement_cookbook_manager" />12 13        <menuitem id="menu_engagement_projects" name="Engagements" parent="menu_engagement_operations"14            action="action_engagement_project" sequence="10" />15        <menuitem id="menu_engagement_deliverables" name="Deliverables" parent="menu_engagement_operations"16            action="action_engagement_deliverable" sequence="20" />17 18        <menuitem id="menu_engagement_milestones" name="Milestones" parent="menu_engagement_planning"19            action="action_engagement_milestone" sequence="10" />20        <menuitem id="menu_engagement_sites" name="Client sites" parent="menu_engagement_planning"21            action="action_engagement_site" sequence="20" />22 23        <menuitem id="menu_engagement_analysis" name="Engagement analysis" parent="menu_engagement_analytics"24            action="action_engagement_analysis" sequence="10" />25 26        <menuitem id="menu_engagement_contacts" name="Contacts (extended)" parent="menu_engagement_clients"27            action="action_engagement_contacts" sequence="10" />28 29        <menuitem id="menu_engagement_tags" name="Tags" parent="menu_engagement_configuration"30            action="action_engagement_tag" sequence="10" groups="engagement_cookbook.group_engagement_cookbook_manager" />31        <menuitem id="menu_engagement_service_lines" name="Service lines" parent="menu_engagement_configuration"32            action="action_engagement_service_line" sequence="20" groups="engagement_cookbook.group_engagement_cookbook_manager" />33        <menuitem id="menu_engagement_tutorial" name="About / tutorial" parent="menu_engagement_configuration"34            action="action_engagement_tutorial" sequence="99" groups="engagement_cookbook.group_engagement_cookbook_manager" />35    </data>36// …

1<?xml version="1.0" encoding="utf-8"?>2<sumeru>3    <data>4        <record id="module_category_engagement_cookbook" model="sys.module.category">5            <field name="name">Engagements Cookbook</field>6            <field name="sequence">100</field>7        </record>8 9        <record id="group_engagement_cookbook_user" model="core.group">10            <field name="name">User</field>11            <field name="category_id" ref="module_category_engagement_cookbook"/>12            <field name="implied_ids" eval="[(4, ref('base.group_user'))]"/>13        </record>14 15        <record id="group_engagement_cookbook_manager" model="core.group">16            <field name="name">Manager</field>17            <field name="category_id" ref="module_category_engagement_cookbook"/>18            <field name="implied_ids" eval="[(4, ref('group_engagement_cookbook_user'))]"/>19        </record>20    </data>21</sumeru>

1id,name,model,group_id,perm_read,perm_write,perm_create,perm_unlink2access_engagement_project_user,access_engagement_project_user,engagement.project,group_engagement_cookbook_user,1,1,1,03access_engagement_project_manager,access_engagement_project_manager,engagement.project,group_engagement_cookbook_manager,1,1,1,14access_engagement_deliverable_user,access_engagement_deliverable_user,engagement.deliverable,group_engagement_cookbook_user,1,1,1,05access_engagement_deliverable_manager,access_engagement_deliverable_manager,engagement.deliverable,group_engagement_cookbook_manager,1,1,1,16access_engagement_tag_user,access_engagement_tag_user,engagement.tag,group_engagement_cookbook_user,1,1,0,07access_engagement_tag_manager,access_engagement_tag_manager,engagement.tag,group_engagement_cookbook_manager,1,1,1,18access_engagement_service_line_user,access_engagement_service_line_user,engagement.service_line,group_engagement_cookbook_user,1,1,0,09access_engagement_service_line_manager,access_engagement_service_line_manager,engagement.service_line,group_engagement_cookbook_manager,1,1,1,110access_engagement_milestone_user,access_engagement_milestone_user,engagement.milestone,group_engagement_cookbook_user,1,1,1,011access_engagement_milestone_manager,access_engagement_milestone_manager,engagement.milestone,group_engagement_cookbook_manager,1,1,1,112access_engagement_site_user,access_engagement_site_user,engagement.site,group_engagement_cookbook_user,1,1,1,013access_engagement_site_manager,access_engagement_site_manager,engagement.site,group_engagement_cookbook_manager,1,1,1,1

Compile and run

Ensure ./addons is on addons_path in sumeru.conf.
make generate refreshes addonimports/zimports.go.
Install with -i, then serve on http://localhost:8080.

Install & run

from sumeru_custom_addons

$make generate$go run . -- -c sumeru.conf -i engagement_cookbook --stop-after-init$make run

What not to do

Do not put client modules inside sumeru/ or sumeru_addons/. Keep those pull-only.
Do not skip make generate after adding or removing an addon folder.
Do not call RegisterModel / implement ModelName() in model files — zmodels.go is generated.
Do not hand-edit zmodels.go or zrefs.go.
Do not ship scaffold groups/CSV without reviewing who can write and unlink.

Next step

Map the three repos in Project structure. Workspace Makefile detail: Custom addons workspace.