# Introduction Welcome to openBuild openBuild is a [framework](/introduction/the-framework) for building Bubble apps professionally. It is the result of years of Bubble design and development experience packed into a Bubble template. {% hint style="success" %} Get the Bubble template here 👉 {% endhint %} {% hint style="danger" %} The 2.0 version of the openBuild extension, designed to work with the latest responsive engine, is currently in closed beta testing. The current version of the extension only works with the legacy template, which was built on the old responsive engine. The updated version of the extension will be made available to the public soon. {% endhint %} openBuild is built on top of [Bubble](/core-concepts/bubble-vs-openbuild) and cannot be used as a standalone product. {% hint style="info" %} openBuild is a professional framework for Bubble.io. While its concepts are easy to understand and learn, it is not a beginner template. {% endhint %} # The Framework The most flexible Bubble template for your next project openBuild is a starter template for Bubble. It comes with different starting point pages, prebuilt navigation, an admin page, login/signup, profile settings, other useful reusable components, workflows and beautiful transactional emails. The framework uses the Bubble new responsive engine with a smart design system, taking care of the bulk responsive work while you can focus on creating beautiful user interfaces. This template has everything you need to build beautiful responsive, clean and scalable web applications. 1. Different app [Layouts](broken://pages/-M4dVflJRAUVQDqHLAl7) 2. [Responsive grid](broken://pages/-M4dc1YWvMRVC3MTcmvZ) compatible with openBuild Library 3. openBuild [styles](broken://pages/-M4dcCL1Xg6nZT1z9p7P) 4. [Option sets](broken://pages/-M4dfqTIvgpV_UwJGoND) 5. [Navigation](broken://pages/-M4deT3hJC8HLOHAIp-F) with workflows (including mobile navigation with hamburger menus and nav bar) 6. [Menus ](broken://pages/-M4i09OuK9kRFRhs1jVK)with workflows 7. [Login & Sign up](broken://pages/-M4deWZW4PlipAfxAx5n) 8. [Transactional email](broken://pages/-M4dehZeRjo9M_vW6gur) 9. [User Settings](broken://pages/-M4de_639YZ2fjlDkYia) 10. [Admin panel](broken://pages/-M4deeMQOudxhWx90ep1) 11. Workflows for creating and inviting users 12. [Reusable elements ](broken://pages/-M4dgA9zTMURl-LzKzJ2) # The Library Coming soon! # Release Notes # Bubble vs openBuild How is openBuild different from Bubble? openBuild is a framework for using Bubble. It is meant to help you build more structured and more easily than simply using ‘vanilla’ Bubble. You can compare it best to CSS frameworks you may already be familiar with. Similarly, you can compare openBuild to UI builders for Wordpress. > **For Wordpress there is Elementor and Divi. For CSS there is Bootstrap and Tailwind. For Bubble there is openBuild.** On top of that, the openBuild Bubble template is full of best practices of having been used to build thousands of Bubble apps, all rolled into one powerful starting point for your next app! Ultimately, openBuild is a thoughtful process for building responsively on Bubble as well as a vast library of components and widgets to help you build even faster. This process consists of the way we structure applications: many apps are single page. With openBuild we have a system in place to help you deal with navigating ‘pages’ within the page to create a single page app (SPA). It also helps you deal with data in a better way, making sure you never have too many data queries on your page, or duplicate a query reducing performance of your app. {% hint style="info" %} openBuild is a way of building responsively on Bubble as well as a vast library of style-matching components and widgets to help you build even faster. {% endhint %} # Responsive Design One structure to create 90% of all app and websites layouts, fully responsive. The openBuild structure consists of 5 levels of containers, with their own specific rules making the framework to be responsive from small phone (320px) to 4K monitor. But don't worry, you only need to worry about one to build! ## Specifications
ElementContainer TypeMin WidthPaddingGap
PageColumn--
⃞ Content AreaColumn--
❖ SectionColumn--20
▭ Row ContainerRow-0 0 20 2020
⧆ BlockVaries280pxVariesVaries

The Block element is where all the stuff in your app happens.

### Page This is a bubble page. By default we use Page as column and set up the UI width at 1280px. ![Width of the editor is 1280px.](https://3323346004-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FW4eajJmOk3q8BX2WzhCG%2Fuploads%2FMZ9qkQvf6X430yr2IBck%2Fimage.png?alt=media\&token=7896b226-5f7b-4359-bb22-d7b98838d64e) ### Content Area A content area is the container holding all your sections. So it's basically holding all your page contents except your page navigation (Header, Left Menu, etc.). As the content area is located differently whether your page is with a left menu, a header or a right menu for example, its margins will be modified according to the page layout.

Example of content area according to page layout

### ❖ Section A section is the container holding all your row containers. Depending on how you use your page (Single Page App (SPA) or website) a section has a different usage. In the case of a website page, think of the hero image of a site as a section, or the features area as a section. In the case of SPA, a section is used as a 'virtual' page that is hidden/shown depending the [navigation URL parameter](/working-with-the-framework/navigation).

In SPA's a Section acts as a Page.

### ▭ Row Container Row containers are used to build the contents of a section. As the name explains, these are rows that build the section interface from top to bottom. Row containers always have 20px padding on left/right, to ensure a 20px distance from the screen edges on any device.

Row containers build your content in neat rows.

### ⧆ Block Finally, blocks are components that are added into row container. This is your actual page content, like a table, image, map or card. One or multiple blocks can be combined together. Note that a standard block has a minimum width of 280px to ensure correct display on 320px Mobile (280px + 20x2 padding from their Row container).

Blocks make up of the actual visual content of your page.

