How to

⌘K
  2. Home
  4. Docs
  6. How to
  8. Salesforce WordPress Plugin : Complete Shortcode and Attribute Reference

Salesforce WordPress Plugin : Complete Shortcode and Attribute Reference

Sawfish Connect for Salesforce lets you query your Salesforce database and display live records anywhere in WordPress using shortcodes — as cards, responsive tables, calendars, charts, JSON, or CSV downloads. This reference documents every shortcode and every attribute the plugin accepts, with working examples for each.

This guide covers plugin version 1.13.26. If you are new to the plugin, start with the [showsforce] shortcode — it handles the majority of use cases. You can also generate a ready-made shortcode from Sawfish Connect → Add New Layout in your WordPress admin menu, then fine-tune it with the attributes below.

Table of contents

  1. Quick reference: all shortcodes at a glance
  2. Displaying Salesforce records: [showsforce]
  3. Custom layouts: [sectionsforce]
  4. Salesforce reports and charts: [reportsforce]
  5. Writing back to Salesforce: forms and record creation
  6. Salesforce file downloads
  7. Field syntax: cross-object, translated picklists, and addresses
  8. Frequently asked questions

Quick reference: all shortcodes at a glance

Shortcode What it does Typical use
[showsforce] Queries Salesforce and renders records as cards, tables, calendars, JSON, or CSV. Product catalogues, event listings, member directories, account portals.
[sectionsforce] Repeats your own HTML block once per record, substituting field placeholders. Fully custom layouts that cards and tables cannot express.
[reportsforce] Pulls a Salesforce report and renders its totals as metrics or charts. Dashboards, KPI tiles, public-facing statistics.
[submitsforce] Receives a form submission and writes one or more records to Salesforce. Contact forms, registrations, lead capture.
[wp2sforce] Creates or updates a single record when the page renders. Scripted or automated record writes.

Displaying Salesforce records: [showsforce]

The [showsforce] shortcode builds a SOQL query from your attributes, retrieves matching records, and renders them in the layout you choose. A minimal working example:

[showsforce fields="Name,StageName,Amount,CloseDate" o="Opportunity" by="CloseDate" n="10"]

Query attributes (required and optional)

Four attributes are required. If any is missing, the shortcode returns a message asking you to generate a new code from the Add Cards & Tables page rather than rendering an empty block.

Attribute Required Default Description
o Yes — The Salesforce object API name, for example Opportunity, Contact, or a custom object such as Course__c.
fields Yes — Comma-separated list of field API names. Spaces are stripped automatically. See field syntax for cross-object and translated-picklist support. The record Id is added to the query automatically so rows can link to records.
by Yes — The field to sort by (the SOQL ORDER BY clause).
n Yes — Maximum number of records to retrieve (the SOQL LIMIT). Values above 1999 trigger automatic pagination through the Salesforce API, up to a ceiling of 10,000 records.
order No ASC Sort direction. Use DESC for newest or highest first.
filter No — A SOQL WHERE clause without the WHERE keyword, for example filter="StageName = 'Closed Won'". Supports dynamic values.
offset No — SOQL OFFSET, for skipping the first N records. Accepts a {!parameter} token, which is cast to an integer.
groupby No — Adding this attribute groups results by every field in your fields list. Sorting is disabled while grouping, and the automatic Id field is omitted.
redirect No — A URL to send the visitor to when the query returns zero records. Useful for gated pages that should fall back to a “no access” or “not found” page.

Dynamic filters: WordPress users, URL parameters, and ACF

The filter attribute accepts tokens that are replaced with live values before the query runs. This is how you build personalised pages — a customer portal that shows only the logged-in user’s records, or a detail page driven by a URL parameter.

Token Replaced with Example
$WPId The current WordPress user ID. Logged-out visitors see “Please login to view this info” instead of the records. filter="WP_User_Id__c = '$WPId'"
$WPEmail The current user’s email address. filter="Email = '$WPEmail'"
$WPUserName The current user’s WordPress login name. filter="Username__c = '$WPUserName'"
$WPPostId The ID of the post or page the shortcode sits on. filter="WP_Post__c = '$WPPostId'"
{!parameter} A URL query-string parameter. Values are quoted as text by default. Prefix the parameter name with d_ to pass a date unquoted, or n_ to pass an integer unquoted. filter="AccountId = '{!acct}'" reads ?acct=001...
$ACF_fieldname An Advanced Custom Fields value from the current post. Requires ACF to be active. filter="Region__c = '$ACF_region'"

