This is used for when a game is known to load stuff in https mode, preventing bonus collection in a normal way.

Setting this to true causes the main WM script to behave differently when it checks that a bonus page has loaded.

This flag should also be set if the game you are collecting for is not an apps.facebook hosted game. Non-facebook apps that post to facebook draw the user off-site and the sidekick will not be able to return information to the main script body normally.

See also the flag skipResponse for dealing with some off-facebook apps.

This is used for games such as PT and CW where a link must actually be clicked to get a bonus.

Because the bonus collection page info may be lost if the sidekick did this clicking, we pass the info back to the WM script for processing. Setting this to true activates another part of the WM script.

Most games don't need to worry about this, and clicking their links or buttons via the script is just fine.

This is used for games such as FV where a link needs to be modified before it is processed so that the destination page is more useful to this script. For instance, we modify some links that take us to the gift sending page for FV so that only one resource exists to choose from.

Other games such as MouseHunt have an apps.facebook page and a non-facebook page. Some links take you off-site and will cause cross-domain errors, so forcing them to stick to their apps.facebook version is helpful.

Not many games can benefit from this option.

You can use this flag to cause your sidekick to ignore return values. Instead, the main script body will just look for load status on the sidekick window.

When the status checker thinks it has found a fully loaded page in the sidekick window, the status will become "status: 2: responseless collection". All status 2 urls are stored as accepted.

• Not all load statuses are accurate, so not every page marked as accepted will be correctly accepted.

I suggest using this flag for games where the user has 100+ bonuses to collect per day and no limits. Using this flag can make bonus collection much faster because some steps are omitted. Again, this is a very inaccurate method of collecting bonuses, and every attempt should be made to try other methods.

• You cannot use skipResponse with games that also need the "requiresTwo" flag.

• You cannot use skipResponse with games that have a bonus collection page that requires another click to accept or decline a bonus type

The text to find in the link url. This parameter can convert to a RegEx using the following "isRegex" parameter.

Converts the find string into a RegEx with no modifiers.

The replacement text for the link url.

A list of words that can be found in the post body to determine the changes needed in the link url. This begins a second function of the find and replace combo. By setting the find parameter to something containing {%1}, it will search the post body for all the values in the words parameter until one is found. It will then convert the link url to include a block of code from the "conversionChart" parameter below, using the found word as an index into that chart.

A set of word to item code associations. For instance, one entry for FV would be "shovel":"shovel_item_01" where "shovel" is a string in the "words" array and "shovel_item_01" is the code for 2 shovels on the FV gifts page.

• See the FV sidekick for a better look at alterLink use. That sidekick makes excellent use of the alterLink ability by pre-selecting 1 to 3 items from the gift page depending upon what post sent the user to that gift page.

Tests can be in the following forms, and are case sensitive:

• link: the test is run on the link text
• url: the test is run on the link url
• body: the test is run on the body text of a post, which includes the following: title, caption and desc(ription)
• title: the bold text on top of a post. Does NOT include the msg portion.
• caption: normal text below the title, not all games use this. See also desc
• desc: normal text below the title, not all games use this. See also caption
• html: the test is run on the whole post contents. In WM 2, this is not actually the html of the post, but a jumble of all the other searchable sections of the post.
• either: you can do both the link test and the body test in the same line, in that order.
• msg: you can test for text in the message portion of the post. The section above the post where users can add their own text. This is NOT included in a body search.
• img: the url for the image that goes with the post. Not all posts use this field. Mostly that is a mistake on the part of the game engine to attach one to the FB database.
• fromName: the name of the person who created the post case. sensitive as fromName
• fromID: the id of the person who created the post. case sensitive as fromID
• targetName: the array of people the post targets, name form.* case sensitive as targetName
• targetID: the array of people the post targets, id form.* case sensitive as targetID
• canvas: the location on facebook where the game runs, for instance farmville="onthefarm"
• likeName: the array of people who like the post, name form.* case sensitive as likeName
• likeID: the array of people who like the post, id form.* case sensitive as likeID
• comments: the text of all comments attached to the post
• commentorName: the array of people who commented on the post, name form.* case sensitive as commentorName
• commentorID: the array of people who commented on the post, id form.* case sensitive as commentorID