# Repeating groups Anything list related Repeating groups follow specific rules to be compliant with openBuild. In order for RG's to have the same alignment, we have a specific RG containers containing our RG's, ensuring 20px gap between our items as well as 20px padding on both sides. ![](https://3323346004-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FW4eajJmOk3q8BX2WzhCG%2Fuploads%2FTAfM4rrrbuegoogVuYpp%2Frgcontainer.png?alt=media\&token=da1e52da-bac0-497a-b7c4-6623bd97cc3e)
ElementPadding
RG container10px Left/Right
RG-
Outer10px Left/Right/Top/Bottom
InnerDepends (how the card is designed)
#### RG number of columns While Bubble allows you to set up the number of columns you want in your RG, this number is fixed. With openBuild framework, you can play with RG column min width to get the desired layout.
RG column min wdth# of columns on 1280 px# of columns on 768px# of columns on 320px
280px421
224px531
204px641
#### Set up max column # (CSS) Another possibility offered to set up the maximum number of RG column you need is to use custom CSS. ``` ``` # Advanced Responsiveness While our standard specifications allow you to generate consistent layouts, you might want to use some custom settings to build your desired UI. For example, having blocks of different widths within the same row container might be important in a certain layout. In order to do that, we override the min-width of the blocks and/or make the width fixed for certain blocks. ![Example of different blocks width](https://3323346004-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FW4eajJmOk3q8BX2WzhCG%2Fuploads%2Fw4y1F1gFdz2o26o6o81X%2Fimage.png?alt=media\&token=2b88b7b2-52ab-4fe3-a4d7-e68a973c8aa8) When you're using this method, it's likely also that you want your layout to behave differently on smaller devices. Using the [Viewport Option Set](/framework-elements/option-sets), you can then either hide certain blocks or make those full width for certain devices. ![Make element full width when not desktop](https://3323346004-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FW4eajJmOk3q8BX2WzhCG%2Fuploads%2Fon2r3oJh8pFjZdC0wLkh%2Fimage.png?alt=media\&token=3a1dce35-301a-4756-b3c7-a145efabdb72) ![Hiding an element when not desktop](https://3323346004-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FW4eajJmOk3q8BX2WzhCG%2Fuploads%2FUa0vYBugfO4BVIIEmTQN%2Fimage.png?alt=media\&token=adfcae67-684f-4854-9136-2f7cb1f12c36) # Styles {% hint style="warning" %} All openBuild styles include the ⊝ icon as a first character to avoid mixing those with your own created styles. Remember to not delete openBuild styles if you want later to swap your style guide for another one. {% endhint %} ## ![](https://3323346004-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FW4eajJmOk3q8BX2WzhCG%2Fuploads%2FejPFs8KOe85W2zbACjyP%2FStyleguide.png?alt=media\&token=9183f40a-baf7-4450-ad06-e288ab947434) # Typography openBuild typography consists of 9 Headings, 4 Bodys, Caption and Overline. ![](https://3323346004-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FW4eajJmOk3q8BX2WzhCG%2Fuploads%2FDvOuBTX6S7zKeTYQlJ2q%2Fimage.png?alt=media\&token=2faf3ad3-f94a-4e92-a577-3dd057dc9c00) Regarding variations, each text style is available in any variation of colors and alignment. Note that the style name syntax is always the same : ⊝TEXT STYLE-TONE-ALIGNMENT, like the example below. ![](https://3323346004-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FW4eajJmOk3q8BX2WzhCG%2Fuploads%2FEtNpqrcMHqtZ3MwsXOd1%2Fimage.png?alt=media\&token=8a231f02-b9a6-4773-a51e-c0d2f8d85205) Additionally, we added 3 text styles related to navigation : NavText S, NavText M & NavText L. Those are used primarily in navigation components (header, left menu, sub navigation etc..). openBuild typography consists of 9 Headings, 4 Bodys, Caption and Overline. ![](https://3323346004-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FW4eajJmOk3q8BX2WzhCG%2Fuploads%2FDvOuBTX6S7zKeTYQlJ2q%2Fimage.png?alt=media\&token=2faf3ad3-f94a-4e92-a577-3dd057dc9c00) Regarding variations, each text style is available in any variation of colors and alignment. Note that the style name syntax is always the same : ⊝TEXT STYLE-TONE-ALIGNMENT, like the example below. ![](https://3323346004-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FW4eajJmOk3q8BX2WzhCG%2Fuploads%2FEtNpqrcMHqtZ3MwsXOd1%2Fimage.png?alt=media\&token=8a231f02-b9a6-4773-a51e-c0d2f8d85205) Additionally, we added 3 text styles related to navigation : NavText S, NavText M & NavText L. Those are used primarily in navigation components (header, left menu, sub navigation etc..). # Colors Flexible and in-depth 9-colors token to get structured and consistent color palette. openBuild 9-colors palette structure has been carefully decided to allow variety of color schemes while keeping high consistency in your apps. This structure ensure infinite possibilities of color schemes (dark mode, saturated, monochromatic, triadic etc...). ![openbuild color palette example (from DeepBlue OB Style)](https://3323346004-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FW4eajJmOk3q8BX2WzhCG%2Fuploads%2F5iqKcAGrCrNKeqP9FbR7%2FGroup%20298.png?alt=media\&token=dc074a03-c33a-4b14-a1d3-ad83852f404b) ### Colors While Main color is usually the main brand color, the two others are supportive colors. Depending the style guide you pick, those can be analogous, complementary or even inverted colors from the main one. Colors tones are used as variants in all OB text styles, as well as OB group styles. Buttons are available for Main color and Secondary color only. ### Shades Shades represent 6 tones going from Primary to Negative. Depending the styleguide, those are slightly tainted toward the main Color, which reinforce the overall consistency of the app color palette. Shades tones are used as variants across different OB styles like typography, groups, buttons. While the color palette is employed across style variations, it's important to note that the color palette is also saved in your app within the option Set 'UI Colors'. This allows you to use it outside of app defined styles (like in element properties, conditionals etc...). # Groups & Box Shadow ### Main group styles We have 6 types of group styles used across all the color tones. ![](https://3323346004-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FW4eajJmOk3q8BX2WzhCG%2Fuploads%2F6XMdQji86kbhbMqvg8Ui%2Fimage.png?alt=media\&token=c4c3a6fb-fdbf-456c-98fd-3530c7f1c6a6) ![](https://3323346004-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FW4eajJmOk3q8BX2WzhCG%2Fuploads%2Fw4psNK8FHvlOa7AypEEH%2Fimage.png?alt=media\&token=3bd1f6d6-4057-448f-9343-d42037f0aca0) Flat : No radius, no border, no shadow. Flat Rounded : Radius, no border, no shadow. Bordered : Radius, Borders, No shadow. Elevation S : Radius, Borders, Shadow, Padding Elevation M : Radius, Borders, Shadow, Padding Elevation L : Radius, Borders, Shadow, Padding #### Empty Group We have an additional group style name ⊝Empty which have no appearance attribute. This style is used mainly for group used purely as container with no design attributes. # Inputs All inputs elements are using two different styles in openBuild : Standard or Transparent. ### Standard Standard input style are used for full input elements, and consist in a bordered input field used in combination with input label and optionnally input helper.
### Transparent Transparent input styles are used when custom input need to be created. They consist in a full transparent / borderless styles.
# Buttons Buttons styles are organized around size and appearance.
# Style Variations Coming soon with Extension # Changing styles Coming soon! # Custom CSS This CSS is added via openBuild Toolkit plugin which links to CDN containing the file. You can download the plugin for free [here](https://bubble.io/plugin/openbuild-toolkit-1652100141816x544111532603605000) or adding it via plugin marketplace.
``` ``` # Pages # index Landing page
# base-menu
# base-top
# base-ribbon
# base-mobile
# admin
# verify
# styleguide
# terms
# login # reset\_pw
# privacy
# 404
# Menu Depending of chosen page template you get access to following menus:

base-menu

base-top

base-ribbon

# Base Layouts openBuild template comes with 2 page layout starter : base - left & base - top #### Base - Left This page layout consists of a content area with sections surrounded by a left Ribbon menu. The left menu become invisible on tablet (screen width < 1024 px) and it's replaced by a header with a hamburger menu. This layout is recommended as a starting point for SPA. #### Base - Top This pages layout consists of a content area with sections along with a header menu. The navigations items are replaced by a hamburger menu on tablet (screen width < 1024 px) . This layout is recommended either for SPA or website. # Getting Started Throughout the editor you will find references to openBuild documentation, that you will help you understand how we work.

Example: Send Email Instructions

Example: Element Display Instructions

# Navigation How your users move around your app openBuild uses 4 different ways of navigation: * [Go to page action](#go-to-page) * [Navigation through custom states](#navigation-through-custom-states) * [Navigation through URL parameters](#navigation-through-url-parameters) * [Navigation through URL parameters and w/ Option sets](#navigation-through-url-parameters-and-w-nav-pages-option-set) (recommended) Depending on your use case it might make sense to use all of these in your app. # Go to page The simplest for of navigating This is the most straightforward navigational action. Simply define the destination page in the action and whenever a button or link is clicked with this workflow, the user is directed to this page.
# Navigation through custom states Perfect for sub-navigating tabs or menus on your page You can use custom states to navigate between tab menus for example. It's a perfect use case for simple sub-navigation in your groups. When a tab is clicked, you can set a custom state of 'show' to the parent section or group. This 'show' is simply a text field. A custom state is arbitrary data that you can load into a page or element and use without having to store it in the database.

Setting a value to the 'show' state

Conditional on the UI element. The element is invisible on page load by default.

Here is a simplified diagram of what we're trying to accomplish. Let's say we have 3 tabs: Account, Billing, and Notifications. Each time we click any of the tabs we set the custom state to the tab we clicked (eg. Account). Each of the 3 tabs have a group with all the content inside. These are all hidden by default and have a condition that looks at the custom state. When the custom state corresponds with one of the hidden groups, it shows. ![The navigation through custom states workflow explained](https://lh3.googleusercontent.com/buz-I_Wow8f6kKSTV_QZFX3hY2FHOeWs2qwGr0C6EWYEa_LaoaNCDXs3mkuVA0YpPg5Tdc4nizWg4PBRFvqnDgAzeSF9DE_SfBSdS_Kb_itf6zoj_bqr4qkbpTiJbnXmVuXvFwGFjwM) # Navigation through URL parameters Keep your navigation history A more advanced way of navigating is to use URL parameters. These have two distinct advantages over custom states: a) when you use url parameters, you still navigate by the URL even if you do not seem to leave the page. This means you build up a breadcrumb trail and can go back and forth in the browser to go to a previous page. B) you can append parameters to your URL's that can interact with your page as you navigate. You can add a URL parameter in a link in your emails to navigate to the right section of your page for example. In general passing data along in URL parameters is a common practice and very versatile.

Set type of content for the section as 'text' and type in the text you want to refer to when navigating

Section is invisible by default

We are referring the URL parameter to make the right section visible

Navigation action can refer to the text on the ❖ Section Users we set. The workflow will look like this:
Additionally, you can use extra parameters such as 'tab' to create a sub-navigation. Or UID if you are working with data (read more about this in [this section](/working-with-the-framework/data-and-workflows/crud)). You can also use more advanced practice such as using Option set to navigate. You can read about it in the [next section](/working-with-the-framework/navigation/navigation-through-url-parameters-with-option-sets). # Navigation through URL parameters with Option sets A scalable way to handle navigation ### 🧭 Navigation - Option Set Using the option set to navigate between pages and sections will help you build faster, avoid bugs and keep your app structure consistent. It also opens up a lot of possibilities around advanced navigation options such as in onboarding pages or more complex forms. It is our preferred means of navigation, especially in single-page apps. By default, all [pages](/core-concepts/pages) across the template contain a [Source Popup](/working-with-the-framework/data-and-workflows/source-popup) in which you will find a 🧭 Source - Navigation group. It is connected to the 🧭 Navigation option set.

🧭 Navigation Option set

The simple structure contains two attributes: a) section and b) tab. The option has to at least have a Section filled for it to work properly.

