All templates in Myghty are referred to as "Components". Components, while they may look like plain HTML pages with a few lines of Python in them, are actually callable units of code which have their own properties, attributes, input arguments, and return values. One can think of a Component anywhere within the spectrum between "HTML page" and "callable Python object", and use it in either way or a combination of both.
A single template, while it is a component itself, also can contain other components within it, which are referred to as "subcomponents", and a subcategory of subcomponents called "methods". The template's component itself is called a "file-based component", and when it is the main component referenced by a request it is also known as the "top level component".
When a component is instantiated within the runtime environment, it is a Python object with the usual reference to "self" as well as its own attributes and methods, and the body of the component occurs within a function call on that object. All components extend from the base class myghty.component.Component. File-based components extend from myghty.component.FileComponent and subcomponents extend from myghty.component.SubComponent.
Additionally, unique to Myghty is a non-template form of component called a "module component", which is written instead as a regular Python class. These components are described in the next section, Module Components, extending from the class myghty.component.ModuleComponent.
The most basic component operation is to have one template call another. In the simplest sense, this is just an HTML include, like a server side include. To have a template "page.myt" call upon another template "header.myt":
<html> <& header.myt &> <body> ... rest of page </body> </html>
<head>
<title>header</title>
</head>Produces:
<html>
<head>
<title>header</title>
</head>
<body>
... rest of page
</body>
</html>When calling components, the path to the component is given as an environment-specific URI, and not an actual filesystem path. While the path can be specified as absolute, it is still determined as relative to one or more of the configured Myghty component roots. Myghty uses the component_root parameter as a list of filesystem paths with which to search for the requested component. If a relative path is used, the path is converted to an absolute path based on its relation to the location of the calling component, and then matched up against the list of component roots.
Components, since they are really Python functions, support argument lists. These arguments are supplied to the top-level component from the client request arguments, such as via a POST'ed form. When a component is called from another component, the calling component specifies its own local argument list to be sent to the called component.
A component can access all arguments that were sent to it by locating them in the ARGS dictionary. More commonly, it can specify a list of arguments it would like to receive as local variables via the <%args> tag:
<%args> username password # sessionid defaults to None sessionid = None </%args> <%python scope="init"> if sessionid is None: sessionid = create_sid() if password != get_password(username): m.send_redirect("loginfailed.myt", hard=True) </%python>
In the above example, the 'username' and 'password' arguments are required; if they are not present in the argument list sent to this component, an error will be raised. The 'sessionid' argument is given a default value, so it is not required in the argument list.
A component like the one above may be called with a URL such as:
http://foo.bar.com/login.myt?username=john&password=foo&sessionid=57347438
The values sent in an <%args> section are analgous to a Python function being called with named parameters. The above set of arguments, expressed as a Python function, looks like this:
def do_run_component(self, username, password, sessionid = None):
What this implies is that the default value sent for "sessionid" only takes effect within the body of the component. It does not set a default value for "sessionid" anywhere else. Different components could easily set different default values for "sessionid" and they would all take effect if "sessionid" is not present in the argument list.
Components can pass argument lists to other components when called. Below, a component 'showuser.myt' is called by another component 'page.myt':
<%args> username email </%args> Username: <% username %><br/> Email: <a href="mailto:<% email %>"><% email %></a><br/>
Login information: <& showuser.myt, username='john', email='jsmith@foo.com' &>
The component call tags "<& &>" take a named-parameter list just like a Python function, and can also have as the very last argument dictionary with ** notation just like in regular Python:
<& comp.myt, arg1=3.7, **ARGS &>
Above, the dictionary ARGS always has a list of all arguments sent to the component, regardless of whether or not they were specified in the <%args> section. This is a way of passing through "anonymous" arguments from a component's caller to its components being called.
So far we have talked about "component-scoped" arguments, that is, the list of arguments that are sent directly to a component by its caller. While the very first component called in a request (i.e. the top-level component) will receive the client request arguments as its component-scoped arguments, any further component calls will only receive the arguments sent by its direct caller.
To make it easier for all components to see the original request arguments, the attribute scope="request" may be specified in any <%args> section to indicate that arguments should be taken from the original request, and not the immediate caller. Normally, the default value of scope is component, indicating that only the immediate component arguments should be used.
<%args scope="request"> sessionid </%args> <%args scope="component"> username </%args> hello <% username %>, to edit your preferences click <a href="prefs.myt?sessionid=<% sessionid %>">here</a>.
Above, the argument "sessionid" must be sent by client request, but the argument "username" must be sent by the calling component. If this component is called as the top-level component, both arguments must be present in the client request.
Request arguments are also always available via the request_args and root_request_args members of the request object.
Note that there is special behavior associated with request-scoped arguments when using subrequests (described later in this section). Since a subrequest is a "request within a request", it is not clear whether the "request" arguments should come from the originating request, or the immediate, "child" request. The attribute scope="subrequest" indicates that arguments should be located in the immediate request, whether or not it is a subrequest, in contrast to scope="request" which always refers to the arguments of the ultimate root request. Subrequests are described in the section Subrequests below.
The component that wants to be flexible about its arguments may also specify its arguments with "dynamic" scope. In dynamic scope, the argument is located within the most local arguments first, and then upwards towards the request until found. The following component will retrieve its arguments locally if present, or if not, from the request, no matter where it is called:
<%args scope="dynamic"> username email </%args> hello <% username %>, your email address is <% email %>.
A subcomponent is a component defined within a larger template, and acts as a callable "subsection" of that page. Subcomponents support almost all the functionality of a file-based component, allowing Python blocks of init, cleanup and component scope, but not global, request or thread scope.
A subcomponent, albeit a nonsensical one, looks like this:
<%def mycomponent> <%args> arg1 = 'foo' arg2 = 'bar' </%args> <%python scope="init"> string = arg1 + " " + arg2 </%python> i am mycomponent ! <% string %> </%def>
A regular subcomponent like this one is always called by another component, i.e. it can never be called directly from the request as a top-level component. Furthermore, subcomponents defined with the <%def> tag are private to the template file they appear in.
The subcomponent has access to all global variables, such as m and r, but it does not have access to the local variables of its containing component. This would include variables specified in the body of the main component, i.e. in init-, cleanup- and component-scoped <%python> blocks. Variables declared in global-, request- and thread-scoped <%python> blocks are available within subcomponents, subject to the restrictions on variables declared in those blocks. Variables declared within the body of a subcomponent remain local to that subcomponent.
Subcomponents are called in a similar manner as a file-based component:
welcome to <& title, username='john' &> <%def title> <%args> username </%args> <b>bling bling bling <% username %> bling bling bling</b </%def>
Note that a subcomponent can be defined at any point in a template and is still available throughout the entire template.
A method is similar to a subcomponent, except its functionality is available outside of the file it appears in, and it can take advantage of inheritance from other template files.
<%method imamethod> <%args> radius coeffiecient = .5424 </%args> <%python scope="init"> foob = call_my_func(radius, coefficient) </%python> fractional fizzywhatsle: <% foob %> </%method>
A method can be called from within the file it appears in the same fashion as a subcomponent, i.e. simply by its name, in which case it is located in the same way as a subcomponent. The other format of method calling is <location>:<methodname>, where location specifies what component to initially search for the method in. The location may be specified as the URI of the desired component file, or one of the special keywords SELF, REQUEST, or PARENT.
# call the method print_date in # component file /lib/functions.myt <& /lib/functions.myt:print_date, date="3/12/2004" &> # call a method in the local template <& tablerow, content="cell content" &> # call a method in the base component, taking # advantage of inheritance <& SELF:printtitle &>
With the compound method calling format, if the method is not located in the specified component, the component's inherited parent will be searched, and in turn that component's inherited parent, etc., until no more parents exist. The parent-child relationship of components, as well as the keywords SELF, REQUEST, and PARENT are described in the section Inheritance.
<%closure format_x> <%args> format = '%d' </%args> <% format % x %> </%closure> % for x in (1,2,3): <& format_x, format='X:%d' &> %
Closures support the <%args> tag, as well as Init Scope and Cleanup Scope. Closures can also be nested. They currently do not support the "component call with content" calling style but this may be added in the future.
Subcomponents and methods also may specify flags as described in the section <%flags>. The most useful flags for a subcomponent are the trim and autoflush flags, described in Filtering and Flushing (and Escaping).
There are two formats for specifing flags in a subcomponent:
# traditional way <%def buffered> <%flags> autoflush=False </%flags> this is a buffered component </%def> # inline-attribute way <%method hyperlink trim="both"> <%args> link name </%args> <a href="<% link %>">name</a> </%method>
Subcomponents and methods can also be called with a slightly different syntax, in a way that allows the calling component to specify a contained section of content to be made available to the called component as a Python function. Any subcomponent can query the global m object for a function that executes this content, if it is present. When the function is called, the code sent within the body of the component call with content is executed; this contained code executes within the context and namespace of the calling component.
<&| printme &> i am content that will be grabbed by PRINTME. </&>
The called component can then reference the contained content like this:
<%def printme> I am PRINTME, what do you have to say ?<br/> <% m.content() %> </%def>
The method m.content() executes the code contained within the <&| &>/</&> tags in its call to "printme", and returns it as a string. A component may query the request object m for the presense of this function via the method m.has_content().
A component call with content is one of the most powerful features of Myghty, allowing the creation of custom tags that can produce conditional sections, iterated sections, content-grabbing, and many other features. It is similar but not quite the same as the template inheritance methodology, in that it allows the body of a component to be distilled into a callable function passed to an enclosing component, but it involves a client explicitly opting to wrap part of itself in the body of another component call, rather than a client implicitly opting to wrap its entire self in the body of another component call.
The special component calling tags described above are just one way to call components. They can also be called directly off of the request object m, which is handy both for calling components within %python blocks as well as for capturing either the return value or the resulting content of a subcomponent. Component objects can also be directly referenced and executed via these methods.
The full index of request methods and members can be found in The Request.
This method allows you to call a component just like in the regular way except via Python code. The arguments are specified in the same way to the function's argument list. The output will be streamed to the component's output stream just like any other content. If the component specifies a return value, it will be returned. A component, since it is really just a python function, can have a return value simply by using the python statement return. The value of component can be an actual component object obtained via fetch_component(), or a string specifying a filesystem path or local subcomponent or method location.
<%python> m.comp('/foo/bar.myt', arg1='hi') </%python>
This method is the same as "comp" except the output of the component is captured in a separate buffer and returned as the return value of scomp().
<%python> component = m.fetch_component('mycomponent') content = m.scomp(component) m.write("<pre>" + content + "</pre>") </%python>
A subrequest is an additional twist on calling a component, it calls the component with its own request object that is created from the current request. A subrequest is similar to an internal redirect which returns control back to the calling page. The subrequest has its own local argument list as well, separate from the original request arguments.
<%python> ret = m.subexec('/my/new/component.myt', arg1='hi') </%python>
The subexec method takes either a string URI or a component object as its first argument, and the rest of the named parameters are sent as arguments to the component.
Use subrequests to call a component when you want its full inheritance chain, i.e. its autohandlers, to be called as well.
The subexec method is comprised of several more fine-grained methods as illustrated in this example:
<%python> # get a component to call component = m.fetch_component('mysubreq.myt') # make_subrequest - # first argument is the component or component URI, # following arguments are component arguments subreq = m.make_subrequest(component, arg1 = 'foo') # execute the request. return value is sent ret = subreq.execute() </%python>
The make_subrequest method can also be called as create_subrequest, which in addition to supporting component arguments, lets you specify all other request object arguments as well:
<%python> import StringIO # get a component to call component = m.fetch_component('mysubreq.myt') # make a subrequest with our own # output buffer specified buf = StringIO.StringIO() subreq = m.create_subrequest(component, out_buffer = buf, request_args = {'arg1':'foo'}, ) # execute the request. # return value is sent, our own buffer # is populated with the component's # content output ret = subreq.execute() </%python>
The "call_self" method is provided so that a component may call itself and receive its own content in a buffer as well as its return value. "call_self" is an exotic way of having a component filter its own results, and is also the underlying method by which component caching operates. Note that for normal filtering of a component's results, Myghty provides a full set of methods described in the section Filtering, so call_self should not generally be needed.
call_self uses a "reentrant" methodology, like this:
<%python scope="init"> import StringIO # value object to store the return value ret = Value() # buffer to store the component output buffer = StringIO.StringIO() if m.call_self(buffer, ret): m.write("woop! call self !" + buffer.getvalue() + " and we're done") return ret() # ... rest of component </%python>
The initial call to call_self will return True, indicating that the component has been called and its output and return value captured, at which point the component should return. Within the call_self call, the component is executed again; call_self returns False to indicate that the thread of execution is "inside" of the initial call_self and that content is being captured.
It is recommended that call_self be called only in an init-scoped Python block before any other content has been written, else that content will be printed to the output as well as captured.
Instances of Component objects can be accessed many ways from the request object, including the fetch_component method, and the current_component, request_component, and base_component members. The fetch_next method returns the next component in an inheritance chain. Finally, self refers to the current component.
The methods available directly from Component are listed below, followed by the members.
| args | |
A list of argument names, corresponding to variable names in the component-scoped <%args> section, which have a default value specified.
|
|
| attr | |
A dictionary of component attributes, corresponding to those set by the <%attr> tag. The attributes can be set at once
by assigning a dictionary to this member. However, to set and retrieve individual attributes, it is best to use the special attributes member which takes advantage of inheritance.
|
|
| attributes | |
A dictionary accessor for the attr dictionary member that locates its members first in the local component attributes, then searches up the inheritance chain for the attribute.
|
|
| dir_name | |
The web-specific directory name where the current component resides, i.e. for this component its "/". For a subcomponent or method, it is the directory name of the owning (file-based) component. |
|
| file | |
The actual filesystem location of a component, for a component that was loaded directly from a Myghty template file, else it is None. |
|
| filter | |
Reference to the function that will perform filtering on the component. This filter is directly stated in the <%filter> section described in The <%filter> Tag. |
|
| flags | |
Dictionary of flags for this component. Also can be accessed via the get_flag method.
|
|
| id | |
A unique identifier for the current component, which is comprised of the key name for its component root joined with its web-specific path, i.e. for this component its "content|components.myt". |
|
| is_file_component | |
True if this component is a file based component. |
|
| is_method_component | |
True if this component is a method component. |
|
| is_module_component | |
True if this component is a module component. |
|
| is_sub_component | |
True if this component is a subcomponent or method component. |
|
| name | |
The filename or name of the current component, i.e. for this component its "components.myt". |
|
| owner | |
For a subcomponent or method subcomponent, the owning file-based component, otherwise it is self. |
|
| parent_component | |
For a component in an inheritance chain (i.e. via %flags or via autohandlers), the inheriting component. For a subcomponent or method, returns the parent of the owning (file-based) component. Inheritance is described in Inheritance. |
|
| path | |
The URI corresponding to the component. For this component its "/components.myt". For a subcomponent or method, it is the URI of the owning (file-based) component. |
|
| request_args | |
A list of argument names, corresponding to variable names in the request-scoped <%args scope="request"> section, which do have a default value specified.
|
|
| required_args | |
A list of argument names, corresponding to variable names in the component-scoped <%args> section, which do not have a default value specified., i.e. they are required component arguments.
|
|
| required_request_args | |
A list of argument names, corresponding to variable names in the request-scoped <%args scope="request"> section, which do not have a default value specified, i.e. are required request arguments.
|
|
| required_subrequest_args | |
A list of argument names, corresponding to variable names in the subrequest-scoped <%args scope="subrequest"> section, which do not have a default value specified, i.e. are required subrequest arguments.
|
|
| subrequest_args | |
A list of argument names, corresponding to variable names in the subrequest-scoped <%args scope="subrequest"> section, which do have a default value specified.
|
|