Pages standards & best practices

Pages

Templates

A template is a predefined layout that can be used while creating a page. The available templates can be chosen when the builder is creating individual pages, for example, Register form, Login form, or Error pages. The builder can give the project a jumpstart by using templates.

All applications need to be provided with 404 and 500 error pages. In case of errors, these pages will be shown instead of the default error pages.

Components

You can check the size of your page by using the network tab provided by your browser when you hard refresh the page. We recommend handling a limit of 2.5 MB for your pages, this will allow the average user to load the page with decent speed whilst not making the pages too big for it to affect your SEO.

Of course building bigger is optional but keep in mind that for some users this might mean a less pleasant user experience.

Naming conventions

The platform gives the builder the freedom to name the page and create the path of the pages. It will help a builder (and other builders) when there is a consistent naming convention in the application.

Page name and URL paths

There are a lot of combinations possible for naming the page name and URL path, so make it evident that the page name and URL path leads to certain pages.

Rename components

When adding several Data Containers, Data lists, or input components, you soon lose track of where certain data comes from. Rename the component to make it evident what data is provided. Don’t change/delete the component type name though!

Examples:

• “Data Container” > “DataContainer - Webuser”

• “DataList” > “DataList - Tasks”

• “TextField” > “TextField - Name”

Actions

See the section actions for more information.

Custom styles

When creating a custom style (for example at a button), start the name with the color (Primary, Secondary, etc.) followed by the attribute (rounded, thin, etc.). Example: Primary rounded.

Partials

When creating a partial, use a descriptive name as a partial name (for example Header or Top menu).

Error pages

An error page should always exist to refer the user to when a page can’t be found or is not existing. The default error pages are the 404 and 403 pages. Both pages can be created from a default template.

After the error pages are created, the Not found page can be set in the Application settings.

Partials

The most common partials are the Header, Footer, Navbar, and Sidebar. Also, other parts of the page can be converted to a partial, so try to reuse it if that’s possible. Use input variables to make the partial more dynamic.

UX/UI

All pages should have a congruent look and feel. Apply the same styling on every single page of the application. Partials help you achieve this.

Standardized form

The forms can be used to create, update or delete records. This can be standardized by using the following rules.

• Placeholders
  Use placeholders in all input fields to make sure that an input field is never empty.

• Loading state when submitting
  Toggle the submit button to a loading state when the visitor submits the form. This prevents visitors from submitting the form multiple times.

• Hide all alerts when submitting
  It can be very confusing if an old success/error message is still visible when the visitor is submitting the form.

• Show the response
  Show an alert or snack bar at a success or error response. The success message can be fixed, the error message can be dynamically from the server.

• Clear all input fields
  When the form responds in success, all inputs in the form can be cleared or set to default. This step is irrelevant when a redirect will be done after a successful response.

• Refetch the data table
  ​When a table is present and a new record is created, the data table can be refetched so that the new record is immediately visible as a table row.

Colors

In the Theme builder, all types of colors can be set. Select the brand colors as primary and secondary colors and use these colors in the pages.

Dialog, drawer, and new page

It’s possible to use dialogs and drawers on a page to show data of a specific record or create/update a record. In the case of page limits, the advice is to split it up into new pages as much as possible.

Search Engine Optimization (SEO)

SEO stands for search engine optimization, which is a set of practices designed to improve the appearance and positioning of web pages in organic search results.

Especially when you’re creating a customer-facing application, it’s important that search engines are able to find the pages. Following the next technical rules help you achieve a better indexation. Which content to use is another topic and will not be handled in this document.

• Correct use of H1, H2,.. H6
  Compare each page to a book’s chapter. The H1 represents the chapter title, there should be only one per page. The H2 breaks the content up into sub-chapters. The H3-6 is used to further break up the content making it easily scannable.

• URL paths
  You can find information about this topic in the following article: Refer to naming conventions section.

• Images should have a proper Alt text
  Provide each image with an alternative text to improve SEO ranking.

• Reduce page size
  You can find information about this topic in the following article: Refer to page size.

• Use links for navigation instead of interactions
  Elements need to have an HREF to enable search engines to crawl them, so use refer to the page in the component settings instead of an interaction. If the application is using interactions to navigate to the next page, no HREF is added to the Anchor tag.

• Title, meta description, and favicon
  The title, meta description, and favicon should be present to assist search engines in understanding what the web page is all about. Its primary job is to guide the visitors and search engines on what to expect from the web page shortly and concisely.

• All pages should be reachable through the workflow of the app
  When a page is not reachable through the workflow of the app, it is not necessary for the application and can be removed. ‘Orphaned’ pages clutter the page builder and can end up being a security hazard.

Responsiveness

Responsiveness is the approach that suggests that design and development should respond to the user’s behavior and environment based on screen size, platform, and orientation. Keep in mind that the visitors of your application don’t always use a desktop, but may also visit the page using a mobile phone or tablet. For that reason, all pages should be responsive. Some tips can help you:

• Think vertically
  In other words: don’t make the pages too wide. You can force this by using a container.

• Fixed width columns
  Set a fixed width in the column of a data table so that a scroll bar will be shown when the data table is wider than the visitor’s screen.

• Hide components for small devices
  In some cases, it’s better to hide specific components on small devices (i.e. tablets and mobiles) when they are not necessary or when there is no space.

• Progressive Web App
  The best solution for tablets and mobiles is a Progressive Web App (PWA) to use as a native mobile application. PWA is still a website and it looks and feels like an app and includes push notifications and offline capabilities.

