Overview

Saved Rows allows end users to select a row in a design and save it for later use. More specifically, it allows end users to submit a request to the host application to save a piece of content and turn it into a reusable element. The host application, using externalContentURLs, can feed these saved elements back to the builder as rows that can be dragged into other designs.

In the following video tutorial, you will learn how to implement Self-hosted Saved Rows in an application that has embedded Beefree SDK.

You can also reference the sample code in our GitHub repository used throughout this video.

How it works

When the Self-hosted Saved Rows feature is enabled, a Save icon is added to the action icons when a row is selected. The following image displays an example of a row with the Save icon enabled in the upper right-hand corner.

The Save icon is also available in the Row properties panel when a row is selected. The following image displays an example of this.

By clicking on the Save icon, the end user triggers a request to the host application to store the row’s JSON document.

This JSON document includes the following:

• Row structure and settings.

• Contents and their settings.

• All style settings.

The host application needs to determine the following:

• Where to store the JSON documents that describe these saved rows.

• If and how to display them to end users of the application.

• Whether to allow end users to edit them individually.

• When and how to feed them back to the builder, using the externalContentURLs parameter.

Enable Self-Hosted Saved Rows in the Developer Console

Take the following steps to enable Self-hosted Saved Rows in the Beefree SDK Developer Console:

1. Log in to the Beefree SDK Console.

2. Locate the application you'd like to activate Self-hosted Saved Rows for.

3. Click the application's corresponding Details button.

   You will be prompted to the Application Details page.

4. Click the View more link under the Application configuration heading.

5. Navigate to the Saved Rows section.

6. Toggle on the Self-hosted on your own infrastructure option.

7. Click Save on the upper right-hand corner to save your changes.

The following image displays where the toggle is located in the Beefree SDK Developer Console.

Making Saved Rows available only to select users

Once the feature has been turned on at the global level, in Beefree SDK Console, you may want to disable Saved Rows on a per-user basis. This can be accomplished via the client-side configuration document that you feed to an application when initializing the builder for a certain user.

Why? Because you may decide to make the feature available to different users of your application:

• depending on the subscription plan that they are on (you could push users to a higher plan based on the ability to save a row for later);

• depending on the purchase of an optional feature (same);

• to allow “beta” users to see it while keeping it hidden from the rest of your users;

• etc.

Here’s how to do so:

• Enable Saved Rows in the Beefree SDK Console. as mentioned above.

• Add the configuration parameter saveRows to the beeConfig document:

  • Set it to false for all users that cannot saved rows.

Here is a simple example:

Saved Row Configuration

const beeConfig = {
    uid: 'dev-user',
    language: 'en-US',
    ...
    saveRows: false // boolean
    ...
}

Understanding the end user experience

Visit the Saved Rows section of the Reusable Content page to learn more about the end user experience with saved rows. You can also reference the white label end user documentation on Saved Rows to learn more.

The following GIF provides a quick visual example of the end user experience:

Saving rows workflow for developers

When the saved row action is triggered by the user, the builder starts the following sequence:

1. Metadata Content dialog Used to collect data from the host application and add it to the row object. Metadata helps your application to identify a row, overwrite a previously saved version, etc.

2. Saved Rows Callback. Function that returns the row to the host application.

The following describes the recommended workflow to implement saved rows in a host SaaS application.

1. Enable Saved Rows in the Beefree SDK Console as described above.

2. Load a Beefree SDK template.

3. Select the row you want to save and make note of the new save icon.

4. Click the save icon to trigger a Metadata Content Dialog. To successfully handle this step, you must complete these tasks:

   • Add a Metadata Content Dialog object to your beeConfig. This configures your handler.

   • Implement the handler method to open a dialog (e.g., modal window) to collect any metadata you wish your users to input when saving a row.

5. The dialog should contain a form and complete the following specs:

   1. Save the row returned in the Metadata Content Dialog’s args object.

   2. Collect metadata from the end-user, such as row name.

   3. Merge the metadata with the row, so it can be immediately returned to the application.

   4. Return a metadata object to the application so the stage can immediately use the data.

6. The application will update the selected row on the stage with the returned metadata.