Example 🧭 Navigation Option set - Admin/Section A

Inside the 🧭 Source - Navigation group you find the following logic implemented: ***If this 🧭 Navigation option's section matches the 'section' value that you we get from URL parameters and if this 🧭 Navigation option's tab matches the 'tab' value that we get from the URL then pick this Option.*** Note that if for example, the 'tab' URL parameter is empty it will still match with an option that has the 'tab' attribute empty. You can see the logic implemented in the image below:

Filtering logic implemented

The section's conditional in referring to the 🧭 Source - Navigation Group 🧭 Navigation

{% hint style="warning" %} Having two 🧭 Navigation options using the same 'section' and 'tab' values will create a conflict since the logic defaults to picking the first option that matches the criteria. If you have to use the same attribute values for the same 🧭 Navigation option (for example for different pages), you may want to create a new additional attribute called 'page' and add it to the filtering criteria. {% endhint %} ### 🧭 NAVIGATION - Custom Event On every page you will find a 🧭 NAVIGATION Custom Event. The when triggering this event you need to pass at least 🧭 Navigation option from the option set. {% hint style="info" %} For information on the basics of working with Custom Events in Bubble.io, refer to the official [documentation](https://manual.bubble.io/core-resources/actions/custom#custom-event-1). {% endhint %}

Notice that UID is optional