(*) Does not show id's of people who block non-friends from seeing their activity.

Since the WM's internal makeup has changed a lot over the last year, I will go through a bunch of ways you can use to identify posts.

• Using relic methods to create a test:
• {url:"frType=Q", ret:"coins25"}

Searches the link url for "frType=Q" and returns "coins25" if found

• Using current methods to create a test:
• {search:"url", find:"frType=Q", ret:"coins25"}

Does exactly the same as above

• Using an array to create a test searching multiple post parts:
• {search:["link","body"], find:"send", ret:"send"}

Searches the post link text for "send", and if found returns "send". If not found, it then searches the post body with the same results.

• Using an array to create a test searching for multiple words:
• {search:"link", find:["lunch","breakfast","dinner"] ret:"meal"}

Searches the post link text for lunch, breakfast or dinner, and if found, returns "meal".

• Using two arrays to create a test searching for multiple words in multiple search regions:
• {search:["link","body"], find:["lunch","breakfast","dinner"] ret:"meal"}

Searches the post link text for lunch, breakfast or dinner, and if found, returns "meal", and if not found, performs the same search on the post body.

• Using a subTest array to identify multiple post types:
• {search:"link", find:"{%1}", subTests:["lunch","dinner","breakfast"], ret:"{%1}"}

Searches the post link text for breakfast, lunch, or dinner and returns the word found.

• Using a subTest array to identify a single post type:
• {search:"link", find:"{%1}", subTests:["lunch","dinner","breakfast"], ret:"meal"}

Searches the post link text for breakfast, lunch, or dinner and returns the word "meal".

• Using a subNumRange to identify multiple post types:
• {search:"body", find:"level {%1}", subNumRange:"1,20", ret:"getlevel{%1}"}

Searches the post body for the word "level" followed by any number in the range from 1 to 20 and returns "getlevel" followed by the number found. Numbers are run from highest to lowest to prevent "level 10" from being identified as "level 1".

• Using a subNumRange to identify a single post type:
• {search:"body", find:"level {%1}", subNumRange:"1,20", ret:"getlowlevel"}

Searches the post body for the word "level" followed by any number in the range from 1 to 20 and returns "getlowlevel" no matter what number is found.

• Using a registered expression to identify multiple post types:
• {search:"link", find:"(black|white) (pony|horse)", regex:true}

Searches the post link text for any combination of black or white, pony or horse, and returns whatever matches first

• Using a registered expression to identify a single post type:
• {search:"link", find:"(black|white) (pony|horse|bear|cat)", regex:true, ret:"adopt"}

Searches the post link text for any combination of horse, pony, bear or cat, preceded by either black or white, and returns "adopt" no matter what is found.

Since version 2.1, WM can make use of the search parameter instead of supplying search:test pairs such as url:string, or body:array.

Now you can say:

• search:region string, find:string
• search:region string, find:string array
• search:region array, find:string
• search:region array, find:string array

See examples above.

Tests can accept arrays in the search parameter.

Remember arrays are searched in the order supplied. If you pass an array to your test object, be sure it is ordered in the way you want the searches to be performed.

See examples above.

Tests can accept arrays in the testing parameter (ie. link, body, url, html, etc. or the new find parameter). This version of the test does not have any ability to return multiple values like the subTest array (see below). Use it to grab multiple texts that represent the same return value.

Remember arrays are searched in the order supplied. If you pass an array to your test object, be sure it is ordered in the way you want the searches to be performed. For instance if your array contains "pea" before "peanut", it will find "pea" in the word "peanut" before finding the word "peanut".