7. The application will trigger the onSaveRow callback with the following details:

   • JSON of the selected row

   • HTML preview of the selected row

   • Page Partial of the selected row contained in a page. Use this JSON document to allow users to edit a saved row independently of any message or landing page that might use it.

8. The application will refresh the Rows panel to reload the selected rows data feed.

9. Host app will listen for onSaveRows callback and update the previously saved records with the HTML preview.

Displaying rows

To display saved rows in the Rows tab, add them to the list of rows available to users by leveraging Custom Rows.

The rows are organized in lists that are displayed based on your rows configuration. Use the metadata submitted by your users to categorize them, creating multiple lists of rows: this can significantly improve the user experience.

The following code sample shows an example of a rowsConfiguration that displays saved rows organized by category:

rowsConfiguration: {
            emptyRows: true,
            defaultRows: true,
            maxRowsDisplayed: 40, //optional parameter, the max number of displayed rows is 30 by default         
            externalContentURLs: [{
                name: "Headers",
                value: "https://URL-01"
                },{
                name: "Footers",
                value: "https://URL-02"
                },{
                name: "Product grids",
                value: "https://URL-03"
                },{
                name: "Main article",
                value: "https://URL-04"
            }]         
        },

In this code snippet example, the Rows tab will show:

• Empty rows

• Default rows

• Headers

• Footers

• Product grids

• Main article

… retrieving the arrays of JSON documents for custom rows (externalContentURLs) from the URLs specified.

These custom rows names (Headers, Footers, Product grids, etc.) could be the result of a “Category” metadata entered by the user at the time the row was saved. The input could be the result of:

1. The user writing a new category name for the selected row.

2. The user selecting from a list of existing categories, previously created by the user, or set up by you.

Here is another example that shows saved rows organized in the Rows tab based on the campaign type:

rowsConfiguration: {
            emptyRows: true,
            defaultRows: true,         
            externalContentURLs: [{
                name: "Acquisition series",
                value: "https://URL-01"
                },{
                name: "Newsletter",
                value: "https://URL-02"
                },{
                name: "Transactional",
                value: "https://URL-03"
                },{
                name: "Post-Purchase Drip",
                value: "https://URL-04"
            }]         
        },

Setting a Category's Maximum Rows

You can set a category's maximum rows using the following configuration"

rowsConfiguration: {
  maxRowsDisplayed: 50
}

For more information on setting a category's maximum rows, visit Manage Reusable Content.

Saved Row Management Actions

Accessing, and organizing saved rows is intuitive with Saved Rows Management. With this feature, we’ve introduced a new action in the list of saved rows that your application can intercept to handle changes in this list itself. This means you can now delete, rename, or re-organize your saved rows, right inside the builder.

Visit the Saved Row Management Actions section of the Manage Reusable page to learn how to configure edit and delete row options for your application's end users.

Loading External Rows with an Instance Method

Saved Rows Management also comes with the ability to load any external rows via an instance method instead of an external URL. In addition, since you can now access rows through your application, you don’t need to perform authentication.

To start, define a hook in your application configuration. The hook method should be named getRows and will be nested under the hooks object, as follows:

beeConfig: {
  uid: 'CmsUserName', // [mandatory]
  container: 'bee-plugin-container', // [mandatory]
  hooks: {
    getRows: {
      handler: async (resolve, reject, args) => {

      }
    }
  },
}

Following that, amend your rowsConfiguration object with the additional parameters:

• The handle parameter to utilize in your getRows handler from the previous step

• The isLocal parameter to let the application know to use the hook handler

Here’s an example:

rowsConfiguration: {
  externalContentURLs: [
    {
      name: "Saved Rows via Hooks",
      value: "category-value",
      handle: "category-handle",
      isLocal: true,
    }
  ]
}

When the getRows method is invoked, utilize the 3rd parameter to obtain an argument containing the handle value of the row being requested. Use the handle to determine which set of rows should be returned.

Example args:

{
  value: "category-value",
  handle: "category-handle",
}

Finally, we can call the resolve method, passing in an array of savedRows.

Example hook with args:

beeConfig: {
  uid: 'CmsUserName', // [mandatory]
  container: 'bee-plugin-container', // [mandatory]
  hooks: {
    getRows: {
      handler: async (resolve, reject, args) => {
        // get the handle
        const handle = args.handle
        // pseudo code to get the rows with the handle...
        const rows = await fakeRowsService(handle)
        resolve([ ...rows ]) 
      }
    }
  },
}

