Mercurial > cgi-bin > hgweb.cgi > tincan

comparison doc/api_reference.rst @ 62:fd8c558a89bb draft

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Finished, but not finished proofreading.
author David Barts <n5jrn@me.com>
date Sun, 09 Jun 2019 14:16:17 -0700
parents 55828c01e38f
children 8867b3a5c4fa
comparison
equal deleted inserted replaced
61:55828c01e38f 62:fd8c558a89bb
36 36
37 This class contains one extra method above and beyond the methods ``bottle.Bottle`` objects have: 37 This class contains one extra method above and beyond the methods ``bottle.Bottle`` objects have:
38 38
39 .. method:: forward(target) 39 .. method:: forward(target)
40 40
41 Perform a programmatic, request-time, server-side redirect to the route specified by *target*, which may be either relative to the route issuing the redirect or an absolute route. This differs from the ``#forward`` header directive in that this method causes a server-side redirect to be set up at route creation time. The ``#forward`` directive is both more efficient and less flexible than the ``forward`` method. 41 Perform a programmatic, request-time, server-side redirect to the route specified by *target*, which may be either relative to the route issuing the redirect or an absolute route. This differs from the ``#forward`` header directive in that this method causes a server-side redirect to be set up the time a request is processed, not the when a route is created. That makes this method both more flexible and less efficient than ``#forward``.
42 42
43 One may only forward from a normal page to another normal page; neither the source nor the target of a forward may be an error page. Attempts to create forward loops will also cause an error. 43 One may only forward from a normal page to another normal page; neither the source nor the target of a forward may be an error page. Attempts to create forward loops will also cause an error.
44 44
45 TinCan Configuration Variables 45 TinCan Configuration Variables
46 ------------------------------ 46 ------------------------------
61 61
62 The ``handle`` method is called by TinCan to handle a request. No arguments are passed to it (other than the implied ``self`` argument). By default, this is a no-op method. 62 The ``handle`` method is called by TinCan to handle a request. No arguments are passed to it (other than the implied ``self`` argument). By default, this is a no-op method.
63 63
64 .. method:: export() 64 .. method:: export()
65 65
66 This exports all non-hidden instance variables; it does not export attributes that define callable objects (e.g. methods). A "hidden" instance variable means any one whose name *does not* start with an underscore; the ``request`` and ``response`` instance variables of type ``tincan.Page`` are also considered hidden. Finally, this object itself is exported as the ``page`` variable. This method returns a dict containing the exported items. 66 This is called by TinCan to export template variables; it must return a ``dict`` or ``dict``-like object.
67
68 The default implementation exports all non-hidden instance variables; moreover, it does not export attributes that define callable objects (e.g. methods). A "hidden" instance variable means any one whose name *does not* start with an underscore; the ``request`` and ``response`` instance variables of class ``tincan.Page`` are also considered hidden. Finally, ``self`` is exported as the ``page`` variable.
67 69
68 Note that the exporting happens *after* header processing; thus, if there is a conflict between a template variable defined by the ``#load`` header directive and this exporting logic, the value exported by this method will always overwrite the earlier one. 70 Note that the exporting happens *after* header processing; thus, if there is a conflict between a template variable defined by the ``#load`` header directive and this exporting logic, the value exported by this method will always overwrite the earlier one.
69 71
70 If the above exporting behavior is for some reason unsuitable, it is permitted to override this method. 72 If the above exporting behavior is for some reason unsuitable, it is permitted to override this method.
71 73
72 .. class tincan.Page 74 .. class:: tincan.Page
73 75
74 The parent class of all normal (non-error) pages. This is a subclass of ``tincan.BasePage`` above. 76 The parent class of all normal (non-error) pages.
75 77
76 .. class tincan.ErrorPage 78 .. class:: tincan.ErrorPage
77 79
78 The parent class of all error pages. 80 The parent class of all error pages.
81
82 ==========
83 Exceptions
84 ==========
85
86 .. class:: tincan.TinCanException
87
88 The parent class of all exceptions TinCan raises.
89
90 .. class:: tincan.TemplateHeaderError
91
92 Raised upon encountering a syntax error in the template header directives.
93
94 .. class:: tincan.LoadError
95
96 Raised when we run into problems ``#load``'ing something, usually because it doesn't exist.
97
98 .. class:: tincan.TinCanError
99
100 General-purpose exception raised by TinCan when things go wrong, either when attempting to launch webapps, or attempting to service requests. Often caused by errors in user-created files.
79 101
80 ============================ 102 ============================
81 Request and Response Objects 103 Request and Response Objects
82 ============================ 104 ============================
83 105
84 The ``request`` and ``response`` instance variables of ``tincan.Page`` are standard ``bottle.Request`` and ``bottle.Response`` objects. In the ``environ`` attribute of the ``request`` object, any key beginning with ``tincan.`` is reserved. 106 The ``request`` and ``response`` instance variables of ``tincan.Page`` are standard ``bottle.Request`` and ``bottle.Response`` objects. In the ``environ`` attribute of the ``request`` object, any key beginning with ``tincan.`` is reserved.
107
108 .. _header-directives:
85 109
86 ================= 110 =================
87 Header Directives 111 Header Directives
88 ================= 112 =================
89 113
100 124
101 ``#hidden`` 125 ``#hidden``
102 This is a hidden page; do not create a route for it. The page can only be displayed by a server-side forward. 126 This is a hidden page; do not create a route for it. The page can only be displayed by a server-side forward.
103 127
104 ``#load`` 128 ``#load``
105 Load the specified Chameleon template file and make the loaded template available as a template variable. Useful for importing and invoking macros. See the :ref:`loading-templates` below for more information. 129 Load the specified Chameleon template file and make the loaded template available as a template variable. Useful for importing and invoking macros. See :ref:`loading-templates` below for more information.
106 130
107 ``#methods`` 131 ``#methods``
108 A list of HTTP request methods, separated by whitespace, follows. The route will allow all specified methods. Not specifying this line is equivalent to specifying ``#methods GET``. 132 A list of HTTP request methods, separated by whitespace, follows. The route will allow all specified methods. Not specifying this line is equivalent to specifying ``#methods GET``.
109 133
110 ``#python`` 134 ``#python``
111 What follows is the name of the Python file containing the code-behind for this route; the file name must end in ``.py``. 135 What follows is the name of the Python file containing the code-behind for this route; the file name must end in ``.py``.
112 136
113 ``#template`` 137 ``#template``
114 Ignore the body of this file and instead use the template in the body of the specified file, which must end in .pspx. Any headers in the referred template file are ignored. 138 Ignore the body of this file and instead use the template in the body of the specified file, which must end in ``.pspx``. Any headers in the referred template file are ignored.
115 139
116 Error Pages 140 Error Pages
117 ----------- 141 -----------
118 142
119 Error pages supersede the standard Bottle error handling, and are created by using the ``#errors`` page header. The ``#hidden`` and ``#method`` header directives are ignored in error pages (error pages are effectively hidden anyhow, by virtue of never having normal routes created for them). 143 Error pages supersede the standard Bottle error handling, and are created by using the ``#errors`` page header. The ``#hidden`` and ``#method`` header directives are ignored in error pages (error pages are effectively hidden anyhow, by virtue of never having normal routes created for them).
130 Loading Templates 154 Loading Templates
131 ----------------- 155 -----------------
132 156
133 The ``#load`` directive may be used to load additional templates, e.g. ones containing macro definitions. Note that the loaded files are standard Chameleon templates and *not* TinCan ``.pspx`` files (i.e. they cannot contain any header directives); as such, loaded files must have the standard ``.pt`` extension for Chameleon template files. 157 The ``#load`` directive may be used to load additional templates, e.g. ones containing macro definitions. Note that the loaded files are standard Chameleon templates and *not* TinCan ``.pspx`` files (i.e. they cannot contain any header directives); as such, loaded files must have the standard ``.pt`` extension for Chameleon template files.
134 158
135 In the normal case, ``#load foo.pt`` will load a file relative to the same directory as the page containing the ``#load`` directive itself. The loaded template object will be made available as a template variable matching the file name sans extension (e.g. ``foo``). One can change the name of the variable created by prefixing the file specification with a variable name followed by an equals sign, e.g. ``#load t=foo.pt``. If one places the specification inside angle brackets (e.g. ``#load <t=foo.pt>``), loaded files are searched for in ``WEB-INF/tlib`` instead. 159 In the normal case, ``#load foo.pt`` will load a file relative to the same directory as the page containing the ``#load`` directive itself. The loaded template object will be made available as a template variable matching the file name sans extension (e.g. ``foo``). One can change the name of the variable created by prefixing the file specification with a variable name followed by an equals sign, e.g. ``#load t=foo.pt``. If one places the specification inside angle brackets (e.g. ``#load <t=foo.pt>``), files to be loaded are searched for in ``WEB-INF/tlib`` instead.
136 160
137 Finally, as is allowed for all arguments to header directives, one may enclose the argument to ``#load`` inside single or double quotes and use the normal Python string syntax. 161 Finally, as is allowed for all arguments to header directives, one may enclose the argument to ``#load`` inside single or double quotes and use the normal Python string syntax.
138 162
139 Using Loaded Macros 163 Using Loaded Macros
140 ------------------- 164 -------------------
141 165
142 Once a template has been loaded, it will be available as a sub-attribute of the macros attribute of the associated template object. E.g.:: 166 Once a template has been loaded, it will be available as a sub-attribute of the ``macros`` attribute of the associated template object. E.g.::
143 167
144 #load foo.pt 168 #load foo.pt
145 <!DOCTYPE html> 169 <!DOCTYPE html>
146 <html> 170 <html>
147 <head> 171 <head>