Hi @Amerehei,
Great question! Elements that require uploading a file, like images and documents can get a bit confusing regarding width, height, and scale. It is important to note that document and image elements width and height are the actual document/image asset width and height, not to be confused with the boundingBox
width/height (which is the width/height * scale) which is the width/height in pixels shown on the screen.
Document Upload and management happens in a few steps:
- Initial Upload: There is a temporary placeholder while the element ingestionState is transferring and/or processing. If you set width/height and scale from
createDocument
mutation you are setting the transfer/upload placeholder container, not the actual document.
sample pdf: https://create.bluescape.com/hubfs/One_Pagers_2020/Collaboration_Solutions_and_Bluescape.pdf
Example transfer area with default values:
- width = 1000
- height = 1000
- scale = 1: documents only have scale, not scaleX and scaleY since they are a fixed aspect ratio, but note that an element query will return scaleX/scaleY but they will be equal to each other, based on fixed aspect ratio
- x = 0 and y = 0 (for illustration purposes)
# Create Document from URL using default width/height/scale
mutation createDocumentFromUrl(
$workspaceId: String!,
$x: Float!,
$y: Float!,
$title: String!,
$documentFormat: DocumentFormatInput!,
$url: String!
) {
createDocument(
workspaceId: $workspaceId,
input: {
title: $title
documentFormat: $documentFormat
sourceUrl: $url
transform: {
x: $x
y: $y
}
}
) {
content{ uploadId url fields}
preview{uploadId url fields}
document{id width height ingestionState}
}
}
variables:
{
"workspaceId": "{{workspaceID}}",
"title":"testPDF.pdf",
"documentFormat":"pdf",
"url":"https://create.bluescape.com/hubfs/One_Pagers_2020/Collaboration_Solutions_and_Bluescape.pdf",
"x":0,
"y":0
}
illustration showing temporary placeholder:
,
- Upload transfer complete: Once the document is uploaded and processed, it will be scaled to fit into the temporary container as defined in the original
createDocument
mutation.
In our example pdf that is 8.5x11 inches, or 989x1280 pixels, it is scaled to fit in the 1000x1000 placeholder and centered:
After the pdf is scaled to fit in 1000x1000 container it is centered at x = 113.671875.
You can verify with document element query:
#find Document element by elementID:
query getElementById($workspaceId: String!, $elementId:String!){
elements(workspaceId: $workspaceId, id:$elementId) {
id
transform{
x y scaleX scaleY
}
boundingBox{
width
height
x
y
}
... on Document{
width
height
title
filename
}
}
}
response:
{
"data": {
"elements": [
{
"__typename": "Document",
"id": "658249299a301cc61d1f961b",
"transform": {
"x": 113.671875,
"y": 0,
"scaleX": 0.78125,
"scaleY": 0.78125
},
"boundingBox": {
"width": 772.65625,
"height": 1000,
"x": 113.671875,
"y": 0
},
"width": 989,
"height": 1280,
"title": "testPDF.pdf",
"filename": "Collaboration_Solutions_and_Bluescape.pdf"
}
]
}
}
- Updating Document: You can then update the document element using
UpdateDocument
, but since you can only update the scale, not the width/height you will need to calculate the scale to get a desired width/height.
For example, if you want the document to be 500 pixels wide, and you know the document width = 989:
500/989 = scale 0.505561172901921.
You can then use the the scale with updateDocument
:
mutation myUpdateDocument($workspaceId:String!, $x:Float!, $y:Float!, $scale:Float!, $documentID: String!){
updateDocument( workspaceId:$workspaceId id:$documentID input:{
transform:{
x:$x
y:$y
scale:$scale
}
})
{id}
}
and get the following:
{
"data": {
"elements": [
{
"__typename": "Document",
"id": "658249299a301cc61d1f961b",
"transform": {
"x": 0,
"y": 0,
"scaleX": 0.506572295247725,
"scaleY": 0.50703125
},
"boundingBox": {
"width": 500,
"height": 649,
"x": 0,
"y": 0
},
"width": 989,
"height": 1280,
"title": "testPDF.pdf",
"filename": "Collaboration_Solutions_and_Bluescape.pdf"
}
]
}
I hope this helps you understand the Document transfer and management and how to deal with width/height and scale.
If you have any questions just let me know.