Saved rows schema

The following is the basic structure of the row’s JSON schema. Simply put, the schema is the structure of your saved rows data feed.

[
    {
        metadata: {
            name: 'My row name' // Identifies the row, required.
        }
        columns: { ... }
        ...
    }, // The row that was previously saved. - (*)
    ...
]

The metadata section of the rows schema allows you to keep track of row-specific information.

metadata: {
    "name": "My Saved Row", // The row's title displayed in the "Rows" panel.
    "tags": "product, two columns, blue",
    ... additional custom parameters
}

Required metadata

name The saved row’s title displayed in the Rows panel.

• A string of plain text that identifies the row.

• Displayed in the row card when the row is shown in the Rows panel.

• Used for text searches within the Rows panel

Recommended metadata

category A category can be useful for organizing your feeds on the Rows tab.

id A handle that identifies the row in the host application’s data storage.

idParent Useful to track rows that were saved from previously saved rows. Keeping track of where a row came from allows you to implement additional editing features.

dateCreated The date the row was created: useful for filtering/sorting rows for content management purposes in your application. It can also help with technical support tasks.

dateModified The date a saved row was updated: useful for filtering/sorting rows for content management purposes in your application. It can also help with technical support tasks.

userId To let your application decide whom can edit or saved rows.

tags Useful to create filters, management, search, and in general to organize the content in your application.

Metadata Content Dialog

The metadata content dialog is triggered by the save icon in Beefree SDK. This step is required to provide Beefree SDK with information about the row, such as its name and/or id. The Metadata Content Dialog is added in the same manner as other Content Dialogs, such as Merge Tags. Please review the Content Dialog section for more details about how to use Beefree SDK’s Content Dialog feature.

An example Metadata Content Dialog configuration can be found below.

contentDialog: {
    saveRow: {
        handler: function (resolve, reject, args) {
            return window.bee.onHandleMetadata(args)
               .then((metadata) => {
                 resolve(metadata, { synced: true }) //  {
                reject()
              })
       }
    },
externalContentURLs: {
   handler: function (resolve, reject, args) {
       return window.bee.onSearchSavedRows(args)
           .then((rows) => {
             resolve(rows)
           })
           .catch(() => {
             reject()
           })
     }
   },
},

The metadata resolve function now accepts an options object in which you can pass the property synced to determine if the row needs to be saved and treated by the builder as synced.

{ synced: true }

Saved Rows callback

When the Metadata Content Dialog is completed, the application triggers the Saved Rows callback. The callback returns the following details:

rowJSON JSON of the selected row.

rowHTML HTML preview of the selected row

pageJSON Page Partial of the selected row contained in a page (for editing a row as an independent piece of content).

onSaveRow: function (rowJSON, rowHTML, pageJSON) {
    // Do something with the returned values...
},

Edit Saved Rows

With Edit Single Row mode you can offer an easy way for your end users to edit saved rows individually, using a tailored UI built to modify 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.

Enabling a more modular approach to saved rows simplifies how users can design and act on content: updating small details in a saved row, saving it, then deploying it to existing templates becomes a matter of minutes. If you want to learn more about how to leverage Edit Single Row mode to safely modify a Saved Row, take a look at the dedicated technical documentation.

Saved Rows Overview

This page provides an overview of Saved Rows and their key benefits.

What Are Saved Rows?

Saved Rows in Beefree SDK optimize the content creation process by allowing users to save, categorize, and manage reusable rows for future use. When this feature is enabled, users can simply click the Save icon on a row within their design and store it for later. This ensures quick access to preferred layouts and design elements across multiple projects.

Save Rows are particularly helpful in the following scenarios:

• Standardizing Footers: Save a footer row with contact details, social media links, and copyright information. Use it across multiple email templates to ensure consistency.

• Designing E-Commerce Product Grids: Create reusable rows showcasing product images, descriptions, and call-to-action buttons. Pull these rows dynamically from an e-commerce catalog for up-to-date content.

• Creating Promotional Banners: Save promotional rows with pre-configured styles and messaging. Reuse them across campaigns to maintain branding and reduce setup time.

Benefits of Saved Rows

