Htmlform - Revision history

StDoodle at 15:57, 3 December 2010

2010-12-03T15:57:22Z

← Older revision		Revision as of 15:57, 3 December 2010
Line 14:		Line 14:
	There are two global variables defined by the library that you'll need to know about:		There are two global variables defined by the library that you'll need to know about:
	'''string [string]''' ''fields'' is a map holding the result of a call to {{f\|form_fields}}. The current value of any input element can be retrieved as '''''fields[name]''''', although you probably won't have to do that very often as the functions that actually write the elements to the page will return the current value of that element. You can also modify values in the map, prior to writing the corresponding element, to change their value - for example, to change the default values of certain fields based on the user's input in other fields.		'''string [string]''' ''fields'' is a map holding the result of a call to {{f\|form_fields}}. The current value of any input element can be retrieved as '''''fields[name]''''', although you probably won't have to do that very often as the functions that actually write the elements to the page will return the current value of that element. You can also modify values in the map, prior to writing the corresponding element, to change their value - for example, to change the default values of certain fields based on the user's input in other fields.
	The global '''boolean''' ''success'' is true when a valid page submission has occurred - the fields map will be non-empty (unlike the initial run of the script in which the choices are initially shown in the browser), and none of the fields have a validation failure. Button actions should generally be conditional on this variable being true (and will automatically be so, if you use the ~~[[#test_button~~\|test_button~~()]]~~ function).		The global '''boolean''' ''success'' is true when a valid page submission has occurred - the fields map will be non-empty (unlike the initial run of the script in which the choices are initially shown in the browser), and none of the fields have a validation failure. Button actions should generally be conditional on this variable being true (and will automatically be so, if you use the {{fa\|test_button}} function).

	All other internal global variables, and functions for internal use, have names starting with an underscore, to minimize the chance of a name collision with your script.		All other internal global variables, and functions for internal use, have names starting with an underscore, to minimize the chance of a name collision with your script.
Line 31:		Line 31:
	void attr( string attribute )		void attr( string attribute )
	The string will be inserted at the appropriate place in the HTML tag being written. If called multiple times, the strings will be separated by spaces.		The string will be inserted at the appropriate place in the HTML tag being written. If called multiple times, the strings will be separated by spaces.


	{{att_box\|<p>{{att\|title='TEXT'}} will add a tooltip to any element. Advanced users may want to use style & class attributes for fine control over element appearance. A complete list of attributes is entirely beyond the scope of this documentation (see any HTML reference, instead), but the most useful ones will be pointed out in blocks like this.</p>}}		{{att_box\|<p>{{att\|title='TEXT'}} will add a tooltip to any element. Advanced users may want to use style & class attributes for fine control over element appearance. A complete list of attributes is entirely beyond the scope of this documentation (see any HTML reference, instead), but the most useful ones will be pointed out in blocks like this.</p>}}
Line 36:		Line 37:
	== Validators ==		== Validators ==

	The functions that produce a field for the user to type in (write_field() and write_textarea()) can be passed the name of a validator function that can check (and possibly modify) the field value. Any validation failure is shown in red to the right of the field, and blocks submission of the form until the user corrects the problem. Validator functions are provide for all the datatypes for which typed-in values make sense:		The functions that produce a field for the user to type in (both {{fa\|write_field}} and {{fa\|write_textarea}}) can be passed the name of a validator function that can check (and possibly modify) the field value. Any validation failure is shown in red to the right of the field, and blocks submission of the form until the user corrects the problem. Validator functions are provide for all the datatypes for which typed-in values make sense:
	intvalidator, floatvalidator, itemvalidator, locationvalidator, skillvalidator, effectvalidator, familiarvalidator, monstervalidator		'''intvalidator, floatvalidator, itemvalidator, locationvalidator, skillvalidator, effectvalidator, familiarvalidator, monstervalidator'''
	(They AREN'T provided for types like 'class' and 'slot' that have only a few possible values; other input elements are more appropriate in those cases).		(They AREN'T provided for types like 'class' and 'slot' that have only a few possible values; other input elements are more appropriate in those cases).
	None of these accept the 'none' value; there is a separate itemnonevalidator that will accept items or 'none' (similar validators for other types didn't seem likely to be as useful). There is also a nonemptyvalidator that simply requires the entered string to not be blank.		None of these accept the 'none' value; there is a separate '''itemnonevalidator''' that will accept items or 'none' (similar validators for other types didn't seem likely to be as useful). There is also a '''nonemptyvalidator''' that simply requires the entered string to not be blank.

	intvalidator and floatvalidator ~~additionally~~ support bounds checking via the function:		Additionally, '''intvalidator''' and '''floatvalidator''' support bounds checking via the function:
	void ~~range(~~ float min, float max ~~) - place~~ this just before the call to write_field().		{{HideLink\|range}}{{Function\|
			name=range\|
			return_type=void\|
			parameter1={{Param\|float\|min}}\|
			parameter2={{Param\|float\|max}}\|
			}}
			Pace this just before the call to {{fa\|write_field}}.

	The provided validators only check that the entered text is something understandable to KoLmafia - not that you (for example) actually have the named familiar, or that the item goes in some specific slot. If you want to perform such checks, you'll need to write your own validator, which is just a function with one string parameter (the element name), that returns a string. Any non-empty string is treated as a validation error. Returning an empty string indicates success, in which case the function is allowed to modify the value in the fields[] map, which will update the value shown in the browser. (That's why the function is passed the field name, rather than the field value. All of the built-in validators that allow fuzzy matching use this feature, in order to replace an abbreviated user entry with the full, proper name of the object.) Here's a simple example that verifies that the entered text is a valid item (duplicating the function of itemvalidator), which furthermore is a hat that you own:		The provided validators only check that the entered text is something understandable to KoLmafia - not that you (for example) actually have the named familiar, or that the item goes in some specific slot. If you want to perform such checks, you'll need to write your own validator, which is just a function with one string parameter (the element name), that returns a string. Any non-empty string is treated as a validation error. Returning an empty string indicates success, in which case the function is allowed to modify the value in the fields[] map, which will update the value shown in the browser. (That's why the function is passed the field name, rather than the field value. All of the built-in validators that allow fuzzy matching use this feature, in order to replace an abbreviated user entry with the full, proper name of the object.) Here's a simple example that verifies that the entered text is a valid item (duplicating the function of itemvalidator), which furthermore is a hat that you own:

	== ~~Generating~~ the ~~Page Structure~~ ==		{{CodeSample\|
			code=<syntaxhighlight>
			string hatvalidator(string name)
			{
			item it = to_item(fields[name]);
			if (it == $item[none]) {
			return "A valid hat is required.";
			}
			fields[name] = to_string(it); // normalize
			if (item_type(it) != "hat") {
			return "That's not a hat.";
			}
			if (available_amount(it) == 0) {
			return "You don't have that hat.";
			}
			return ""; // success!
			}
			</syntaxhighlight>\|}}
			You'd then pass "hatvalidator" as the 4th parameter to {{fa\|write_field}}.

			== Top-Level Functions ==

	{{HideLink\|write_header}}{{Function\|		{{HideLink\|write_header}}{{Function\|
	name=write_header\|		name=write_header\|
	return_type=void\|		return_type=void\|
	}}		}}{{HideLink\|finish_header}}{{Function\|
	{{Function\|
	name=finish_header\|		name=finish_header\|
	return_type=void\|		return_type=void\|
	}}		}}{{HideLink\|write_page}}{{Function\|
	{{Function\|
	name=write_page\|		name=write_page\|
	return_type=void\|		return_type=void\|
	}}		}}
	write_page() is equivalent to write_header() followed by finish_header(), but the separate functions may be preferred so that you can add information into the page header such as a script or stylesheet.		{{fa\|write_page}} is equivalent to {{fa\|write_header}} followed by {{fa\|finish_header}}, but the separate functions may be preferred so that you can add information into the page header such as a script or stylesheet.

	{{HideLink\|finish_page}}{{Function\|		{{HideLink\|finish_page}}{{Function\|
Line 71:		Line 97:
	parameter1={{Param\|string\|label}}\|		parameter1={{Param\|string\|label}}\|
	return_type=void\|		return_type=void\|
	}}		}}{{HideLink\|finish_box}}{{Function\|
	{{Function\|
	name=finish_box\|		name=finish_box\|
	return_type=void\|		return_type=void\|
Line 78:		Line 103:
	These can be used in matched pairs around a group of elements to enclose them in a box. The label will be at the top of the box.<br />		These can be used in matched pairs around a group of elements to enclose them in a box. The label will be at the top of the box.<br />
	'''attr("align=center")''' or '''attr("align=right")''' will change the position of the label.		'''attr("align=center")''' or '''attr("align=right")''' will change the position of the label.



			{{HideLink\|test_button}}{{Function\|
			name=test_button\|
			return_type=boolean\|
			}}



	== Making use of HTMLform ==		== Making use of HTMLform ==

StDoodle at 15:30, 3 December 2010

2010-12-03T15:30:00Z

@@ Line 4: / Line 4: @@
 }}
 == About jasonharper's Form Library ==
-It does stuff with forms. Like Magic. Also, it turns your body into html so that all your attacks will do html damage. This is obviously placeholder text, duh.
+[http://kolmafia.us/showthread.php?3842 HTMLform] is a code library for building relay browser scripts that accept user input.
-Note: This author wants to warn the user that you actually turn into an xml document, not an html document. While your damage will still be similar to html damage, this actually leaves you vulnerable to attacks by the W3C should you ever fail to validate against your schema. Oh the horror!
+== Scope ==
-== Functions ==
+The purpose of HTMLform is to allow you to write relay scripts without necessarily having a deep knowledge of HTML forms (although you will need to know at least a bit about HTML formatting if you want your scripts to look nice). It is designed to make the process of gathering input from the user look like a simple sequence of prompts, when in fact the script is being reloaded multiple times in order to present and validate the user's choices.
-=== Generating the Page Structure ===
+== Globals ==
 {{HideLink|write_header}}{{Function|
 name=write_header|

StDoodle: lies & damn lies (I'm bored)

2010-11-29T19:52:37Z

lies & damn lies (I'm bored)

← Older revision		Revision as of 19:52, 29 November 2010
Line 5:		Line 5:
	== About jasonharper's Form Library ==		== About jasonharper's Form Library ==
	It does stuff with forms. Like Magic. Also, it turns your body into html so that all your attacks will do html damage. This is obviously placeholder text, duh.		It does stuff with forms. Like Magic. Also, it turns your body into html so that all your attacks will do html damage. This is obviously placeholder text, duh.

			Note: This author wants to warn the user that you actually turn into an xml document, not an html document. While your damage will still be similar to html damage, this actually leaves you vulnerable to attacks by the W3C should you ever fail to validate against your schema. Oh the horror!

	== Functions ==		== Functions ==

StDoodle: /* Making use of HTMLform */

2010-11-29T19:49:04Z

Making use of HTMLform

← Older revision		Revision as of 19:49, 29 November 2010
Line 47:		Line 47:
	code=		code=
	<syntaxhighlight>		<syntaxhighlight>
	import "~~zlib~~.ash";		import "htmlform.ash";
	</syntaxhighlight>}}		</syntaxhighlight>}}
	Then all these functions will be available in your script. Have fun! Note that most of these functions are intended for use in relay info scripts, which must be placed in the /relay directory (top-level only, no sub-directories) and must begin with "relay_" to show in the user's relay browser.		Then all these functions will be available in your script. Have fun! Note that most of these functions are intended for use in relay info scripts, which must be placed in the /relay directory (top-level only, no sub-directories) and must begin with "relay_" to show in the user's relay browser.

StDoodle: /* Making use of HTMLform */

2010-11-29T19:48:49Z

Making use of HTMLform

← Older revision		Revision as of 19:48, 29 November 2010
Line 43:		Line 43:
	== Making use of HTMLform ==		== Making use of HTMLform ==

	To include this library in your script, simply add the following towards the top ~~of your~~ script:		To include this library in your script, first you must download it from the location provided below and make sure it is in your /scripts directory (or a sub-directory thereof). Then, simply add the following towards the top any script in which you wish to have access to these functions:
	{{CodeSample\|		{{CodeSample\|
	code=		code=
	<syntaxhighlight>		<syntaxhighlight>
	import "~~htmlform~~.ash";		import "zlib.ash";
	</syntaxhighlight>}}		</syntaxhighlight>}}
	Then all these functions will be available in your script. Have fun!		Then all these functions will be available in your script. Have fun! Note that most of these functions are intended for use in relay info scripts, which must be placed in the /relay directory (top-level only, no sub-directories) and must begin with "relay_" to show in the user's relay browser.

	== More Information ==		== More Information ==

StDoodle at 19:45, 29 November 2010

2010-11-29T19:45:29Z

← Older revision		Revision as of 19:45, 29 November 2010
Line 1:		Line 1:
	{{TOCright}}{{DISPLAYTITLE:HTMLform (htmlform.ash)}}		{{TOCright}}{{DISPLAYTITLE:HTMLform (htmlform.ash)}}
			{{Attention\|
			This page details the use of functions in a script library. The information here is only useful to those who have followed the included steps to make use of these functions; they are not built-in to KoLmafia.
			}}
	== About jasonharper's Form Library ==		== About jasonharper's Form Library ==
	It does stuff with forms. Like Magic. Also, it turns your body into html so that all your attacks will do html damage. This is obviously placeholder text, duh.		It does stuff with forms. Like Magic. Also, it turns your body into html so that all your attacks will do html damage. This is obviously placeholder text, duh.

Bale: Adding some functions. Joy.

2010-11-29T10:36:11Z

Adding some functions. Joy.

@@ Line 5: / Line 5: @@
 == Functions ==
 {{HideLink|write_header}}{{Function|
 name=write_header|
 return_type=void|
 }}
-Writes the header, yo.
+{{Function|
 == Making use of HTMLform ==

Bale: forgot this important effect

2010-11-29T08:25:43Z

forgot this important effect

← Older revision		Revision as of 08:25, 29 November 2010
Line 1:		Line 1:
	{{TOCright}}{{DISPLAYTITLE:HTMLform (htmlform.ash)}}		{{TOCright}}{{DISPLAYTITLE:HTMLform (htmlform.ash)}}
	== About jasonharper's Form Library ==		== About jasonharper's Form Library ==
	It does stuff with forms. Like Magic. This is obviously placeholder text, duh.		It does stuff with forms. Like Magic. Also, it turns your body into html so that all your attacks will do html damage. This is obviously placeholder text, duh.

	== Functions ==		== Functions ==

StDoodle: Created page with '{{TOCright}}{{DISPLAYTITLE:HTMLform (htmlform.ash)}} == About jasonharper's Form Library == It does stuff with forms. Like Magic. This is obviously placeholder text, duh. == Fun…'

2010-11-29T07:12:30Z

Created page with '{{TOCright}}{{DISPLAYTITLE:HTMLform (htmlform.ash)}} == About jasonharper's Form Library == It does stuff with forms. Like Magic. This is obviously placeholder text, duh. == Fun…'

New page

{{TOCright}}{{DISPLAYTITLE:HTMLform (htmlform.ash)}}
== About jasonharper's Form Library ==
It does stuff with forms. Like Magic. This is obviously placeholder text, duh.

== Functions ==

{{HideLink|write_header}}{{Function|
name=write_header|
return_type=void|
}}
Writes the header, yo.

== Making use of HTMLform ==

To include this library in your script, simply add the following towards the top of your script:
{{CodeSample|
code=
<syntaxhighlight>
import "htmlform.ash";
</syntaxhighlight>}}
Then all these functions will be available in your script. Have fun!

== More Information ==
<p>See the thread for HTMLform on the KoLmafia forum [http://kolmafia.us/showthread.php?3842 here].</p>

[[Category:Scripting]][[Category:ASH Function Libraries]]