Document lt_setvar, lt_getvar and lt_isvar

bartnv · Apr 30, 2020 · f167616 · f167616
1 parent 44e574e
commit f167616
Show file tree

Hide file tree

Showing 2 changed files with 128 additions and 66 deletions.
diff --git a/docs/concepts.md b/docs/concepts.md
@@ -1,64 +1,64 @@
-# Libtables concepts
-
-## Minimize boilerplate PHP/HTML code
-
-Libtables was initially created to avoid the repetitiveness of formatting tabular data with
-HTML table elements by hand. Further on, other functionality such as edit-in-place and
-insert mechanics were added. Libtables allows you to describe the elements and functionality
-the tables need to have, rather than spell them out for each item individually. In other words,
-Libtables is more of a declarative way to create web-tables than an imperative way.
-
-## Harness the strengths of SQL
-
-Where possible, Libtables allows you to use the strengths of SQL, as opposed to many
-ORMs which completely abstract the SQL away. In most Libtables functions you can use
-the full power of the SQL language. As such it is expected that you do type-conversions
-and string concatenations in the SQL queries, rather than afterwards using PHP.
-
-The drawback of this approach is that switching a Libtables application from one database
-type to another may take more time to deal with differences in SQL dialects.
-
-## Primary keys
-
-Libtables requires the first column of every query to contain a numeric primary key larger
-than zero. Furthermore the 'edit' functionality assumes this column to be named 'id'. It's
-possible to use a different column name for a specific table by defining them in the
-'id_columns' item of the $lt_settings array in config.php.
-
-## Hashtags and column numbers
-
-Each query to populate a Libtables table needs to start with the unique "id" column for
-that table. This column is not shown to the user but is used internally all the time. We
-count columns starting from zero, so column 0 is the id number and column 1 is the first
-column visible to the user.
-
-Most Libtables function parameters that allow text inputs will interpret hashtags inside
-these strings. The basic hashtags are column numbers such as "#0", "#1", "#2" etc to use
-the values of each row in texts that relate to that row. For instance the 'appendcell'
-option commonly uses #0 to construct a URL with an id number inside it.
-
-## Blocks
-
-The main organizing unit in Libtables is the block. A block can contain any HTML
-and/or PHP, but generally it will contain one or more lt_* functions. Blocks need
-to be separate files because they have to be loaded both from regular pageviews
-as well as AJAX-calls to Libtables' data.php. The latter is done so that the server
-can verify whether certain operations are allowed.
-
-Blocks are included in the main flow of your website by calling lt_print_block().
-This function can be used recursively, so a block can include another block. Some
-libtables workflows operate by replacing the content of the current block with that
-of another block.
-
-## Variables
-
-You should not use global PHP variables like $_SESSION or $_GET in blocks, because
-Libtables calls blocks on AJAX context where they may not be available. To store state
-between blocks, such as 'the logged in user' or 'the currently selected product', you
-should use the lt_setvar(), lt_getvar() and lt_isvar() functions instead.
-
-These variables can be used in all SQL queries issued from within libtables by using
-named parameter syntax (eg. "SELECT * FROM product WHERE id = :product").
-
-PHP and Libtables variable names starting with 'lt_' are reserved for use by Libtables
-and should not be defined within your application.
+# Libtables concepts
+
+## Minimize boilerplate PHP/HTML code
+
+Libtables was initially created to avoid the repetitiveness of formatting tabular data with
+HTML table elements by hand. Further on, other functionality such as edit-in-place and
+insert mechanics were added. Libtables allows you to describe the elements and functionality
+the tables need to have, rather than spell them out for each item individually. In other words,
+Libtables is more of a declarative way to create web-tables than an imperative way.
+
+## Harness the strengths of SQL
+
+Where possible, Libtables allows you to use the strengths of SQL, as opposed to many
+ORMs which completely abstract the SQL away. In most Libtables functions you can use
+the full power of the SQL language. As such it is expected that you do type-conversions
+and string concatenations in the SQL queries, rather than afterwards using PHP.
+
+The drawback of this approach is that switching a Libtables application from one database
+type to another may take more time to deal with differences in SQL dialects.
+
+## Primary keys
+
+Libtables requires the first column of every query to contain a numeric primary key larger
+than zero. Furthermore the 'edit' functionality assumes this column to be named 'id'. It's
+possible to use a different column name for a specific table by defining them in the
+'id_columns' item of the $lt_settings array in config.php.
+
+## Hashtags and column numbers
+
+Each query to populate a Libtables table needs to start with the unique "id" column for
+that table. This column is not shown to the user but is used internally all the time. We
+count columns starting from zero, so column 0 is the id number and column 1 is the first
+column visible to the user.
+
+Most Libtables function parameters that allow text inputs will interpret hashtags inside
+these strings. The basic hashtags are column numbers such as "#0", "#1", "#2" etc to use
+the values of each row in texts that relate to that row. For instance the 'appendcell'
+option commonly uses #0 to construct a URL with an id number inside it.
+
+## Blocks
+
+The main organizing unit in Libtables is the block. A block can contain any HTML
+and/or PHP, but generally it will contain one or more lt_* functions. Blocks need
+to be separate files because they have to be loaded both from regular pageviews
+as well as AJAX-calls to Libtables' data.php. The latter is done so that the server
+can verify whether certain operations are allowed.
+
+Blocks are included in the main flow of your website by calling lt_print_block().
+This function can be used recursively, so a block can include another block. Some
+libtables workflows operate by replacing the content of the current block with that
+of another block.
+
+## Variables
+
+You should not use global PHP variables like $\_SESSION or $\_GET in blocks, because
+Libtables calls blocks on AJAX context where they may not be available. To store state
+between blocks, such as 'the logged in user' or 'the currently selected product', you
+should use the lt_setvar(), lt_getvar() and lt_isvar() functions instead.
+
+These variables can be used in all SQL queries issued from within libtables by using
+named parameter syntax (eg. "SELECT * FROM product WHERE id = :product").
+
+PHP and Libtables variable names starting with 'lt_' are reserved for use by Libtables
+and should not be defined within your application.
diff --git a/docs/functions.md b/docs/functions.md
@@ -6,6 +6,7 @@ in your site's PHP code, as long as you include() the 'libtables.php' file.
 
 [^1]: for an explanation on blocks, read the [concepts item on blocks](concepts/#blocks)
 
+
 ## lt_table
 
 The lt_table() function adds a table to the current block.
@@ -30,6 +31,7 @@ See [lt_table() options](table_options_display/) for more information.
 [^2]: in special cases you can pass in an array of column names instead of a query, to generate
 a 'table' with no data but only insert fields (deprecated in favor of the lt_insert function below)
 
+
 ## lt_insert
 
 The lt_insert() function is like lt_table(), except that it only shows insert fields and no
@@ -56,6 +58,7 @@ Basic example:
 
 All insert functionality from [lt_table() database mutation options](table_options_database/) can be used here.
 
+
 ## lt_print_block
 
 Insert the contents of the specified Libtables block at this point in your website code.
@@ -78,9 +81,66 @@ Parameters:
 
 This function is the primary way to integrate the libtables functionality in your own PHP code.
 
+
 ## lt_setvar, lt_getvar, lt_isvar
 
-Manipulate the secure serverside variables used by Libtables.
+Manipulate the serverside session variables used by Libtables.
+
+### - Setting variables
+
+Syntax to set a Libtables variable:
+
+    lt_setvar(varname, value)
+
+for instance:
+
+```php
+  lt_setvar('userid', $userid);
+```
+
+This saves the short-lived PHP variable $userid as a persistent Libtables variable. An alternative
+syntax can be used to save for instance $\_GET and $\_POST variable into a Libtables variable. The
+Libtables variable will not be changed if the key doesn't exist in the array.
+
+    lt_setvar(varname, array, key)
+
+for instance:
+
+```php
+  lt_setvar('confirmationcode', $_GET, 'code')
+```
+
+### - Reading variables
+
+Syntax to use a variable:
+
+    lt_getvar(varname, defaultvalue)
+
+for instance:
+
+```php
+  lt_getvar('userid', 0)
+```
+
+Specifying a default value is optional. However, if you use lt_getvar with a nonexistent varname
+and no defaultvalue, Libtables will throw a PHP exception. This is a security feature intended to
+prevent users from accessing blocks they are not supposed to.
+
+Libtables variables can also be used in all SQL queries issued from within libtables by using
+named parameter syntax (eg. "SELECT * FROM product WHERE id = :product").
+
+### - Testing variables
+
+To test for the existence of a variable without the risk of getting an exception:
+
+    lt_isvar(varname)
+
+for instance:
+
+```php
+  if (!lt_isvar('userid')) print 'Error: you are not logged in';
+```
+
 
 ## lt_query_single
 
@@ -101,7 +161,8 @@ Parameters:
   lt_query_single('SELECT city.populationcount FROM city WHERE name = :name', [ 'name' => $_POST['cityname'] ]);
 ```
 
-Reminder: don't use $_POST variables within a libtables block, use lt_setvar() instead
+Reminder: don't use $\_POST variables within a libtables block, use lt_setvar() instead
+
 
 ## lt_control [experimental]
 
@@ -130,6 +191,7 @@ Parameters:
   ]);
 ```
 
+
 ## lt_text [experimental]
 
 The lt_text() function generates a text from a database query and adds it to the current block.