Embedding
Studio Web Component
Embed the Carbone Studio in your application
Integrate Carbone Studio directly into your application
From Carbone v5, the studio is a HTML Native Web component which can be integrated into any web application 🎉
From the software editor's perspective:
- Make all reports in your app customizable.
- Increase revenue potential by upselling access to this feature or offering personalized reports.
From the user's perspective:
- Enjoy a seamless experience by editing reports directly within the application.
- Automatically open the studio with user data as a sample.
- Add documentation to explain your data (coming soon).
From the developer's perspective:
- The studio is a customizable, lightweight HTML5 web component compatible with all front-end frameworks like Vue.js, React.js, Angular, and Riot.
- The studio requires only four endpoints to function.
Important notes and consideration during the beta phase:
- Do not use it for production: This beta version is intended for testing and feedback only.
- Potential Instability: It may contain bugs or incomplete features; we plan to release regular updates.
- Breaking Changes: Future updates may include breaking changes, so be prepared for possible API changes or deprecations.
1. Load the web component file
- Start Carbone On-Premise with
-s
option to start the studio. - Then, download the js from there with this URL http://localhost:4000/carbone-studio.js (More option with CDN will come soon)
- Include the JS file in your app:
<script src="/carbone-studio.js"></script>
<style>
carbone-studio {
height:100%;
width:100%;
}
</style>
2. Start the studio
// Instantiate the Web component
const studio = document.createElement('carbone-studio');
// Or insert `<carbone-studio></carbone-studio>` directly in the DOM.
// Add the studio component to the DOM
document.body.appendChild(studio);
// Configure the studio
studio.setConfig({
origin : 'https://api.carbone.io/', // Defaults to `window.location.origin`
token : '', // Provide a JWT Token if authentication is enabled on your On-premise instance
});
const templateFile = {
// The studio will automatically call `URL_ORIGIN/template/:templateId` to download the template
templateId : '424242424242424242424242424',
// Extension is used for the user interface and may change in the future
extension : 'docx'
};
// Pre-initialize the studio with data, language, etc.
const options = {
data : {},
complement : {},
enum : {},
translations : {},
lang : 'fr-fr', // Defaults to browser language
timezone : 'Europe/Paris', // Defaults to browser language
currencySource : 'EUR', // Defaults to browser language
currencyTarget : null
};
// Open the template in the studio
studio.openTemplate(templateFile, options);
URLs called by the studio:
POST /render
GET /render/:id
POST /template
GET /template/:idTemplate
More options for request hooks are coming soon; we look forward to your feedback!
3. Listen events
studio.addEventListener('connected');
studio.addEventListener('disconnected');
studio.addEventListener('options:updated', optionsUpdated);
studio.addEventListener('template:updated', templateUpdated);
function optionsUpdated(e) {
console.log(e.detail);
// {
// "data": {}
// }
}
function templateUpdated(e) {
console.log(e.detail);
// {
// "templateId": "424242424242424242424242424",
// "extension": "docx"
// }
}