WebParser: How UpdateRate Works

This guide is intended to explain how WebParser measures are controlled. How often the measure actually accesses and parses the remote resource defined in the URL option, and how you control how often and when this happens.

Let's start by defining how a WebParser parent measure operates:

  • A Webparser parent measure always has an UpdateRate option on it. If you don't set one explicitly, it will default to 600. More on this in a second.
  • When a WebParser parent measure is first loaded, or when the skin is refreshed. The plugin sets up an internal counter, let's just call it UpdateCounter. The name isn't important, it's not visible to the skin. The value of UpdateCounter is initialized to zero. This counter is a loop from zero to the value of the UpdateRate option on the measure.
  • On each update of the measure, the plugin will evaluate the value of UpdateCounter, and if it is zero, it will access and parse the remote resource. This means it will always do so when the skin is first loaded or when refreshed.
  • The plugin will then increment the value of UpdateCounter by one.
  • If the value of the internal UpdateCounter is equal to the value set for UpdateRate on the measure, then the UpdateCounter loop resets to zero, and the cycle begins again. The remote resource is accessed and parsed, and the UpdateCounter is incremented by one.

So in short, a WebParser parent measure does its work, accesses and parses the remote resource, every UpdateRate times that the measure is updated. By default, a WebParser parent measure will be updated on each update of the skin, controlled by the Update option in the [Rainmeter] section.

This is why, with a default skin Update of 1000 milliseconds, and a default UpdateRate of 600 on the measure, a WebParser parent measure will access the remote resource every 10 minutes.

1000 milliseconds equals 1 second, times 600 equals 600 seconds, which equals 10 minutes.

Why do you NEVER use UpdateDivider on a WebParser measure?

Normally, you would use the UpdateDivider option to control how ofen a measure is updated. This is not recommended on WebParser measures, as it is far better to entirely control the rate that WebParser does its work with UpdateRate. Allow the WebParser parent measure to update, and thus increment the internal UpdateCounter on each skin Update, and set UpdateRate as needed to control things. With a skin Update of 1000, it's pretty easy. UpdateRate simply equates to "how many seconds?".

All that using UpdateDivider will do is make it far more complex and confusing to get the timing right, and it is just not needed. This is because like all measures, WebParser will obey UpdateDivider, which makes the formula:

Update times UpdateDivider times UpdateRate

UpdateDivider defaults to "1", and that is how it should always be left on WebParser measures. Multiplying a value by "1" has no impact. That is what you want.

Why do you NEVER use an !UpdateMeasure bang on a WebParser measure?

Normally, you would use an !UpdateMeasure bang in an action to force a measure to update NOW, rather than waiting for the next normal update. This is not effective on WebParser measures, and should never be used.

While using !UpdateMeasure will cause an immediate update of the measure, all that will do in the WebParser plugin is increment our internal UpdateCounter loop by one. Depending on where the plugin currently is in the internal UpdateCounter loop, this might be from say 458 to 459, and you are only one measure update closer to your goal. If UpdateRate is the default 600, You still have 141 measure updates to go before anything happens.

!UpdateMeasure will not cause the plugin to immediately access the remote resource, and should never be used on WebParser measures.

So how DO you update the measure immediately?

You can do so, by using the !CommandMeasure bang to send an Update command to the WebParser parent measure.

Example: LeftMouseUpAction=[!CommandMeasure MeasureName "Update"]

What an action like [!CommandMeasure MeasureName "Update"] does is very simple. It immediately sets the value of our internal UpdateCounter in the plugin to zero. That will cause the plugin to immediately access and parse the remote resource, and start the cycle over. This is the only effective way to do this.

 

Note: All of this is about controlling WebParser "parent" measures. Never use ANY of this on WebParser "child" measures, as they are entirely controlled by their "parent". When the parent WebParser measure completes accessing and parsing the information you want, it will automatically "force" the values on each of its child measures, based on the StringIndex option on them. Child measures take no independent action, and are simply set by their parent measure. Only use UpdateRate and / or [!CommandMeasure MeasureName "Update"] on parent WebParser measures.