Skip to content

Commit ab17a54

Browse files
info-bitbybit-devinfo-bitbybit-dev
authored
Merge pull request #100 from bitbybit-dev/develop
DXF Generator, updates to points of interest and dimensions
2 parents 120eceb + e7f000b commit ab17a54

File tree

187 files changed

+5761
-2113
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

187 files changed

+5761
-2113
lines changed

‎docs/blog/2024-11-08-updated-bitbybit-runners.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -121,7 +121,7 @@ We are serving the Bitbybit Runners from the **JSDelivr CDN**. You can include t
121121
<script src="https://cdn.jsdelivr.net/gh/bitbybit-dev/bitbybit-assets@<version-number-of-bitbybit>/runner/bitbybit-runner-lite-threejs.js"></script>
122122
```
123123

124-
**Note:** You should replace `<version-number-of-bitbybit>` with an actual version number (e.g., `0.20.8`). You can find all the official versions of Bitbybit.dev here:
124+
**Note:** You should replace `<version-number-of-bitbybit>` with an actual version number (e.g., `0.20.9`). You can find all the official versions of Bitbybit.dev here:
125125
➡️ **[Bitbybit.dev GitHub Releases](https://github.com/bitbybit-dev/bitbybit/releases)**
126126

127127
### Examples of the Runners

‎docs/learn/3d-bits/for-developers/_category_.json‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
{
2+
"label": "For Developers",
3+
"position": 8,
4+
"link": {
5+
"type": "generated-index",
6+
"title": "For Developers",
7+
"description": "Learn about the integration best practices and implementation details for the 3D Bits Shopify App. This section is more technical and is meant mostly for developers of third party apps or custom UI solutions.",
8+
"slug": "/3d-bits/for-developers"
9+
}
10+
}

‎docs/learn/3d-bits/for-developers/integration.md‎

Lines changed: 296 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,296 @@
1+
---
2+
sidebar_position: 1
3+
title: "Integrating 3D Bits with Custom Forms"
4+
sidebar_label: Integration Best Practices
5+
description: Learn how to properly integrate 3D Bits with custom forms and third-party apps using standard HTML practices.
6+
tags: [shopify, 3d-bits]
7+
---
8+
import Admonition from '@theme/Admonition';
9+
10+
## Building Compatible Forms for 3D Bits Integration
11+
12+
When integrating 3D Bits with custom pricing apps or building your own product forms, the key to success lies in using proper HTML form elements. This tutorial will guide you through best practices that ensure your forms work seamlessly with 3D Bits while maintaining accessibility and usability for all users.
13+
14+
## Understanding the Integration Challenge
15+
16+
3D Bits specializes in creating powerful 3D configurators and immersive experiences for your products. While we excel at rendering and manipulating 3D geometry based on user selections, we intentionally don't provide custom UI building tools, pricing engines, or fancy form elements. Instead, we integrate with the solutions you're already using, whether that's third-party Shopify apps or custom-built forms.
17+
18+
The magic happens when 3D Bits automatically detects changes in your form inputs and updates the 3D model accordingly. However, this automatic detection only works when your forms follow standard HTML practices.
19+
20+
## Why Standard HTML Elements Matter
21+
22+
When you use proper HTML form elements with correct attributes, you're not just making your forms compatible with 3D Bits – you're creating an inclusive experience for all users. Standard form elements provide built-in keyboard navigation, screen reader compatibility, and semantic meaning that assistive technologies can understand.
23+
24+
Consider the difference between these two approaches:
25+
26+
### ❌ Poor Practice - Custom Div Elements
27+
```html
28+
<!-- This won't work with 3D Bits and breaks accessibility -->
29+
<div class="custom-option" onclick="selectColor('red')" data-value="red">
30+
<img src="red-swatch.jpg" alt="Red color">
31+
<span>Red</span>
32+
</div>
33+
<div class="custom-option" onclick="selectColor('blue')" data-value="blue">
34+
<img src="blue-swatch.jpg" alt="Blue color">
35+
<span>Blue</span>
36+
</div>
37+
```
38+
39+
### ✅ Good Practice - Standard Radio Buttons
40+
```html
41+
<!-- This works perfectly with 3D Bits and is accessible -->
42+
<fieldset>
43+
<legend>Choose Color</legend>
44+
<label>
45+
<input type="radio" name="color" value="red" checked />
46+
<img src="red-swatch.jpg" alt="Red color option" />
47+
Red
48+
</label>
49+
<label>
50+
<input type="radio" name="color" value="blue" />
51+
<img src="blue-swatch.jpg" alt="Blue color option" />
52+
Blue
53+
</label>
54+
</fieldset>
55+
```
56+
57+
## Essential HTML Patterns for 3D Bits
58+
59+
### Radio Buttons for Single Selections
60+
61+
When users need to choose one option from multiple choices (like material, color, or size), radio buttons are your best friend. The `name` attribute groups related options together, while the `value` attribute tells 3D Bits which option is selected.
62+
63+
```html
64+
<fieldset>
65+
<legend>Material Selection</legend>
66+
<label>
67+
<input type="radio" name="material" value="wood" checked />
68+
Natural Wood
69+
</label>
70+
<label>
71+
<input type="radio" name="material" value="metal" />
72+
Brushed Steel
73+
</label>
74+
<label>
75+
<input type="radio" name="material" value="plastic" />
76+
Recycled Plastic
77+
</label>
78+
</fieldset>
79+
```
80+
81+
### Checkboxes for Multiple Selections
82+
83+
For features that can be independently enabled or disabled (like add-ons or accessories), checkboxes provide the perfect solution. The `value` attribute determines what gets sent to 3D Bits when the checkbox is checked, while the `checked` attribute sets the initial state.
84+
85+
```html
86+
<fieldset>
87+
<legend>Additional Features</legend>
88+
<label>
89+
<input type="checkbox" name="led_lighting" value="enabled" checked />
90+
LED Lighting System
91+
</label>
92+
<label>
93+
<input type="checkbox" name="wireless_charging" value="enabled" />
94+
Wireless Charging Pad
95+
</label>
96+
<label>
97+
<input type="checkbox" name="premium_finish" value="enabled" />
98+
Premium Finish Coating
99+
</label>
100+
</fieldset>
101+
```
102+
103+
<Admonition type="info" title="Checkbox Values Explained">
104+
- **`value="enabled"`**: When checked, 3D Bits receives "enabled" as the value
105+
- **`checked`**: Makes the checkbox selected by default when the page loads
106+
- When unchecked, no value is sent (which 3D Bits interprets as the feature being disabled)
107+
</Admonition>
108+
109+
Alternatively, you might want to use boolean values or specific identifiers:
110+
111+
```html
112+
<fieldset>
113+
<legend>Optional Accessories</legend>
114+
<label>
115+
<input type="checkbox" name="leather_seats" value="leather" />
116+
Leather Seats
117+
</label>
118+
<label>
119+
<input type="checkbox" name="sunroof" value="panoramic" />
120+
Panoramic Sunroof
121+
</label>
122+
</fieldset>
123+
```
124+
125+
### Select Dropdowns for Space-Efficient Options
126+
127+
When you have many options but limited screen space, select elements provide a clean, accessible solution.
128+
129+
```html
130+
<label for="size-selector">Product Size</label>
131+
<select name="size" id="size-selector">
132+
<option value="small">Small (10cm)</option>
133+
<option value="medium" selected>Medium (15cm)</option>
134+
<option value="large">Large (20cm)</option>
135+
<option value="extra-large">Extra Large (25cm)</option>
136+
</select>
137+
```
138+
139+
### Range Inputs for Continuous Values
140+
141+
For dimensions, quantities, or other numeric values that users can adjust within a range, the range input provides an intuitive interface.
142+
143+
```html
144+
<label for="height-slider">Height: <span id="height-value">50</span>cm</label>
145+
<input
146+
type="range"
147+
name="height"
148+
id="height-slider"
149+
min="30"
150+
max="100"
151+
value="50"
152+
oninput="document.getElementById('height-value').textContent = this.value" />
153+
```
154+
155+
### Number Inputs for Precise Values
156+
157+
When users need to enter specific numeric values, number inputs provide validation and appropriate keyboard interfaces on mobile devices.
158+
159+
```html
160+
<label for="quantity">Quantity</label>
161+
<input
162+
type="number"
163+
name="quantity"
164+
id="quantity"
165+
min="1"
166+
max="100"
167+
value="1" />
168+
```
169+
170+
## Critical Attributes for Success
171+
172+
The `name` attribute is absolutely crucial for 3D Bits integration. This attribute identifies which form field controls which aspect of your 3D model. Make sure your `name` attributes are:
173+
174+
- **Descriptive**: Use names like `material`, `color`, or `size` rather than generic names like `option1` or `field2`
175+
- **Consistent**: If you have multiple products, use the same naming convention across all forms
176+
- **Unique**: Each form control should have a unique name within its form context
177+
178+
<Admonition type="warning" title="Avoid Duplicate Input Names">
179+
If you have multiple inputs with the same `name` attribute on the same page, 3D Bits may have difficulty determining which one to monitor. When this happens, 3D Bits will automatically add suffixes to distinguish between them, which can make your configuration more complex and harder to maintain. Always ensure input names are unique across your entire page.
180+
</Admonition>
181+
182+
For example, avoid patterns like this:
183+
184+
```html
185+
<!-- DON'T DO THIS - Duplicate names cause confusion -->
186+
<div class="product-1">
187+
<input type="radio" name="color" value="red" />
188+
<input type="radio" name="color" value="blue" />
189+
</div>
190+
<div class="product-2">
191+
<input type="radio" name="color" value="red" />
192+
<input type="radio" name="color" value="blue" />
193+
</div>
194+
```
195+
196+
Instead, use unique, descriptive names:
197+
198+
```html
199+
<!-- DO THIS - Unique names are clear and reliable -->
200+
<div class="product-1">
201+
<input type="radio" name="product1_color" value="red" />
202+
<input type="radio" name="product1_color" value="blue" />
203+
</div>
204+
<div class="product-2">
205+
<input type="radio" name="product2_color" value="red" />
206+
<input type="radio" name="product2_color" value="blue" />
207+
</div>
208+
```
209+
210+
<Admonition type="tip" title="Pro Tip">
211+
Always test your forms with keyboard navigation (Tab key) and screen readers to ensure they work for all users. If you can't navigate your form without a mouse, neither can users who rely on assistive technologies.
212+
</Admonition>
213+
214+
## What Breaks the Integration
215+
216+
Certain HTML patterns will prevent 3D Bits from detecting user selections and create barriers for users with disabilities:
217+
218+
### Custom Clickable Divs
219+
```html
220+
<!-- Don't do this -->
221+
<div class="option" onclick="changeOption('blue')">Blue Option</div>
222+
```
223+
224+
This approach fails because:
225+
- 3D Bits can't detect the selection change automatically
226+
- Screen readers don't announce it as a selectable option
227+
- Keyboard users can't navigate to it
228+
- The current selection state isn't communicated to assistive technologies
229+
230+
### Image-Only Selections Without Form Elements
231+
```html
232+
<!-- Don't do this -->
233+
<img src="option1.jpg" onclick="selectOption(1)" class="selectable">
234+
```
235+
236+
While visually appealing, this pattern excludes users who rely on keyboard navigation or screen readers.
237+
238+
### JavaScript-Dependent Custom Controls
239+
```html
240+
<!-- Don't do this -->
241+
<span class="custom-radio" data-value="option1">Custom Option</span>
242+
```
243+
244+
Custom controls that rely entirely on JavaScript event handling often lack the semantic meaning and keyboard accessibility of native form elements.
245+
246+
## Testing Your Integration
247+
248+
To ensure your forms work correctly with 3D Bits and remain accessible:
249+
250+
1. **Navigate with keyboard only**: Press Tab to move through all form elements. Every interactive element should be reachable and usable.
251+
252+
2. **Test with a screen reader**: Use built-in screen readers (like VoiceOver on macOS or NVDA on Windows) to verify that options are announced clearly.
253+
254+
3. **Verify 3D Bits integration**: Make selections in your form and confirm that the 3D model updates appropriately.
255+
256+
4. **Check on mobile devices**: Ensure form elements display and function correctly on touch interfaces.
257+
258+
## When Custom Solutions Are Necessary
259+
260+
<Admonition type="warning" title="Last Resort Only">
261+
The approach described below should only be used when you absolutely cannot achieve your design requirements with standard HTML form elements. This pattern introduces complexity and potential accessibility issues that you'll need to carefully manage.
262+
</Admonition>
263+
264+
Sometimes your business requirements demand custom UI elements that go beyond standard form controls. In these rare cases, you can still maintain compatibility with 3D Bits and accessibility by using hidden form elements that mirror your custom interface. However, this approach comes with significant drawbacks and should be avoided whenever possible.
265+
266+
This pattern is problematic because it duplicates functionality, increases maintenance complexity, and can easily fall out of sync between your visual interface and the hidden form elements. Additionally, users with disabilities may miss important visual cues that aren't properly communicated to assistive technologies.
267+
268+
```html
269+
<!-- Custom visual interface -->
270+
<div class="custom-color-picker">
271+
<div class="color-option red" onclick="selectColor('red')"></div>
272+
<div class="color-option blue" onclick="selectColor('blue')"></div>
273+
</div>
274+
275+
<!-- Hidden form element for 3D Bits integration - NOT RECOMMENDED -->
276+
<input type="hidden" name="color" id="selected-color" value="red" />
277+
278+
<script>
279+
function selectColor(color) {
280+
// Update visual state
281+
document.querySelectorAll('.color-option').forEach(el =>
282+
el.classList.remove('selected'));
283+
document.querySelector('.color-option.' + color).classList.add('selected');
284+
285+
// Update hidden form element for 3D Bits
286+
document.getElementById('selected-color').value = color;
287+
288+
// Trigger change event so 3D Bits can detect the update
289+
document.getElementById('selected-color').dispatchEvent(new Event('change'));
290+
}
291+
</script>
292+
```
293+
294+
Remember that this approach requires you to manually ensure that keyboard navigation works, screen readers can understand the interface, and the hidden form elements stay synchronized with your visual interface. Before implementing this pattern, seriously consider whether your design goals can be achieved by styling standard form elements instead.
295+
296+
By following these practices, you'll create forms that work seamlessly with 3D Bits while providing an excellent experience for all your users, regardless of how they interact with your website.

‎docs/learn/3d-bits/theme-app-extensions/bitbybit-viewer.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -110,7 +110,7 @@ Save your JSON configurator as a file, upload it to Shopify CDN as a file. Copy
110110

111111
While our Viewer Editor is the recommended way to create and manage the Scene Config JSON, you can also edit the JSON directly using any text editor. For a better editing experience with features like syntax highlighting and autocompletion (intellisense), we provide a JSON schema.
112112

113-
* **JSON Schema:** You can find the schema [here](https://ik.imagekit.io/bitbybit/app/assets/start/shopify/viewer-scene-config-schema-0-20-6.json). (Note: This schema link points to version `0.20.8`. The schema may be updated in the future, so ensure you refer to the latest version compatible with your "3D Bits" app version.)
113+
* **JSON Schema:** You can find the schema [here](https://ik.imagekit.io/bitbybit/app/assets/start/shopify/viewer-scene-config-schema-0-20-9.json). (Note: This schema link points to version `0.20.9`. The schema may be updated in the future, so ensure you refer to the latest version compatible with your "3D Bits" app version.)
114114
Many modern code editors (like VS Code) can use this schema to provide validation and autocompletion as you edit the JSON.
115115

116116
## Video Tutorial: BITBYBIT VIEWER Block Setup

‎docs/learn/3d-bits/tutorials/product-customizable-text.mdx‎

Lines changed: 1 addition & 1 deletion
Large diffs are not rendered by default.

0 commit comments

Comments
 (0)