Security note: values taken from the URL are inserted into the SOQL query. Treat any page using {!parameter} as publicly reachable with arbitrary parameter values, and avoid relying on a URL parameter alone to protect private records. Prefer $WPId or $WPEmail, which cannot be altered by the visitor.

Layout and display attributes

Attribute Values Default Description
t 0, 1, 2, 3, 5 0 The layout: 0 or omitted renders cards, 1 a table, 2 a calendar, 3 raw JSON, and 5 a CSV file download. Any other value falls back to cards.
search on, off on Shows a live search box above cards and tables. Automatically disabled for calendar, JSON, and CSV output.
page Number — Records shown per page. Adding this attribute enables client-side pagination beneath the results.
style cards, tables, calendar — Only applies when t="3" (JSON). Loads the stylesheet and scripts for the named layout so you can render the JSON yourself with the plugin’s own styling.

CSV downloads

Setting t="5" turns the page into a CSV export: the file streams to the browser using the page title as its filename, with your Salesforce field labels as column headings. Place this shortcode on a dedicated page, since the download replaces the page output entirely.

[showsforce fields="Name,Email,Phone" o="Contact" by="Name" n="500" t="5"]

Table layout attributes

Table view (t="1") is responsive by default: on narrow screens each row collapses into a stacked block with the column label beside each value. For wide tables where that stacking is hard to read, you can switch to a frozen first column with horizontal scrolling instead.

Attribute Values Default Description
stack on, off on on keeps the default responsive behaviour, where rows stack vertically on small screens. off pins the first column in place and lets the remaining columns scroll horizontally, which keeps each record on a single readable line.

The attribute is optional and only affects table view. Existing shortcodes without it are unchanged.

[showsforce fields="Name,StageName,Amount,CloseDate,Owner.Name" o="Opportunity" by="CloseDate" n="50" t="1" stack="off"]

Column headings are clickable in both modes, so visitors can re-sort the table without reloading the page.

Calendar layout attributes

Calendar view (t="2") plots records on a full monthly, weekly, daily, or list calendar. The first field in your fields list becomes the event title and the second field becomes the event start date, so field order matters.

The remaining calendar attributes identify fields by their position in the fields list, counting from 1. A 0 means “not set”.

Attribute Format Description
c Two digits The end date/time field position followed by the category field position. c="34" means field 3 is the end date and field 4 is the category. Use 0 to skip one, for example c="03" for a category with no end date.
f One digit per field Fields to expose as dropdown filters above the calendar. f="56" adds filters for fields 5 and 6.
p One digit per field Fields to show in the hover tooltip on each event. Dates and times in the tooltip are formatted automatically.
k One digit The field holding a URL. Clicking an event opens that link in a new tab. 
[showsforce fields="Name,StartDate__c,EndDate__c,Type__c,Region__c,Link__c" o="Event__c" by="StartDate__c" n="200" t="2" c="34" f="5" p="45" k="6"]

Category values are colour-coded automatically from a nine-colour palette. To override the palette or any calendar setting, define myCalendarTheme or myCalendarOptions_1 in your own JavaScript before the calendar renders.

Caching, refresh, and debugging attributes

Results are cached in a WordPress transient so repeat visits do not consume Salesforce API calls. Logged-in users always receive fresh data.

Attribute Values Default Description
refresh 1–86400 60 How long, in seconds, to cache the results. The maximum of 86400 is one full day.
nocache Present or absent Absent Adding this attribute bypasses the cache entirely and queries Salesforce on every page load. Use sparingly on high-traffic pages.
debug Present or absent Absent Prints the generated SOQL query, the parsed attributes, the raw Salesforce response, and the field labels above the output. Remove before publishing, as the output is visible to all visitors.

Custom layouts: [sectionsforce]

When cards, tables, and calendars are not the shape you need, [sectionsforce] gives you complete control. It is an enclosing shortcode: whatever markup you put between the opening and closing tags is repeated once per record, with {!FieldName} placeholders replaced by that record’s values.

[sectionsforce o="Opportunity" by="CloseDate" order="DESC" n="5" filter="StageName = 'Closed Won'"]
<h3>{!Name}</h3>
<p>Closed {!CloseDate} for {!Amount}</p>
[/sectionsforce]

There is no fields attribute — the field list is built automatically from the placeholders you use in the content. The following attributes are supported:

Attribute Required Default Description
o Yes — The Salesforce object API name.
n No 1 Number of records to output. The default of 1 makes this shortcode ideal for single-record detail blocks.
by No Id The sort field.
order No ASC Sort direction.
filter No — A SOQL WHERE clause. Supports every dynamic token available to [showsforce].
offset No — SOQL OFFSET.
style No — cards, tables, or calendar. Loads that layout’s CSS and JavaScript so you can reuse the plugin’s styling inside your custom markup.
refresh, nocache, debug No As above Identical behaviour to [showsforce].