There are several benefits to utilizing saved rows. This section outlines benefits for both end users and the host applications.

Saved Rows enable end users to:

• Save and reuse content: Create emails, landing pages, and popups, apply their own style and brand guidelines, and save all of that hard work inside of a row and reuse it at a later date. After saving a row, they can still edit the row and make any adjustments to the content blocks inside of it.

• Flexible Categorization: Organize rows into intuitive categories to easily find and reuse them later on.

• Easily Manage Rows: Edit the name and category of a saved row easily. Or, delete rows if they are no longer needed.

Saved Rows enable host applications to:

• Enhance the User Experience: Enable users to save, categorize, and manage rows efficiently.

• Customize Permissions: Enable or disable end user permissions to delete, edit, manage, or add Saved Rows.

• Make Saved Rows Available to Select Users: Control which users can and cannot save rows.

How Saved Rows Work

When enabled, Saved Rows allow end users to select a row in their design and save it. This process involves:

1. Selecting a row in the builder.

2. Clicking the Save icon in the toolbar or row properties panel.

3. Storing the row’s structure, content, and styles as a JSON document in your chosen storage solution.*

Using Saved Rows

Once created and saved, end users can reuse saved rows through the builder’s ROWS tab.

There, users can:

• Browse saved rows by category.

• Search for rows using metadata like row names or descriptions.

• Drag and drop rows into their designs for immediate use.

Activation and Storage Paths for Saved Rows

There are two paths you can take to activate and store Saved Rows for your application:

Clone the Sample Project Demo

Clone the the sample project demo to follow along with the steps outlined on this page.

Overview

In this guide you will:

• Enable the saved rows feature in your developer console.

• Configure the Beefree SDK with the proper hooks.

• Build a frontend with content dialogs (for saving, editing, and deleting rows).

• Manage metadata (names, categories) for each saved row.

• Create API endpoints (GET, POST, PUT, DELETE) on your backend.

• Set up a database to store row data.

• Connect your frontend with the backend through these endpoints.

• Test your endpoints using tools like Postman or Insomnia.

Each step below is designed to build upon the previous ones, guiding you from initial setup to the final integration. This guide explains not only what to do, but also why each step is important and how it interacts with the other parts of the overall solution.

Note: Self-hosted saved rows is a highly customizable feature. While this guide provides one approach to implementing Self-hosted saved rows, it is important to note that there are several ways you can customize this implementation based on your application's needs. While this guide mentions core implementation concepts, such as toggling the feature on, setting up the beeConfig accordingly, and so on, it is also important to note it mentions approaches that you can customize, such as designing frontend modals, configuring your database, and so on.

1. Enable Saved Rows in Your Developer Console

Overview and Context

• Creating the user interface for end users to create, save, and manage saved rows.

• Creating, configuring, and connecting your own database to store the saved rows data.

• Creating CRUD operations with your own API endpoints.

Enabling this toggle is a prerequisite for all the integration steps outlined in the subsequent sections. Without this toggle, none of the custom hooks or API endpoints will function properly.

Steps to Complete

To enable Self-hosted saved rows for your application, follow these steps:

2. Navigate to the application you'd like to configure Self-hosted saved rows for.

3. Click on Details.

4. Navigate to Application configuration and click View more.

5. Scroll to the Saved Rows section.

6. Toggle on the Self-hosted on your own infrastructure option.

2. Configure the Beefree SDK

Overview and Context

The Beefree SDK must be configured with custom hooks to handle your saved rows. This involves defining a client configuration type and setting up a configuration object that includes your custom getRows handler. This step is crucial because it connects the SDK with your backend API, allowing it to fetch and update saved rows dynamically.

Code Snippet

Reference the Type Definition & Client Config in the following code snippet.

// Define the type for the client configuration
type ClientConfig = {
  uid: string; // Unique client identifier
  container: string; // DOM element where the editor will mount
  language: string;
  saveRows: boolean;
  hooks: {
    // Custom hook to retrieve saved rows from your backend
    getRows: { handler: (resolve: Function, reject: Function, args: any) => void };
  };
  rowsConfiguration: {
    emptyRows: boolean;
    defaultRows: boolean;
    // Array of external content URLs dynamically generated based on categories
    externalContentURLs: Array<{
      name: string;
      value: string;
      handle: string;
      behaviors: { canEdit: boolean; canDelete: boolean };
    }>;
  };
};

