Home
Games
Marketplace
Compendium Character Vault Roll20 for iPad and Android
Character Vault
Any Concept / Any System
Compendium
Your System Come To Life
Roll20 for Android
Streamlined for your Tablet
Roll20 for iPad
Streamlined for your Tablet

Personal tools

Difference between revisions of "Mod:Function/Roll20 object"

From Roll20 Wiki

Jump to: navigation, search
(Created page with "Roll20 objects are a special kind of JavaScript object. They represent something in your campaign, such as a token on the tabletop or a character in the journal, and there is ...")
 
m
 
(18 intermediate revisions by 3 users not shown)
Line 1: Line 1:
βˆ’
Roll20 objects are a special kind of JavaScript object. They represent something in your campaign, such as a token on the tabletop or a character in the journal, and there is some special consideration for using them. [[Script:ESRO|Extended Syntax Roll20 Objects]] is an API script which modifies how you can interact with Roll20 objects.
+
{{revdate}}{{API dev}}{{apibox}}
 +
 
 +
Roll20 objects are a special kind of [[JavaScript]] object. They represent something in your campaign, such as a token on the tabletop or a character in the journal, and there is some special consideration for using them. [[Script:ESRO|Extended Syntax Roll20 Objects]] is an Mod script which modifies how you can interact with Roll20 objects.
  
 
== Roll20 object fields ==
 
== Roll20 object fields ==
Line 11: Line 13:
 
|}
 
|}
  
