If you're on the Essentials plan, upgrade a development application for free to try this and other Core-level features.
Synced Rows expands on the foundational capabilities of Save Rows and Edit Single Row Mode, helping users manage rows more effectively. Using the merge-rows and synced-rows methods in the Content Services API (CSAPI), you can create an efficient row management workflow. This ensures that when users update content in one row marked as “synced,” those updates are reflected across all connected designs using that synced row.
Cross-design synchronization: Sync saved row contents across multiple linked designs.
Design consistency: Lock rows in linked designs to keep designs uniform.
Editing flexibility: Convert rows from synced to unsynced, making individual changes as needed.
Intuitive edit indicator: Look for the pencil icon at the top-right of synced rows, which provides access to editing options
Auto-updating contacts: Change a contact in one email, and it updates across multiple campaigns.
Effortless re-branding: Edit your logo once and watch it reflect across all designs.
Unified transactional footers: Update details like copyright or social links, and it automatically updates in all relevant email templates.
Row details: This includes structure, settings, and styles.
Content details: Settings and styles of individual content blocks.
Metadata: Any metadata tied to the saved row.
With Edit Single Row Mode you can offer an easier way for your end users to modify a single row with a tailored UI built to edit the row structure, content, and style settings without interfering in the overall design of the email campaign, landing page, or pop-up.
Edit Single Row mode complements both Saved Rows and Synced Rows, because it allows complete control over the content of an individual row (for example, a footer that requires an update) without the need to intervene in a full template's design. This will help you in implementing a more effective way to manage libraries of Saved Rows and Synced Rows with a streamlined design and editing process.
This feature is available on Beefree SDK Core plan and above. If you're on the Essentials plan, upgrade a development application for free to try this and other Core-level features.
Synced Rows expands on the foundational capabilities of Save Rows and Edit Single Row Mode, helping users manage rows more effectively. Using the merge-rows and synced-rows methods in the Content Services API (CSAPI), you can create an efficient row management workflow. This ensures that when users update content in one row marked as “synced,” those updates are reflected across all connected designs using that synced row.
Cross-design synchronization: Sync saved row contents across multiple linked designs.
Design consistency: Lock rows in linked designs to keep designs uniform.
Editing flexibility: Convert rows from synced to unsynced, making individual changes as needed.
Intuitive edit indicator: Look for the pencil icon at the top-right of synced rows, which provides access to editing options
Auto-updating contacts: Change a contact in one email, and it updates across multiple campaigns.
Effortless re-branding: Edit your logo once and watch it reflect across all designs.
Unified transactional footers: Update details like copyright or social links, and it automatically updates in all relevant email templates.
Row details: This includes structure, settings, and styles.
Content details: Settings and styles of individual content blocks.
Metadata: Any metadata tied to the saved row.
Prior to implementing Synced Rows, review the following prerequisites:
Save Rows: Implement Self-hosted Saved Rows first, because it establishes the foundation for a row management workflow.
Edit Single Row Mode & Content Services API (CSAPI): Familiarizing yourself with Edit Single Rows Mode and CSAPI will provide you with a mechanism to edit and manage synced rows, which will support your implementation workflow. However, they are not strictly necessary to implement Synced Rows.
When a row is saved with the synced property, it becomes a “synced row.” To maintain consistency, synced rows cannot be edited within a design. Instead, they function as reference points, ensuring uniformity across all linked designs. The host app must load the row’s JSON using Single Row Edit Mode to edit synced rows. Any modifications to synced rows can be propagated to all linked designs with the help of the CSAPI’s merge-rows and synced-rows methods.
Unsynced saved rows, in contrast, allow for edits that don’t impact other designs. They’re ideal for making design-specific changes without influencing other designs that might share the same base row.
As previously mentioned, a synced row is a saved row designated synced when saved. To set a row’s synced property, adjust the JSON response from the saveRow Content Dialog.
You might need to modify the saveRow handler from the Metadata Content Dialog step in your app’s Save Rows workflow.
If you need a refresher, check out:
Here’s a sample implementation for the Metadata Content Dialog, offering the synced row option:
The JSON returned to the builder includes the user’s input and selections from the UI. The configuration below shows the new synced row setting applied to the options argument of the resolve method.
Look for the pencil icon at the top-right of synced rows. Rows without this icon are standard saved rows. The icon provides a clear visual cue for quickly identifying and editing synced rows.
To edit a synced row, click the pencil icon. Editing options appear in the sidebar panel. Inside, you’ll find a CTA button and optional text.
The CTA button opens the editSyncedRow Content Dialog, allowing the host application to interact with the end-user and receive their selection.
The host application has complete control over the content dialog and UX. However, the content dialog must always return a boolean value of true or false to trigger one of the following outcomes:
If true, the row remains synced to disable content editing in the design before closing the dialog.
If false, the row updates to enable editing and remove the synced property before closing the dialog.
For example, a content dialog might present users with two options:
Edit the row across all designs.
Unsync the row, turning it into a standard saved row.
The first option, to edit the row across all designs, allows users to make changes to the synced row that will be reflected in all designs that use it.
The second option, to unsync the row, converts the synced row into a standard saved row. This means that any changes made to the row will only affect the design in which it is being edited. This option is useful when the user needs to make specific changes to a single design without affecting other designs that may use the same saved row.
The user’s selection from the above example editSyncedRow content dialog UI is returned to the builder as a boolean value. Below is an example of the editSyncedRow configuration for the UI above. Note the boolean value false in the resolve method unlocks the row:
A comprehensive reference of the editSyncedRow Content Dialog settings, such as the CTA button label and optional text, can be found in our Content Dialog docs.
The following animation shows this example of edit synced rows workflow in action. We’ll dive into this process in the following sections.
Suppose a user selects “Edit and update everywhere” from the content dialog. How does the host app ensure seamless editing and synchronization of the row?
Here’s a breakdown of the typical workflow the host app adopts:
Initialization: The host app launches the Edit Single Row Mode in a new builder instance to enable editing of the synchronized row. Our Edit Single Row Mode documentation is available for reference for a deeper understanding.
User edits: Users generally hit ‘Save’ to confirm their edits once they modify the synchronized row. Simultaneously, the host app can proactively track these edits using the onChange method.
Synchronization timing: The decision on when to synchronize changes across all designs rests with the host application. Given the potential need to propagate edits to multiple designs, holding off until the user indicates their wish to exit is customary.
Initiation of synchronization: The synchronization is initiated as soon as the user signifies their satisfaction with the edits, either through the ‘Save’ or ‘Save & Exit’ options.
Redirection & Synchronizing changes: After editing a row, the host app usually performs a synchronous merge rows using the CSAPI. The user will then be redirected to their ongoing design, where they can see their edits reflected in the synced row.
Background syncing: Given the possible existence of numerous linked designs, a background process is usually set in motion to update all other templates.
In the fifth step of the sample workflow, the goal is to bring the user back to their ongoing design with the updated content. This is achieved using the CSAPI’s merge-rows method.
The merge-rows method functions as a sophisticated “find and replace.”
i.e., To synchronize content, the host app forwards a request comprising the outdated template, the newly edited row, and a succinct query detailing which row(s) the API should target for replacement. The “query” is a standards-based JSON Path query typically referencing a globally unique identifier that was added to the saved row during the Metadata Content Dialog step.
For an example on how to use the merge-rows method, visit our API Reference on Merge Rows.
To update rows across all designs, keeping track of the templates where rows have been dropped is crucial. There are two principal methods to associate rows with templates:
Using the onChange method
Upon adding a synced row into a design, the onChange callback method supplies the row’s metadata. The metadata will contain the row’s guid, which can be used to link the synced row to the guid assigned to the template by the host app. Commonly, this is achieved by establishing an index record within the app’s database linking the template’s guid with the row’s guid.
Leverage the synced-rows method
For those rows incorporated into designs before the implementation of the onChange tracking method, CSAPI’s synced-rows method is available. Use the synced-rows method get a list of all the synced rows inside a template with their corresponding rowIdentifier values. To learn more about how to use this endpoint, visit our API Reference on Synced Rows.
The specific objectives of the host application steer the choice between these methods. Whatever the choice, the primary focus is meticulously tracking the row across all linked templates, ensuring accurate and efficient updates.
This feature is available on Beefree SDK Core plan and above. If you're on the Essentials plan, upgrade a development application for free to try this and other Core-level features.
Our builders offer ready-to-go rows to your end-users, which provide both structure and content to create contents faster. With Edit Single Row mode you can offer an easier way for your users to modify a single row with a tailored UI built to edit the row structure, content, and style settings without worrying about messing up with the overall design of the email campaign, landing page, or pop-up.
Edit Single Row mode complements the Saved Rows as it allows a complete control over the content of individual rows (e.g. the footer that requires to be updated) without the need to intervene into a full template, this will help you in implementing a more effective way to manage libraries of Saved Rows with a streamlined design process.
When a builder application is initialized with this mode enabled the UI will show to the user only properties that pertain to editing a single row, therefore:
the options to insert custom rows, saved rows, or new default rows are disabled,
the Settings tab is unavailable, as those properties are specific to the entire document,
when a row is selected on the editing stage, the action to Delete, Duplicate, Comment, Save are not available.
The following describes the recommended workflow to implement the Save action in your host SaaS application when the Single Edit Row mode is enabled.
In case your application uses the default Toolbar, you can leverage the save button to trigger the sequence of action to correctly save the row, the workflow is the same as the one documented in saving-rows-workflow-for-developers, in short :
The user clicks on the save button
A contentDialog of type saveRow will be triggered.
In case your application doesn’t use the default Toolbar you will need to handle the row saving in a different way, following a couple of examples:
Calling the save method. It will trigger the on onSave event with two arguments, one of them is the full message JSON that can be saved as a Saved Row (it’s the same JSON returned by the onSaveRow event).
Listening to the onChange event. It will receive the updated full message JSON which again can be saved as a Saved Row.
An effective way to update saved rows across multiple templates is by implementing the save action in combination with the CSAPI, to handle a row update across multiple existing templates.