// Set up the configuration object for the Beefree SDK
const beeConfig: ClientConfig = {
  uid: 'your-client-uid', // Your unique client ID
  container: 'bee-plugin-container', // ID of the container element
  language: 'en-US',
  saveRows: true,
  hooks: {
    // Assign your custom getRows handler here
    getRows: { handler: getRowsHandler },
  },
  rowsConfiguration: {
    emptyRows: true,
    defaultRows: true,
    externalContentURLs: externalContentURLs, // This array is built based on your categories
  },
};

Additional Context

By correctly configuring Beefree SDK, you guarantee that the editor will know how to fetch and display saved rows. The getRows hook becomes the bridge between the editor and your data source, while the rowsConfiguration object provides the necessary settings for displaying external content based on categories.

3. Build the Frontend with Content Dialogs

Overview and Context

Next, you will create the user interface (using a framework like React) that interacts with Beefree SDK. This step involves building modals for saving, editing, and deleting rows. The frontend is responsible for gathering user input and communicating with the backend, so the UX needs to be both responsive and intuitive.

Key Tasks

This step covers the following key tasks:

• Create a React component (e.g., SavedRowsEditor) that will render the Beefree SDK editor.

• Fetch saved rows and categories during the component's mounting phase.

• Implement modal dialogs that capture user input (e.g., row name, category) and trigger backend updates.

Code Snippet

The following code snippet is for the Save Row Modal.

// Function to show a modal for saving a new row
function showSaveRowModal(resolve, reject, args) {
  // Create modal container with inline styles for positioning and appearance
  const modal = document.createElement('div');
  modal.style.cssText =
    'position:fixed;top:50%;left:50%;transform:translate(-50%,-50%);padding:24px;background:#fff;border-radius:8px;box-shadow:0 4px 12px rgba(0,0,0,0.15);z-index:1000;width:320px;font-family:Arial,sans-serif;';

  // Input for Row Name
  const nameInput = document.createElement('input');
  nameInput.placeholder = 'Row Name'; // User enters the row name
  nameInput.style.cssText = 'display:block;width:100%;padding:8px;margin-bottom:16px;';
  modal.appendChild(nameInput);

  // Input for Category
  const categoryInput = document.createElement('input');
  categoryInput.placeholder = 'Category'; // User enters the category
  categoryInput.style.cssText = 'display:block;width:100%;padding:8px;margin-bottom:16px;';
  modal.appendChild(categoryInput);

  // Save button with click handler
  const saveButton = document.createElement('button');
  saveButton.textContent = 'Save';
  saveButton.style.marginRight = '8px';
  saveButton.onclick = async () => {
    // Validate inputs before proceeding
    if (!nameInput.value || !categoryInput.value) {
      alert('Please provide both a name and a category.');
      return;
    }
    // Build the row data object using provided inputs
    const rowData = {
      metadata: {
        id: args.metadata?.id || generateUniqueId(), // Use helper to generate a unique ID
        name: nameInput.value,
        category: categoryInput.value,
      },
      synced: false, // Default synced state
    };
    try {
      await updateSavedRows(rowData); // Call function to update or create the row in the backend
      resolve(rowData);
      document.body.removeChild(modal);
    } catch (error) {
      alert('Failed to save row');
      reject(error);
      document.body.removeChild(modal);
    }
  };
  modal.appendChild(saveButton);

  // Cancel button to close modal without saving
  const cancelButton = document.createElement('button');
  cancelButton.textContent = 'Cancel';
  cancelButton.onclick = () => {
    reject();
    document.body.removeChild(modal);
  };
  modal.appendChild(cancelButton);

  document.body.appendChild(modal);
}

Code Snippet

The following code snippet shows the React Component Skeleton.

class SavedRowsEditor extends React.Component {
  componentDidMount() {
    // Fetch initial saved rows and categories from the backend
    fetch(`${BASE_URL}/rows`)
      .then(res => res.json())
      .then(savedRows => this.setState({ savedRows }));

    // Similarly, fetch categories then initialize the Beefree SDK editor
    this.initializeBeeEditor();
  }

