2016-12-19 05:52:49 -08:00
--[[ Example for Documentation System [`doc`].
Reminder This mod is the core of the Help modpack . It is thus rather low - level .
Use this to add your very own categories and entries .
This example demonstrates how to add categories and how to add entries into them .
It also demonstrates the versality of the very important ` build_formspec ` field of
categories .
] ]
-- Let's start with a very simple text-based category
2016-12-19 10:00:52 -08:00
-- This category only contains simple text
2016-12-15 14:27:11 -08:00
doc.new_category ( " example1 " , {
2016-12-19 05:52:49 -08:00
-- This is for humans and mandatory
2016-12-15 14:27:11 -08:00
name = " Text Example " ,
-- This category uses a preset formspec builder for displaying simple text
build_formspec = doc.entry_builders . text
2016-12-19 05:52:49 -08:00
-- Reminder: build_formspec determines how the entry data will be presented to the user
2016-12-15 14:27:11 -08:00
} )
2016-12-19 10:00:52 -08:00
-- Entry for the aforementioned category. We add 2 entries
2016-12-15 14:27:11 -08:00
doc.new_entry ( " example1 " , " text " , {
2016-12-19 10:00:52 -08:00
-- This is for the entry title in the user interface, it's mandatory
2016-12-15 14:27:11 -08:00
name = " Text example " ,
2016-12-19 05:52:49 -08:00
-- For this category, the entry data is simply the text to be displayed
2016-12-15 14:27:11 -08:00
data = " Lorem Minetest dolor sit amet. Bla bla bla bla Minetest bla bla bla bla Mese bla. Bla bla bla bla bla, celeron55 bla bla, bla. " ,
} )
2016-12-19 10:00:52 -08:00
-- We will use this entry in doc_identifier.lua
doc.new_entry ( " example1 " , " entity " , {
name = " Entity entry " ,
data = " This is the entry for the entity (added in doc_identifier.lua). The example entity is just a boring cube which floats in the air. Punch it to destroy it. " ,
} )
2016-12-19 05:52:49 -08:00
-------------------------------------------------------------------------------
-- Category with hidden entry.
-- This is a category like the one before, but this time, we add one entry which starts hidden
2016-12-15 14:27:11 -08:00
doc.new_category ( " example_hide " , {
name = " Example Hidden " ,
build_formspec = doc.entry_builders . text
} )
2016-12-19 05:52:49 -08:00
-- This entry will start hidden. The user will not see it until it gets revealed by using
-- `doc.mark_entry_as_revealed`.
-- TODO: Add example for that, too
doc.new_entry ( " example_hide " , " hidden " , {
2016-12-15 14:27:11 -08:00
name = " Hidden Entry " ,
2016-12-19 05:52:49 -08:00
hidden = true ,
2016-12-15 14:27:11 -08:00
data = " This entry is hidden. " ,
} )
2016-12-19 05:52:49 -08:00
-------------------------------------------------------------------------------
--[[ A simple category with 3 entries: Cities.
Now we ' re getting somewhere! This time, we define a custom build_formspec function to display
entry data dynamically . ] ]
2016-12-15 14:27:11 -08:00
doc.new_category ( " example2 " , {
2016-12-19 05:52:49 -08:00
name = " Example: Cities " ,
description = " Example category: Quick information about the cities of the world " ,
2016-12-15 14:27:11 -08:00
-- This is a manual formspec builder: This will parse the entry data and turns it into nice formspec widgets
2016-12-19 05:52:49 -08:00
-- Reminder: We MUST return a valid formspec string
2016-12-15 14:27:11 -08:00
build_formspec = function ( data )
return " label[0,1;Description: " .. minetest.formspec_escape ( data.description ) .. " ] " ..
" label[0,2;Population: " .. data.population .. " ] "
end ,
2016-12-19 05:52:49 -08:00
--[[ Sorting example ]]
-- The entry data includes population as a number. This means we could (if we want to) define a custom sorting functino
--[[ This affects the order of the entries. It makes sure that in the list of entries, the city with the highest population
comes first . Custom sorting is entirely optional but it might make it easier for the user to navigate . But note that the
default alphabetical sorting is often good enough . ] ]
sorting = " function " ,
sorting_data = function ( entry1 , entry2 )
return entry1.data . population > entry2.data . population
end ,
2016-12-15 14:27:11 -08:00
} )
doc.new_entry ( " example2 " , " london " , {
name = " London " ,
2016-12-19 05:52:49 -08:00
-- Reminder: This data is put into the previous build_formspec function
2016-12-15 14:27:11 -08:00
data = {
description = " London is the capital of the United Kingdom. " ,
population = 8538689 ,
} ,
} )
doc.new_entry ( " example2 " , " shanghai " , {
name = " Shanghai " ,
data = {
description = " Shanghai lies in China and is one of the biggest cities in the world. " ,
population = 23019148 ,
} ,
} )
doc.new_entry ( " example2 " , " tripoli " , {
name = " Tripoli " ,
data = {
description = " Tripoli is the capital of Lybia. " ,
population = 1780000 ,
} ,
} )
2016-12-19 05:52:49 -08:00
-------------------------------------------------------------------------------
--[[ Formspec category: This category shows how you can add widgets in entries and even interact with them ]]
2016-12-15 14:27:11 -08:00
doc.new_category ( " example3 " , {
name = " Example: Formspec " ,
description = " Example category for manual freeform formspec entries " ,
2016-12-19 05:52:49 -08:00
-- This is a built-in formspec builder. In this case, the entry data is expected
-- to contains the full formspec definition for any entry. This is useful if you want
-- to build every entry by hand. The downside is that it doesn't allow for dynamic entries.
2016-12-15 14:27:11 -08:00
build_formspec = doc.entry_builders . formspec ,
2016-12-19 05:52:49 -08:00
--[[ Sorting example ]]
-- This demonstates the custom sorting type. In the entry list, the entries will appear in the exact order as specified
sorting = " custom " ,
sorting_data = { " simple " , " widgets " , " testbutton " } ,
2016-12-15 14:27:11 -08:00
} )
doc.new_entry ( " example3 " , " simple " , {
name = " Label " ,
2016-12-19 05:52:49 -08:00
-- Please note the coordinates are shoddily chosen here.
-- FIXME: Show how to properly align widgets
2016-12-15 14:27:11 -08:00
data = " label[5,5;Just a label.] "
} )
doc.new_entry ( " example3 " , " widgets " , {
name = " Widget Chaos " ,
-- Just some meaningless widgets for demonstration purposes
data = " label[0,1;Label]label[0,2;Label 2]button[0,3;3,1;example_ignored;Button]textlist[0,4;4,4;example_ignored2;A,B,C,D;]scrollbar[4,1;2,0.2;horizontal;example_ignored3;0] " ,
} )
doc.new_entry ( " example3 " , " testbutton " , {
name = " Event Button " ,
-- This button actually will be used for an event …
data = " button[2,2;3,1;example_button;Event] " ,
} )
2016-12-19 05:52:49 -08:00
-- … and here we react on the button event by writing something into the chat
-- This demonstrates how you can use an entry widget for custom actions
2016-12-15 14:27:11 -08:00
minetest.register_on_player_receive_fields ( function ( player , formname , fields )
-- Condition 1: This checks if the player is even using the entry tab. This check is always the same
if formname == " doc:entry " then
local playername = player : get_player_name ( )
-- Condition 2: this check is required to make sure we “listen” to the correct entry
local category_id , entry_id = doc.get_selection ( playername )
if category_id == " example3 " and entry_id == " testbutton " then
-- Condition 3: Has the widget we actually care about been pressed?
if fields.example_button then
-- All conditions are met! Now the custom action can be executed
minetest.chat_send_player ( playername , " You have pressed the event button! " )
end
end
end
end )
2016-12-19 05:52:49 -08:00
-------------------------------------------------------------------------------
2016-12-15 14:27:11 -08:00
--[[ This category shows off the gallery widget ]]
doc.new_category ( " example4 " , {
name = " Example: Galleries " ,
build_formspec = function ( data , playername )
local formspec = " "
-- Mostly using default values, but we want an aspect ratio of 1:1 (square).
formspec = formspec .. doc.widgets . gallery ( data , playername , nil , nil , 1 )
return formspec
end ,
} )
-- Several gallery entries
doc.new_entry ( " example4 " , " gallery2 " , {
name = " Gallery with 2 images " ,
2016-12-19 05:52:49 -08:00
-- The entry data will be also fed into `doc_widgets_gallery`
2016-12-15 14:27:11 -08:00
data = { { image = " default_grass.png " } , { image = " default_book.png " } } ,
} )
doc.new_entry ( " example4 " , " gallery3 " , {
name = " Gallery with 3 images " ,
data = { { image = " default_grass.png " } , { image = " default_book.png " } , { image = " default_papyrus.png " } } ,
} )
doc.new_entry ( " example4 " , " gallery4 " , {
name = " Gallery with 4 images " ,
data = { { image = " default_dirt.png " } , { image = " default_leaves.png " } , { image = " default_brick.png " } , { image = " default_gold_block.png " } } ,
} )
doc.new_entry ( " example4 " , " gallery5 " , {
name = " Gallery with 5 images " ,
data = { { image = " default_dirt.png " } , { image = " default_leaves.png " } , { image = " default_brick.png " } , { image = " default_gold_block.png " } , { image = " default_bronze_block.png " } } ,
} )
doc.new_entry ( " example4 " , " gallery6 " , {
name = " Gallery with 6 images " ,
data = { { image = " default_grass.png " } , { image = " default_dirt.png " } , { image = " default_leaves.png " } , { image = " default_brick.png " } , { image = " default_gold_block.png " } , { image = " default_bronze_block.png " } } ,
} )
2016-12-19 04:31:59 -08:00
2016-12-15 14:27:11 -08:00
doc.new_entry ( " example4 " , " gallery7 " , {
name = " Gallery with 7 item images " ,
data = {
2016-12-19 04:31:59 -08:00
-- You can use this syntax to display item images instead of normal textures
2016-12-15 14:27:11 -08:00
{ image = " default:bookshelf " , imagetype = " item " } ,
{ image = " default:grass_5 " , imagetype = " item " } ,
{ image = " default:dirt " , imagetype = " item " } ,
{ image = " default:fence_wood " , imagetype = " item " } ,
{ image = " default:flint " , imagetype = " item " } ,
{ image = " default:goldblock " , imagetype = " item " } ,
{ image = " default:bronzeblock " , imagetype = " item " } } ,
} )