ShapeDiver App Builder SDK

This repository contains the code of the single page application (SPA) which serves as the frontend of ShapeDiver App Builder.

Note

You can find the latest deployed version of this code here:

• Anonymous access (used for embedding of App Builder): https://appbuilder.shapediver.com/v1/main/latest/
• In-platform access (requires you to be logged in on the ShapeDiver platform): https://www.shapediver.com/app/builder/v1/main/latest/

Click one of these links to see instructions on how to load your model.

Specific versions of the App Builder can be accessed by replacing latest with a version string.

Example:

• https://appbuilder.shapediver.com/v1/main/0.3.0-beta.7/

What is App Builder ?

Read about ShapeDiver App Builder in our help center. This repository contains the App Builder Open-Source SDK. Building this code results in the single page application that renders the skeleton consisting of containers, tabs, widgets, and elements as explained here.

Highlights of the App Builder SDK:

• Extensive support for styling using themes
• Easy to be extended by further types of widgets etc
• Great starting point for custom web apps using ShapeDiver and React

Some hints about the code

App Builder React components

These components are used to render the containers, tabs, widgets, and elements defined by the skeleton.

App Builder page templates

So far we have implemented two page templates. The template to be used can be configured using a property of the theme.

• appshell (default):

  • This template is based on the AppShell component of Mantine (the components library used by this codebase, read more about it below).
  • The appshell template allows customization using the theme.
  • Review the template code here.

• grid:

  • A simple grid layout without responsiveness.
  • This template allows customization using the theme.
  • Review the template code here.

App Builder main page

The main page component serves as the root of all App Builder pages. It does this:

• Uses some custom hooks to resolve all the settings based on the query string.
• Opens a session with the ShapeDiver model to be used.
• Gets the JSON content of the data output called AppBuilder. This content represents the skeleton.
• Instantiates App Builder React components based on the skeleton.
• Uses the template selector to render the instantiated components using the selected page template.
• You can find the TypeScript type definition of the skeleton and the settings here. There are also validators for parsing these objects from JSON and validating them.

Themes

The useCustomTheme hook defines the default theme. Refer to the documentation of the Mantine theme object and the possibility to define default props for Mantine components to understand what can be customized (basically everything). The App Builder components make use of Mantine's useProps hook to plug into the theme, which means the behavior and styling of the App Builder components can be controlled by the theme as well.

There is no need to fork and adapt the code to customize the theme. You can store the theme properties in a settings file in JSON format, and instruct the App Builder SPA to use the settings from this file using the g query string parameter. Some examples:

• Default theme:
  • https://appbuilder.shapediver.com/v1/main/latest/?slug=240425-perforationswall-4 (notice that there is no g query string parameter)
• Custom theme 1:
  • https://appbuilder.shapediver.com/v1/main/latest/?slug=240425-perforationswall-4&g=customTheme1.json
  • customTheme1.json
• Custom theme 2:
  • https://appbuilder.shapediver.com/v1/main/latest/?slug=240425-perforationswall-4&g=customTheme2.json
  • customTheme2.json

Note that you can pass an absolute URL to the settings file when using the g query string parameter, i.e., you can host the settings file anywhere: https://appbuilder.shapediver.com/v1/main/latest/?slug=240425-perforationswall-4&g=https://appbuilder.shapediver.com/v1/main/latest/customTheme2.json

In a later release, we plan to implement a theme editor and to host the settings on the ShapeDiver platform.

How to reference models

The following query string parameters can be used to instruct the App Builder SPA which model to load:

Option 1: slug

See the following link for instructions on how to use this: https://www.shapediver.com/app/builder/v1/main/latest/

Option 2: ticket and modelViewUrl

See the following link for instructions on how to use this: https://appbuilder.shapediver.com/v1/main/latest/

Option 3: Referencing a settings file using g

You can use a settings file in JSON format to specify which model to load. This supports referencing the model using slug or using a ticket and modelViewUrl. The settings file can also include theme properties as explained above. Example:

• Settings file: perforationswall.json
• Using the settings file: https://appbuilder.shapediver.com/v1/main/latest/?g=perforationswall.json

As mentioned above, you can pass an absolute URL to the settings file when using the g query string parameter, i.e., you can host the settings file anywhere. Note that the slug (or ticket and modelViewUrl) defined directly in the settings file take precedence over the query string parameters.

How to implement new widgets and contribute

Feel free to fork from this repository in case you want to develop and deploy your own flavour of the App Builder SPA.

In case you want to extend App Builder by new widgets, these are your options:

• Option 1:
  • Fork this repository,
  • extend the skeleton type definition and the skeleton validator by your new widget properties (look for IAppBuilderWidget), and
  • implement them.
  • Plug your new widgets into AppBuilderWidgetsComponent. Then
  • build and deploy yourself, or
  • submit a pull request to this repository.
• Option 2: Create an issue and tell us about the widgets you would like to be included.
• Option 3: Ask us on the forum.

Getting started

Install dependencies:

npm i

Start local development server:

npm run start

This runs the app in development mode. Open http://127.0.0.1:3000 to view it in the browser. The page will re-render when you make edits. You will also see potential errors in the console.

Prerequisites

We recommend using an IDE like Visual Studio Code.

Recommended extensions:

• ESLint

The code works using node.js 18 and 20.

Further available scripts

npm run build

Builds the app for production to the dist folder.

Developer tools

When developing using Chrome, the following browser extensions are useful:

• React Developer Tools
• Redux DevTools: allows to inspect the stores managed by zustand

Learn More

To learn React, check out the React documentation.

This playlist contains some valuable tutorials about React, TypeScript, and Mantine.

• ShapeDiver Help Center
• ShapeDiver Forum

Some hints about ShapeDiver

The complete API documentation of the ShapeDiver 3D Viewer can be found here.

This example includes some tickets of ShapeDiver models for testing. You can author and upload your own Grasshopper models.

What else can this codebase do for me ?

Apart from the App Builder functionality, this repository contains useful React components and hooks for using the ShapeDiver 3D Viewer and the ShapeDiver Platform Backend. If you want to develop a web application using React and ShapeDiver, this is a great codebase to start from.

In case you want to contribute to this repository, feel free to fork it and open pull requests.

Dependencies and insights for developers

Basics

This codebase is implemented using TypeScript. We use Vite as a build tool for fast development experience.

UI Kit

This codebase uses the Mantine UI Kit. However, the code has been developed having reusability in mind, which means it will easily be possible to swap out the UI Kit.

State management

We use the zustand state manager to provide the following stores:

ShapeDiver session and viewport store

This store is used to manage viewports and sessions of the ShapeDiver 3D viewer.

Interface: IShapeDiverStoreViewer, Implementation: useShapeDiverStoreViewer

Related hooks:

• useViewport
• useSession
• useSessions

Related components:

• ViewportComponent makes use of useViewport
• ViewPage creates a single session using useSession and uses a ViewportComponent

Parameter and export store

This store provides a stateful abstraction of the parameter and export functionality offered by the ShapeDiver 3D Viewer.

Interface: IShapeDiverStoreParameters, Implementation: useShapeDiverStoreParameters

Related hooks:

• useSession
• useSessions
• useDefineGenericParameters
• useSessionPropsParameter
• useSessionPropsExport
• useParameter
• useExport
• useParameterComponentCommons
• useSortedParametersAndExports
• useParameterChanges

Related components:

• Parameter components Components for the most common parameter types supported by ShapeDiver, uses useParameterComponentCommons.
• ExportButtonComponent allows to trigger an export and makes use of useExport.
• ParametersAndExportsAccordionComponent implements an accordion of grouped parameter and export components.

Disclaimer

This code is provided as is. We do not warrant it to be useful for any purpose.