  // Custom handler for retrieving rows, used by Beefree SDK
  getRowsHandler(resolve, reject, args) {
    fetch(`${BASE_URL}/rows/${encodeURIComponent(args.handle)}`)
      .then(res => res.json())
      .then(rows => resolve(rows))
      .catch(error => reject(error));
  }

  render() {
    return <div id="bee-plugin-container" style={{ minHeight: '600px' }} />;
  }
}

Additional Context

This step ties together your user interface with the Beefree SDK and backend. By using modal dialogs for CRUD actions, users can interact with the saved rows feature directly within the Beefree SDK editor. The React component handles data fetching and state updates, ensuring that the UI remains in sync with the backend.

4. Manage Metadata for Saved Rows

Overview and Context

Managing metadata is critical for organizing and retrieving saved rows. Metadata such as the row's ID, name, and category allow you to group rows, edit them, and build dynamic external content URLs. In this step, you'll update and refresh external content URLs based on current categories and see how the Beefree SDK configuration uses this data.

Key Tasks

• Define the metadata structure (ID, name, category) in your saved rows.

• Create a function to update the external content URLs whenever categories change.

• Ensure that the Beefree SDK's configuration (rowsConfiguration) is dynamically updated with these URLs.

Code Snippet

The following code snippet shows an example of Updating External URLs.

function updateExternalContentURLs(categories) {
  // Map each category to an external content URL object
  const externalContentURLs = categories.map(category => ({
    name: category,
    value: `${BASE_URL}/rows/${encodeURIComponent(category)}`, // URL endpoint for the category
    handle: category, // Identifier used for row management
    behaviors: { canEdit: true, canDelete: true }, // Permissions for row actions
  }));
  return externalContentURLs;
}

Supplementary Code Snippet

The following code snippet shows an example Beefree SDK Row Configuration.

// Example snippet showing how beeConfig integrates the rows configuration
const beeConfig = {
  // ...other configuration properties...
  rowsConfiguration: {
    emptyRows: true,
    defaultRows: true,
    // External content URLs dynamically set based on current categories
    externalContentURLs: updateExternalContentURLs(currentCategories),
  },
  // ...hooks and additional configuration...
};

Additional Context

Managing metadata effectively allows you to organize saved rows into logical groups. When a new category is added or updated, refreshing the external content URLs ensures that the editor displays the correct endpoints for fetching rows. This dynamic behavior is crucial for maintaining data consistency across your frontend and backend.

5. Create API Endpoints in the Backend

Overview and Context

The backend API endpoints serve as the communication bridge between your frontend and database. These endpoints are responsible for creating, reading, updating, and deleting saved rows. Proper endpoint implementation ensures that user actions in the frontend correctly update the database and that the Beefree SDK editor receives the latest data.

Key Tasks

This section covers the following key tasks:

• Set up an Express server.

• Implement CRUD endpoints (GET, POST, PUT, DELETE) to handle row operations.

• Validate incoming data to ensure that required metadata (name and category) is present.

Code Snippet

The following code snippet shows a POST Endpoint example.

app.post('/rows', (req, res) => {
  const rowData = req.body;
  // Validate that required metadata exists
  if (!rowData.metadata || !rowData.metadata.name || !rowData.metadata.category) {
    return res.status(400).json({ error: 'Missing required fields.' });
  }
  const { id, name, category } = rowData.metadata;
  const synced = rowData.synced || false;
  db.run(
    // Insert the new row into the database
    'INSERT INTO saved_rows (id, name, category, synced, row_data) VALUES (?, ?, ?, ?, ?)',
    [id || generateUniqueId(), name, category, synced, JSON.stringify(rowData)],
    (err) => {
      if (err) res.status(500).json({ error: err.message });
      else res.json({ message: 'Row saved successfully!' });
    }
  );
});

Additional Context

6. Set Up the Database

Overview and Context

Using SQLite in this example, you must set up a database to persist saved rows. Creating the appropriate table schema ensures that all necessary data (such as metadata and row content) is stored reliably. This database will be accessed by your API endpoints to perform CRUD operations.

Code Snippet

The following code shows shows the SQLite Table Creation.