Because we use option set Bubble allows us to pick the option from the list when triggering this event.
In the Custom Event you will find a 'Go to page' action that will always send 3 parameters to the page. * section * tab * UID - only used when navigating to a section or tab which requires data source. Read more about use of UID in the URL structure in [this section](https://openbuild.gitbook.io/manual/working-with-the-framework/data-and-workflows/source-popup). All these parameters work automatically with [Source Popup](/working-with-the-framework/data-and-workflows/source-popup) allowing you for seamless transitions between sections and at the same time displaying the data that you need.
Multiple subsections If your section structure has multiple subsections you have to remember that their parent section e.g *Details C* does not exist on its own. In other words at least one of the subsections has to always be visible. That's why the conditional on the Section itself will contain the logic to make this section visible if 🧭 Source - Navigation 🧭 Navigation option is 'tab a', 'tab b' or 'tab c' You can find the following logic implemented in the admin page under *Details C* section in the openBuild template.

Section with Tabs

### 🧭 Element Display Since navigating in the reusable elements is a bit different, in the template you will find a dedicated Option set specifically to use for Reusable elements, such as example CRUD Popup, CRUD Floating, Settings, and User Access Management.
Using the 🧭 Element Display option follows the same logic as using [`🧭 Navigation to navigate the pages`](/working-with-the-framework/navigation/navigation-through-url-parameters). By default, the groups we want to navigate between are hidden. 🧭 Element Display option set has only two fields: display and text. The 'text' field is used in an action that gets triggered on page load (see explanation below).
For example, in the 👥 USER ACCESS MANAGEMENT reusable, the login section is visible by default. Adding the 'type=signup' parameter in the URL structure will change the section to the one that text matches the option set, in the case of 'signup' value it is going to be a signup section. You can see above that Option set 'Access - Signup' have 'signup' as 'text' field value. 👥 USER ACCESS MANAGEMENT reusable comes with a pre-build 'page is loaded' workflow. It triggers a custom event which then changes the section depending on if the URL key 'type' is not empty and there is an Option set that matches the 'text' field value.
{% hint style="warning" %} Keep in mind that like with 🧭 Navigation logic, this action picks the first item from the list. If you have more than one Option having the same 'text' field value it will pick the first one on the list. If you find that limiting you can always add an additional attribute e.g. page and add it as an additional filter so you can use multiple Option using the same value. {% endhint %} We set that state on the top parent element. In our example its 👥 USER ACCESS MANAGEMENT. Here you can also set which section should be visible by default by changing the 'Default value' field.
The sections follow the basic conditional logic of being shown/ hidden depending the on the state of the Reusable.

Referring to the 🧭 Element Display state.

Additionally, the 👥 USER ACCESS MANAGEMENT contains the 💡 CHANGE SECTION custom event which you pick the section you want to navigate to within that element

Because we use option set as a parameter you can pick the section you want to navigate to.

# Data & Workflows Everything your app revolves around openBuild uses 5 concepts around data manipulation. * [Custom states](/working-with-the-framework/data-and-workflows/custom-states) - learn how to store data temporarily on a page. * [Custom events](/working-with-the-framework/data-and-workflows/custom-events) - learn why we recommend using custom events. * [Source Popup](/working-with-the-framework/data-and-workflows/source-popup) - learn how we centralize data management on a page. * [CRUD](/working-with-the-framework/data-and-workflows/crud) - learn how to work smart and communicate with reusable elements. * [Backend Workflows](/working-with-the-framework/data-and-workflows/backend-workflows) - why & when you should use them. # Custom States A custom state is an arbitrary container capable of holding any type of data (single or list) that is readily available to the user in the current browser session. {% hint style="warning" %} It doesn't matter where you create the custom state (or how), as long as you keep in mind that when you add it inside a cell of a repeating group or inside a reusable element, you cannot access it through a normal 'set state' action. {% endhint %} Custom states have two major use cases: * Storing temporary data on the page * Navigation {% hint style="danger" %} Remember Custom states will not store the data you have saved if you reload the page. {% endhint %} ### Storing data on your page temporarily In the example below, based on the pre-build admin page that you will find in the template, we want to select multiple users in a list and perform a bulk action on those selected users.
When the user clicks the checkbox for selecting a user in the table, we add this user to our custom state list of users which we created previously.

We selected 3 users from the table. All of them are added to the Custom state list.

We can then send the list of users from the ⚡️selectedUsers to the backend workflows to delete them. {% hint style="warning" %} Make sure that the custom state is of the type you want to work with and the 'is a list' checkbox is checked. {% endhint %}

Using list & states in action

### Working with pre-loaded data If you work with set of data that has be pre-loaded on a page it's better to use Repeating Group element rather than a custom state as a list. For example imaging we have a field called ' Permissions' on the User data type. If you would like to display list of Permission on page load for that User via state would have to set that values on the page load since you cannot set default values of a state if it's a list or custom datatype. If you have more then one custom state list or custom state field where data needs to always be available on page load, the 'Page is loaded' can quickly become bulky with 'Set state' action, especially if you have multiple elements where you want to set the state.

Setting default state on page load

It's much better to work with repeating groups when it comes to lists. On the page load, you do not have to worry about setting the state of the list as it will automatically pre-populate since it's a repeating group. You can structure your repeating groups in the [Source popup](/working-with-the-framework/data-and-workflows/source-popup) or use the Repeating group in which you display the data.

Repeating group storing permissions of the User

Additionally manipulating the list in the Repeating group is as easy as manipulating the custom state with the 'Display list in a repeating group' action. # Custom Events From the Bubble manual: > *Custom events are a way to define a workflow in your page that can be reused multiple times ("functions" in a code-driven language).* You will find multiple uses of custom events in the template.

Dedicated custom events for sending emails. You will find these in 👥 USER ACCESS MANAGEMENT reusable.

Read more about the basics of Custom events in [Bubble manual](https://manual.bubble.io/help-guides/building-workflows/using-custom-events). Advanced practices of using Custom events are based on the connection between Custom events and Reusable elements (you can read about the basics of Reusable elements in [Bubble manual](https://manual.bubble.io/help-guides/structuring-an-application/reusable-elements)) Reusable elements can be used as sections with UI's or just workflows (no UI). A great use case for creating reusable with only workflows in it is for example integrating payments in your app. Workflows created in one place could be then reused on multiple pages throughout your app. {% hint style="info" %} We are heavy proponents of Custom events as we try to avoid duplicate work as much as we can. Custom events are a great tool to keep your workflows lean, your debugging time short and your teammates happy. {% endhint %} Read how we use custom events and reusable elements together [in this section](/working-with-the-framework/data-and-workflows/crud). ### Workflow execution rules Bubble actions do NOT run sequentially. Most of the time actions will not be completed in the same order as they are triggered. In the example below you cannot be sure that every time you run this workflow step 3 will be executed after step 1 and step 5 will always be before step 2 etc. The execution order is dependent on the type of action of client-side criteria (e.g. the newly created object needs to be displayed immediately on the page etc.)

Example

There are two ways you can force Bubble to run your actions sequentially: a) Use 'Result from Step X' in your conditional logic. For example 'Result of step 1 unique id is not empty' b) use Custom Events. In the example below Bubble will first trigger Custom Event A meaning all actions inside the Custom Event will be run *before* triggering Custom Event B.
From [Bubble manual](https://manual.bubble.io/help-guides/building-workflows/using-custom-events#execution-of-a-custom-event): > *When a workflow is triggered in Run-mode and hits a trigger a custom event action, the first workflow will pause, the custom event will be run till completion, and the first workflow will resume. Using the debugger can be very helpful to understand the flow of actions if you are hitting some difficulties setting things up* Learn more about order of execution from this Bubble video: {% embed url="" %} # Working with Reusables ### Communicating with reusable elements This explanation is based on pre-built workflows in the openBuild template. In 🍿CRUD FLOATING GROUP and 🍿CRUD POPUP reusable elements you will find a pre-built 💡SHOW POPUP workflow. The workflow consists of 2 actions: 1. setting states on the reusable itself and 2. showing the reusable. When triggering this Custom event we are required to always pass the 🧭 Element Display parameter (which is based on the option set) and User datatype. The second parameter is optional since we don't always need to manipulate the User object. When you will add additional parameters to this Custom Event, most of the time all of them (except the Nav Reusables) should be marked optional.

Notice that only 🧭Nav Reusable parameter is required

The passed parameters are set as a state on the reusable so we can act based on the information provided. When we place a reusable element on the page or inside another reusable element we do get access to an action called *Trigger a custom event from a reusable element.*
In our case, we are clicking RG User Row which contains information about the User datatype. When clicked we want to trigger the 💡SHOW POPUP workflow from the reusable and the information we need to manipulate the object.

We want to show CRUD User section so we pass 'CRUD - User' from Nav reusables Option Set

When triggering 💡SHOW POPUP we are required to pass the right 🧭 Element Display option set to display the right section. Since we want to display the user details section we are passing the 'CRUD - User' parameter. The visibility of the CRUD - User section in 🍿CRUD Floating is based on conditional logic.

When conditional is true, the CRUD - User section will be visible

User details section inside the 🍿CRUD Floating

The state 'show' on the 🍿 CRUD Floating Group is an option set type '🧭 Nav Reusables'

The elements inside the CRUD - User section are referring to the main datapoint which in this case is 🍿CRUD FLOATING GROUP User - the top-level datapoint in the Reusable which values we set with '💡SHOW POPUP' custom event. ### How to add a new group in the reusable element #### 1. Add a new option to 🧭 Element Display option set
#### 2. Copy or add a new group section In the template, you will find 3 template sections inside the 🍿 CRUD Popup and 🍿CRUD FLOATING GROUP. These are: a) CRUD Template b) MSG Template c) MSG Template Icon You can duplicate those or you different section with workflows already connected (e.g. CRUD User). #### 3. Set or update conditional on the newly created section
{% hint style="warning" %} Remember that all sections inside the reusable should not be visible by default! {% endhint %} #### 4. Make sure to use the new option when triggering 💡SHOW POPUP custom event

Trigger a custom event from reusable and pick your newly created option

# CRUD ### Create, Read, Update and Delete CRUD is the acronym for CREATE, READ, UPDATE and DELETE. These terms describe the four essential operations for creating and managing persistent data elements. Custom events are great for repetitive tasks. When you allow users to edit a Thing in multiple places on a page, you can add a 'make a change to' workflow each time you want to save this data. You can imagine that managing multiple workflows could result in errors or, at best, a lot of duplicate work.
Alternatively, you can create a Custom Event. It is a generic workflow that can be triggered or scheduled and use any type of data or no type of data at all.

We are sending the User object that we want to update to the Custom event.

Instead of having multiple 'make changes to Thing' workflows, you just create one and it's triggered by a custom event.

A custom event that updates a User

In this Custom Event we make changes to the User (we pass the user to the custom event and it will be accessible as the 'User'), but we can also use it to reset the form and trigger a Toast notification or edit the User in another way.

Make changes to thing is placed inside Custom event

Inside the update action, we refer to the inputs where we define that values. Note that we have the ability to define multiple parameters when triggering the Custom event and it means that you don't always have to refer to input but you could also refer to data that you send via Custom event. See the example below:

Here the suspended value could be also a dynamic variable. This is just for example purposes.

Example of passing additional value

You should also use this custom event when you create a new Thing. You create the Thing in step 1 and send it to the Custom event in step 2:

Create a User and save all the fields in the custom event.

{% hint style="info" %} This principle applies to all data types and not just only to the User data type. {% endhint %} # Source Popup Declutter your data sources To centralize the management of data points in your app, we default to using a Source Popup. A singular reference point for your data sources. By default, all [pages](/core-concepts/pages) have this popup. ![](https://3323346004-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FW4eajJmOk3q8BX2WzhCG%2Fuploads%2FoLHnbq3e1H6dhSCrLhhT%2FFDB99BAD-97E8-4C7A-8CE9-0596F32D3B52.png?alt=media\&token=1d652fb7-d60a-4f34-a2da-7a4f9479845c) Group naming should follow: 🚩 Source - \[object]. If you want to read more how we name elements read [this article](/working-with-the-framework/best-practices/syntax). Because we follow the convention of using UID in the URL, we can reuse the same parameter as a different source for different data types. For example, by selecting type Customer in the 'Get from Page URL action, the UID will be recognized as a Customer data type.

By selecting type Customer, the UID will be recognized as a Customer data type.

Now the same uid text is a Product

Then when loading the User details section we can refer directly to the source. Thanks to the used icon and naming convention, it creates nice visual consistency in the editor's UI, especially when used in workflows and conditionals.
{% hint style="warning" %} When working with single-page apps, a good practice is to add the 'Reset data' action when navigating to reset the section that displays the data. Bubble sometimes does not overwrite the inputs and group values correctly with new data, especially when new data contains some empty field values which can create bugs when saving the object. {% endhint %} # Backend Workflows All workflows that do not run on the page Backend workflows are workflows executed on the server side of your application. In principle, the heavy actions that run on the backend should be at least a couple of times faster because they are use server resources and not the client. And because they are run server-side they will use your app's available capacity. Rule of thumb: you should use backend workflows for data changes that require substantial resource availability like the creation of dozens and dozens of database things, making changes to the lists or the result of the change or creation of the object does not have to be immediately visible to the user. When you create or update a thing on the client side, Bubble is smart enough to display the change first for the User and then make changes to the database behind the scenes. Because of that sometimes it makes sense to build a workflow specifically for client-side as it will provide better UX (changes will be visible faster for the User). For example: adding an item to a shopping cart, or adding 3 newly created items to the list. Other advanced use cases are for example exposing your endpoints to communicate with 3rd party solutions via webhooks integration. Read more about server-side actions in the [Bubble manual](https://manual.bubble.io/help-guides/the-bubble-api): * [Database triggers](https://manual.bubble.io/core-resources/events/trigger-event#trigger-event) * [Data API](https://manual.bubble.io/core-resources/api/data-api) * [Recurring events](https://manual.bubble.io/help-guides/the-bubble-api/scheduled-workflows#set-up-a-recurring-event) Read about how to secure your backend [in this section](/working-with-the-framework/security-and-privacy/authenticating-endpoints). # Users and Roles openBuild adds a few fields to the default User data type.

User datatype

These are: * avatar - by default pre-built pages and elements use this field to display User avatar * firstName - user first name * lastName - user last name * fullName - useful in workflows. Remember to update the field whenever firstName or lastName changes. You can either do this manually or create a database trigger * phone - user phone number * userType - it's a field linked to the [User Type](/framework-elements/option-sets) option set. Read about the rules around creating syntax for fields and elements [in this section](/working-with-the-framework/best-practices/syntax).

By default template comes with two option's available

User Types are used to create security rules around users accessing data and pages. For example only admin users (i.e. User's with User type of Admin) should have access to the admin page or see certain data. {% hint style="warning" %} Remember that if you do not see the data on the page it does not mean it's not accessible to 3rd parties in some other way. Read more about security [in this section](/working-with-the-framework/security-and-privacy). {% endhint %} In the framework, you will also find that we use the User type option set in [Security Reusable](/framework-elements/security-redirect). # Signup, Login, Password reset The keys to your castle The openBuild framework comes with a reusable that handles Sign up, Log in, Reset passwords and much more. The resauble is used on the login page and reset\_pw page in the framework. ### Signup Sign up with email workflows and UI for social logins.

Signup section

Workflows connected to Signup section are in the 'Signup' folder.
By default, the new user has to accept the *Terms and Conditions* and *Privacy policy* to be able to signup. That's why we use the conditionals logic on the button and pre-built workflows for changing the state.

Only when the T&C is accepted, the workflow runs

Signup workflow triggers a SIGN-UP custom event, that depending on your app settings will trigger a confirmation email sequence or not. Read about it in [this section](#enabling-email-validation-workflows).
### Login

Login section

Two main events connected to the login section are: a) 'Log the user in' action - that gets triggered directly on the button click. It is placed there to enable the user to submit the login when hitting 'enter', b) 'LOG IN' custom event - by default, only the redirect action is placed in this custom event, but this is the Workflow where additional actions should be placed. The same custom event is used for 3rd party signup/login.

Actions run when btn.login is clicked

'LOG IN' Custom event

### Forgot password In the reusable, there is a dedicated section with workflows connected to password reset.

Forgot password section

When a user inputs their email we send it to a custom event called '📧 SEND RESET PASSWORD EMAIL'
In the custom event there are 3 actions: a) Send password reset email - native Bubble action to generate reset password token b) Send Email - Reset Password Link - a standard email with information about how to reset your password and dedicated link c) Send Email - Activation Link - from the [admin panel](/core-concepts/pages/admin) you are able to send user invites to the new users. The email content of that invite is different than a standard Reset Password email.

