Widget operations
Overview
The basic flow of editing the layout of a page is the following:
-
Lock the page
It is important to lock the page before modifying it, because this way other users can see that this page is being edited by someone else and they will see a message that it is currently not available for modifications on their end.
To lock a page, perform procedure Page lifecycle operations » Lock a page.
-
Edit the layout
After you have locked a page, you can then proceed with adding and removing widgets on and from the page, moving widgets around the page, or updating widgets on the page.
-
Publish the page
For the changes that you made to the layout of the page to take effect, you must publish the page after editing it.
To publish a page, perform procedure Page lifecycle operations » Publish a page.
-
Unlock the page
After you have published a page, you must unlock it, so that other users have access to it.
To unlock a page, perform procedure Page lifecycle operations » Unlock a page.
IMPORTANT: The following endpoints are designed to support .NET Core widgets only. You cannot use the widget operations endpoints for MVC widgets.
For a comparison on using .NET Core vs using MVC framework when developing widgets, see Development comparison.
Get the properties of a widget
You can obtain the structure of a widget together with its properties and their values.
To do this, execute a GET request to the following endpoint:
{baseurl}/api/default/pages({page_id})/Default.GetPropertyValues(componentId={widget_key})
Where:
{page_id} is the ID of the page where the widget whose properties you want to get is located.{widget_key} is the ID of the widget whose properties you want to get.
Sample request
GET http://mysite.com/api/default/pages(917ef635-3099-4a8e-bbd0-298191a4b547)/Default.GetPropertyValues(componentId=6fde353b-e1bd-4c77-99f3-23dc7316dd25)
Sample response
This request requests a Content block widget and returns its content - Hello world.
Create a widget on top level
This procedure creates a Section widget and places it on a page. You can then place other widgets inside this widget.
To create a Section widget, execute a POST request to the following endpoint:
{baseurl}/api/default/pages({page_id})/Default.AddWidget()
Where {page_id} is the ID of the page where you want to add the widget.
In the request body, you must send the type of the widget and specify that it should be placed on root level.
Sample request
POST http://mysite.com/api/default/pages/(917ef635-3099-4a8e-bbd0-298191a4b547)/Default.AddWidget()
This request creates a .NET Core Section widget and adds it on the specified page.
The Name property specifies the type of widget that you are creating.
In this example, you are creating a .NET Core Section widget.
The PlaceholderName property and the ParentPlaceholderKey property specify where to place the widget on the page. For example, in column one of a particular Section widget.
In this request, the properties are set to body and null, because the Section widget that you are creating will be attached to the body of the page.
Sample response
The response of this request contains the Key of the Section widget, which you can then use in subsequent requests to add a widget inside this Section widget.
Create a widget inside another widget
This procedure creates a .NET Core Content block widget and places it inside a .NET Core Section widget.
To create a widget inside another widget, execute a POST request to the following endpoint:
{baseurl}/api/default/pages({page_id})/Default.AddWidget()
Where {page_id} is the ID of the page where you want to add the widget.
In the request body, you must send the type of the widget and where on the page it should be placed.
Sample request
POST http://mysite.com/api/default/pages/(917ef635-3099-4a8e-bbd0-298191a4b547)/Default.AddWidget()
-
The
Name property specifies the type of widget that you are creating.
In this example, you are creating a Content block widget.
-
The
ParentPlaceholderKey property specifies the Key of the widget where the current widget should be placed.
In this example, the widget should be placed inside the Section widget with Key 21c95d56-74ad-44ec-82a4-7af800f9ed28.
-
The
PlaceholderName specifies the container of the widget where the current widget should be places.
In this example, the widget should be placed inside column 1 of the Section widget.
-
The
Properties collection contains pairs of names and values defining the properties of the widget.
In this example, you are providing the Content and its Value only.
Sample response
Update the properties of a widget
To update the content or the properties of a widget, execute a POST request to the following endpoint:
{baseurl}/api/default/pages({page_id})/Default.SetProperties
Where {page_id} is the ID of the page where the widget whose properties you want to update is located.
In the request body, you must specify which widget you want to update and which properties of that widget you want to edit.
Sample request
POST http://mysite.com/api/default/pages(917ef635-3099-4a8e-bbd0-298191a4b547)/Default.SetProperties
Sample response
Move a widget
You can move a widget on a different place on the page – for example, in a different Section widget or in a different column of a Section widget.
To do this, execute a POST request to the following endpoint:
{baseurl}/api/default/pages({page_id})/Default.MoveWidget
Where {page_id} is the ID of the page where the widget that you want to move is located.
In the request body, you must specify which widget you want to move and where you want to move it.
Sample request
POST http://mysite.com/api/default/pages(917ef635-3099-4a8e-bbd0-298191a4b547)/ Default.MoveWidget
Sample response
Remove a widget from a page
To remove a widget from a page, execute a POST request to the following endpoint:
{baseurl}/api/default/pages({page_id})/Default.ExecuteWidgetOperation
Where {page_id} is the ID of the page where the widget that you want to delete is located.
In the request body, you must specify which widget you want to remove from the page and the type of operation that you want to perform – in this example, delete.
Sample request
POST http://mysite.com/api/default/pages(917ef635-3099-4a8e-bbd0-298191a4b547)/Default.ExecuteWidgetOperation
Sample response