Share Buttons — Reference
The Share Buttons surface owns the social-share affordances that appear on public-facing content. It controls which networks are offered, where the buttons render on a page, and how share events are counted for downstream analytics.
This page is a reference for platform engineers and integrators who need to understand the surface before extending it, theming it, or wiring it into a custom component. Customer-facing how-tos live in the customer docs set; this page describes the shape of the surface, not the steps to drive it.
Overview
Share Buttons live under the Share Buttons module in SG-Admin. The module renders two primary views — the configuration page (per-network toggles, placement, label rules) and the analytics surface (per-network click totals, per-page breakdown) — and exposes a small set of write operations for enable, disable, reorder, label edit, and event reset.
The module is paired by convention with the public-site renderer: SG-Admin owns the configuration; the front-end runtime reads that configuration and emits the buttons into the page template at the configured insertion points.
A second surface — per-content overrides — lives adjacent to the main module and allows the buttons to be hidden or customized on a single post, page, or product. Per-content overrides do not change the network list; they only toggle visibility for the specific record.
Where it lives in SG-Admin:
- Sidebar: SG-Admin → Share Buttons
- URL prefix:
/sg-admin/share-buttons/ - View templates:
application/views/Admin/ShareButtons/
┌──────────────────────────────────────────────────────────────────────┐│ SG-Admin → Share Buttons [Save changes] │├──────────────────────────────────────────────────────────────────────┤│ Network Enabled Label Order Click tracking ││ ────────────── ──────── ──────────────── ────── ───────────────││ Facebook ✔ on Share 1 on ││ X (Twitter) ✔ on Post 2 on ││ LinkedIn ✔ on Share to network 3 on ││ Pinterest — off Pin 4 — ││ Email ✔ on Email a friend 5 on ││ Copy link ✔ on Copy link 6 on ││ ││ Placement: ◉ Above content ○ Below content ○ Floating sidebar ││ Show on: ☑ Posts ☑ Pages ☑ Products ☐ Custom objects │└──────────────────────────────────────────────────────────────────────┘Actions
The Share Buttons surface exposes the following operations. Each is described by what it does to the data, not by its internal method name.
Read configuration
Returns the active network list, placement, content-type scope, and the click-tracking flag for the current site. The response is a flat object shape suitable for direct binding to the configuration form.
Toggle a network
Enables or disables a single network. Disabled networks remain in the stored list (with enabled: false) so that their position and label survive across enable cycles. The public-site renderer skips disabled entries at render time.
Reorder networks
Replaces the stored ordering with a new sequence. The order field controls the left-to-right rendering of the buttons in the row. Reorder is a single write of the full sequence — partial updates of a single position are not supported.
Edit a network label
Replaces the visible text for a single network. Empty strings fall back to the network's default label (Share, Post, Pin, etc.). Labels accept plain text only — markup is stripped on save.
Set placement
Stores one of three placement modes — above content, below content, or floating sidebar. The renderer reads this value once per page request and emits the buttons at the matching insertion point. Floating mode adds the sticky positioning CSS that keeps the button row visible while the visitor scrolls.
Set content-type scope
Stores the set of content types on which the buttons render. Toggling a content type off hides the buttons across every record of that type — per-record overrides are still respected for finer-grained control.
Per-content override
Hides the buttons for a single post, page, or product. The override is stored on the content record (not in the Share Buttons module) so that deleting the record clears the override automatically.
Read click totals
Returns per-network click counts over a date range, grouped by network, page, or content type. Counts come from the click-tracking pipeline and are eventually consistent — typical delay is under one minute.
Reset click counts
Zeros the click counters for one network or all networks. The action is irreversible and is logged in Activity Log with the calling operator and the network identifier.
Data model
A Share Buttons configuration carries the following fields. Field names below are the conceptual shape — the on-disk column names match closely but are not contractually stable across releases.
| Field | Type | Notes |
|---|---|---|
network | string | Network slug. One of facebook, x, linkedin, pinterest, email, copy_link, plus any custom entries registered through the extension surface. |
enabled | boolean | When false, the network is skipped at render time. |
label | string | Visible text on the button. Empty string falls back to the network default. |
order | integer | Sort key for the row. Lower numbers render first. |
click_tracking | boolean | Per-network override of the site-wide click-tracking flag. |
placement | enum | Site-wide. One of above, below, floating. |
content_types | array of strings | Site-wide. Content type slugs on which the buttons render. |
updated_at | timestamp | Touched on any edit. |
| Field | Type | Notes |
|---|---|---|
content_id | integer | Foreign key into the content table for the type. |
content_type | string | The content type slug. |
hidden | boolean | When true, suppresses the buttons for this single record. |
| Field | Type | Notes |
|---|---|---|
network | string | Which network was clicked. |
content_id | integer | Which record carried the button. |
content_type | string | The record's content type. |
clicked_at | timestamp | Event time. |
referrer | string | Optional. Page URL that hosted the button. |
SHARE BUTTONS CONFIG├── networks[]│ ├── network slug│ ├── enabled boolean│ ├── label display│ ├── order integer│ └── click_tracking boolean├── placement above | below | floating├── content_types[] post | page | product | <custom>└── updated_at timestamp↓PER-CONTENT OVERRIDE(stored on the content record, not in this module)CLICK EVENT (read-only stream)├── network · content_id · content_type├── clicked_at└── referrerPermissions
Access to the Share Buttons surface is gated at two layers.
Layer 1 — admin gate. Every action under SG-Admin passes through the platform's standard admin access check at request entry. An unauthenticated request never reaches the Share Buttons surface.
Layer 2 — per-action capability. Within SG-Admin, each Share Buttons action checks a capability associated with the calling operator's role. The default role configuration ships with three roles — Administrator, Editor, Viewer — and the capability map is:
| Capability | Administrator | Editor | Viewer |
|---|---|---|---|
| Read configuration | ✔ | ✔ | ✔ |
| Toggle a network | ✔ | ✔ | — |
| Reorder networks | ✔ | ✔ | — |
| Edit a network label | ✔ | ✔ | — |
| Set placement | ✔ | — | — |
| Set content-type scope | ✔ | — | — |
| Per-content override | ✔ | ✔ | — |
| Read click totals | ✔ | ✔ | ✔ |
| Reset click counts | ✔ | — | — |
Audit. Every write — toggle, reorder, label edit, placement change, scope change, per-content override, count reset — emits an Activity Log entry. The log records the acting operator, the field that changed, and the prior + new values for diffable fields.
PUBLIC PAGE REQUEST│▼┌───────────────────────────┐│ Resolve content record │ loads content_id + content_type└─────────────┬─────────────┘▼┌───────────────────────────┐│ Check per-content override│ hidden=true → skip buttons└─────────────┬─────────────┘▼┌───────────────────────────┐│ Read site-wide config │ content_type in scope? placement?└─────────────┬─────────────┘▼┌───────────────────────────┐│ Filter enabled networks │ sort by order, apply labels└─────────────┬─────────────┘▼buttons render in template│▼click event emitted (if click_tracking on)Related references
- Analytics — Reference. Owns the rollup view of click totals across networks. The Share Buttons module exposes per-network counts; Analytics joins those with traffic and conversion data.
- Custom Objects — Reference. Custom content types can opt in to the Share Buttons content-type scope. Registering a custom object exposes it to the scope checklist.
- Posts — Reference. Per-post share-button overrides are stored on the post record.
- Pages — Reference. Per-page share-button overrides are stored on the page record.
- Products — Reference. Per-product share-button overrides are stored on the product record.
- Activity Log — Reference. Records every Share Buttons configuration write.
/docs/share-buttons.