Edit a Text Widget API

Hi All,
I have a request for an API to edit a text widget / playlist within a region.
At the moment, I am able to add a text widget to a playlistId however, I wish to basically change the text rather than add to the playlist. I am aware there is not currently an API which does this but is there a way I could work around this or request this feature?

I am currently getting the information which I need to amend from here…
(please see the bottom widgetId where I outline “Test Region”)

Any thought would be greatly appreciated!!


There is.

I appreciate that editing widgets might not be the most clear documentation ever made, but I tried to make it look sensible.

Ok, in the end we will use this call Swagger UI

Which will take the same parameters as the widget you want to edit, ie in this case POST text widget - Swagger UI

As you already seem to have the widgetId of the text widget you want to edit. then you will use

Call - {{url}}/api/playlist/widget/155

in text widget case, you pretty much need to pass the widgetId and text all other parameters are optional ie for example something like that:

Now as you can see the ‘text’ paramter comes with all required tags ie <p> <span> <style> etc

Can you enter simply ‘Test Text’ in that parameter?
Yes, you can, but presumably you want to have some sort of formatting there, size etc in which case you do need to enter all of that tags I’ve mentioned.

Text widget edit via API might be quite unfortunate example (due to formatting in the parameter), but I hope it will help you.

Editing all other widgets is with the same logic ie you use the same call for edit (with correct widgetId of course) and parameters from POST (the same widget you want to edit) call that you want to change.

Apologies if that was slightly chaotic here and there, let me know if anything requires clarification.


Just what I was looking for, I think I have been staring at these API’s too long…
I can confirm this is working but not pulling through the changed content immediately (although, changes instantly after a refresh of the layout screen in the GUI)
Is the screen caching the old text?

Also, what is the purpose of the “name” Key in your screenshot? I assume it is optional


It will change instantly on the layout (layout designer), if it is a layout in active schedule on the player and if ‘Expire modified layouts’ setting in Display profile is enabled then that change should be pretty much instant as well (it will cut of the playback though and start from the beginning)

Without ‘Expire modified…’ it should show updated version of this layout after next run (ie after layout reloads ie after region with the longest duration ends).

Yes, it is optional, it’s a name for the widget, in Text widget case only ‘text’ parameter is required and widgetId in the call path of course.

That makes perfect sense, thank you for clarifying. Unfortunately, the change is not happening instantly.

If I give you an example of what I am trying to achieve so you might be able to replicate the issue…

First API is run which is…

Then whilst this is running, I open the other tab which is the PUT API and run that…

(I also tried the “isNew” form field which was set to true but this did not help)

In essence, these will be run by a PHP script and ran one after the other, I would probably run the PUT API first as you wouldn’t get any display flicker or change noticeable to the end user and then change the layout. However, purely for testing purposes, I wanted to visibly see the change happen so I can be sure it is happening when I want it to. I have tried running the other way round (while the Change Layout call has technically expired) and the same text is still displayed on screen. I have also ensured that “Expire modified layouts” is enabled in the display profile.


hmm that might be it, I don’t recall if player actions (like changeLayout) will be affected when you edit the layout that was ‘pushed’ to the player with it.

As it does not create new scheduled event or anything like that, I do believe that this is the reason why you don’t see this change there.

As you say the other way around ie change text first then push the layout, should be fine.
Unless this edit widget call is not correctly updating layout flag.

 * I will have a look at it tomorrow to confirm it though *

It does update, but it requires manual intervention, such as opening the region through the GUI (which almost forces the layout to update) so it is working, but not fully.

Thank you for your help, I’m not working on this until next Tuesday now so will catch up then.


Scenario 1

I had a layout with 1 region and 1 text item in it scheduled to my player
I edited the text via API
It did correctly update on the player (after about 30s), I might have been unlucky here.

Scenario 2

I had some other layout scheduled to my player
I edited the text on my other layouts via API
called changeLayout on my player (to change the layout to the ‘text’ layout from scenario 1)
It changed the layout instantly and showed it with correct text (edited via API just before changeLayout call).