βˆ’
=== id ===
+
=== <code>id</code> ===
βˆ’
This field is shorthand for <code>obj.get('id')</code>. All Roll20 objects have a <code>_id</code> property which uniquely identifies them within a campaign, but their properties are not directly accessible. Normally you have you call <code>[[#get|get]]</code> in order to get the value of a property, but because <code>_id</code> is needed on such a frequent basis, this shim filed is provided for convenience.
+
This field is shorthand for <code>obj.get('id')</code>. All Roll20 objects have a <code>_id</code> property which uniquely identifies them within a campaign, but their properties are not directly accessible. Normally you have to call <code>[[#get|get]]</code> in order to get the value of a property, but because <code>_id</code> is needed on such a frequent basis, this shim field is provided for convenience.
  
 
== Roll20 object functions ==
 
== Roll20 object functions ==
Line 24: Line 26:
 
| <code>[[#get|get]]</code>
 
| <code>[[#get|get]]</code>
 
| Gets the value of a specified property.
 
| Gets the value of a specified property.
 +
|-
 +
|
 +
| <code>[[#get %5BAsynchronous%5D|get]]</code>
 +
| Gets the value of "notes", "gmnotes", or "bio" properties of a character or handout Roll20 object.
 
|-
 
|-
 
|
 
|
Line 32: Line 38:
 
| <code>[[#set|set]]</code>
 
| <code>[[#set|set]]</code>
 
| Sets one or more specified property values.
 
| Sets one or more specified property values.
 +
|-
 +
|
 +
| <code>[[#setWithWorker|setWithWorker]]</code>
 +
| Sets specified property values, and runs any applicable [[Sheet Worker Scripts]].
 
|}
 
|}
  
 
=== <code>get</code> ===
 
=== <code>get</code> ===
 +
{{function parameters
 +
|parameter
 +
|''(String)'' The name of the parameter to get. If you are getting the value of a read-only property (one which starts with an underscore, like <code>_id</code> or <code>_type</code>), the leading underscore is not required.}}
 +
{{returns|The value of the specified property}}
 +
==== Examples ====
 +
<pre data-language="javascript">var character = getMyCharacter(),
 +
    strength = findObjs({ type: 'attribute', characterid: character.id, name: 'strength' })[0];
 +
 +
log(strength.get('current'));</pre>
 +
 +
=== <code>get</code> {{asynchronous}} ===
 +
This version of <code>get</code> will be automatically called if ''parameter'' is "notes", "gmnotes", or "bio" and the Roll20 object is a character or handout.
 +
 +
{{function parameters
 +
|parameter
 +
|''(String)'' The name of the parameter to get. If you are getting the value of a read-only property (one which starts with an underscore, like <code>_id</code> or <code>_type</code>), the leading underscore is not required.
 +
|callback
 +
|''(Function)'' A callback function which will receive the value of the property as a parameter.}}
 +
{{returns}}
 +
==== Examples ====
 +
<pre data-language="javascript">var character = getMyCharacter();
 +
character.get('bio', function(text) {
 +
    log(text);
 +
});</pre>
 +
 
=== <code>remove</code> ===
 
=== <code>remove</code> ===
 +
{{function parameters}}
 +
{{returns}}
 +
==== Examples ====
 +
<pre data-language="javascript">var graphics = findObjs({ type: 'graphic', pageid: Campaign().get('playerpageid') });
 +
_.each(graphics, (g) => {
 +
    g.remove();
 +
});</pre>
 +
 
=== <code>set</code> ===
 
=== <code>set</code> ===
βˆ’
[[Category:Docs]]
+
{{function parameters|section=Parameters (single property)
 +
|property
 +
|''(String)'' The name of the property to set.
 +
|value
 +
|''(varies)'' The value to set for the specified property.}}
 +
{{function parameters|section=Parameters (multiple properties)
 +
|attributes
 +
|''(Object)'' The properties of the <code>attributes</code> object will be mapped to the properties of the Roll20 object.}}
 +
{{returns}}
 +
==== Examples ====
 +
You can set each property one at a time:
 +
<pre data-language="javascript">var token = getMyToken();
 +
token.set('left', 70);
 +
token.set('top', 70);
 +
token.set('rotation', 90);
 +
token.set('flipv', true);
 +
token.set('fliph', false);</pre>
 +
 
 +
Or you can set multiple properties at once:
 +
<pre data-language="javascript">var token = getMyToken();
 +
token.set({
 +
    left: 70,
 +
    top: 70,
 +
    rotation: 90,
 +
    flipv: true,
 +
    fliph: false
 +
});</pre>
 +
 
 +
=== <code>setWithWorker</code> ===
 +
{{ambox|small=left|type=notice|image=none|text='''Only applicable to Attribute objects.'''}}
 +
{{function parameters|section=Parameters (multiple properties)
 +
|attributes
 +
|''(Object)'' The properties of the <code>attributes</code> object will be mapped to the properties of the Roll20 object.}}
 +
{{returns}}
 +
==== Examples ====
 +
This function is called in the same fashion as <code>[[#set|set]]</code> with a single object parameter, except it can only be used with Attribute objects.
 +
<pre data-language="javascript">getObj("attribute", "-KUI1fO2L7Jv0Y4AOSFK").setWithWorker({ current: "Cleric" });</pre>
 +
 
 +
[[Category:API Development]]

Latest revision as of 09:13, 9 June 2024

Wiki-Logo 75x49.png
Page Updated:
  2024-06-09
Octicons-terminal.png
This is related to Mods, which require
Pro
info to be able to use.
Main Page: Mod:Development

Roll20 Mod
Use Mods

Mod Development

Reference

Cookbook


Roll20 objects are a special kind of JavaScript object. They represent something in your campaign, such as a token on the tabletop or a character in the journal, and there is some special consideration for using them. Extended Syntax Roll20 Objects is an Mod script which modifies how you can interact with Roll20 objects.

Contents

[edit] Roll20 object fields

Property Description
id This property is shorthand for obj.get('id').

[edit] id

This field is shorthand for obj.get('id'). All Roll20 objects have a _id property which uniquely identifies them within a campaign, but their properties are not directly accessible. Normally you have to call get in order to get the value of a property, but because _id is needed on such a frequent basis, this shim field is provided for convenience.

[edit] Roll20 object functions

Return type Function Description
varies get Gets the value of a specified property.
get Gets the value of "notes", "gmnotes", or "bio" properties of a character or handout Roll20 object.
remove Deletes the Roll20 object.
set Sets one or more specified property values.
setWithWorker Sets specified property values, and runs any applicable Sheet Worker Scripts.

[edit] get

Parameters

parameter
(String) The name of the parameter to get. If you are getting the value of a read-only property (one which starts with an underscore, like _id or _type), the leading underscore is not required.

Returns

The value of the specified property

[edit] Examples 

var character = getMyCharacter(),
    strength = findObjs({ type: 'attribute', characterid: character.id, name: 'strength' })[0];

log(strength.get('current'));

[edit] get [Asynchronous]

This version of get will be automatically called if parameter is "notes", "gmnotes", or "bio" and the Roll20 object is a character or handout.

Parameters

parameter
(String) The name of the parameter to get. If you are getting the value of a read-only property (one which starts with an underscore, like _id or _type), the leading underscore is not required.
callback
(Function) A callback function which will receive the value of the property as a parameter.

Returns

(Void)

[edit] Examples 

var character = getMyCharacter();
character.get('bio', function(text) {
    log(text);
});

[edit] remove

Parameters

No parameters

Returns

(Void)

[edit] Examples 

var graphics = findObjs({ type: 'graphic', pageid: Campaign().get('playerpageid') });
_.each(graphics, (g) => {
    g.remove();
});

[edit] set

Parameters (single property)

property
(String) The name of the property to set.
value
(varies) The value to set for the specified property.

Parameters (multiple properties)

attributes
(Object) The properties of the attributes object will be mapped to the properties of the Roll20 object.

Returns

(Void)

[edit] Examples

You can set each property one at a time: 

var token = getMyToken();
token.set('left', 70);
token.set('top', 70);
token.set('rotation', 90);
token.set('flipv', true);
token.set('fliph', false);

Or you can set multiple properties at once: 

var token = getMyToken();
token.set({
    left: 70,
    top: 70,
    rotation: 90,
    flipv: true,
    fliph: false
});

[edit] setWithWorker

Only applicable to Attribute objects.

Parameters (multiple properties)

attributes
(Object) The properties of the attributes object will be mapped to the properties of the Roll20 object.

Returns

(Void)

[edit] Examples

This function is called in the same fashion as set with a single object parameter, except it can only be used with Attribute objects. 

getObj("attribute", "-KUI1fO2L7Jv0Y4AOSFK").setWithWorker({ current: "Cleric" });
Retrieved from "https://wiki.roll20.net/index.php?title=Mod:Function/Roll20_object&oldid=34032"