Formspecs: examples, clarification and images

chapters/formspecs.md

@@ -7,6 +7,13 @@ root: ../
 Introduction
 ------------
 
+<figure class="right_image">
+	<img src="{{ page.root }}/static/formspec_example.png" alt="Furnace Inventory">
+	<figcaption>
+		Screenshot of furnace formspec, labelled.
+	</figcaption>
+</figure>
+
 In this chapter we will learn how to create a formspec and display it to the user.
 A formspec is the specification code for a form.
 In Minetest, forms are windows like the Inventory which allow you to move your mouse
@@ -27,7 +34,7 @@ Formspec Syntax
 Formspecs have a rather weird syntax.
 They consist of a series of tags which are in the following form:
 
-	element[param1;param2;...]
+	element_type[param1;param2;...]
 
 Firstly the element type is declared, and then the attributes are given in square brackets.
 
@@ -47,8 +54,9 @@ The x and y values are separated by a comma, as you can see above.
 
 ### Field[x, y; w, h; name; label; default]
 
-Most elements follow a similar form to this. The name attribute is used in callbacks
-to get the submitted information. The others are pretty self-explaintary.
+This is a textbox element. Most other elements have a similar style of attributes.
+The "name" attribute is used in callbacks to get the submitted information.
+The others are pretty self-explaintary.
 
 	field[1,1;3,1;firstname;Firstname;]
 
@@ -74,9 +82,43 @@ to see, along with the formname.
 Formnames are used in callbacks to identify which form has been submitted,
 and see if the callback is relevant.
 
+### Example
+
+<figure class="right_image">
+	<img src="{{ page.root }}/static/formspec_name.png" alt="Name Formspec">
+	<figcaption>
+		The formspec generated by<br />
+		the example's code
+	</figcaption>
+</figure>
+
+{% highlight lua %}
+-- Show form when the /formspec command is used.
+minetest.register_chatcommand("formspec", {
+	func = function(name, param)
+		minetest.show_formspec(name, "mymod:form",
+				"size[4,3]" ..
+				"label[0,0;Hello, " .. name .. "]" ..
+				"field[1,1.5;3,1;name;Name;]" ..
+				"button_exit[1,2;2,1;exit;Save]")
+	end
+})
+{% endhighlight %}
+
+The above example shows a formspec to a player when they use the /formspec command.
+
+Note: the .. is used to join two strings together. The following two lines are equivalent:
+
+{% highlight lua %}
+"foobar"
+"foo" .. "bar"
+{% endhighlight %}
+
 Callbacks
 ---------
 
+Let's expand on the above example.
+
 {% highlight lua %}
 -- Show form when the /formspec command is used.
 minetest.register_chatcommand("formspec", {
@@ -126,6 +168,15 @@ Some elements can submit the form without the user having to click a button,
 such as a check box. You can detect for these cases by looking
 for a clicked button.
 
+{% highlight lua %}
+-- An example of what fields could contain,
+--   using the above code
+{
+	name = "Foo Bar",
+	exit = true
+}
+{% endhighlight %}
+
 Contexts
 --------
 
@@ -133,10 +184,14 @@ In quite a lot of cases you want your minetest.show_formspec to give information
 to the callback which you don't want to have to send to the client. Information
 such as what a chat command was called with, or what the dialog is about.
 
-Let's say you are making a form to handle land protection information. Here is
-how you would do it:
+Let's say you are making a form to handle land protection information.
 
 {% highlight lua %}
+--
+-- Step 1) set context when player requests the formspec
+--
+
+-- land_formspec_context[playername] gives the player's context.
 local land_formspec_context = {}
 
 minetest.register_chatcommand("land", {
@@ -157,6 +212,11 @@ minetest.register_chatcommand("land", {
 	end
 })
 
+
+
+--
+-- Step 2) retrieve context when player submits the form
+--
 minetest.register_on_player_receive_fields(function(player, formname, fields)
 	if formname ~= "mylandowner:edit" then
 		return false

static/style.css

@@ -10,6 +10,21 @@ a {
 	text-decoration: underline;
 }
 
+.right_image {
+	float: right;
+	margin: 0 0 0 10px;
+	padding: 0;
+}
+
+.right_image img {
+	margin: 0;
+	padding: 0;
+}
+
+.right_image figcaption {
+	padding: 0 0 0 6px;
+}
+
 #page {
 	background: white;
 	margin: 0;
@@ -91,6 +106,7 @@ h2 {
 	margin: 30px 0 10px 0;
 	display: block;
 	padding: 0 0 5px 0;
+	clear: both;
 }
 
 h3 {