Actions

When a form has been dropped on the canvas, an action will be automatically created and assigned to the form. The naming convention of the actions can be categorized with the following prefix:

• Page builder actions start with [PB], for example [PB] Login webuser.

• Sub actions start with [SUB], for example [SUB] Create order line.

Interactions

Component interactions are interactions with a function between components based on a certain trigger.

Security

A developer should know how to set up a secure page. A page should apply to the following requirements.

Authentication profile

All pages that shouldn’t be publicly available, should have an authentication profile selected. This is the first line of defense when it comes to data security in the page builder. Not logged in? No show of the page.

By selecting an authentication profile on a page, this page is only accessible to authenticated web users. Not logged in? No show of the page and redirected to the login page.

All secured pages should check that the data should be visible to the logged in webuser. When a page is meant to be used for a webuser with a specific role or a set of roles, CHECK for it in the page and redirect when the webuser does not comply.

“Why? I do this with a menubar that doesn’t show the button so you can’t go to that page.”

A page is reachable through its URL so that way people can circumvent your ‘clever’ security solution.

Validations

Before submitting a form, do a frontend check on the input values when applicable, i.e: required field, min length, regex, etc. These checks can easily be manipulated by the page’s visitors, but help prevents posting invalid data. Use server-side conditions to further check the input.

When posting a form to the application or using a REST API, you often use a custom model. To increase security and prevent conflicts it’s advised to set server-side validations. This can be done by setting content types on custom models and data model properties and using the expression valid?(var:custom_model) in a condition.

Cross-Site Request Forgery (CSRF) is an attack that forces a(n) (end) user to execute unwanted actions on a web application in which they're currently authenticated. It is a type of malicious exploit of a website where unauthorized commands are transmitted from a user that the web application trusts. You should enable CSRF protection on every POST, PUT and DELETE endpoint. Do not disguise or mislabel those endpoints as GET endpoints.

Web users

Web users should be able to register for an account. The passwords must contain at least 8 characters, uppercase, and lowercase letters, numbers, and symbols

Furthermore, web users should be able to reset their passwords. The old passwords shouldn’t be reusable

When logging in, two-factor authentication is recommended. If there are too many failed login attempts, a webuser’s account should be blocked from logging in for at least 5 minutes.

Web users should be able to delete their accounts to comply with the GDPR. The developer needs to reflect on how this affects the webuser's created data.

Parameters

When using parameters, either path parameters or query parameters, always keep in mind that they can be manipulated through the URL. When retrieving data based on given parameters, always check whether the webuser is allowed to retrieve that data.

In some scenarios with sensitive data (like a password-forgotten page) it’s better to save a globally unique identifier (GUID) and use this as a parameter in the URL. A record ID can be guessed easier by changing the numeric value. GUIDs are written in the form of eight (hexadecimal) digits, then three times four digits, and finally another twelve digits, such as “3F2504E0-4F89-11D3-9A0C-0305E82C3301”. The chance of creating the same GUID twice is very small and it’s very difficult to guess by the visitor.

Roles & Rights

The role permissions at model level determine what a user (based on the given role) is authorized for and what not. It’s important that every role has the right permissions to create, read, update, delete, or export.

Others

• Delete/disable unused actions and endpoints

Every developer should at least disable, but preferably delete actions and pages that aren’t used by the application. If you leave them in the application, they pose a security risk. Besides that, it becomes unclear to fellow developers which endpoints and/or actions affect the application.

• Use the checkbox “Filter value from logs” for sensitive data

An endpoint (POST) can have incoming sensitive data like a password. This data can be hidden from the application logs when it’s a single input variable (no custom model) by checking the checkbox Filter value from logs.

Page limits

There’s a risk in making pages too big when you’re building in the page builder. You could see it as a car and its trailer. When you add too much stuff to the trailer, it might be hard getting from A to B. This also applies to pages. The bigger the page, the harder it is to manage them and the longer the page loading times are. Longer loading times mean a bigger risk of visitors dropping out or less building happiness. Choose the contents wisely, and don’t add an excessive number of components to keep good page loading times.

We advise you to keep the runtime pages below 2.5MB, depending on which components are used. You’re able to manage this by limiting the number of components you add to the page to about. The advice is to use maximum:

• 50 data tables components;

• 500 buttons components;

• 100 media components;

• 100 text components.

You can check the runtime page size by following the next step:

1. Open the pages overview

2. Open the developer tools in Chrome and check the tab Network. The advice is to check Disable cache at the top of the tab.

Split up pages

A builder of a page can be very optimistic by creating a lot of components and functionality in one page. The downside is that the maintenance of the page can be complex and there is a potential degradation of the performance. The solution is to split up the page when tabs, steppers, dialogs and/or drawers have been used. Instead of using a dialog and drawer on a page, a master-detail page can be created to show the data. In this way, the page size can be limited.

Custom components

When a custom component is needed on a page, the advice is to create a Github repo. Even when it’s a simple change, a Github repo containing the custom component can help you and your colleagues to find it at a later stage. This repo can be created in the Betty-Services GitHub organization.

Delete

Pages

A page can be assigned to different components (form > option Redirect after successful submit) or an interaction (redirect). When deleting a page, those dependencies aren’t linked anymore. The builder can check the dead ends by compiling one of the pages. An error will appear that shows the location of the error and the error text.

Components

Deleting a form means automatically that the generated action will also be deleted. Keep this in mind.

Actions

An action can have multiple dependencies. For that reason, check the dependencies before you delete them.