Salesforce reports and charts: [reportsforce]

Rather than querying objects directly, [reportsforce] reads an existing Salesforce report and renders its summary values as metrics or interactive charts. Because the report already contains the grouping and filtering logic, this is the fastest route to a dashboard.

Finding the right shortcode

Start by placing the shortcode with only a report ID. The plugin enters help mode and lists every metric and chart available in that report, each with a copy-ready shortcode and a live preview:

[reportsforce id="00O5g000005XyZ1EAK"]

The id attribute is required and must be a valid 15 or 18 character Salesforce report ID. Both id and Id are accepted.

Report metrics and totals

Attribute Values Description
summary Number The position of a summary column in the report, counting from 1. On its own it outputs that column’s grand total as plain text, ready to drop into a sentence or a heading.
totals show, json, html show renders every total as a styled metric card. json outputs the totals as raw JSON. html outputs a script that fills your own markup by CSS class, so you can design the tiles yourself.
totalsborder Present or absent Adds a card border and shadow around each total when using totals="show".
recordcount Present or absent Includes the report’s “Record Count” total, which is hidden by default.
refresh 1–86400 Cache lifetime in seconds, defaulting to 60. Administrators always see fresh data.

Chart types

Add a chart attribute to a summary to render it visually instead of as a number.

Value Renders Default size
bar Vertical bar chart. This is the fallback for any unrecognised value. 800 × 300 px
line Smoothed line chart. 800 × 300 px
area Line chart with the area beneath it filled. 800 × 300 px
pie Pie chart. 400 × 350 px
donut or doughnut Doughnut chart with a hollow centre. 400 × 350 px
gauge or guage Gauge dial for progress against a goal. 300 × 250 px
json The underlying chart data as JSON, with no visual output. —

For grouped reports, adding group with a bar, line, or area chart produces a stacked chart broken down by that grouping:

[reportsforce id="00O5g000005XyZ1EAK" summary="1" group="1" chart="bar"]

Chart styling attributes

Attribute Default Description
color #36A2EB The primary series colour, as a hex value.
colortheme — A comma-separated list of hex colours used in sequence, for example colortheme="#004E64,#00A5CF,#9FFFCB".
title The report column name Heading shown above the chart.
subtitle The chart legend Secondary line beneath the title.
prefix — Text placed before each value, such as a currency symbol.
suffix — Text placed after each value, such as % or k.
width, height Varies by chart type Any CSS length, for example width="100%" or height="420px".
border on Set to off, no, or false to remove the card shadow around the chart.
rotate Absent Swaps the axes, turning a vertical bar chart into a horizontal one. Useful when category labels are long.
options Absent Adds an on-chart toolbar with a “save as image” button, plus a line/bar toggle on bar, line, and area charts.
rounded Absent Doughnut charts only. Rounds the ends of each segment.

Gauge chart attributes

Attribute Default Description
goal 1000 The value at the top of the dial.
start 0 The value at the bottom of the dial.
yellow 25% of the goal The value at which the dial turns yellow.
green — The value at which the dial turns green. 
[reportsforce id="00O5g000005XyZ1EAK" summary="1" chart="gauge" goal="50000" yellow="20000" green="40000" prefix="$"]

Writing back to Salesforce: forms and record creation

[submitsforce] and form field naming

Place [submitsforce] on the page your form posts to — typically a thank-you or confirmation page. When a submission arrives, the shortcode reads the posted fields and writes the records to Salesforce. Submissions are rejected unless they originate from your own site.

[submitsforce]

The shortcode takes no attributes. Instead, the names of your form fields tell the plugin what to do. Prefix each field name as follows:

Field name Purpose
sf-o The Salesforce object to write to, for example Lead.
sf-form The action: create a new record, update an existing one, upsert to update a match or create when none exists, or related to find a match and then create related records against it.
sf-Id The record ID to update. Required when sf-form is update.
sf-matchby The field used to look for an existing record, for example Email. Required for upsert and related.
sf-FieldName Any field on the record, for example sf-LastName or sf-Company. Fields that submit multiple values, such as checkbox groups, are joined with semicolons to suit Salesforce multi-select picklists.
sf2-o A second object to create alongside the first, for example an Opportunity created against a Contact.
sf2-lookup The lookup field on the second object that should hold the first record’s ID.
sf2-FieldName Any field on that second record.

