Dashboard entries

Your plugin adds pages, cards, actions, palette commands and a Settings tab to the Commera dashboard at /commera. You write each one as a Vue file. The build kit, @commera/plugin-kit, checks it and builds it. Commera draws the frame: the page header, the card title, the dialog and its buttons.

Where your plugin shows up

Each folder under commera/ fills one place in the dashboard. The images show the Qikink plugin. An orange box marks what the plugin adds when the image shows more than that.

Sidebar

Each page adds a row under Plugins, with the logo from your plugin. Folders: commera/pages/<name>/index.vue and commera/plugin-icon.svg.

Plugin page

Commera draws the header. Your page sets the title, breadcrumbs and buttons with usePage(), and fills the rest. Folder: commera/pages/<name>/index.vue.

Order cards

Your card goes in the right column of the order page, below Commera's cards. Folder: commera/order/cards/<name>/index.vue.

Order actions

Your action is a row in the Plugins group of the More actions menu. Folder: commera/order/actions/<name>/index.vue.

Action dialog

An action with a template opens in a dialog. Commera draws the title, Cancel and the primary button, and your index.vue is the body. The Qikink order actions all use method, so this image shows its product action. Folder: commera/product/actions/<name>/index.vue.

Failed delivery notice

You do not write this one. When an event handler from hooks.py fails on every attempt, Commera shows this notice on the order with Retry.

Product cards

Your card goes in the right column of the product page. Folder: commera/product/cards/<name>/index.vue.

Product actions

Your action is a row in the Plugins group at the bottom of the More actions menu. Folder: commera/product/actions/<name>/index.vue.

Customer cards

Your card goes in the right column of the customer page, below the address and note. Qikink has no customer card, so this image shows the Gift Wrap example plugin. Folder: commera/customer/cards/<name>/index.vue.

Customer actions

Your action is a row in the Plugins group of the More actions menu. This image also shows the Gift Wrap example plugin. Folder: commera/customer/actions/<name>/index.vue.

Settings tab

Your tab is listed under Installed plugins in Settings. Folder: commera/settings/index.vue.

Settings > Plugins

Settings > Plugins lists each installed plugin, the number of things it adds and the number of failed deliveries. You do not write this page.

Click Open to see each thing the plugin adds and its recent deliveries. A failed delivery has Retry. Commera builds this from your folders.

Search palette

Your pages show under Go to, your settings tab under Settings, and your commands under Plugins. Folder for a command: commera/commands/<name>/index.vue.

Set up the plugin

Create a Frappe app, go into its folder and run bench commera init. It makes the app whose folder you are in a Commera plugin.

bench new-app my_app
cd apps/my_app
bench commera init
bench --site <site> install-app my_app

The command adds required_apps = ["commera"], commera_api_version = [1] and commera_plugin_title to hooks.py. commera_plugin_title is the name Commera shows for your plugin: the sidebar row of a plugin with several pages, Settings → Plugins and the search palette. A plugin with one page shows that page's label in the sidebar instead. It starts as your app_title. Without it, Commera uses app_title. It writes package.json, commera/vite.config.js, a starter page, my_app/api.py and commera/README.md, and then runs yarn install.

my_app/
├── package.json
├── yarn.lock                        # commit it
├── commera/
│   ├── vite.config.js
│   ├── pages/jobs/index.vue
│   ├── order/cards/status/index.vue
│   ├── order/actions/resend/index.vue
│   ├── settings/index.vue
│   ├── plugin-icon.svg
│   └── shared/                      # your own code
└── my_app/public/commera/           # build output, gitignored

The starter page calls my_app.api.get_summary. Delete both when you write your own page.

Add a placement

Run bench commera add <kind> <name> inside your plugin's folder to add one placement with a starter that builds. A running dev server builds it and reloads the page.

The command never overwrites: it stops when the placement or the method already exists.

Placements

<name> is 1 to 40 lowercase letters, digits and hyphens, and starts with a letter or a digit. It is also the URL slug.

Order cards and actions get a Sales Order, product ones an Item, and customer ones a Customer.

The plugin block

Each placement's index.vue starts with a plain <script> that holds one literal object:

<script>
export const plugin = {
	label: 'Print status',
	condition: 'my_app.conditions.order_has_jobs',
};
</script>

<script setup>
// the card's own code
</script>

A condition that raises counts as false, and Commera writes an Error Log.

Actions

An action has a template, which Commera opens in a dialog, or a method. Never both.

<script>
export const plugin = {
	label: 'Send to printer',
	icon: 'printer',
	method: 'my_app.api.send_order',
	confirm: 'Send this order to the printer?',
};
</script>

import frappe
from frappe import _


@frappe.whitelist()
def send_order(name):
	frappe.has_permission("Sales Order", "write", doc=name, throw=True)
	...
	return _("Order {0} sent").format(name)

