2024-02-25 19:17:06 +01:00
<?xml version="1.0" encoding="UTF-8" ?>
2024-04-26 17:32:25 +02:00
<class name= "HTMLTemplate" inherits= "Resource" version= "4.4" >
2024-02-25 19:17:06 +01:00
<brief_description >
2024-02-25 23:37:46 +01:00
A class that can be used to easily script and render HTML with.
2024-02-25 19:17:06 +01:00
</brief_description>
<description >
2024-02-26 19:03:39 +01:00
A class that can be used to easily render HTML with. An instance of this class could be one of a traditional web application's View. (From the Model-View-Controller or MVC pattern.)
Some traditional web applications use a templating language to render their final output using a set of variables. Some templating language examples: Blade, Handlebars, Razor, etc. Some of these have features like for loops, ifs, they can even support method calls. This class implements similar functinality, albeit in a different manner.
The render control logic should be implemented by overriding [method _render], variable substitutions can be done using the available helper methods.
This class uses a templating syntax like: [code]{{ EXPRESSION }}[/code]. Everything inbetween [code]{{ }}[/code] is an expression that the system will replace during rendering with actual values from a passed in Dictionary.
Assuming you pass in the following Dictionary to [method render_template]:
[code]var d : Dictionary = {
"var": VALUE,
"var1": VALUE,
"var2": VALUE,
"var_dict": {
"x": VALUE
},
"var_arr": [
VALUE,
]
}[/code]
Supported expressions:
0. To escape [code]{{[/code] use: [code]{\{[/code]. [code]{\\{[/code] will turn into [code]{\{[/code] etc.
1. [code]p(var)[/code] - print, escaped, also includes to string cast.
2. [code]{{ var }}[/code] - equivalent to [code]p(var)[/code].
3. [code](var)[/code] - equivalent to [code]p(var)[/code].
4. [code]pr(var)[/code] - print_raw, not escaped, also includes a cast to string.
5. [code]pb(var)[/code] - print_newline_to_br, escaped, turns newlines into br tags, also includes a to string cast.
6. [code]prb(var)[/code] - print_raw_newline_to_br, not escaped, turns newlines into br tags, also includes a to string cast.
7. [code]vf("%d %d", var1, var2)[/code] - vformat or snprintf or String fromatting using % in gdscript.
2024-02-26 21:27:20 +01:00
8. [code]qp(var1, var2)[/code] - Same as p, but only prints when it's first argument evaluates to true. (First arg is not printed!)
9. [code]qpr(var1, var2)[/code] - Same as pr, but only prints when it's first argument evaluates to true. (First arg is not printed!)
10. [code]qpb(var1, var2)[/code] - Same as pb, but only prints when it's first argument evaluates to true. (First arg is not printed!)
11. [code]qprb(var1, var2)[/code] - Same as prb, but only prints when it's first argument evaluates to true. (First arg is not printed!)
12. [code]qvf(var1, "%d %d", var1, var2)[/code] - Same as vf, but only prints when it's first argument evaluates to true. (First arg is not printed!)
13. [code]p(var_arr[0])[/code] - Array indexing.
14. [code]p(var_dict["x"]), p(var_dict[x]), p(var_dict['x'])[/code] - Dictionary indexing.
15. [code]p(var1, var2)[/code] - All methods supports multiple arguments.
16. Let's say [code]var1[/code] is a [Vector3], [code]var["x"][/code] and [code]var[0][/code] and [code]var[x][/code] will also work.
17. Indexing will also call [code]get()[/code] on [Object]s.
2024-02-26 19:03:39 +01:00
Not supported:
0. [code]p(var[var[var[2]]])[/code] Recursive indexing.
1. No actual method calls. Make everything available that your templates need in your controller class!
So this is how your HTML will look like: [code]... HTML markup ... {{ p(var) }} ... {{ pr(var) }} ... {{ pb(var) }} ... {{ prb(var, var2) }} ... {{ vf("%d %d", var1, var2) }} ... etc.[/code]
2024-02-25 23:37:46 +01:00
Note: For a different approach to generating HTML, you can also take a look at [HTMLBuilder].
2024-02-25 19:17:06 +01:00
</description>
<tutorials >
</tutorials>
<methods >
<method name= "_render" qualifiers= "virtual" >
2024-02-26 19:03:39 +01:00
<return type= "String" />
2024-02-25 19:17:06 +01:00
<argument index= "0" name= "request" type= "WebServerRequest" />
<argument index= "1" name= "data" type= "Dictionary" />
<description >
2024-02-25 23:37:46 +01:00
Override this method to implement your own rendering for any given HTMLTemplate.
2024-02-25 19:17:06 +01:00
</description>
</method>
<method name= "add_template" >
<return type= "void" />
<argument index= "0" name= "template" type= "HTMLTemplateData" />
<description >
2024-02-25 23:37:46 +01:00
Adds a [HTMLTemplateData] template.
2024-02-25 19:17:06 +01:00
</description>
</method>
2024-02-26 19:03:39 +01:00
<method name= "call_template_method" >
<return type= "String" />
<argument index= "0" name= "method" type= "int" enum= "HTMLTemplate.TemplateExpressionMethods" />
<argument index= "1" name= "data" type= "Array" />
2024-02-26 21:33:40 +01:00
<argument index= "2" name= "first_var_decides_print" type= "bool" />
2024-02-26 19:03:39 +01:00
<description >
Turns an [Array] of Variants into [String] using the given method.
</description>
</method>
2024-02-25 19:17:06 +01:00
<method name= "clear_template_defaults" >
<return type= "void" />
<description >
2024-02-25 23:37:46 +01:00
Clears template defaults.
2024-02-25 19:17:06 +01:00
</description>
</method>
<method name= "clear_template_overrides" >
<return type= "void" />
<description >
2024-02-25 23:37:46 +01:00
Clears template overrides.
2024-02-25 19:17:06 +01:00
</description>
</method>
<method name= "clear_templates" >
<return type= "void" />
<description >
2024-02-25 23:37:46 +01:00
Clears templates.
2024-02-25 19:17:06 +01:00
</description>
</method>
<method name= "get_and_render_template" >
<return type= "String" />
<argument index= "0" name= "name" type= "StringName" />
2024-02-26 11:36:13 +01:00
<argument index= "1" name= "data" type= "Dictionary" />
2024-02-25 19:17:06 +01:00
<description >
2024-02-26 11:36:13 +01:00
Gets a template string using [method get_template] and does method substitutions on it.
2024-02-25 19:17:06 +01:00
</description>
</method>
<method name= "get_template" >
<return type= "HTMLTemplateData" />
<argument index= "0" name= "index" type= "int" />
<description >
2024-02-25 23:37:46 +01:00
Gets a template.
2024-02-25 19:17:06 +01:00
</description>
</method>
<method name= "get_template_count" qualifiers= "const" >
<return type= "int" />
<description >
2024-02-25 23:37:46 +01:00
Returns the template count.
2024-02-25 19:17:06 +01:00
</description>
</method>
<method name= "get_template_default" qualifiers= "const" >
<return type= "String" />
<argument index= "0" name= "name" type= "StringName" />
<description >
2024-02-25 23:37:46 +01:00
Returns a default template value previously set.
2024-02-25 19:17:06 +01:00
</description>
</method>
<method name= "get_template_override" qualifiers= "const" >
<return type= "String" />
<argument index= "0" name= "name" type= "StringName" />
<description >
2024-02-25 23:37:46 +01:00
Returns an override template value previously set.
2024-02-25 19:17:06 +01:00
</description>
</method>
<method name= "get_template_text" >
<return type= "String" />
<argument index= "0" name= "name" type= "StringName" />
<description >
2024-02-25 23:37:46 +01:00
Returns a template text identified by name. This method first looks into overrides, then it tries to get it from [member templates] (in order), and then it tries default values.
2024-02-25 19:17:06 +01:00
</description>
</method>
<method name= "has_template_default" qualifiers= "const" >
<return type= "bool" />
<argument index= "0" name= "name" type= "StringName" />
<description >
2024-02-25 23:37:46 +01:00
Returns whether a template default denoted by name is set.
2024-02-25 19:17:06 +01:00
</description>
</method>
<method name= "has_template_override" qualifiers= "const" >
<return type= "bool" />
<argument index= "0" name= "name" type= "StringName" />
<description >
2024-02-25 23:37:46 +01:00
Returns whether a template override denoted by name is set.
2024-02-25 19:17:06 +01:00
</description>
</method>
2024-02-26 19:03:39 +01:00
<method name= "process_template_expression" >
<return type= "String" />
<argument index= "0" name= "expression" type= "String" />
<argument index= "1" name= "data" type= "Dictionary" />
<description >
Processes an expression in a template. An expression in the template look like: [code]{{ EXPRESSION }}[/code].
</description>
</method>
<method name= "process_template_expression_variable" >
<return type= "Variant" />
<argument index= "0" name= "variable" type= "String" />
<argument index= "1" name= "data" type= "Dictionary" />
2024-02-26 21:58:35 +01:00
<argument index= "2" name= "allow_missing" type= "bool" default= "false" />
2024-02-26 19:03:39 +01:00
<description >
Processes one variable from an expression in a template. An expression in the template look like: [code]{{ EXPRESSION }}[/code].
</description>
</method>
2024-02-25 19:17:06 +01:00
<method name= "remove_template" >
<return type= "void" />
<argument index= "0" name= "index" type= "int" />
<description >
2024-02-25 23:37:46 +01:00
Removes a template.
2024-02-25 19:17:06 +01:00
</description>
</method>
<method name= "remove_template_default" >
<return type= "void" />
<argument index= "0" name= "name" type= "StringName" />
<description >
2024-02-25 23:37:46 +01:00
Removes a template default.
2024-02-25 19:17:06 +01:00
</description>
</method>
<method name= "remove_template_override" >
<return type= "void" />
<argument index= "0" name= "name" type= "StringName" />
<description >
2024-02-25 23:37:46 +01:00
Removes a template override.
2024-02-25 19:17:06 +01:00
</description>
</method>
<method name= "render" >
<return type= "String" />
<argument index= "0" name= "request" type= "WebServerRequest" />
<argument index= "1" name= "data" type= "Dictionary" />
<description >
2024-02-25 23:37:46 +01:00
Use this method to render the final output. This calls [method _render].
2024-02-25 19:17:06 +01:00
</description>
</method>
<method name= "render_template" >
<return type= "String" />
<argument index= "0" name= "text" type= "String" />
2024-02-26 19:03:39 +01:00
<argument index= "1" name= "data" type= "Dictionary" />
2024-02-25 19:17:06 +01:00
<description >
2024-02-26 19:03:39 +01:00
Soes does variable substitutions on the given template text.
2024-02-25 19:17:06 +01:00
</description>
</method>
<method name= "set_template_default" >
<return type= "void" />
<argument index= "0" name= "name" type= "StringName" />
<argument index= "1" name= "value" type= "String" />
<description >
2024-02-25 23:37:46 +01:00
Sets a template default value.
2024-02-25 19:17:06 +01:00
</description>
</method>
<method name= "set_template_override" >
<return type= "void" />
<argument index= "0" name= "name" type= "StringName" />
<argument index= "1" name= "value" type= "String" />
<description >
2024-02-25 23:37:46 +01:00
Sets a template override value.
2024-02-25 19:17:06 +01:00
</description>
</method>
</methods>
<members >
2024-02-26 19:03:39 +01:00
<member name= "template_defaults" type= "Dictionary" setter= "set_template_defaults" getter= "get_template_defaults" >
2024-02-25 23:37:46 +01:00
Returns all template default values.
2024-02-25 19:17:06 +01:00
</member>
2024-02-26 19:03:39 +01:00
<member name= "template_overrides" type= "Dictionary" setter= "set_template_overrides" getter= "get_template_overrides" >
2024-02-25 23:37:46 +01:00
Returns all template override values.
2024-02-25 19:17:06 +01:00
</member>
<member name= "templates" type= "Array" setter= "set_templates" getter= "get_templates" default= "[ ]" >
2024-02-25 23:37:46 +01:00
Returns all templates.
2024-02-25 19:17:06 +01:00
</member>
</members>
<constants >
2024-02-26 19:03:39 +01:00
<constant name= "TEMPLATE_EXPRESSION_METHOD_PRINT" value= "0" enum= "TemplateExpressionMethods" >
xml_excape() and add value to the final string.
</constant>
<constant name= "TEMPLATE_EXPRESSION_METHOD_PRINT_RAW" value= "1" enum= "TemplateExpressionMethods" >
Add value to the final string.
</constant>
<constant name= "TEMPLATE_EXPRESSION_METHOD_PRINT_BR" value= "2" enum= "TemplateExpressionMethods" >
xml_excape() and add value to the final string. This also converts newlines into br html tags.
</constant>
<constant name= "TEMPLATE_EXPRESSION_METHOD_PRINT_RAW_BR" value= "3" enum= "TemplateExpressionMethods" >
Add value to the final string. This also converts newlines into br html tags.
</constant>
<constant name= "TEMPLATE_EXPRESSION_METHOD_VFORMAT" value= "4" enum= "TemplateExpressionMethods" >
vformat the given string, using it's passed variables.
</constant>
2024-02-25 19:17:06 +01:00
</constants>
</class>