A minimal lead capture form:

<input type="hidden" name="sf-o" value="Lead">
<input type="hidden" name="sf-form" value="create">
<input type="text"   name="sf-LastName">
<input type="email"  name="sf-Email">
<input type="text"   name="sf-Company">

Elementor Pro and HTML Forms

The same naming convention works with form plugins. Elementor Pro users get a dedicated “Salesforce” action in the form’s Actions After Submit panel — name your form fields with the sf- prefixes and the action handles the rest, with no [submitsforce] page required.

HTML Forms is supported through the same hook and additionally accepts an sfm- prefix for creating multiple related records from one submission, using sfm-o, sfm-lookup, and sfm-field.

If submissions are not arriving, check the error log linked from Sawfish Connect → Settings; Salesforce validation failures are recorded there with the exact message returned by the API.

[wp2sforce]

This shortcode writes a single record when the page renders, without any form. It produces no visible output.

Attribute Required Description
o Yes The Salesforce object API name.
type Yes create or update.
content Yes The field values as a JSON object.
recordid For updates The ID of the record to update.

Because the record is written every time the page loads, reserve this shortcode for pages that are triggered deliberately rather than browsed.

Salesforce file downloads

Files stored in Salesforce can be served directly through WordPress without a shortcode. Add these parameters to any page URL on your site:

https://example.com/any-page/?sforce=ContentVersion&fileid=0685g00000XyZ1EAAV&filename=brochure.pdf
Parameter Description
sforce The file object type. Accepted values are ContentDocument, ContentVersion, ContentDocumentLink, Attachment, and Document. Any other value is ignored.
fileid The Salesforce record ID of the file, 15 or 18 characters.
filename Optional. The filename offered to the browser, defaulting to download.

Combine this with [sectionsforce] to build a download list straight from your Salesforce files, using {!Id} and {!Title} to construct each link.

Field syntax: cross-object, translated picklists, and addresses

The fields attribute accepts more than plain field names.

Cross-object fields

Use dot notation to pull fields from a parent record. The plugin flattens the nested response so the value displays like any other field:

fields="Name,Account.Name,Account.Owner.Email"

Translated picklist values

Wrap a picklist field in the SOQL toLabel() function to return the translated label instead of the stored API value. The plugin recognises this and matches the response correctly:

fields="Name,toLabel(Status__c)"

Compound address fields

The standard address fields — MailingAddress, BillingAddress, ShippingAddress, OtherAddress, and Address — arrive from Salesforce as nested objects. The plugin detects them and combines street, city, state, postal code, and country into a single readable line, so you can list them like any other field:

[showsforce fields="Name,BillingAddress,Phone" o="Account" by="Name" n="25" t="1"]

Dates and times

Salesforce date and date/time values are detected automatically and rendered in the visitor’s local format. No attribute is needed.

Frequently asked questions

Which shortcode should I use to display Salesforce records in WordPress?

Use [showsforce] for almost everything. It covers cards, tables, calendars, JSON, and CSV through the t attribute. Switch to [sectionsforce] only when you need a fully custom HTML layout, and to [reportsforce] when the numbers already exist in a Salesforce report.

How do I show only the logged-in user’s Salesforce records?

Add a filter that matches a field on the record against the current WordPress user, for example filter="Contact_Email__c = '$WPEmail'". Logged-out visitors on a page filtered by $WPId see a prompt to log in rather than another user’s data.

How many records can the plugin display at once?

Set n to any value up to 10,000. Beyond Salesforce’s own 2,000-record response limit the plugin pages through the results automatically and re-sorts them before display, so large lists work without extra configuration. Pair a large n with the page attribute to keep the page usable.

Why is my table hard to read on mobile?

By default a table stacks each row vertically on small screens, which suits a handful of columns but becomes long and repetitive with many. Add stack="off" to pin the first column and scroll the rest horizontally instead, keeping each record on one line.

How often does the plugin call the Salesforce API?

Results are cached for 60 seconds by default, so repeat visits within that window cost no API calls. Raise the window with refresh (up to 86400 seconds, or one day) on data that changes slowly. Logged-in users always receive fresh data, and nocache disables caching for a specific shortcode.

Can visitors sort and search the results?

Yes. Cards and tables include a live search box by default, which you can remove with search="off". Table column headings are clickable for sorting, and adding page introduces pagination.

Can the plugin write data back to Salesforce?

Yes. Use [submitsforce] with sf- prefixed form fields to create, update, or upsert records from any form, including Elementor Pro and HTML Forms. A single submission can create a primary record plus related records in one pass.