Commands

A command is a row in the search palette that runs one method. Staff open the palette with Cmd+K (Ctrl+K on Windows and Linux). The plain <script> is the whole file. The build refuses a command with a <template> or a <script setup>.

<script>
export const plugin = {
	label: "Sync Qikink orders",
	icon: "refresh-cw",
	keywords: ["qikink", "print"],
	method: "commera_qikink.api.sync_open_orders",
};
</script>

• Commera calls method() with no arguments, after the confirm dialog if you set confirm.
• A returned string shows in the success toast. Any other return value shows " done". Call frappe.throw to show an error.
• condition takes no arguments, like a page condition. When it returns False, the command does not show.
• The palette lists your plugin's pages under Go to without a command. Add a command only for work that a page link cannot do.

condition only hides the row. Any user can still call the whitelisted method, so check permissions in the method. The tutorial step Add a palette command builds this command.

Settings tab

A settings tab has a template, or a doctype. Never both.

<script>
export const plugin = { label: 'Printer', icon: 'settings', doctype: 'My App Settings' };
</script>

With doctype, Commera draws each field of the Single as a row that saves itself. A mandatory field shows a *, and a row cannot clear it. Each row saves alone, so other mandatory rows can still be blank. Your validate must allow blanks, and your code must check the values before it uses them. A blank Password row keeps the stored secret.

Composables

Import these from @commera/admin.

navigate(to) and a breadcrumb's to resolve against /commera/plugins/<app>/. 'jobs/JOB-1', '../' and '/orders/SO-1' all work.

@commera/admin also exports EmptyState, ListPagination, ListSkeleton, ResponsiveButton, StatusBadge, money, shortDate and usePolling.

Call your methods

Use useMethodRead for reads and useMethodAction for writes. Point them at a whitelisted method by its full dotted path.

import { usePlugin, useMethodAction, useMethodRead } from '@commera/admin';

const { record, toast } = usePlugin();
const jobs = useMethodRead('my_app.api.get_jobs', {
	params: () => ({ sales_order: record.value.name }),
});
const send = useMethodAction('my_app.api.send_order');

async function sendOrder() {
	const message = await send.submit({ name: record.value.name });
	if (send.error) return;
	toast.success(message);
	jobs.reload();
}

• useMethodRead sends a GET request and loads on mount. Frappe does not commit a GET request, so never write data in a read method.
• useMethodAction sends a POST request when you call submit(params). submit resolves to the method's return value, or to null on an error. Check request.error after it.
• Both show a toast for an error. Inside an action dialog, useMethodAction does not. Throw request.error from onSubmit and the dialog shows it once.

Plugin logo

Put an optional commera/plugin-icon.svg next to pages/. bench commera init writes a placeholder there: the Commera logo in violet, orange, blue or green. The colour is picked at random when the file is written, and running bench commera init again never changes it. Replace it with your own logo. It is the icon of everything your plugin adds: the sidebar, Settings, the search palette and More actions rows. An entry with its own icon shows that one instead, and a plugin with only one page shows that page's icon in the sidebar when it has one. Without plugin-icon.svg, the sidebar row uses the first page's icon.

Commera shows the logo as it is, in its own colours, in light and dark mode. Pick colours that read on both. A currentColor in the file draws black.

Styling

Use any frappe-ui or Tailwind class, including arbitrary values such as min-w-[60rem]. Your plugin ships no CSS of its own: Commera compiles your classes into the dashboard's one stylesheet, so they always sort the way Tailwind expects next to the dashboard's own classes.

• While you work, the dashboard's yarn dev adds a new class as soon as you save.
• In production, a new class is styled after bench build --app commera or bench build. Your plugin's own bench build --app my_app still builds, and warns which classes are waiting for the Commera build.

Build checks

The build reports all folder and plugin problems together.

The class, export and icon checks read the files that the Commera dashboard build writes. Build Commera before you build your plugin.

Develop

1. Build Commera one time.
2. Turn on developer mode on your site.
3. Run yarn dev in apps/commera/dashboard.
4. Open /commera on port 8080 with your site's host name, for example http://my.site:8080/commera, and log in there.

The dev server loads your plugin's .vue files from source. When you save a file, the page changes in place, without a reload. Your plugin has no yarn dev of its own.

Each save also runs yarn build in your plugin's folder, so the checks above run while you work. A failed check shows in the browser's error overlay. A new placement folder, or a changed plugin field, reloads the page. The build reads the folders on disk: a placement folder that you rename or move stays a live entry until you delete it.

For production, run bench build --app my_app. bench build --app commera also builds every installed plugin, after the dashboard. If one plugin fails, the others still build, and the command ends with an error that names it.

Next steps

• SDK
• Compatibility
• Testing