// Initialize SQLite database and create the saved_rows table if it doesn't exist
db.run(`
  CREATE TABLE IF NOT EXISTS saved_rows (
    id TEXT PRIMARY KEY,
    name TEXT,
    category TEXT,
    synced BOOLEAN,
    row_data TEXT
  )
`);

Additional Context

A well-defined database schema is essential for data consistency and performance. In a production environment, you might choose another database system, but this SQLite example provides a simple starting point to demonstrate the concept.

7. Connect the Frontend to the Backend

Overview and Context

To enable real-time data interactions, your frontend must connect to the backend via HTTP requests. This connection allows the Beefree SDK editor to fetch saved rows and update data based on user actions. The integration of fetch calls in your React component ensures that the user interface is always synchronized with the underlying data store.

Code Snippet

The following code snippet shows Connecting via Fetch.

componentDidMount() {
  // Fetch saved rows from the backend
  fetch(`${BASE_URL}/rows`)
    .then(res => res.json())
    .then(savedRows => this.setState({ savedRows }));

  // Fetch categories and update external content URLs accordingly
  fetch(`${BASE_URL}/categories`)
    .then(res => res.json())
    .then(categories => {
      const urls = updateExternalContentURLs(categories);
      this.setState({ categories, externalContentURLs: urls });
    });
}

Additional Context

By establishing these fetch connections, the frontend remains dynamic and responsive. Changes in the backend are quickly reflected in the UI, which is crucial for maintaining a seamless user experience.

8. Test Your Endpoints

Overview and Context

Before deploying your solution, it's critical to test all endpoints to verify that CRUD operations work as expected. Using tools like Postman or Insomnia allows you to simulate API requests and ensure that both the backend and frontend are interacting correctly. Comprehensive testing helps catch potential errors early.

Testing Steps

Take the following steps to test your endpoints.

• GET /rows: Verify that all saved rows are returned.

• GET /rows/:category: Confirm that rows for a specific category are fetched.

• GET /categories: Check that the unique list of categories is correct.

• POST /rows: Ensure that a new row is added when metadata is provided.

• PUT /rows/:id Validate that an existing row is updated correctly.

• DELETE /rows/:id Confirm that a row is removed successfully.

Final Guide Notes

By following this guide you have:

1. Enabled self-hosted saved rows in your developer console.

2. Configured the Beefree SDK with a custom getRows hook.

3. Built a user-friendly React component with modals to save, edit, and delete rows.

4. Managed metadata (name and category) for each row, and integrated dynamic external content URLs into the Beefree SDK configuration.

5. Created complete API endpoints (GET, POST, PUT, DELETE) on your Express backend.

6. Set up an SQLite database (or your preferred database) to store row data.

7. Connected your frontend to the backend using standard HTTP requests.

8. Tested your endpoints to ensure a smooth integration.

Overview

With Hosted Saved Rows, you can provide your end users with the option to save and manage reusable content directly within the builder. Hosted Saved Rows can be activated through a toggle within the Developer Console, which makes it an excellent option for those who are interested in a fast implementation of Saved Rows. Once you toggle this feature on, your end users will be able to save the rows they create within the builder, and reuse them easily in the future. They can also perform actions to manage the rows that they save, such as renaming them, deleting them, categorizing, or recategorizing them. This page covers the steps you need to take to successfully implement Hosted Saved Rows.

The following video tutorial discusses what Saved Rows are, how reusable content can support your end users throughout their content creation journeys, and how you can implement Hosted Saved Rows in your application.

Enable Hosted Saved Rows

To enable Hosted Saved Rows for your application, follow these steps:

1. Log in to the Developer Console.

2. Navigate to the application you'd like to configure Hosted Saved Rows for.

3. Click on Details.

4. Navigate to Application configuration and click View more.

5. Scroll to the Saved Rows section.

   1. Toggle on the Hosted on the Beefree SDK Infrastructure option.
   2. Read the pricing information in the popup closely, because additional fees may apply.*
   3. If you'd like to proceed, confirm you read and understand the pricing to activate the feature.

*Hosted Saved Rows have the following pricing structure:

Note: Visit our Usage-based fees article to learn more about Hosted Saved Rows pricing.

Once you've successfully enabled Hosted Saved Rows in the Developer Console, you'll access the following:

• Rows saved by your application's end users will be stored and hosted in the Beefree SDK storage option.

