From ae19991c63143969987b40f9d3bcd59811a36f90 Mon Sep 17 00:00:00 2001 From: Relintai Date: Mon, 22 Aug 2022 00:01:10 +0200 Subject: [PATCH] Added descriptions and brief descriptions for most of the classes in the web module. --- modules/web/doc_classes/BBCodeParser.xml | 4 ++++ .../web/doc_classes/BBCodeParserAttribute.xml | 3 +++ modules/web/doc_classes/BBCodeParserTag.xml | 3 +++ modules/web/doc_classes/FileCache.xml | 7 +++++++ modules/web/doc_classes/FormField.xml | 4 ++++ modules/web/doc_classes/FormFieldEntry.xml | 2 ++ modules/web/doc_classes/FormValidator.xml | 18 ++++++++++++++++++ modules/web/doc_classes/HTMLBuilder.xml | 16 ++++++++++++++++ modules/web/doc_classes/HTMLPaginator.xml | 5 +++++ modules/web/doc_classes/HTMLParser.xml | 14 ++++++++++++++ .../web/doc_classes/HTMLParserAttribute.xml | 3 +++ modules/web/doc_classes/HTMLParserTag.xml | 3 +++ modules/web/doc_classes/HTMLTag.xml | 9 +++++++++ modules/web/doc_classes/HTTPServerEnums.xml | 2 ++ modules/web/doc_classes/MarkdownRenderer.xml | 2 ++ .../SessionSetupWebServerMiddleware.xml | 3 +++ modules/web/doc_classes/WebServerCookie.xml | 2 ++ 17 files changed, 100 insertions(+) diff --git a/modules/web/doc_classes/BBCodeParser.xml b/modules/web/doc_classes/BBCodeParser.xml index 3259a0145..bef7e9cba 100644 --- a/modules/web/doc_classes/BBCodeParser.xml +++ b/modules/web/doc_classes/BBCodeParser.xml @@ -1,8 +1,12 @@ + A class that parses bbcode into a class structure for easy manipulation, or processing. + The BBCodeParser class works the same way as the HTMLParser class, except it parses BBCode, which is a bit simpler, so some complexity was removed. + BBCode was created for providing a safer and simpler format for formatting post on forums. It is very similar to html. + For example: [code][b]This text should would be bold if this bbcode was interpreted.[/b] [size=14]This text would have a font size of 14.[/size] etc.[/code] diff --git a/modules/web/doc_classes/BBCodeParserAttribute.xml b/modules/web/doc_classes/BBCodeParserAttribute.xml index 3191d8e20..9efa75aa8 100644 --- a/modules/web/doc_classes/BBCodeParserAttribute.xml +++ b/modules/web/doc_classes/BBCodeParserAttribute.xml @@ -1,8 +1,11 @@ + [BBCodeParser] stores bbcode attributes using this class. + [BBCodeParser] stores bbcode attributes using this class. + It has helper methods for searching and modifying data. diff --git a/modules/web/doc_classes/BBCodeParserTag.xml b/modules/web/doc_classes/BBCodeParserTag.xml index 7d00ed9aa..46e7fc07c 100644 --- a/modules/web/doc_classes/BBCodeParserTag.xml +++ b/modules/web/doc_classes/BBCodeParserTag.xml @@ -1,8 +1,11 @@ + [BBCodeParser] stores bbcode tags using this class. + [BBCodeParser] stores bbcode tags using this class. + It has helper methods for searching and modifying data. diff --git a/modules/web/doc_classes/FileCache.xml b/modules/web/doc_classes/FileCache.xml index 8f0941ec5..e9bece44c 100644 --- a/modules/web/doc_classes/FileCache.xml +++ b/modules/web/doc_classes/FileCache.xml @@ -1,8 +1,15 @@ + The FileCache class provide functionality for file and directory caching for the web module. + The FileCache class provide functionality for file and directory caching for the web module. + It can evaluate a folder, and save all file paths into memory. + Using this functionality can increase performance in certain scenarios, as the application does not have to use a syscall to evaluate whether a file exists or not, and also helps with avoiding directory traversal attacks, as relative paths are not going to be expanded by accident. + (A directory traversal attach would be if an application receives this get request: [code]server.net/../../../etc/passwd[/code], and it would result in success, if the app then returns the contents of the "passwd" file, which is outside of the root folder of the server.) + [FileCache] has a drawback for now, as it doesn't yet watch for changes in the folder, so if files change it needs to be manually refreshed. + It can also save contents of files into memory if needed using the [code]set_cached_body()[/code] helper method. diff --git a/modules/web/doc_classes/FormField.xml b/modules/web/doc_classes/FormField.xml index f2b176b63..46fe50438 100644 --- a/modules/web/doc_classes/FormField.xml +++ b/modules/web/doc_classes/FormField.xml @@ -1,8 +1,12 @@ + [FormField] represents one field in a html form, like a password or user name input. + [FormField] represents one field in a html form, like a password or user name input. + It contains a list of FormFieldEntries that actually check constraints using polymorphism. + It also contains helper methods to allow for simpler construction. diff --git a/modules/web/doc_classes/FormFieldEntry.xml b/modules/web/doc_classes/FormFieldEntry.xml index 40f5514a0..739ed7bf3 100644 --- a/modules/web/doc_classes/FormFieldEntry.xml +++ b/modules/web/doc_classes/FormFieldEntry.xml @@ -1,8 +1,10 @@ + Used by [FormField]s to implement html form validation capabilities. + Used by [FormField]s to implement html form validation capabilities. diff --git a/modules/web/doc_classes/FormValidator.xml b/modules/web/doc_classes/FormValidator.xml index f5919277f..85dba8abd 100644 --- a/modules/web/doc_classes/FormValidator.xml +++ b/modules/web/doc_classes/FormValidator.xml @@ -1,8 +1,26 @@ + The [FormValidator] implements html form validation capabilities. + The [FormValidator] implements html form validation capabilities. This helps with forcing constraints to input provided by users through HTML forms. [FormValidator] is the main class, it contains helper methods for adding form fields, and validations. + Construction of a simple validator: + [code]var lv : FormValidator = FormValidator.new() + + lv.new_field("username", "Username").need_to_exist() + .need_to_be_alpha_numeric().need_minimum_length(5).need_maximum_length(20) + + var pw : FormField = lv.new_field("password", "Password") + pw.need_to_exist() + pw.need_to_have_lowercase_character().need_to_have_uppercase_character() + pw.need_minimum_length(5) + + #validation + var errors : PoolStringArray = lv.validate(request) + if (errors.size() > 0): + for i in range(errors.size()): + print(errors[i])[/code] diff --git a/modules/web/doc_classes/HTMLBuilder.xml b/modules/web/doc_classes/HTMLBuilder.xml index 8a62723a5..0fab93907 100644 --- a/modules/web/doc_classes/HTMLBuilder.xml +++ b/modules/web/doc_classes/HTMLBuilder.xml @@ -1,8 +1,24 @@ + A class that can be used to easily build html from code. + A class that can be used to easily build html from code. + This class has helper methods for all valid HTML tags. It have an another set, but with a c prefix, these methods write the closing tag. All of these helpers return an [HTMLTag], this allows for the addition of arguments into the tags. This [HTMLTag] should not be stored, it's reused internally. Some of these methods also have alternates with parameters for the most common attributes, like the link tag (a) has a helper method that takes the link, class, id as an argument for convenience. + Other helper methods, like [code]input_*[/code] are also available, these should simplify the creation of forms. + The [code]w()[/code] helper method is provided for appending strings directly at the end. The [code]wn[/code], [code]wns[/code], etc. helpers can be used to append numbers (converted to string) to the output. + Helper methods are also provided for the easy addition of csrf tokens to forms. These can protect from forged form submissions. + [code]var a : float = _model.predict() + va b : HTMLBuilder = HTMLBuilder.new() + + b.h5().attrib("align", "center") + b.w("The model predicted:").br() + b.w("Current: ").wn(a).w(" Units") + b.w(".").br() + b.ch5() + + request.body += b.result[/code] diff --git a/modules/web/doc_classes/HTMLPaginator.xml b/modules/web/doc_classes/HTMLPaginator.xml index 18084df79..71d942b8a 100644 --- a/modules/web/doc_classes/HTMLPaginator.xml +++ b/modules/web/doc_classes/HTMLPaginator.xml @@ -1,8 +1,13 @@ + A class that can be used to generate html pagination. + A class that can be used to generate html pagination. + Pagination means page selection links on HTML pages when more than one page is available. + The [code]get_current()[/code] helper can be used to get the generated HTML for the current page. [code]start()[/code] and [code]next()[/code] helpers are also provided as an enumerator like interface. They are convenient if pages can be built and cached during startup for example. + A Renderer [HTMLPaginator] can be set to an another [HTMLPaginator] class. If a renderer [HTMLPaginator] is set, then it's render methods will be used to render the links instead of the built in of the current class. This enables customization of styles for core classes, in a relatively simple and in a less error prone way. diff --git a/modules/web/doc_classes/HTMLParser.xml b/modules/web/doc_classes/HTMLParser.xml index 3ed651423..97538918d 100644 --- a/modules/web/doc_classes/HTMLParser.xml +++ b/modules/web/doc_classes/HTMLParser.xml @@ -1,8 +1,18 @@ + A class that parses html into a class structure for easy manipulation, or processing. + A class that parses html into a class structure for easy manipulation, or processing. + The HTMLParser class parses HTML using a simple algorithm in one pass into a simple class structure. It handles erroneous HTML documents relatively well. It does not know and check HTML tag validity, it will just handles all of them in a generic way. + A String containing HTML data can ba parsed using it's parse() method. The resulting class structure can then be accessed via it's root member variable. + [code]var p : HTMLParser = HTMLParser.new() + p.parse(data) + var article_tag : HTMLParserTag = p.root.get_first("article") + save_data(article_tag.to_string()) + var n_link_tag : HTMLParserTag = p.root.get_first("a", "rel", "next") + String next_link = n_link_tag.get_attribute_value("href")[/code] @@ -10,22 +20,26 @@ + The HTML document can be turned back into well formatted HTML using this method. + The resulting root [HTMLParserTag]. + Parses the given data as html. + Equivalent to [code]print(convert_to_string())[/code]. diff --git a/modules/web/doc_classes/HTMLParserAttribute.xml b/modules/web/doc_classes/HTMLParserAttribute.xml index a62c394e5..8d8ea4a17 100644 --- a/modules/web/doc_classes/HTMLParserAttribute.xml +++ b/modules/web/doc_classes/HTMLParserAttribute.xml @@ -1,8 +1,11 @@ + [HTMLParser] stores html attributes using this class. + [HTMLParser] stores html attributes using this class. + It has helper methods for searching and modifying data. diff --git a/modules/web/doc_classes/HTMLParserTag.xml b/modules/web/doc_classes/HTMLParserTag.xml index da1273be2..48586b7df 100644 --- a/modules/web/doc_classes/HTMLParserTag.xml +++ b/modules/web/doc_classes/HTMLParserTag.xml @@ -1,8 +1,11 @@ + [HTMLParser] stores html tags using this class. + [HTMLParser] stores html tags using this class. + It has helper methods for searching and modifying data. diff --git a/modules/web/doc_classes/HTMLTag.xml b/modules/web/doc_classes/HTMLTag.xml index 289ef9458..acf3e8151 100644 --- a/modules/web/doc_classes/HTMLTag.xml +++ b/modules/web/doc_classes/HTMLTag.xml @@ -1,8 +1,17 @@ + The HTMLTag class helps with the creation of HTML tags. HTMLBuilder uses it internally. + The HTMLTag class helps with the creation of HTML tags. HTMLBuilder uses it internally. + It has helper methods for most of the available HTML attributes, some of these were omitted from the UML diagram, to improve readability. It supports simple and complex tags. Self-closing tags are considered simple (like <br>). + If an attribute is not directly implemented, the [code]attrib(attr, val)[/code] helper method is available. + It also contains the f() helper method that returns the owner [HTMLBuilder], for ease of use. + [code]var b : HTMLBuilder = HTMLBuilder.new() + #<a href="/main" class="main_link">link text</a>: + b.a().href("/main").cls("main_link").f().w("link").ca() + request.body += b.result[/code] diff --git a/modules/web/doc_classes/HTTPServerEnums.xml b/modules/web/doc_classes/HTTPServerEnums.xml index 97a4220f5..c848c20b0 100644 --- a/modules/web/doc_classes/HTTPServerEnums.xml +++ b/modules/web/doc_classes/HTTPServerEnums.xml @@ -1,8 +1,10 @@ + Contains Enums used by the web module. + Contains Enums used by the web module. diff --git a/modules/web/doc_classes/MarkdownRenderer.xml b/modules/web/doc_classes/MarkdownRenderer.xml index 0b9ac37d5..35831007c 100644 --- a/modules/web/doc_classes/MarkdownRenderer.xml +++ b/modules/web/doc_classes/MarkdownRenderer.xml @@ -1,8 +1,10 @@ + Renders markdown as HTML. + Renders markdown as HTML. diff --git a/modules/web/doc_classes/SessionSetupWebServerMiddleware.xml b/modules/web/doc_classes/SessionSetupWebServerMiddleware.xml index ce3b16d9e..e7578c453 100644 --- a/modules/web/doc_classes/SessionSetupWebServerMiddleware.xml +++ b/modules/web/doc_classes/SessionSetupWebServerMiddleware.xml @@ -1,8 +1,11 @@ + The [SessionSetupWebServerMiddleware] will look up [HTTPSession]s for a particular request using the stored session id. + The [SessionSetupWebServerMiddleware] will look up [HTTPSession]s for a particular request from the stored session id automatically. + It will take session id ([code]session_id[/code] key) from a request's cookie (if exists), and it will set the HTTPSession belonging to that id to the Request's session variable. Note that it will not create sessions automatically. diff --git a/modules/web/doc_classes/WebServerCookie.xml b/modules/web/doc_classes/WebServerCookie.xml index dffbc3989..b128ffe8e 100644 --- a/modules/web/doc_classes/WebServerCookie.xml +++ b/modules/web/doc_classes/WebServerCookie.xml @@ -1,8 +1,10 @@ + Used by [WebServerRequest]s, to set or delete cookies on the client. + Used by [WebServerRequest]s, to set or delete cookies on the client.