📧 SEND RESET PASSWORD EMAIL

Section visible after successful submission of the 'Forgot password?' form.

Check your email section

After clicking the link in the email user will be redirected to the Reset password section.

Reset password section

### Password strength checker

Want a password strength bar or checkbox details?

In the framework, you will find two versions of the password strength checker i.e progress bar or displaying password details. Both of them work independently so you can choose one that matches your app, or you can keep using both. ### Login with magic link

Login with magic link section

Same as with the Reset Password workflows, there is a dedicated Custom event to handle the actions connected to sending the user magic link via email.

Creating the magic link

Sending the link via email

### Invalid password token Currently, the reset password activation token is only active for 24 hours from the creation date. This time window is definitely restrictive so we handle invalid tokens via a better User Experience. In openBuild we take advantage of the error-handling feature that allows us to trigger an action whenever the User tries to use an expired token. By default whenever a user requests a reset password token via the User Access Management reusable we create a link that contains his email in the URL. If you did send your user a reset password email without the email parameter, the pre-built workflow logic will also handle that user.

Catching the Invalid token error

If the is not email parameter this section will be visible

If the is an email in the URL parameter it will automatically send the a new reset password / activation email

### Email validation workflows openBuild template comes with pre-build validation workflows. To enable them set the verifyEmail attribute in 🔒 System option set to 'yes'.
If you enabled the email verification workflows, after the Signup we trigger CONFIRM-EMAIL custom event.

Sending confirmation email

Redirecting to verify page

In the verify page you find two sections.
{% hint style="warning" %} Remember to correctly connect redirect workflows to your app pages. {% endhint %} Additionally in the [🔐 SECURITY REDIRECT](/framework-elements/security-redirect) you find a disabled workflow that needs enabling if you want to block access to the app for every user who does not have his/her email verified.
## User Access Management in a popup # Security & Privacy ### Password policy Bubble allows you to set up a password policy for user sign up. Stick to password best practices and force your users to create a secure password. The [User Access Management ](/framework-elements/user-access-management)element has a password validation workflows so users understand if their password is secure enough. ### Limit access to your app with a password By default, Bubble requires a username and password to preview the development version of your app. It's a good practise to create a secure username and password during the development of your application. When someone knows the Bubble app name of the application you are developing, he or she can access the development version as you are building you app. You would want to avoid this for obvious reasons. ### Redirect rules You may want to limit access to certain app pages for specific users or user roles. By setting up a [User Role](/working-with-the-framework/users-and-roles) on your users you can create workflows on your pages to redirect users away from that page. You can also use the 'user is logged in' or 'not logged in' expression to prevent users from accessing pages or content they should not have access to. As the page can load data for a brief moment the user navigates to it, you can add additional security on your content groups, unhiding it for certain users. There is a dedicated reusable element (Security Redirect) to handle redirects, you can read more about it [in this section](/framework-elements/security-redirect). ## Workflow API When you use API/backend workflows, the endpoints you create can be accessed publicly unless you specify otherwise. #### Expose as public endpoint When an outside service needs access to your application, check this box. Otherwise the endpoint will never be visible from outside your application. If you create an API workflow for internal use only, you can uncheck this box. #### Run without authentication Your app has a private key that you can use to sign API requests. If you want a service or user to run the workflow without authentication (non-logged in), check this box. If you need to expose your public endpoint there are multiple ways you can secure it. Read more about how to authenticate your endpoints[ in this section.](/working-with-the-framework/security-and-privacy/authenticating-endpoints) #### Ignore privacy rules If you want the workflow to run as an 'Admin' user, having access to all data, check this box. Be very careful with this checkbox as it could potentially allow outside services access to running workflows that could potentially harm your application. ## Privacy Rules #### Privacy rules basics: * View all fields: If unchecked User will not be able to read/display the field in UI and in workflows. * Find this in searches: Limitation applies to do a search for repeating groups but if you use single Unique Id e.g. when displaying Product details then he will be able to access that data (only when he can view those fields) * Exposing data without having privacy rules setup will allow 3rd parties to easily access data. * Authenticating webhooks: see article → API's endpoints Authentication #### Advanced: * If element referring to the data point is not rendered on the page data is not loaded on the page. The exception of this rule is loading data in repeating groups - even if the data is not displayed in repeating group, it is loaded on the page. Keep this in mind when creating privacy rules. * As we do work a lot with repeating groups keep in mind that Privacy rules can break the ‘auto-refreshing’ of data on the page. * For example: If you give access to data type on page load, the page needs to be refreshed for Bubble to fetch the data again, now under different privacy rules. * Also Privacy rules block access from accessing that data, but they sometimes show empty cells in repeating group etc. Best practice is to setup searches with constraints and privacy rules at the same time. ### File security If you store files with sensitive information - you need to attach the images to datatypes for best file security. From Bubble manual: * *This option is only visible if 'Make this file private' is selected. Private files uploaded with this element are permanently attached to a thing, which is used to determine who has access to view the file. Only users who have the 'View attached files' permission for that thing can view the file. Go to the Privacy section to create privacy rules that grant this permission. If the value of 'Attach this file to' is empty or the thing does not exist, the file will be visible to anyone who has the link, which is the same as if 'Make this file private' was not selected* Files that are not attached to an object and exposed long enough will be vulnerable to a data breach. # Authenticating endpoints Authenticating endpoints is a secure way to run workflows as admin of the app. Workflows will not get initiated if they are not authenticated.
### Method 1: Include the Authorization header in the call. a) Generate a token in settings b) Include the header 'Authorization' in your call. Use 'Bearer' + TOKEN as the value.
### Method 2: URL parameter If you are working with 3rd party API's and you are not able to add Custom header, include 'api\_token' parameter in the URL when making the call. ``` POST: https://app.bubbleapps.io/version-[env]/api/1.1/wf/create?api_token=TOKEN ``` ### Method 3: Act on behalf of a API User a) Create API endpoint that contains Log in action as a workflow (Have user created within your app or you can have a signup workflow before login action to create a new user)
* Setting the field “Stay logged in” to ‘yes’ will give you token valid 365 days. * Setting the field “Stay logged in” to ‘no’ will give you token valid 24 hours. b) Initiate the endpoint via Postman or API connector. The response of the api will look like this: ``` { "status": "success", "response": { "token": "1646485307119x480839771339487600", // API TOKEN Generated "user_id": "1646485006806x789796348942187500", "expires": 31536000 // valid 365 days } } ``` In the response, you will get an API Token (valid 365 days) that will allow you to create an endpoint with the 'require authentication' option set to run the workflow, but all subsequent actions will have access to the data as that User and Privacy Rules set to that User (e.g. you can set a special Privacy Role set to that only API User, etc.) \ c) see Method 1 or Method 2 to authenticate the endpoint.
# Transactional Email Send beautiful branded emails from your app 🤩 openBuild allows you to create beautifully styled and versatile emails, managed through the Mail Management reusable and sent with Postmark or Sendgrid. You can put the 📧 MAIL MANAGEMENT reusable on any page. By default it is part of the Admin page. {% embed url="" %}

