image | Contains image files used by the file manager. Image files for new applications should be in sub-folders here. |
src | Contains template files for the file manager. Template, Perl module, and configuration files for new applications will be in sub-folders here. |
perl | For Perl modules installed by new applications to be shared by multiple applications |
install | Application installation packages. KuKu log files. Other miscellaneous files used by KuKu. debug.ftl - if exists, kuku does not reinstall the file manager and developer when starting. |
install/upload | Used internally by the file manager. When files are uploaded, they go here while uploading and are then moved to the appropriate destination when upload completes. |
share | Reserved for a module in the file manager. (Currently not used, this module is being redesigned). |
application root directory | Reserved for KuKu configuration.
All application files should be in sub-folders.
ku.cfg - configuration for KuKu system, file manager, and web servers (HTTP and HTTPS). ku1.cfg - default configuration favicon.ico |
KuKu system and file manager | |
apps= | List of installed applications (for main menu) |
build=YYYYMMDD | KuKu build date |
files_path= | Path to KuKu root directory |
keepAlive=seconds | For devices with dynamic IP addresses. The IP address is periodically rechecked and configuration entries are updated when it changes. |
log= | File path for HTTP server log |
mobile=yes/no | |
portmask=8*** | Generate port number for the HTTP server. One to three asterisks can be used to make port number unique when multiple KuKu devices are behind a nat router which uses port forwarding. The last one to three digits of the device IP address is used in place of the asterisks. |
port= | The resulting port number created by the portmask (updated each time KuKu is started). |
pwdAdmin= | Password for admin. Full access. |
pwdRead= | Password for read access. Can see most files, but update nothing. Cannot see configuration page. |
pwdWrite= | Password for read / write access. Can view / update most files. Cannot see configuration page. |
version= | KuKu installed version |
install= | Timestamp set when installed |
javaPath= | Java bin folder path on non-Android systems. Needed if running the HTTPS (SSL) server. |
javaVersion= | Set to version of installed java system. Checked each time KuKu starts. |
HTTP Server | |
home=. | Internal use (don't change) |
reuse=1 | Internal use (don't change) |
mime=mime.txt | Mime definition file path |
log=http.log | Will write log information to this file if file exists. Create empty file to activate logging (requires restart). Change name to end logging (requires restart). Take care using this log. It contains REQ data in plain text, which could be a security problem. |
maxheader=5000 | Requests with headers larger than this number will be rejected. |
maxpost=100000 | Requests with posted data larger than this number will be rejected. |
gzip= | Regex used to determine what mime types can be compressed. |
port= | Port number for HTTP access. Will use either 8000 or 8080 if the selected port can't be accessed. |
HTTPS (SSL) Server | |
sslCertPwd= | Certificate password |
sslKeyset= | Keyset file path |
sslKeysetPwd= | Keyset file password |
sslKeystore=BKS | Keystore type. Android requires Bouncy Kastle. Can use JKS on MS-Windows. |
sslLog= | SSL log file path. (Viewable only by admin user). |
sslPort= | Port number for HTTPS access. If not specified, the HTTPS server does not run. |
Dynamic DNS | |
dnsHost= | Dynamic Host name (dyndns.org) |
dnsUser= | Dyndns user login name |
dnsPassword= | Dyndns user password |
dnsStatus= | Status set when DNS / IP updates are done |
dnsMyIP= | IP address used for the last Dyndns update |
myLocalIP= | Local network IP address (set each time KuKu starts) |
myPublicIP= | IP address for internet access to your KuKu device (set when KuKu starts, and each time it is found to change - based on keepAlive) |
kuku.cfg | KuKu system configuration |
*.ftl | Template files |
mime.txt | Mime definitions for web server |
kuku.bks | Sample keyset file (bouncy castle format). This keyset is for testing only. It is self-signed by Codatech. For production SSL use, you must create your own certificate and keyset file, whether self-signed or officially signed. |
sub-folders | A sub-folder in the src folder is created for each custom application. An application consists of a configuration file, and one or more template files and Perl modules. Additional folders can be created for files used by the application. |
*.cfg | Application configuration |
app:name | Application name |
app:version | Version |
app:date | Date created |
|
Application title for the main menu |
menu:Icon.name | Image file path for icon for the main menu |
install:path.* | One entry for each file to be included in the application release package. To create a folder with no files - folder-name/.void |
HTTP:content_length=999All form data from the request will be defined as templates and added to the template object. These templates will be defined in the REQ: namespace. Example:
REQ:myfield=some dataFields with names ending with '_q' are encrypted when the request is sent to the KuKu server. The server decrypts the fields and adds template definitions for the plain text named without the '_q' on the end. Example:
REQ:private_q=encrypted text REQ:private=plain textAny templates defined in previous requests within the SESSION: namespace are copied to the template object.
pm:secure(field from to) << Task::encryptField($ftl, '%field%_q', '%from%', '%to%'); return(''); <<pm:secure data() << %pm:secure(name plain:fld secure:fld)% <input type=text name=name_q value="%secure:fld%"> <<data
RESP:content_type=text/htmlThe response is then formatted for return to the browser using the RESP: templates and the web page text from the template processing. The response is sent to the browser. Any templates defined in the SESSION: namespace are saved for the session. The request processing is then complete.
Request Header TIME= HTTP:COMMAND= HTTP:HOME=. HTTP:METHOD= HTTP:PATH= HTTP:PEERHOST= HTTP:PEERPORT= HTTP:SEQUENCE= HTTP:URL= HTTP:ARGS= HTTP:DATA= HTTP:https_ip= HTTP:https_port= HTTP:https_cipher_suite= HTTP:https_protocol= HTTP:name=value All header items Request Body REQ:token= REQ:sig= REQ:name=value All fields from form Response Header RESP:cache_control= RESP:content_encoding= RESP:content_length= RESP:content_type= RESP:creation_date= RESP:date=Day, dd Mth yyyy hh:mm:ss GMT RESP:error= RESP:error_msg= RESP:expires= RESP:last_modified= RESP:read_date= RESP:abort=
Self-signed - Android requires BKS keytool -genkey -keyalg RSA -alias kukukey -keypass kukuKey -keystore kuku.bks -storepass kukuKey -validity 9999 -storetype BKS -providerClass org.bouncycastle.jce.provider.BouncyCastleProvider -providerpath bcprov-jdk16-145.jar Self-signed - JKS - non-Android keytool -genkey -alias kukukey -keypass kukuKey -keystore kuku.jks -storepass kukuKey -validity 9999 -keyalg RSA (?default) -storetype JKS (?default) List keytool -list -v -keystore kuku.bks -storetype BKS -providerClass org.bouncycastle.jce.provider.BouncyCastleProvider -providerpath bcprov-jdk16-145.jar
See dyn.com/dns/ Configuration dnsHost= dnsUser= dnsPassword= dnsStatus= dnsMyIP= myLocalIP= myPublicIP= publicLocalIP=
file.ftl # Main templates for application <src/global.ftl <src/app/app.cfg <src/app/%PAGE%.ftl PACKAGE=myApp # Directives # Definitions
def1=abcReferences to other templates can be anywhere in the template. A reference begins with a % followed by the name of the referenced template, some optional parameters, ending with another %.
def2=here is some %def1%.A definition can specify parameters for which arguments can be supplied when invoking the template.
def3(arg1 arg2)=The args are %arg1% and %arg2%.The definition can specify an argument count rather than names. This will create arguments named as 1_, 2_, etc.
def3(2)=The args are %1_% and %2_%.The argument list in a reference can be either space delimited or tab delimited. When space delimited, each argument must be one word or must be quoted. Data templates created by application modules can easily tab delimit the data. Tab characters within template text are easily confused with spaces. A template %t% is used instead, which is defined as the tab character. If a reference has a single argument with spaces, it must be quoted. Another syntax allows for definitions requiring multiple lines:
def4() << some stuff. and this: %def3("first thing" "%def2%")% and more: %def3(more stuff here %t% %def2%)% more stuff. <<def4The text of a template definition does not include the last line-feed character at the end of the definition. If a line-feed is needed at the end, a %n% template is defined as the line-feed character.
def3(2)=The args are %1_% and %2_%.%n%When a template reference does not include enough arguments for the template, the template is not processed and an empty string is returned. A list of numbers can be created for arguments in the format: n..n. When a template reference includes more arguments than are defined for the template, the arguments are divided into groups and multiple references are made to the template.
%def3(one two three four 5..8)%Will produce:
The args are one and two. The args are three and four. The args are 5 and 6. The args are 7 and 8.A reference can apply a Regex to a template.
RE:phone= (\d{3})(\d{4}) :: %1_%-%2_% myphone(num)=phone: %num/RE:phone%%n% %myphone(5551234 8887890)%Will produce:
phone: 555-1234 phone: 888-7890Prefix the template name in a reference with a ! to test a condition:
%!myphone("%list%")%.If the reference returns text, the text is replaced with an empty string. If the reference returns an empty string, a string with the single character '1' is returned.
def5() << %<another.ftl %@app::func <<def5Templates can be organized into logical arrays by appending a subscript value to the name.
mybox.high=3 mybox.wide=4 mybox.length=8 part(x)=the part [%x%] = %mybox.x%In the above example, mybox is the array name, and
mydef=1234 main:mydef=1234The default namespace is defined by a special template named :PACKAGE. The :PACKAGE definition is saved before reading another file and restored when reading is compete. The default can be changed by redefining :PACKAGE. The colon (:) on :PACKAGE is assumed when defining it. The following will define a template named
PACKAGE=mySpace mydef=1234Multiple levels of namespaces are supported.
space1:subspace:lowspace:mydef=4567 RAW:data:record=anything OUR:global:header=my title stuff pm:module1:func=some codeSeveral predefined namespaces have special functionality.
main: | The initial default namespace |
RAW: | Any templates in the RAW: namespace are copied as is. No embedded directives or references will be processed. |
OUR: | OUR: templates are processed in the context of the referring template. |
SESSION: | Templates in the SESSION: namespace are saved by the web server between requests. |
pm: | The definition for a pm: template is Perl code. When referenced, the template will be processed and the resulting code will be compiled and executed. This occurs on every reference to the template. |
: | An unnamed namespace is used for some internal definitions. |
:PACKAGE | Defines the default namespace. :PACKAGE maintains the namespace context. Template definitions or references that do not specify a namespace use the namespace defined by :PACKAGE. When a template reference is being processed, :PACKAGE is set to the namespace of the template being processed. The :PACKAGE definition will be restored to the referring namespace when the processing is complete. References to templates in the OUR: namespace are processed in the context of the referring template. The :PACKAGE definition will not be changed for references to the OUR: namespace. |
:PARENT | Defines the previous namespace context. Template references that do not specify a namespace are searched for first in the namespace specified by :PACKAGE. If not found, the namespace specified by :PARENT is searched. |
<file | Read definitions from file. A template, :PathFTL, defines paths for searching for template files (if undefined, defaults to '.'). |
<%mydef% | Read definitions from a template. If the result of a template reference is a name with no line-feed, it is the name of a file containing the definitions. If the text contains any line-feeds, it is the actual text of the definitions. |
<file defname | Read file into definition. A template is defined for defname, which will contain the entire text from the file. |
>file defname | The result of %defname% will be written to the file. |
|
Same, but appends to file. |
-defname | Delete the template definition defname |
@module::sub | Call Perl |
pm:example() << my $item1 = $ftl->{item}; #will not find item when no namespace included my $item3 = $ftl->{'my:item'}; #item text before template processing my $item2 = $ftl->FETCH('item'); #item text after template processing $ftl->STORE('item', 'new text'); #item redefined $ftl->DELETE('something'); my ($name, $value) = $ftl->FIRSTKEY(); my ($name, $value) = $ftl->NEXTKEY(); my $val = $ftl->SCALAR(); $ftl->EXISTS('somekey') and dostuff(); return("text string"); <<pm:exampleThe hash methods will access template definitions within the context of the namespace from which the pm: template or Perl module was referenced.
my %hash; my $obj; $obj = tie(%hash, 'Text::Ftl', 'mydefs.ftl'); $hash{def1} = "some %def2% stuff"; $hash{def2} = "whatever"; my $text = $hash{def1}; $obj->read('file.ftl');
d1=one d2=two def=Values are %d1% and %d2%. |
Basic template definitions. Templates are name - value pairs. A value is any string of characters. A reference to a template is the template name delimited by '%' characters. A reference to template d1 returns a value of one. A reference to template def returns a value of Values are one and two. |
---|---|
t1()=string t2(1)=[%1_%] t4(param) << multiple lines -- %t3(%param% xyz)% -- last line <<t4 |
A definition can include parameters.
When referencing a template that requires parameters,
values for the parameters must be included.
When the template is referenced, a temporary template will be defined for each
parameter name with the value supplied in the reference.
When a definition specifies a count instead of a parameter list,
the parameter templates will be named as 1_, 2_, 3_, etc.
A reference to %t4(abc)% will return - multiple lines -- string with abc and [xyz] -- last line |
PACKAGE=mySpace name1=value otherSpace:name1=other value RAW:myData=my value |
Templates can be organized within multiple namespaces. A special template :PACKAGE is used to define the current namespace (default is main:). A RAW: namespace is used for templates for which embedded directives will not be processed. An OUR: namespace is for templates that will be processed within the context of the invoking template. |
:00= \x00 :FF= \xff :t= \t :r= \r :n= \n :f= \f :e= \e :LIST :PathFTL :PathPM |
An unnamed namespace (:) is used by FTL to define internal templates. |
pm:uc(str) << return("\U%str%"); <<pm:uc |
A pm: namespace is used for templates which are perl source code which will be compiled and executed when retrieved with the return value of the code replacing the reference to the template. If an error occurs when executing the code, a template FTL:PM:error will be defined with an error message as the template value. |
<filename <%my:defs% |
Reads a template file or text from a template. All definitions in the file will be added to the current template object. |
<filename defname | Reads a text file or template and creates a template definition with the file text as the value. |
>filename template | Writes the processed template to the file. |
-template | Removes the template from the hash (deletes). |
@pkg::sub string | Calls perl code pkg::sub(\$ftl) passing the Ftl object. The string is passed as a template with the same name as the sub. The sub can get processed templates from the object and add new templates. |
Embedded directives are processed when a template is retrieved from the hash. An embedded directive or definition begins with a '%' character and ends at the end of the line. Embedded definitions can be the single line format only. For a directive that is a reference to another template, the template will be retrieved and will replace the directive. | |
%name% %name()% %name(arg1 arg2)% |
When the referenced template requires parameters, arguments must be supplied in the reference. If the argument list contains tabs (\t, or %t%), then the list is split on the tabs. Otherwise, the list is split on spaces. When space delimited, arguments containing spaces must be quoted with double quotes. If the number of arguments is less than the number of parameters, the reference will be replaced with an empty string. Temporary templates are defined for each of the specified parameters using the parameter name and the corresponding argument value. If the parameter list is specified as a count rather than a list of names, the parameter templates will be named with numbers as 1_, 2_, 3_ ... |
If the number of arguments supplied is greater than the parameter list, the argument list will be divided into multiple lists of the required number and the referenced template will be retrieved multiple times, once for each of the argument lists. | |
If the name contains any substrings of the format .str, each str in the name will be replaced with the result of processing the template named str. | |
regexname=regex :: replacement | If a Regex is specified in the reference, it will be used to perform a global substitution on the retrieved template string. Each substring in the template string matching the Regex will be replaced with the replacement. Any groups captured by the match will be defined as templates with names as 1_, 2_, 3_ ... The entire matching string will be defined as a template named 0_ . The replacement is defined as a template and then retrieved causing any embedded references to be processed. |
If the template reference begins with a "!", the retrieved template will be checked for content. If it is blank, it will be set to the string "1". If it is not blank, it will be set to an empty string. |
yourapp.cfg | The configuration file for the application |
yourapp.ftl | Main template file for the application |
yourapp.pm | A sample perl module for the application |
index=%xyz:page1% page1=%xyz:page1% page2=%xyz:page2%The template
xyz:page1=%OUR:page(page1 "App First Page" "/ftl/xyz/page1")%Three arguments are required. The first is the template name which will be used to reference other templates for this page. The second is the string which will be used for the
All file contents are © Copyright Codatech, Inc. 2003-2016. All rights reserved. |