Page updated on October 29, 2024.
Estimated final release date: February 28, 2025.
Historically, Carbone had two different "studios":
We have been working for about a year to unify everything and offer the same tool for Cloud, On-Premise, and even within your application with an embedded solution.
The new studio is composed of two parts (two pages):
Here are all the new features of the Designer Assistant:
This feature is hidden during the Beta phase. View our roadmap.
Embed Carbone Studio directly in your application!
From the software editor's perspective:
From the user's perspective:
From the developer's perspective:
Important notes and consideration during the beta phase:
-s
option to start the studio. <script src="/carbone-studio.js"></script>
<style>
carbone-studio {
height:100%;
width:100%;
}
</style>
// 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!
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"
// }
}
Carbone merges data with templates, but the document conversion (e.g., DOCX to PDF) has traditionally been handled by a single external tool, LibreOffice.
Even though we financially support the LibreOffice foundation every year, we have a deep knowledge of LibreOffice's technical limitations. This is why we wanted to lift this constraint and offer more flexibility.
Now, you can choose from 4 different document converters, all managed directly by Carbone.
Converter | Performance | Precision | Custom PDF Features | Availability |
---|---|---|---|---|
LibreOffice (default) | - | Best for ODT/ODS/ODP/ODG to PDF | ++++ | Yes |
OnlyOffice | +++ | Best for DOCX/XLSX/PPTX to PDF | + | Yes |
Chrome | ++ | Best for HTML to PDF | - | Nov-24 |
Carbone Ice | +++++ | Best for simple DOCX to PDF | + | Q4 2025 |
Carbone Ice is our own converter for specific use cases where very high performance is required.
We may stop working on this solution if OnlyOffice or LibreOffice become as fast as our solution 😛.
{
// L : LibreOffice
// O : OnlyOffice
// I : Carbone Ice
// C : Chrome
"converter" : "L",
"convertTo" : "pdf",
"data" : {}
}
Other methods:
By default, LibreOffice is used. During the beta phase, we will gather feedback from you to determine the best method for selecting the converter. When the stable version of Carbone v5 is released, we may offer additional options like "automatic selection" or "fastest."
Internally, Carbone balances conversion jobs across multiple threads.
It ensures that only N (params.factories
) jobs are executed in parallel, regardless of the number of converters.
This feature also introduces a new "two-level" priority system for job conversion. All tasks are guaranteed to be executed, and high-priority tasks will not starve low-priority tasks. More details will be provided later.
Carbone is compatible with the default installation of these external converters.
However, in a server environment, you likely want secure, compact software with minimal dependencies for your servers or Docker images.
That’s why we provides pre-built binaries on our own CDN (bin.carbone.io), offering optimized and compact versions of all these tools: LibreOffice, OnlyOffice, and Chrome, for multiple architectures (ARM, x64).
Several new Docker images are available as examples. You can use any of them or use our Dockerfile as a template to build your own.
By default, Carbone On-Premise starts with LibreOffice.
To activate the OnlyOffice converter, install OnlyOffice Desktop on your Mac or use our Debian package (Linux):
Then, configure Carbone as follows:
factories : 4, // = nb CPUs
libreOfficePath : 'auto', // = env CARBONE_EE_LIBRE_OFFICE_PATH
onlyOfficePath : 'auto' // = env CARBONE_EE_ONLY_OFFICE_PATH
Other options will be documented soon.
One of our main development principles is to make each new version faster than the previous one. Carbone v5 marks an important milestone with documents that can be generated up to 10 times faster compared to Carbone v4.
Opening templates and saving generated documents can account for 35% of Carbone's internal resource consumption, excluding the time spent on document conversion. We achieved a 4x improvement in template opening speed and a 2x improvement in saving the generated document. Overall, this results in a 2x performance gain on a 15MB PPTX template (without PDF conversion) between Carbone v4 and Carbone v5:
Carbone v5 supports multiple document converters (see the previous section above). OnlyOffice can be used as a replacement for LibreOffice, and here are our benchmarks for converting a large and complex 200-page DOCX file to PDF:
OnlyOffice may be slightly slower for small documents (due to a higher cold start compared to LibreOffice), but we will optimize this before the final release of Carbone v5.
All prerelease features delivered in v4 with optional flags {o.preReleaseFeatureIn=4022011}
are now activated by default for all templates.
This new v5 engine is more stable and handles more complex use cases compared to v4, while maintaining backward compatibility with v4.
Here are the major improvements:
Supports a wider range of use cases for conditional blocks and loops. It handles more scenarios and significantly reduces the likelihood of creating an invalid file ("Could not open document" error). The engine now accepts syntaxes that may not be logical for a computer but are understandable for a human, especially in documents. For example, writing tags in a document can sometimes generate an algorithm like this:
IF
START LOOP
END IF
END LOOP
// END IF should be here for a computer. Carbone fixes this automatically
This example below, which combines filters, aggregators, and a conditional block on the same array, was not supported without this new algorithm:
Additionally, it is no longer necessary to repeat the full tag at the end of a conditional block; {d:showEnd}
or {d:hideEnd}
is sufficient.
{d.arr[sort>1].id:aggCount:ifGT(0):showBegin}
{d.arr[i].id}
{d.arr[i+1].id}
{d:showEnd}
😎 Improved syntax error detection and clearer messages when debug mode is activated (see screenshot of the studio above).
🥳 Enhanced support for XLSX files (e.g., no suppression of empty cells).
Added support for bindColor
in PPTX templates (for text, background color, and shapes).
New :transform(axis, unit)
formatter to move an image or shape in ODT/ODP/PPTX on the X or Y axis:
axis
can be x
or y
to move the item horizontally or vertically from its current position. Positive numbers move the item to the right or bottom.unit
can be cm
, mm
, inch
, or pt
.Whitespace is now accepted in attribute names when using single quotes: {d.'new param'.'second level yes'[1].'sub obj'}
.
Known limitation: This is not accepted inside formatters, array filters, and aliases.
Fix: Conditional blocks (show, hide) and smart conditional blocks (drop, keep) were not executed when combined with an array filter.
In this example {d.arr[i, filter=3].id:ifEM:hideBegin} AAAA {d.arr[i, filter=3].id:hideEnd}
, AAAA
was printed if no rows matched the condition filter=3
.
⚡️ Transform your JSON without limits using :set()
. This formatter, introduced in v4.5.2, was previously limited.
It can now be used to convert a flat JSON into a new hierarchical JSON with unlimited array depth, or vice versa (more details to come).
The CLI has been completely rewritten for greater clarity and ease of use when starting and deploying.
CARBONE_AUTHENTICATION_PUBLIC_KEY
environment variable allows passing the public key (in stringified PEM format) when authentication is enabled.CARBONE_EE_AUTHENTICATIONPUBLICKEY
(old method) and CARBONE_AUTHENTICATION_PUBLIC_KEY
(new method).We know that many of you are waiting for:
This feature will be made public for Carbone On-Premise as soon as it is in production for the Cloud Edition in February 2025. View our roadmap. Why? Once it runs at scale on our Cloud architecture, it will work for your On-Premise environment as well.
We are working hard to keep things simple and ensure easy deployment on any architecture (Servers, OpenStack, Docker, Kubernetes, AWS, Azure, and GCP, with or without a private network).
Our promise is to maintain a single and simple Carbone binary that is just as easy to deploy on one machine or across multiple machines.
For the curious, Carbone v5 will embed an SQLite database and a NATS messaging system. Both are self-managed by Carbone. Object storage is still recommended for storing templates when deploying Carbone on multiple servers.
Carbone v5 will remain in beta until the end of February 2025.
Some parts are stable, while others are hidden and will be delivered later. To make things clear, here is our roadmap:
Oct-24 | Dec-24 | End of Feb-25 | |
---|---|---|---|
HTTP API v5 (same scope as v4) | Stable | Stable | Stable |
Carbone template engine | Stable | Stable | Stable |
LibreOffice v24.8 converter | Stable | Stable | Stable |
OnlyOffice v8.1 converter | Beta | Stable | Stable |
Processing XLSX Templates (code rework in progress) | Beta | Stable | Stable |
Processing HTML/XML Templates (code rework in progress) | Beta | Stable | Stable |
Studio - Designer assistant | Alpha | Beta | Stable |
Studio - Embedded | Alpha | Beta | Stable |
Studio Viewer HTML/XML | Alpha (Not Public) |
Beta | Stable |
Template manager/versioning/constant ID (Studio + HTTP API) | Alpha (Not Public) |
Beta (Not Public) |
Stable |
On-Premise Plugins/Middlewares (breaking changes) | Alpha (Not Public) |
Beta (Not Public) |
Stable (Breaking Changes) |
Chrome converter | Alpha (Not Public) |
Beta | Stable |
AI Template generator | Experimental | Beta | Stable |
AI Assistant | Experimental (Not Public) |
Beta | Stable |
PDF Comparison (Visual and Text Differences) | Experimental (Not Public) |
Alpha (Not Public) |
Stable |
Missing feature or known bug compared to On-Premise v4 Studio:
data
, complement
, translation
, and constants
carbone-version: 5
.No breaking changes.
Important notes: GET /render/<idRender>
now returns the correct HTTP header Content-Disposition
:
GET /render/:idRender |
GET /render/:idRender?download=true |
|
---|---|---|
Carbone v4 Content-Disposition |
filename=file.pdf |
attachment; filename=file.pdf |
Carbone v5 Content-Disposition |
inline; filename=file.pdf |
attachment; filename=file.pdf |
On-Premise: The new studio replaces the old one.
Cloud: The new studio is accessible only through the "Lab" button (top right corner) during the entire beta phase.
Any edits made to the JSON or Template file will be saved in the Studio database.
It will fully replace the current studio in March 2025.
We always recommend testing your templates before migrating to v5.
The Carbone v5 template engine is backward compatible with templates made for previous Carbone versions.
Despite our thousands of tests, there is always a slight chance of a regression.
Please contact us as soon as you encounter any issues.
The main impact often comes from the version of the converter, LibreOffice.
If you use Carbone On-Premise, you can still use an older version of LibreOffice with Carbone v5.
The Cloud Edition (API v5) uses the latest LibreOffice version (24.8), while Carbone Cloud v4 uses LibreOffice 7.5.
Therefore, document conversion may vary when switching from v4 to v5 (especially for DOCX to PDF).
This is an opportunity to try the alternative converter OnlyOffice
, which performs almost pixel-perfect DOCX-to-PDF conversions.
We have extensive experience solving these problems, so feel free to contact us if you need help. For example, there are two DOCX features that are not well supported by the LibreOffice converter, even in the latest version (24.8):