You can put the MAIL MANAGEMENT reusable anywhere you want in your app

By default openBuild comes with 4 default emails that you can change to your liking. * User email invite * Magic link login * Activation email * Reset password

Four default emails that you can edit, clone or delete

## Creating and using transactional email There are 4 steps to creating and sending an email ### 1. Set up your transactional email provider openBuild supports [Postmark](/working-with-the-framework/transactional-email/setup-postmark) and [Sendgrid](/working-with-the-framework/transactional-email/setup-sendgrid) but you can use many others. ### 2. Create your email Create your email with a name and all the fields you want to add. Add dynamic content with the {{var}} notation. For adding a user’s first name you could use {{var1}}. For other dynamic data you use {{var2}} etc. Use the Var list field in each email to make a note of which {{varX}} belongs to what dynamic data.

Create your email in the email builder and see a live preview.

### 3. Test your email (optionally) Instead of having to invoke the workflow that needs to send this email, you can test it in the Send Email tab. Note that it will not send dynamic data.

Test your email with a sender address you validated with your email provider.

### 4. Send your email from a workflow with variables Go to the workflow that should send the email and add the following action: Schedule API workflow. Select Send email and enter all the data to send. To select the right email, go to your mail management and find the email in the list. Click the copy button to copy the ID. In your action, for the email field, Do a Search for Emails with a constraint of unique ID is the copied UID of the email to send. For dynamic content use the Var list and check the email var list to understand what dynamic data is var 1, var 2 etc. Run the workflow to test if your email was sent successfully with the correct data.

Create a workflow to send your email

Simply schedule the API Workflow 'Send Email' with the parameters you need to send your email.

## Anatomy of 📧 MAIL MANAGEMENT The 📧 MAIL MANAGEMENT module consists of: #### **Reusable** **📧 MAIL MANAGEMENT** - with all the screens and workflows to create and update transactional emails. #### Data Types Email - the Data type that stores your emails. It contains the actual escaped HTML used to send the email as well as all the other fields that (could) make up your email like headers, body, images etc. Email Footer Link - when you want to create footer links for your emails (and select which ones you want to add to which emails) you create an Email Footer Link in the Mail Management module. It is stored in the database as this data type. Email Template - all the HTML and escaped HTML required to display your emails as previews in the mail management module and required to assemble your own unique emails. You would not need to touch this unless you want to change your email template. **Workflows & Actions** 📧Send Email API Workflow Sendgrid - Send Email - for sending Sengrid emails Postmark - Send Email - for sending Postmark emails {% hint style="info" %} You can delete either the Postmark or Sendgrid action if you do not use them or add a condition to not run it (eg. 'When current date/time is empty'.) {% endhint %} ## Sending custom emails You can send your own custom html emails as long as you escape the html. 1. Escape your HTML (for example using ) 2. Create a new Email data type in the bubble editor. 3. Give it at least a name and paste the escaped html in the html field 4. If you want to use dynamic content, make sure to add your {{var1}}, {{var2}} etc. in your escaped HTML 5. Use the email the same way as the other emails for sending. # Setup Sendgrid {% hint style="warning" %} If you verify only a single sender in Sendgrid, you can only send from that email address. Other email addresses will not be accepted unless you verify your domain. {% endhint %} Go to sendgrid.com and register for a free account. Then, navigate to Settings > API Keys and Create a new API Key.

Create an API Key with the settings you need. Full Access is usually enough.

Then, back in your Bubble editor, navigate to Plugins > API Connector > Sendgrid and enter the API key you just generated in the Authorization header. Make sure it's preceded by 'Bearer'.
# Setup Postmark {% hint style="warning" %} Remember to confirm at least one Sender Signature inside the Postmark console. Only that email will work for sending emails. Or verify your entire domain. {% endhint %} Once you signup for the Postmark service pick the server you are going to use:

By default it's going to be 'My first server'

Once in the right Server space go to API tokens and copy the Server API token and past it into the API call:

The API Key

Paste inside the API connector in your Bubble editor

# Alerts and Confirmations ### Toasts {% hint style="warning" %} This documentation is based on openToast plugin. Read more about it [here](https://bubble.io/plugin/opentoast-1583999894901x139148699044937730). {% endhint %} In all pages and reusable elements, you find a Custom event called 🔔 TOAST. When triggering it there are two required parameters to fill: a) Message - this is the text that you want to display to a user. b) Toast Category - this parameter is linked to the 🔔 Toast Categories option set. By default, you can pick Error, Success, or Info as the type oftoast. Read more about this option set [here](/framework-elements/option-sets#toast-category).

Required parameters

Toast action

You can easily customize the toast by adjusting the settings on the action.

Default look for the different toast types

