From af2ef6476e7414f16a7f5cda1fad849040547dfb Mon Sep 17 00:00:00 2001 From: Relintai Date: Mon, 26 Feb 2024 19:03:39 +0100 Subject: [PATCH] Document the new methods, also expression substitution. --- .../users/doc_classes/UserManagerStatic.xml | 2 - modules/web/doc_classes/HTMLTemplate.xml | 87 +++++++++++++++++-- modules/web/doc_classes/HTMLTemplateData.xml | 14 +-- 3 files changed, 85 insertions(+), 18 deletions(-) diff --git a/modules/users/doc_classes/UserManagerStatic.xml b/modules/users/doc_classes/UserManagerStatic.xml index cdc91fd39..4c7967530 100644 --- a/modules/users/doc_classes/UserManagerStatic.xml +++ b/modules/users/doc_classes/UserManagerStatic.xml @@ -9,8 +9,6 @@ - - diff --git a/modules/web/doc_classes/HTMLTemplate.xml b/modules/web/doc_classes/HTMLTemplate.xml index 304290dde..0d9114eb4 100644 --- a/modules/web/doc_classes/HTMLTemplate.xml +++ b/modules/web/doc_classes/HTMLTemplate.xml @@ -4,16 +4,47 @@ A class that can be used to easily script and render HTML with. - A class that can be used to easily render HTML with. An instance of this class could be a traditional web application's View. - Some traditional web applications use a templating language to render their final output using a set of variables. Some examples: Blade, Handlebars, Razor, etc. Some of these have features like for loops, ifs, they can even support method calls. Thic class implements similar functinality, albeit in a different manner. - The render control logic should be implemented by overriding [method _render], variable substitotions can be done using the available helper methods. + 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. + 8. [code]p(var_arr[0])[/code] - Array indexing. + 9. [code]p(var_dict["x"]), p(var_dict[x]), p(var_dict['x'])[/code] - Dictionary indexing. + 10. [code]p(var1, var2)[/code] - All methods supports multiple arguments. + 11. 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. + 12. Indexing will also call [code]get()[/code] on [Object]s. + 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] Note: For a different approach to generating HTML, you can also take a look at [HTMLBuilder]. - + @@ -27,6 +58,14 @@ Adds a [HTMLTemplateData] template. + + + + + + Turns an [Array] of Variants into [String] using the given method. + + @@ -101,6 +140,22 @@ Returns whether a template override denoted by name is set. + + + + + + Processes an expression in a template. An expression in the template look like: [code]{{ EXPRESSION }}[/code]. + + + + + + + + Processes one variable from an expression in a template. An expression in the template look like: [code]{{ EXPRESSION }}[/code]. + + @@ -133,10 +188,9 @@ - - + - Helper method that does variable substitutions on a given text. + Soes does variable substitutions on the given template text. @@ -157,10 +211,10 @@ - + Returns all template default values. - + Returns all template override values. @@ -168,5 +222,20 @@ + + xml_excape() and add value to the final string. + + + Add value to the final string. + + + xml_excape() and add value to the final string. This also converts newlines into br html tags. + + + Add value to the final string. This also converts newlines into br html tags. + + + vformat the given string, using it's passed variables. + diff --git a/modules/web/doc_classes/HTMLTemplateData.xml b/modules/web/doc_classes/HTMLTemplateData.xml index 63b6beba5..2eabd9102 100644 --- a/modules/web/doc_classes/HTMLTemplateData.xml +++ b/modules/web/doc_classes/HTMLTemplateData.xml @@ -8,19 +8,19 @@ It uses a cusom format, which should make it easy to edit. Create files using the [code].phtpl[/code] (Pandemonium HTML Template) file extenstion, the editor will import those files as this class. Double clicking on them will directly open them in the Text Editor (if available). The [code].phtpl[/code] file format looks a bit similar to config files, except it's a lot simpler. For example: [code] - + [ Head ] - + ... Head html here - + [ Content ] - + ... Content html here - + [ Shell ] - + ... Shell html here - + [/code] This file will be parsed as 3 key-value template strings. A key named [code]Head[/code] with the content [code]... Head html here[/code], a key named [code]Content[/code] with the content [code]... Content html here[/code] and a key named [code]Shell[/code] with the content [code]... Shell html here[/code]. Note: Make sure there is no whitespace before and after the square brackets of the section keys. Also note that white space will be stripped on both sides of the keys before storing them.