If you include the WM Library Script in your sidekick, you can call the optimize method on your array as you pass it to the test object, like this: {search:"body",find:"{%1}", subTests:myArray.optimize(), ret:"{%1}"}

See the WM Library Script documentation for details.

Sidekicks make use of the subTests parameter which takes an array of strings. These strings can be fitted into both the find parameter and the return value of each test. Use the string "{%1}" in your find string and your ret parameter string as an insertion marker.

• Example: {body:'needs {%1}',ret:'send{%1}',subTests:["rope","rock","nails"]}

In the example above, the test searches for body text containing "needs " + an array item from subTests. The test process tests in order of appearance, returning the first found value. The above example would test for "needs rope", then "needs rock" and finally "needs nails".

To optimize a subTest array, you must understand and implement the following:

• Arrays are read in order, thus an entry that starts with some string X must come before a string that is simply X. For instance, "popcorn" must come before "corn" or "corn" will be returned if a test string looks like this: "{%1} bushels".

• The same is true: "cornflower" must come before "corn" or "corn" will be returned if a test string looks like this: "send {%1}".

Depending on which value is found, the return value is then altered where the same {%1} appeared. The example above could return "sendrope","sendrock" or "sendnails".

Like the find string, subTest strings are not case sensitive. But since return text is sensitive, when inserting {%1} back to the return text, the search text is converted to lower case and has its spaces removed. For example, if "Energy Pack" was supplied in the subTests array above, the return value would be converted to "sendenergypack".

You can also omit the {%1} from the return value to return the same value for each subTest.

• Example: {body:'needs {%1}',ret:'sendmaterial',subTests:["rope","rock","nails"]}

You can also create and then provide a predefined array. This is handy when you need to use the same list more than once.

• var arrayExample = ["rope","rock","nails"];
• ...
• {link:'send {%1}',ret:'sendmaterial',subTests:arrayExample},
• {body:'needs {%1}',ret:'sendmaterial',subTests:arrayExample}

The examples above always return "sendmaterial" if the body text contains "needs rope", "needs rock" or "needs nails", or if the link text includes "send rope", "send rock" or "send nails".

The subTest parameter is exceptionally useful when many bonus types are awarded using the same basic text layout. Say you have 100+ bonus types and the bonus text appears like this:

• "wants to share a {%1} with you in FarmVille", where {%1} could be any bushel crop, a manure bag, or some other gift.

This parameter can be used to replace the subTests array with a range of numbers. Specify a range such as 10-20 as "10,20".

• Example1: {body: "level {%1} sample" ,subNumRange:"1,20", ret: "samplelow"}.

This would search for any text from "level 1" to "level 20" and return "samplelow" if found.

• Example2: {body: "level {%1} sample", subNumRange:"1,20", ret: "sample{%1}"}.

This would search for any text from "level 1" to "level 20" and return "sample" followed by the number found, such as "sample5".

You can use registered expressions (regex or RegExp) in the testing process. To do so, you must set the regex parameter to true. You also have access to a mods parameter which you can use to override the preset "gi" modifiers.

You may either use a return value, or by default, the test will return what is matched by the regex. Become familiar with RegExp before attempting this method.

You cannot supply an actual registered expression as a test because a registered expression is an object, and a sidekick cannot pass complex objects back to the WM host script. This is why you must supply it as text and then have WM convert it for you once docked.

Below are some examples:

• Example1: {body:"(turkey|chicken) (feed|poop)", regex:true}

This would search for turkey feed, turkey poop, chicken feed or chicken poop and return what was found.

• Example2: {body:"(turkey|chicken) (feed|poop)", regex:true, ret:"material"}

This would search for turkey feed, turkey poop, chicken feed or chicken poop and return "material".

• Example3: {body:"(turkey|chicken) (feed|poop)", regex:true, mods:"g"}