{% hint style="info" %} You might consider using the App text for storing the contents of the messages for easier management. Read more about App text in [Bubble manual](https://manual.bubble.io/help-guides/customizing-an-application/language-and-app-communications). {% endhint %} ### Confirmation popup For longer or more complex messages it's better to use a dedicated section inside a popup. Following our principles of using reusable elements, creating a confirmation popup to message the user is very easy. Read how to add new section in 🍿 CRUD POPUP REUSABLE [in this section](/working-with-the-framework/data-and-workflows/working-with-reusables#step-by-step-how-to-add-a-new-group). # Customization Basic configuration of the template (outside the styles) is done by managing two options sets 🎨 UI Colors and 🔒 System. ### 🎨 UI Colors All 9 options are connected to elements used all over the app and also components from the openBuild extension.

UI Colors option set

### 🔒 System In this option set you will basic app settings and as well branding options connected to images used throughout the app. (Such as header logos, logo's in email, etc.)
# Best Practices Some tips from the experts Here are our best suggestions on how to work within the Bubble editor. * [Syntax](/working-with-the-framework/best-practices/syntax) - learn how to name database fields, elements, backend workflows * [Color coding](/working-with-the-framework/best-practices/color-coding) - learn how to keep your workflow tab clean so you can work efficiently # Syntax ### Database We recommend the [Camel case](https://en.wikipedia.org/wiki/Camel_case) naming convention when it comes to naming database fields. > Camel case is the practice of writing phrases without spaces or punctuation, indicating the separation of words with a single capitalized letter, and the first word starting with either case e.g. firstName, lastName, fullDescription. When linking to other data types follow the upper camel case method which uses an initial uppercase letter e.g. when the User have a field linking to a company data type: Company. Following this convention you will know that fields starting with uppercase are linked to other data types and those starting out with lowercase letters are fields saved directly on the data type (such as text, numbers, and dates). Linking field to option sets should start with lowercase.

User datatype

### Inputs All inputs elements should follow this syntax: `object.input-type.field e.g.` [`user.input.email`](http://user.input.email) `should be used to modify the User’s email.` Thanks to this convention searching for the right input will be fast and easy, as you will have multiple points of reference to the input and they are distinguished enough visually to locate them in the conditional dropdowns and field searches. ![](https://3323346004-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FW4eajJmOk3q8BX2WzhCG%2Fuploads%2FvK9vywMOATipwSnTfmFI%2F0CF784BC-6ED4-4A90-85C3-7CC81DA1497F.png?alt=media\&token=52c6b182-0473-4764-96c4-cab8403afb93) ### Elements When building in the app logic most of the time we heavily really on referring to elements that store values. {% hint style="info" %} Read how to centralize the data management on a page in [this section](/working-with-the-framework/data-and-workflows/source-popup). {% endhint %} Ideally, the naming convention makes things easier for the developer to build fast and the most important factor enabling that is searching for the elements from the workflows tab: Conditional dropdown: * When using a group as a data source its best to keep the same naming conventions for all of the source groups and as well using visual cues that will help us find and locate it faster: * Source: e.g. 🚩 Source - Property

Texts and inputs referring the 🚩 Source - User

Actionable elements such as buttons, icons, texts, link and other group elements follow this convention: *\[elementType].\[actionType]* e.g btn.createUser, icon.toggleMenu, group.closePopup {% hint style="info" %} Tip: Best to rename things as you go, doing it all at the end of the build is not efficient in our experience. {% endhint %} ### States: States should follow the same naming convention as database fields. We recommend using Icon indication to see its representation in actions ⚡️ e.g. ⚡️Product. The icon will act as another visual cue that will help you distinguish between custom states and other input types.

Setting state

Referring to states in searches

### Custom events: For better organization and reading experience, we recommend naming all custom events workflows with capitalized letters and icons, which play a supporting role in distinguishing between different types of custom events.

ustom events among other workflows

### API Workflows Endpoints naming convention should use a dash when using multiple keywords: * e.g. send-email vs sendemail General tips: * Avoid using jargon e.g. email-update vs ems * No abridging e.g. phone-update vs tel-no {% hint style="info" %} There are exceptions to this rule which is making the API endpoint public. You might consider making the endpoint more cryptic especially if you are not using authentication. (See can read about webhook authentication [in this section](/working-with-the-framework/security-and-privacy/authenticating-endpoints)) {% endhint %} ### Workflows Try to be descriptive when renaming your actions or workflows. * Make a change to the Current User -> Update Current User Personal Data * Scheduled API workflow -> API: Send Invite Email * Make changes to thing... -> Add new Project to Company # Color Coding This is how we currently take advantage of color coding of the workflows: * Brown - workflows that are pre-built in the template. Any added workflows that are working and in live. * Red - modified but not finished workflows that need follow-on work * Cyan - modified or newly added workflows that are finished and tested. When pushing live we keep the Cyan color for newly added workflows. After deploying we change these to brown only in the development version. Now live version contains Cyan & Brown workflows and we know that Cyan workflows are workflows that were just pushed live. That makes debugging a bit easier as you can see which workflows were changed compared to the previous live version. # Chrome Extension In progress! # Menus ### ⇥ Popup Mobile Menu. Admin page and all page templates come with a pre-build ⇥ Popup Mobile Menu.

⇥ Popup Mobile Menu

### 🔄 CONTEXT MENU In the User table on the Admin page you will find an example of using 🔄 CONTEXT MENU reusable element.

🔄 CONTEXT MENU

### Pages Per [page](/core-concepts/pages) template you get access to the following menus:​

base-menu

base-top

base-ribbon

# Option sets A list of all the option sets we use in openBuild (and why) ### 🔒 System Main option set to manage your app-related assets and content like the app name or logo. Read more about it [in this section](/working-with-the-framework/customization#system). ### 🔔 Toast Category Option set listing the type of Toast Messages. These are linked to the [Tag Colors](#tag-colors) option set. This option set is used for Alerts and linked to a Custom Event called 🔔 Toast used throughout the app. Read how it works in [this section](/working-with-the-framework/alerts-and-confirmations).
### 🎨 UI Colors UI Colors option set is used on top of the Styles in the app.

UI Colors display. Find yours on /styleguide page

### 📱Viewport The viewport option set is used throughout the app to give you granular controls on your responsive design. ### User Types Using a predefined user type will help you in setting permission rules as opposed to using a simple text field that is error-prone. By default you find two options in the User Types option set: * Admin - administrator of the app. This type has access to the admin page. * User - normal app user. You can add as many User types as you want, but it's good practice to keep the list simple. If you need more flexible way to control what User can see and do, you might consider creating a Permission option set. ### Tag Colors Tag Colors can be used by directly referring to it from the editor or it can also be used by linking it to a database field.

TAG Colors table. See it on /styleguide page in the template

### 🧭 Navigation Using an option set together with Custom events will allow you to build faster and reduce the number of bugs when working with Single Page Apps and cross-page navigation. It also opens up more advanced possibilities such as creating complex onboarding experiences. Read how to use it in [this section.](/working-with-the-framework/navigation) ### 🧭 Element display This option set is dedicated to creating navigation in elements that can be used throughout multiple pages. It is used mainly in combination with reusable elements such as [🍿`CRUD Popup`](/framework-elements/crud-popup) or [👥 User Access Management](/framework-elements/user-access-management). Read more about how to use it in [this section](/working-with-the-framework/navigation/navigation-through-custom-states). # Plugins A list of plugins openBuild uses by default Two plugins are required when it comes to combining the template with the openBuild extension. These are: * openBuild CSS - this plugin adds a header linking to a CSS stylesheet which is compatible with openBuild template. See the CSS included [here](/core-concepts/styles/custom-css). * [Heroicons](https://bubble.io/plugin/heroicons-1662714551448x987904425844277200) - an Icon set from the Heroicons library. {% hint style="danger" %} Working with the openBuild components library without these plugins installed in your app might create issues. {% endhint %} #### Other plugins: * [Air Color Picker](https://bubble.io/plugin/air-color-picker-1498952719168x889602776416649200) * [API Connector](https://manual.bubble.io/core-resources/bubble-made-plugins/api-connector) * [OpenBuild Toolkit](https://bubble.io/plugin/openbuild-toolkit-1652100141816x544111532603605000) * Google * Google Material Icons * [Ionic Elements](https://manual.bubble.io/core-resources/bubble-made-plugins/ionic-elements) * [openToast](https://bubble.io/plugin/opentoast-1583999894901x139148699044937730) * LinkedIn * Multiselect Dropdown * Progress Bar * [Toolbox](https://bubble.io/plugin/toolbox-1488796042609x768734193128308700) # API Connector API Connector is a plugin made by Bubble allowing you to connect to any 3rd party API giving you access to tens of thousands external solutions. Read more about the basics of using API connector in [Bubble manual](https://manual.bubble.io/core-resources/bubble-made-plugins/api-connector). When it comes to the template, by default, you find pre-built API calls such as: * Sendgrid - Send Email - basic POST call for sending emails with Sendgrid. It also works with attachments. Learn how to work email work with openBuild template[ in this section](/working-with-the-framework/transactional-email). (See Sendgrid documentation [here](https://docs.sendgrid.com/api-reference/mail-send/mail-send)) * Postmark - see documentation [here](https://postmarkapp.com/developer/user-guide/send-email-with-api). * Send Email * Send Email (with Attachment) Check our extensive API calls library in openBuild. # User Access Management How users signup and login to your app All users accessing the app, either through signup or login are managed through a single element reusable called [👥 USER ACCESS MANAGEMENT.](/working-with-the-framework/signup-login-password-reset) Its composes of the different pre-built and ready to use sections such as: * Login * Signup * Magic link * Forgot password * Reset Password with password validation * Activate account * Reset success * Link expired * Check your email You can read about different sections and workflows [in this section](/working-with-the-framework/signup-login-password-reset). # CRUD Floating Group 🍿 CRUD FLOATING GROUP is a reusable element used for CrateReadUupdateDelete (CRUD) operations. By default, its width is limited to 480px. But you can change the max width of the reusable by changing the max width of the element inside the element or on the page itself. Read more about responsive design in [this section](/core-concepts/responsive-design).

🍿 CRUD FLOATING GROUP in action

It comes with 2 template sections that can be copied and used to create new ones. These are:

CRUD Template

MSG Template Icon

CRUD Popup contains 1 pre-build and working section:

CRUD User

### Data manipulation and navigation CRUD popup follows the framework practices like navigating with option sets and manipulating data using states. If you want to learn more about passing data into reusables and navigating to different sections you can read about it in [this section.](/working-with-the-framework/data-and-workflows/crud) # CRUD Popup 🍿 CRUD POPUP is a reusable element dedicated to performing CRUD operations and as well confirmation actions. By default, its width is limited to 480px. If you want to read about the UI Framework, read [`this section`](/core-concepts/responsive-design). It comes with 3 template sections that can be copied and reused to create new ones. These are:

CRUD Template

MSG Template Icon

MSG Template

CRUD Popup contains 2 pre-build and working sections:

CRUD User

CRUD Delete - Users

### Data manipulation and navigation CRUD popup follows the framework practices like navigating with option sets and manipulating data using states. If you want to learn more about passing data into reusables and navigating to different sections you can read about it in [this section.](/working-with-the-framework/data-and-workflows/crud) # Data Table ### Table Properties of the base table: * Fully responsive * Build-in 'Name' & 'Joned' field sorting * [Pagination](#pagination) * Multiselect - you can read more about how to store data temporarily on the page work in [this section.](/working-with-the-framework/data-and-workflows/custom-states)

User data table in admin panel

### Pagination The user table used on the Admin page in the openBuild template comes with a pre-built Repeating group pagination.

Pagination is limited to display up to 5 pages in current view

{% hint style="warning" %} the Toolbox plugin is required for the pagination to work {% endhint %} You can edit the number of rows displayed and the pagination bar will update automatically. There is no need to update workflows or other element's values. For pagination to work correctly you have to update the number of rows in the Repeating Group and as well the state of the repeating group called "rows".
{% hint style="danger" %} If the number of 'rows' state will be different than the number of rows in the repeating group, pagination will NOT work correctly. {% endhint %} #### Copying and pasting the workflows to new repeating group If you already have a Repeating Group and are in need of pagination you can copy the 'Pagination' element with workflows.

Pagination group

You will then need to update all elements that are placed within the Fields group. These are 5 Group elements that hold numeric values which are used to calculate pagination.

Example of Group holding numeric value

Additionally, there are 5 action elements that will need to update as well. With the distinction that you only need to pick the right Repeating Group from the list of elements

Example action that will need to be updated

You will find example of action in folder 'Pagination: Users' in the admin page

# Security Redirect Keep unwanted users out Security Redirect is reusable that is used to centralize access to your app pages. It contains only workflows used to redirect users to other pages based on conditional rules. A logged out user or a regular user visiting the admin page? The Security Redirect has a workflow to navigate them away from the page. We put that reusable conveniently in the [Source Popup](/working-with-the-framework/data-and-workflows/source-popup) in every page to keep it from cluttering. {% hint style="warning" %} Remember that just redirecting the user from the page that he should not access is not enough to make your app secure. Make sure to always set the privacy rules on data that is sensitive. Check if your app is secure via [checkSo](https://check.tinkso.com). {% endhint %} The easiest way to set up redirect workflows in complex apps is by separating the workflows by pages and then putting extra conditional logic onto the actions themselves.

Example of redirect the user if he is not an Admin user

# Mail management ⚡️ Superfast email builder We have implemented a dedicated page or section within the admin panel specifically for handling transactional email templates. This user-friendly interface enables users to effortlessly create and manage various email templates as needed. Additionally, you can customize these templates by incorporating dynamic variables, resulting in personalized that meets your specific requirements. This dedicated solution streamlines the process of creating, editing, and managing transactional email templates for a more efficient workflow. ### Email providers openBuild Framework integrates with Postmark and Sendgrid. It uses the openBuild Framework default email template but can just as well be used with any other HTML email template. ### Mail Management Section The interface and workflows you need to list your stored emails, edit those emails and add new ones, and as well test send them.

Manage all app emails

Build and edit your emails

Send test emails

### Dynamic Content Sending emails from your application typically requires incorporating dynamic content, such as a customized greeting, password reset links, or other personalized elements. We achieve this through a 'variable' (or 'vars') system. A variable serves as a placeholder for any type of text, such as a name, a URL, or a reset password token. When constructing your email, you can insert variables anywhere using the format {{varX}}, where 'X' represents the variable number. An email might have only one variable or multiple variables, like 10 or more. There will also be a section for defining variables as you create your email, which ensures that everybody understands the intended content when using this email, stored in your app's database. For example, '{{var1}}' might represent a user's first name in one email, while in another, it could be a URL. The variable placeholders remain consistent across all emails, but you determine the specific content for each variable when scheduling your email send events. This approach ensures clarity and personalization in your email communication. ### Escaped vs html Each email template comes in two versions: 'escaped' and 'html'. We need to escape special characters to prevent issues when sending emails via Postmark or Sendgrid's APIs. In the option set containing the Email templates, there are two fields for each template section: 1. The original HTML version, used for previewing the email in the mail management page. 2. The escaped HTML version, required for actually sending the emails. This setup ensures smooth interaction with email delivery APIs and allows you to preview your email templates accurately. ### Using your own templates To escape your own HTML template, use this free tool: ### Email Templates This data type will be used to retrieve the default email template or a custom email template you created. It consists of all the sections that make up the email in two versions: escaped and plain html.

Email Template

### Email Data Type This datatype stores all your emails, including welcome emails, password reset emails, and others. We have included some example templates which can be found under the App Data tab in the Bubble editor.

Email Datatype

### Send Email Action When creating a new email using the mail management tool, it will be saved in your database as an 'Email' datatype. To send an email, you will need to provide the Unique ID (UID) of the email template you want to send within the 'Send email' action. Additionally, you should include any dynamic content that you want to incorporate into the email. This approach allows for efficient organization and customization of your email templates.

Send Magic Link Example

### The Standard Template openBuild Framework offers one, flexible, transactional email template that you can use for basically every email you need to send.

Standard email template with show/hide section

### System Option Set (optional) The openBuild Framework employs a 'System Option Set' to store information about the app, such as the app name, default color, app email, and logo. While you are not required to use the information from this option set, it's important to consider the formats of the images you wish to display in your email. For instance, if you want to display a logo or any other image in your email, refrain from using the SVG format, as most email clients do not support it. Instead, opt for image formats like JPG or PNG to ensure proper display across various email clients. ### Email Footer Links This datatype allows you to manage the footer links you wish to include in your app. Each entry consists of a display name and an associated link. By default, the following links are provided: 1. Privacy - a link to the privacy policy page 2. Terms - a link to the terms and conditions page Feel free to add any number of additional links, and they will be automatically incorporated into your email footer. This versatile option set makes customizing your email footer easy and straightforward.

Email Footer Link Datatype

### Send Email Workflow The send email workflow is composed of two distinct actions: 1. On the client side, a backend workflow is scheduled, which determines when the email will be sent. 2. The actual email-sending action is then triggered by this scheduled backend workflow. This structure enables you to schedule emails conveniently and effortlessly include variable content within the messages.

Scheduling Backend Workflow

You will find 📧 Send Email API workflow in Backend workflows. This is the actual POST API call that will send the email via Sendgrid.

Actual Send Email Action

### Using emails in live version of the app After creating and testing your emails in the development version, make use of the [Copy and Restore Database](https://manual.bubble.io/core-resources/bubbles-interface/data-tab#copy-and-restore-database) feature. This allows Bubble to transfer development data into live data, maintaining the same unique ID for your emails in both versions. As a result, you won't have to manage two distinct workflows since the email record will retain the same unique ID. {% hint style="info" %} Make sure you only copy the Email data type. {% endhint %}
# User Settings The framework comes with a pre-built User Profile section with working credentials update section.

Account

Credentials

Updating your password

Updating your email

# Header & Footer ### 🔄 HEADER In the template, you will find a reusable element 🔄 HEADER, which is dedicated to website pages such us landing pages, faq, about us, team, terms, and privacy.
The element is responsive and comes with a Popup Mobile Menu.

Mobile Popup Menu

### 🔄 FOOTERS openBuild has two reusable footers that you can edit to your liking.

Dark

Light