Scenario 3

I had some other layout scheduled to my player
called changeLayout on my player (to change the layout to the ‘text’ layout) and make sure it does display it
I edited the text via API on the above layout
I did display ‘old’ text for a few seconds but then updated it to the changed text

I think I’d avoid scenario 3 though, I guess it depends on how long the changeLayout call should last, but if it’s something like 10s then in some cases it might not be enough to show updated text (or show it for too little time).

Scenario 1 and 2 are working as intended I believe, the layout flag is correctly updated when widget is edited via API, therefore the change is reflected on the player as well.

Have I missed anything?

Thanks for this Peter, Scenario 2 is what I am attempting… however I do not have anything scheduled previously, it is just playing the “Default Layout”, would this be affecting things?

I would expect that if I have change the text within the widget and then change the layout (even with a 10 second delay) the text should be updated, but this is not the case.

I am unsure what would be causing this delay.

Any thoughts?

Hi Peter, I have been looking into this for the past few days now and can confirm that the text is being updated on the GUI instantly but not on the player instantly.
If I monitor the Designer GUI of the Layout and refresh the screen after changing the text with the API then the GUI AND Player updates to the correct text?

Is there anything I can do to kick the player into checking for the newly ‘PUT’ text?

It would appear that upon viewing the Layout Designer in my browser, it forces the player to realise there is new text within that region/widget, can you think of any switches I could use in the form text to make this an instant change?

Once I have this working, my project is complete! This is the final hurdle!


I don’t recall doing that, I’d expect it to work without looking in CMS, especially in the scenario when you edit the text first and then call changeLayout on that layout.

Could you please remind me if you’re running the CMS on docker or not?
and if not is the XTR configured? https://xibo.org.uk/manual/en/xtr.html
or rather https://xibo.org.uk/manual/en/install_xtr.html

I would agree, I have changed my PHP script to make sure the Widget Update happens before the changeLayout.
After testing my previous statement, it does not change after 2 or more attempts, but it seems to be time, after time it will change?

I am running the CMS on docker, yes and it is currently running version 1.8.2.


I think I have found the problem…
As I am confident my script is working as expected, I then started to look at the CMS to be the issue.
Sometimes, running the script more than once with different parameters for the “text” field would result in the screen showing the previous text entered (almost like caching)… However, sometimes this was not the case and would not update for ages…

I checked the “Layouts” grid view within the CMS and could see the overlaid display showing the following…

after hovering over the status icon, I can see that it says it has not been built yet.
Once clicking on Design and instantly coming back a page, this Status moves to this…

This goes back to what you were saying about the XTR, is there anyway to force this XTR refresh with an API or from my script?


Right, so when you change something on the layout (either manually or via API), layout should get the status as on your first screenshot - which indicates that there were changes made to it.

Then there should be a task running automatically which will ‘build’ the layout and change the status to the checkmark - player should also be notified that there was a change on the layout and they should show updated version of it.

When you open designer you’re indeed forcing the task to run and build the layout, but that should not be necessary.

I’ll try that tomorrow one another instance and not only on my local dev CMS to see if it will be delayed as well.

Ah, that makes sense, thank you for clarifying Peter. Unfortunately, that change is not happening and the status is not changing as it should, which would explain why the text is not updating. Maybe that widget isn’t sending the right flag in certain situations?

I’ll give the CMS a reboot in the meantime and we can revisit this once you’ve tested your end?

I assume there is no API call to force this task?

EDIT: In addition, I looked through the Logs and could find nothing relating to this process, however, the Audit Log shows that the widget is indeed updating as expected…

Hi Peter, I have the same problem when changing something in the layout by using an API call I need to open CMS to see changes. Did you find a solution already?

This topic was continued here - XTR Layout Changes

in 1.8.3 changeLayout and overlayLayout should trigger layout build and therefore this issue should no longer exist.