This would do the same as the first example AND change the modifiers for the match to just "global" removing the case insensitivity. Remember, that would be bad because the case of every part of the post is put into lower case. Defaults are "gi", global search and case insensitivity, and you might want to keep them that way.

Tests can return the following magic words:

• exclude: Excludes the post from being processed. Note that "exclude" does not start with your game's appID after joining with the WM host script. Use exclude when you want to block a post, especially those meant to lure you to the game without a bonus being given, or for bonus types you don't know how to collect yet and you don't want the "doUnknown" magic menu option to collect on accident.

• wishlist: A type of exclude, except that posts flagged as wishlists can opt to not be hidden with excluded or other unwanted posts. This allows users to click the wishlist posts from WM and process them manually.

• send: A short word that can be picked up by the "sendall" magic menu option. This is useful if the sidekick does not need to know what its sending, or the user would simply not benefit in knowing that information.

• dynamic: This word will flag the post as being grabbed by the dynamic grabber, even though its being identified by your sidekick. Posts flagged with "dynamic" are simply processed as if an option was checked for their type. There is no options to disable or enable the collection of posts flagged as "dynamic". This is also the default return value given by any user created dynamic test that does not supply a ret parameter.

Tests can have any number of other parameters, most of which will have no effect on the WM or its behavior. A sidekick creator can inject a test with any number of these parameters if they wish to store notes for themselves, or if their sidekick performs special transformations on tests before passing them to the WM dock.

One such parameter could be the note parameter. Take special care when leaving notes for yourself in the note parameter as the WM does actually read and use that parameter when identifying posts using user-created dynamic tests. In fact, there is a tab in the dynamic grabber console for each test which shows the note field's contents.

All other parameters unrecognized by the dynamic grabber console are shown on the "Other" tab in the order they appear in the test object.

Defines a closeable section with gray header bar. This should only be used once per sidekick (or once per major function if a sidekick does more than one major thing). Section uses the following other parameters: label,kids,title. Section objects are stored as a variable and remember their open/closed state when you next enter the options menu.

Defines a closeable segment similar to "section" elements, however the bar is blue and it also displays select all/none buttons on the right. Add the parameter hideSelectAll:true to the separator element to disable display of these buttons. Separator elements can be nested inside each other, providing different closeable levels. Future versions may offer a bar color for each depth. Separator uses the following other parameters: label,kids,hideSelectall,title.

• Separator objects are stored as a variable and remember their open/closed state when you next enter the options menu.

Defines a closeable tab that acts as a container just like a "section". There is no need to define a tab container, as the tab element automatically negotiates its position and locates siblings. Tab uses the following other parameters: label, kids, title.

• Tab objects are stored as a variable and remember their open/closed state when you next enter the options menu.
• New tabs which the user has not used before may not have a selected tab, causing the tab bar to look like it has no panels. Selecting a tab cures this anomaly.
• A CSS issue currently prevents tabs from using the newitem special parameter. A future version will remedy this issue.

Defines a selection group, containing the objects in its "kids" parameter as sub elements. It also automatically creates a select all and select none button set for the block. You may add a parameter hideSelectAll:true to the optionblock to disable display of those buttons. Currently the text is a bit small on the block label, but it will be changed. Optionblock uses the following other parameters: label,kids,hideSelectAll,title.

Defines an actual option. Checkbox uses the following other parameters: label,title,"default",newitem.

Creates a link. Link options are always opened in NEW windows or tabs, not the window running the WM script. Be sure to include an href:"your url here" parameter in the link declaration or it wont do much. Link uses the following other parameters: label,href,newitem,title.

defines an actual option in a group where only one can be chosen. Radio uses the following other parameters: label,options,newitem,title.

Defines an option but it does not appear on the options menu. Use this to hide default options that you wish to modify later, or per version options you don't want users to change yet.

Defines an option as a textbox that the user can fill in. Accepts the following additional parameters: cols, rows, title, label,"default".

