Metablock
Metablock allows pro-code designers to leverage libraries to add their dynamic blocks in XMPro using script files.
We recommend leveraging generative AI to write the scripts. This approach can significantly streamline the development process and enhance the functionality of the blocks.
Only the Presentation File (HTML) is required. Utilize the other properties based on your specific needs for the Metablock behavior.
Metablock Properties
Behavior
Presentation File (HTML)
Upload the HTML script file that will be rendered in your Metablock, which is used to create dynamic blocks that may display data from a Data Source or from Value Mapping.
Alternatively, you can write your scripts in a single HTML file that includes both CSS and JavaScript. This approach is ideal for smaller applications.
Styling File (CSS)
If you wish to add styling, upload a CSS file to style your Metablock control.
Script File (JavaScript)
If you wish to run JavaScript, upload a JavaScript file for your Metablock. Place any initial/startup values as constants in this file.
Data Source
Common Properties
Common properties include: filter, sort, show # of results, and skip # of results;
See the Common Properties article for more details on common Data Source properties.
To use the Data Source property, include these predefined JavaScript functions in your Script File:
You can refer to a working example script that demonstrates an Autodesk Forge visualization here.
Value
Value Mapping
If you wish to define value mappings for run-time use, you can configure user-defined key-value pairs. These values remain static during application rendering.
The Value Mapping opens a new blade to setup the Key and Value configuration. The options for the Value Source are Static, Dynamic, Expression and Variables.
When selecting Server Variables as a Source for the Value Mapping, the list of unencrypted Server Variables will be displayed. Tick the Encrypt checkbox to use an encrypted Server Variable for values like keys, secrets, or password.
Encrypted Server Variables will not have their value available immediately on the Metablock. Instead, you can use them inside a Fetch/XHR request and then the request will be proxied automatically on the AD server to replace the actual value of the server variable before being forwarded to the actual request. You can use encrypted server variables as part of the URL, Header, or Body of the Fetch/XHR request.
Proxy Requests
Tick to proxy requests on the AD Server before being forwarded to the actual request. This is ticked by default when using an encrypted server variable on the value mapping, but you can opt in to use it even without any encrypted server variable.
To use Value Mapping, include this predefined JavaScript function in your Script File:
Note: The password property will not have the actual value yet when it is mapped from an Encrypted Server Variable. Instead, it is just a template for the Server Variable name.
Real World Use Cases
Enhancing Chart Display
Use Value Mapping to incorporate user input for displaying Harmonic Frequency, maintaining connector integrity while improving data visualization.
Streamlining Pump Status Display
Leverage Value Mapping to dynamically pass URLs from other data sources or utilize expressions, eliminating the need for manual URL adjustments during version updates.
Autodesk: visualize 2D & 3D models
Access and visualize your engineering data and designs from the cloud using Autodesk Platform Services (APS, formerly Forge).
Leverage Value Mapping when embedding the APS Viewer in XMPro App Pages to display interactive 2D and 3D views of your designs.
Note: This is a simple example to demonstrate the APS Viewer API using an unauthenticated repository. Refer to the authenticated use case for a more complex example that includes security measures for credentials.
Autodesk: Visualize 2D & 3D models with authentication
When authentication is needed to dynamically load 2D and 3D views of your designs using the APS Viewer. We could utilize a Connector or the Value Mapping and use server variables for the credentials. This eliminates the need for hardcoded credentials while maintaining secure access to the visualization platform, Autodesk Platform Services (APS, formerly Forge). See the following Metablock examples on how to use these methods.
Autodesk: Authentication using Connector
Leverage the REST API Connector to get Token from the authentication service and the Data Source to pass the token to the Metablock.
Autodesk: Authenticate using Value Mapping
Leverage the Value Mapping to pass an encrypted Server Variable to the Metablock and call the authentication service using a Fetch request to get the Token.
Creating a Metablock Script: Step-by-Step Guide
Step 1: Search for a code snippet
Find relevant sample, we search for sample Autodesk Forge code and found the following links:
Step 2: Writing your Metablock script
Adapt the sample code to the Metablock format. For simplicity, the HTML, CSS & JavaScript has been combined into a single file.
Step 3: Testing your code locally (Optional)
Test it locally before implementation by running it from another html file (test-harness.html) via a local webserver. A 3D interactive model of a house should load in your browser.
Create the
test-harness.html
file in the same directory as your Metablock files.
Run the
test-harness.html
in a webserver (node.js)Make sure you have Node.js installed on your computer. You can download it from https://nodejs.org/.
Open a terminal or command prompt and navigate to your project folder where the metablock files are.
Initialize a new Node.js project by running
npm init -y
Install Express by running
npm install express
Create
public
folder and moved yourHTML
,CSS
&JavaScript
files insideCreate a file named
server.js
copy and paste below code in
server.js
fileTo start the server, run
node server.js
Open a web browser and go to http://localhost:3000
Step 4: Configure the Metablock in App Designer
Drag the Metablock onto your page.
Open Block Properties.
Add the 3 Metablock files by clicking on the plus icon and uploading the
main.html
,main.css
,main.js
files and selecting each from their respective dropdown.Add a Value Mapping of key
model_url
and Valuehttps://developer-autodesk.github.io/translated-models/dwfx-sample-house/f0224dd3-8767-45c1-ff99-5c9c881b9fee/0.svf
Save the page
Launch the page
Example Files
Refer to the simple Autodesk use case for a complete set of files for this example.
Security Features
We have added security features in Metablock to safeguard the users from potential attacks, When developing applications, we have selectively enabled the following features:
Form Submission
Pop-up windows
Modal Dialogs
JavaScript Features
External Resources
Additionally, Metablock allows the use of specific hardware APIs for enhanced application capabilities, including camera, encrypted-media, full-screen, geo-location, speaker, accelerometer, gyroscope, magnetometer, and midi.
FAQs
Why did the JavaScript code in my Metablock not execute on page load?
Due to the timing of function instantiation, we recommend checking the document's ready state instead of relying on the load event:
Check document's ready state:
Alternatively use one of the existing functions.
Why is the Metablock throwing 500 errors related to styling and script files?
This can occur if your HTML file includes inline script import code. Remove explicit import statements for CSS and JavaScript, and use the dedicated script file configuration property.
How can I load multiple script files?
At present we only support configuration of a single HTML, CSS, and JavaScript file for each Metablock. To simulate multiple JavaScript files, you can dynamically load script from your JavaScript file.
See the Creating a Metablock Script: Step-by-Step Guide for an example on how this is done.
Last updated
Was this helpful?