Developing templates

[Amerehei]

I have two questions about templates:

1. How can I create, update, find (and findAll) a template programatically?
2. How can I detect that an element in a workspace is a Template or belongs to a Template?

[michellefs]

Hey there, @Amerehei. Could you explain what you mean by programatically and what you are trying to accomplish with that search and detect capability.

In the meantime, I’ll try to find an expert from our product team for you to connect with.

[Amerehei]

By “programatically” , I mean by using public APIs without using Bluescape frontend

I have a template, and I would like to add it to a Bluescape workspace then I subscribe to graphql events and monitor user actions to the elements of Template, I need to distinguish between Template elements and other elements

[kkoechley]

Hi @Amerehei,

Thanks for your questions about templates. To your first question regarding template APIs, they are actively under development, but they are not quite yet publicly available. Once the template APIs are released, we can provide detailed information on their usage.

As for your second question, you can still create a template manually with our UI with elements that are created programmatically and use traits to identify if the elements belong to a template.

You can either create all the elements programmatically via API and can set the desired trait variable/s at the time of creation, or you can create the elements in the webUI directly and then programmatically add the desired trait variables to the elements in the canvas you intend to use to create the template.

For Example:

1. Create a canvas element and a shape element in a workspace with unique identifiers to include the templateName and templateCategory with one graphQL mutation:

#create canvas and shape to be used for template with template traits:
mutation myCreateShapeCanvasWithTraits($ws: String!, $textContent:String!, $templateName:String!, $templateTraits:TraitInput!) {
    #the template is the canvas that contains the elements:
    myTemplate:createCanvas( workspaceId:$ws, input:{
        name:$templateName
        transform: {
            x:0 
            y:0
        }
        style:{
            width:800
            height:500
            borderColor: { r: 238, g: 85, b: 80, a: 1 }
        }

        #set traits to indicate template, and template name:
        traits:$templateTraits

    }){
        id traits
    }
    
    #elements in the template
    shape1:createShape(workspaceId: $ws, input: {
            text:$textContent
            traits:$templateTraits
            
            mirrorY: false 
            style: {
                regularShape:{

                    kind:Rectangle
                    width:400 height:300 strokeWidth: 5
                    fillColor: {
                        r: 254,
                        g: 232,
                        b: 108
                    }
                    strokeColor: {r:255 g:255 b:255 a:1}
                }   
            }
            transform:{x:10, y:10}
        })

    #return values:
    {id kind traits}
}

with variables:

{
    "ws": "{{workspaceID}}",
    "textContent" : "shape with template traits",
    "templateName":"My Template",
    "templateTraits":{"context": "http://schema.org/", 
                    "content": {"isTemplate":1, "templateName": "my template"}
    }
}

2. Manually create template with the elements created in step1 (with template traits metadata).
   Note: This manual step will be replaced with create template API call once it is released:
   

   

3. To find elements that are part of a template, or a specific canvas, you can query using the traits data from step 1.

#query to return elements with matching trait data:
query filterTraits($workspaceId: String!, $queryTraits:TraitInput!){
    elements(workspaceId: $workspaceId, traits:$queryTraits) {        
        __typename
        id
        traits

        transform {
            x
            y
            scaleX
            scaleY
        }
    }
}

variables (for looking for all matching isTemplate boolean:

{
    "workspaceId": "{{workspaceID}}",
    "queryTraits":{"context":"http://schema.org/", "content":{"testTraits":1} }
}

or variables for specific template name:

{
    "workspaceId": "{{workspaceID}}",
    "queryTraits":{"context":"http://schema.org/", "content":{"templateName": "my template"} }
}