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:
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
These components are used to render the containers, tabs, widgets, and elements defined by the skeleton.
So far we have implemented two page templates. The template to be used can be configured using a property of the theme.
-
appshell(default): -
grid:- A simple grid layout without responsiveness.
- This template allows customization using the theme.
- Review the template code here.
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.
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
gquery string parameter)
- https://appbuilder.shapediver.com/v1/main/latest/?slug=240425-perforationswall-4
(notice that there is no
- Custom theme 1:
- Custom theme 2:
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/theme01.json
In a later release, we plan to implement a theme editor and to host the settings on the ShapeDiver platform.
The following query string parameters can be used to instruct the App Builder SPA which model to load:
See the following link for instructions on how to use this: https://www.shapediver.com/app/builder/v1/main/latest/
See the following link for instructions on how to use this: https://appbuilder.shapediver.com/v1/main/latest/
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: example02.json
- Using the settings file: https://appbuilder.shapediver.com/v1/main/latest/?g=example02.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.
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.
Install dependencies:
pnpm i
Start local development server:
pnpm 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.
We recommend using an IDE like Visual Studio Code.
Recommended extensions:
The code works using node.js 18 and 20.
pnpm build
Builds the app for production to the dist folder.
When developing using Chrome, the following browser extensions are useful:
- React Developer Tools
- Redux DevTools: allows to inspect the stores managed by zustand
To learn React, check out the React documentation.
This playlist contains some valuable tutorials about React, TypeScript, and Mantine.
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.
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.
This codebase is implemented using TypeScript. We use Vite as a build tool for fast development experience.
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.
We use the zustand state manager to provide the following stores:
This store is used to manage viewports and sessions of the ShapeDiver 3D viewer.
Interface: IShapeDiverStoreSession, Implementation: useShapeDiverStoreSession
Interface: IShapeDiverStoreViewport, Implementation: useShapeDiverStoreViewport
Related hooks:
Related components:
- ViewportComponent makes use of useViewport
- ViewPage creates a single session using useSession and uses a ViewportComponent
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.
This code is provided as is. We do not warrant it to be useful for any purpose.