Defines a group of options as a multiselect box. Select uses the following other parameters: label,options, title,"default"

Creates a button that when clicked highlights an array of elements. Use the "options" parameter to provide that array of elements. Elements in the array are strings that match EXACTLY a defined option.

A second array can be provided in the "clearfirst" parameter and when clicked, the button function will first un-highlight the provided array of elements. You may omit the options parameter to create just an unselect button.

This element also takes the title and label parameters.

Creates a button that when clicked selects an array of elements. See button_highlight above for further details, including the "clearfirst" parameter.

Creates a button that when clicked selects all elements that begin with the given prefix parameter. Unlike other buttons, you do not supply an array in the options parameter. Instead this button fetches its own data. Also there is no clearFirst array parameter. Instead, use the clearPrefix parameter to create an unselect button for a prefix of elements.

As an example, imagine there are 200 animal adoption links, of which you script every one to have an id prefix of "adopt_", and of which 20 are deer and you prefix them with "adopt_deer", where the rest of the id is the color or name of that deer type, such as "adopt_deermule". If you put all the animal adoption options in one optionblock, you would only be able to select that entire block, or single items at at time. But now using the "button_selectprefix" type with a prefix parameter of "adopt_deer", only the deer in that option block will be selected.

This button's function will select ALL options from the options menu for your appID that match the prefix given, even outside the option block, or section you enclosed it in. This allows for selecting of multiple elements from multiple groups of which you provided the same prefix. For instance you may have a group of elements scattered through your options menu that are all somehow related, but generally of different types. You could code them all as "silo_part", "silo_animal" or "silo_reward". Then you could make a button to select anything prefixed by "silo_".

Remember the selectall magic menu option already does something like this without actually checking options. You could duplicate this function by making a button with prefix "send". Remember also that items coded properly as a send function will be prefixed by "send". In the example above, if you created an element with id "sendsilo_part", a button with prefix "silo_" would NOT select that bonus type.

Defines an option as a text box. Be sure to set the parameter "size" or it will default to 25 characters. Text uses the following other parameters: label,title,size,"default". Alternately, you can specify the element type as "float" or "int" to create a number box rather than a text box. It does not prevent letter characters from being entered, but it does change how options are used and stored.

If type is not supplied, type defaults to "checkbox".

Because WM does not allow sidekicks to pass functions, "button" menu items will not have any onclick functions set to them. This is to protect WM users. For built in button functions, see "button_selectmulti" and "button_highlight" above.

If newitem is set to true, most elements take on a green background color. Use this to point out a new item to users. Be sure to remove it on the next update.

If your sidekick needs more than one highlight color, you can opt to set newitem to 1, 2 or 3 instead of just setting it to true. These numbers correspond to green, dark red and royal blue. The value true corresponds to a more lime green color.

• Future versions may allow you to just supply a color value.

Toggles processing of posts the script can't identify.

To make good use of this, you should always find and define any post you want to "exclude" to keep the game from loading without giving a bonus.

For instance, if the link text "go play" was not excluded, whenever somebody started playing a game, enabling "doUnknown" would click that link and just get taken to the game without a bonus.

• Note doUnknown contains an uppercase "U".

A super function to toggle sending of all "send" prefixed links. This only works when "send" type links are defined with the prefix "send".

• Example: send a bucket of water looks like "sendwaterbucket".

If you have 100+ sendable items defined with prefix "send", then "sendall" will enable them all at once. It doesn't click to toggle them, its just an internal override.

This is not a magic option in itself, but you can use it in your menu as long as you also use it in your test techniques.

You can provide the word "send" alone with no item name. To make use of just "send" your sidekick must return just "send" during its test phase, even if the actual item is not fully identified (See PT sidekick for examples). Just "send" is also picked up by the "sendall" magic option.

This becomes useful because even when a send-type post is not fully identified, sendall will still recognize it as a send-type post and will perform collection on that post.