• End users can save rows directly to the hosted infrastructure and retrieve them as needed.

User Interface and End User Experience

Once you successfully enable Hosted Saved Rows within the Developer Console, your application's end users will have access to a new Save icon for each row, and other options for managing the rows they save.

The Hosted Saved Rows UI includes the following experience for end users:

• End users can save a row using the Save icon.
• They have the ability to name and categorize rows.
• They can edit a row's name or category and save those changes.
• End users can decide to reuse or delete rows through the Rows tab in the side panel.
• They can also use the vertical three dots to add and manage categories.

Reference the Hosted Saved Rows end user documentation for more information on the end user steps and experience.

Configure Advanced Permissions

Hosted Saved Rows includes advanced permissions to control how rows and categories are accessed and managed. These permissions allow you to define user capabilities, such as editing or deleting rows.

Available Permissions

The permissions you can control for Hosted Saved Rows through Advanced Permissions are the following:

• canDeleteHostedRow: Allows or prevents deleting hosted rows.

• canEditHostedRow: Enables or disables editing of hosted rows.

• canManageHostedRowCategory: Controls whether end users can manage row categories.

• canAddHostedRowCategory: Determines if end users can add new categories.

Permission Behavior

Keep the following behaviors in mind when setting advanced permissions:

• If both canDeleteHostedRow and canEditHostedRow are set to false, the row menu will be hidden.

• If both canManageHostedRowCategory and canAddHostedRowCategory are set to false, the category management menu will be hidden.

Example Configuration

The following configuration displays an example of the rows object inside of advancedPermissions:

{
...
advancedPermissions:{
  ...
  rows:{
    behaviors: {
        canDeleteHostedRow: false,
        canEditHostedRow: false,
        canManageHostedRowCategory: false,
        canAddHostedRowCategory: false,
      },
    ...
  },
  ...
  }
...
}

Making Saved Rows Available to Select Users

Once Saved Rows is enabled globally in the Developer Console, you can disable it for specific users using the saveRows parameter in the beeConfig document. This lets you control access based on subscription plans, feature purchases, or beta testing.

Take the following step to disable access for specific users:

• Set saveRows to false for users who shouldn’t have access.

The following code provides a simple example of how to add the saveRows configuration parameter and set it to false to make the feature unavailable to select users.

const beeConfig = {
    uid: 'dev-user',
    language: 'en-US',
    ...
    saveRows: false // boolean
    ...
}

Default Behavior

The following image shows the save icon when the end user clicks on the row.

Hiding the Save Icon

The following image does not show the save icon when the end user clicks on the row. This behavior occurs after adding saveRows to your beeConfig and setting it to false.

Removing the Rows Tab for Select Users

Similar to how you may want to restrict which end users can save rows based on subscription type, plan type, and so on, you can also control which users have access to the ROWS tab within the builder altogether. By default, the ROWS tab is available within the builder.

You can remove the ROWS tab by:

• Add the defaultTabsOrder parameter to your beeConfig and set it to: ['content', 'settings'] or ['settings', 'content'].

Keep in mind the defaultTabsOrder is a string array (string[]).

The tab order represented in the snippet below with content first and settings second, results in the visualization displayed in the image after.

defaultTabsOrder: ['content', 'settings']

In the following image, the ROWS tab is no longer available to the end user. In the following image, the ROWS tab is no longer available to the end user and the order of the tabs are Content first and Settings second.

The tab order represented in the snippet below with settings first and content second, results in the visualization displayed in the image after.

defaultTabsOrder: ['settings', 'content']

In the following image, the ROWS tab is no longer available to the end user and the order of the tabs are Settings first and Content second.

Reference the Hosted Saved Rows Webinar to learn more about other customizations that are compatible with Hosted Saved Rows. The webinar discusses the following topics:

• How to enable Hosted Saved Rows

• How to use Advanced Permissions with Hosted Saved Rows

• How to restrict which end users can save rows

• How to customize the modals related to Hosted Saved Rows

• How to use Hosted Saved Rows with Content Services API

Reference the sample code in this GitHub repository to follow along with the webinar tutorial.

Visit the Hosted Saved Rows page to also learn more about the following topics:

• Troubleshooting and FAQs

• Deactivating Hosted Saved Rows

• What Happens When Deactivated