Aiki widget 2
From Aikiframework wiki
Contents |
How is a Page rendered
Aiki generate a page in two steps:
1) first, looks for layout widgets (widgets that have father_widget=0, one or more layout can be parsed)
2) then, generates these widget an search for children widgets.
In all cases, layout or children, widgets must be match the display_urls and don't match kill_urls.
The inline widget are inserted always (no match is required).
Exceptions: if a widget is defined in request (www.aiki.org?widget=1 for example) then only this widget (and his sons) will be generated.
Other considerations:
- in step 1 and 2, order depends on display_order, id.
- not active widgets (is_active=0) will be ignored.
- widget site must be "default", "aiki_shared" or equal site (global variable)
- widget can be referenced by id or widget_name. In this case the name must be unique and a token: first character must be a letter (ASCII), rest, letters,numbers or _.
- if widget is defined in url, only this widget (and sons) will be rendered. For example: www.aiki.org/foo/bar/?widget=1 only rendered, widget 1,
and is equivalent to www.aiki.org?widget=1 , www.aiki.org/foo/?widget=1
Proposal: is_father can be suppressed. Now, you need two step to add a children to a widget: first, in son selected father, and in father define is_father. That allow errors and inconsistencies.
it's sexist too, bugs https://bugs.launchpad.net/aikiframework/+bug/757076, father_widget as parent_widget.
Calling it a parent_widget would make more sense to me. Christopher Adams 00:44, 22 June 2011 (UTC)
To match or not to match
Widget must match display_urls and doesn't match kill_urls.
The too rules have the same syntax: * or url or url|url|url
A url can be:
- a single word or * or a regular expression: admin, user
- more words or * separated by /
- regular expression like #regular#modifiers (note, use # as delimiter. Modifiers can be: Umsi
Examples of display/kill urls.
* admin browse|news new$ admin|list/users user/details #user[s]?#i #admin#i browse|#news/(detail\|configure)#i NOTES: * if token is a regular expression the '|' must be escaped as '\|' * a final $ in token means exact match. foo match foo/bar and foo, but foo$ only match foo.
Examples of matches
for a given url: www.aiki.org/foo/bar, only foo/bar is evaluated. these display_urls match: |*| |foo| |foo/bar| |foo/bar/more| |foo/*| In case of compound urls only one must match: |none|admin|foo| match! And these don't match |foo/bar/*| With * in url, the given url must have same number of parts . |*/bar| No * is permited in root url.
kill_urls
Have the same syntax than display_urls. In kill_urls a empty expression is usual: means not exclude. In display_urls a empty fields means not include (the widget can only be rendered using www.aiki.org?widget=..
conflicts: no thanks!
if url match kill_url although match display_urls, the widget will be ignored. if url don't match kill_url and don't match display_urls, ..be ignored.
other
Exception: when home page is requested, the display_urls is |homepage| not ||.
Problems: Adams have revealed one important problem. There is no way to define a exact url: foo/bar and only foo/bar, not foo/bar/more.. Implement fix 869.
Canditates aiki make first a set of candidate widgets, selecting those widget where first part of path url ( for www.aiki.org/admin/user is admin) is present in display_url or display_url is "*" or is a regular expression.That's why */details doesn't work
Routes and Tokens
At present, Aiki defines a display_urls for each widget and makes the following parts of the widget available via an argument number such as (!(1)!).
However, the exact order number of each argument is much less important that the meaning. Instead, each widget could define a route where the widget appears and introduce tokens as the explicit arguments.
For example:
/ ## this is the route for "homepage" /user/@id ## this widget appears on the /user URL with the user id as the token /user ## this is a *different* route from /user/@id!
Each token as in the sample /user/@id could then be referenced in the widget as {{@id}} instead of (!(1)!). This has a number of advantages. The meaning of each token would be explicit in the widget, rather than having to be surmised. If the admin decides to change the order of the tokens it will not affect the widget content. It would likewise allow widgets to appear on multiple routes but keyed to the same tokens even if the order of the tokens is shifted.
The bare route /user is is not the same as /user/@token. The second should only be displayed if there is in fact another part of the URL that can be mapped to {{@token}}. This will help site designers by discriminating between cases where {{@token}} is defined but does not match a record in the database, and cases where {{@token}} is not defined at all.
It would be even better if you could also somehow distinguish between cases where a widget should appear on all pages for /user... or should only appear on /user/ with nothing after it. This would make it easier to create a generic page for a certain URL (e.g. list of all users) versus a no results error (e.g. there is no user with that id).
One way to do this is to force the use of wildcards for "global" widgets:
/ ## only appears on the homepage /* ## appears on every page /user ## only appears on http://example.org/user /user/* ## appears on that plus every subpage
Or you could keep Aiki's current behavior as default (widgets appears on all subpages):
/ ## widget appears on all pages /$ ##only on the homepage /user ##on all user pages /user$ ##only on http://example.org/user
Either option would be a positive step toward making everything more explicit. However, I believe using wildcards (*) is the better option as it seems easier to read and understand, even though it contradicts Aiki's current behavior.
Routes could be separated either by a newline or a comma (choose one).
roger: very good idea!!!
- perhaps this url parameters can be used in direct access of a widget www.aiki.org?widget=1&id=120. Now, there is no way to do that.
- thinking in our super master chovynz and brad, i prefer maintain certain compatibility with actual markup. So |user/|...and |user/@id| ok?
normal_select
To render the contents of a widget you can specify in field normal_select a sql sentence that will be used to generate a loop. (authorized_select is similar but for protected widgets.
Normal_select field can be:
- Empty.
- An SQL SELECT statement (no TRUNCATE|UPDATE|DELETE (2))
- Multiple SQL statements separated by | OR |. The first statement that return results, will be used
inherent widgets
In inherent widgets field normal_select is not used. Even SQL statement defined in calling is user or, if not defined, any SQL query is executed.
(#(inherent:127|select * from cc_tbl_tags order by rand() LIMIT 30)#)
(#(inherent:97)#) // in this case no SQL query is executed.
In inherent widgets TRUNCATE|UPDATE|DELETE is allowed.
custom_output
This obscure field have two effects of generated page:
- first, all widget created after a widget with this field set on (1), will be generated without initial container, and start-end comments.
- two, the page is rendered without doctype, meta, headers, if at least one custom_output set on (1) is founded.
cleaning widgets field
$custom_output= 0 | 1 $custom_header= Content-Type: application/xml; Content-type: text/css...
When $custom_header is set, custom_output must be 1. If no set, custom_output must be 0. Proposal: Custom header can be suppressed.
note:
- in run-time a $custom_output variable must exists, because if a father have set custom_header, their sons can't be generate a
container.
- QUESTION/HELP: somebody know the use of other $custom_header values?
$widget->widget_type = div, ol, form...) $widget->remove_container = 0,1..
These fields define the container of each widget. Proposal: The last field can be suppressed if widget_type is none,div,ol,form...
note: no container is generated if custom_header is set.
