HFS: Template: Difference between revisions

From rejetto wiki
Jump to navigation Jump to search
No edit summary
 
(Undo revision 5314 by 78.160.89.245 (Talk))
 
(114 intermediate revisions by 31 users not shown)
Line 1: Line 1:
== Applying templates from a forum ==
Some of the procedural information in this section is now outdated.
Although most of the details about sections and symbols etc. is still correct, you should obviously use the new [[HTML Template Editor]].
----
== Applying templates from the forum ==


Download templates from the HFS templates forum.
You can download templates from the [http://www.rejetto.com/forum/viewforum.php?f=24 HFS templates forum] or from the [http://rejetto.com/wiki/index.php?title=Gallery HFS Template Gallery]. To apply a template, follow these steps:
# Open the "Menu" in HFS.
# Select "Other options" and open "Edit HTML template".
# Copy your HTML template and paste it over the HFS  "HTML template".
Test your new HTML template by pressing the "apply" button and reloading the HFS web page into your browser.


1. Open the "Menu" in HFS
== Building your own HTML template ==
1. Open the "Menu" in HFS.
 
2. Select "Other options" and open "Edit HTML template".


2. Select "Other options" and open "Edit HTML template"
3. Press the "Help" button to list the available symbols for your HTML template.


3. Copy your HTML template and paste it over the HFS "HTML template"
== How templates work ==
HFS builds HTML pages dynamically by loading pieces of HTML code from a template.
A template is text divided into sections. Each section describes a part of the final HTML page which will be served to the requesting browser. The template must provide all sections for correct working of the generated HTML, so a section usually contains HTML code. Since the final HTML page is built dynamically, symbols have to be used to get valid output. Symbols are surrounded by '''%percent%''' characters and define the corresponding sections.
A section is labelled by using '''[square brackets]'''. Symbols will be translated into actual values at run-time. Some symbols return a string for the current variable, while others only get activated if a certain condition is met. Besides symbols, some defined address line operators can also call sections to generate HTML for output.  


Test your new HTML template by pressing the "apply" button and reload your HFS web page on your web browser.
In the main section, which can be unlabeled or labeled simply with [], and in all other sections, symbols can be used to control the HTML output. Some symbols are limited to a specific section. Some symbols will produce the HTML from the corresponding sections, while others just return the corresponding actual string or value.


The best way to build a template is to edit an existing template.


== Building your own HTML template ==
== Where is the template stored ==
   
The template is stored always "near" the options. If the options are saved in disk (file ''hfs.ini'') then the template is also saved to disk (file named ''hfs.tpl''). You can find these files in the same folder as ''hfs.exe'' (the software).
1. Open the "Menu" in HFS
More often, both the template and the options are saved in the registry (by default).
 
The template is loaded at HFS startup. If no template is found, then the default one is used.
 
== Other useful things ==
 
If you are bustling with template editing, you will be interested in [[HFS: Template symbols|symbols]], [[HFS: Template macros|macros]] and [[HFS: Address operators|address operators]].
 
== Sections list ==
Sections available in the template:


2. Select "Other options" and open "Edit HTML template"
; [style]  : HTML for the %style% symbol
; [login-link] : HTML for the %login-link% symbol when no user is logged in
; [loggedin] : HTML for the %loggedin% symbol when the user has logged in
; [up] : HTML for the %up% symbol when there's a parent folder (not root)
; [link] : HTML for the a link to an URL
; [folder] : HTML for the link to a folder
; [file] : HTML for the link to a file
; [file.<EXT>] : used in place of [file] when the file has the specified extention
; [files] : HTML for the %files% symbol when the current folder is not empty
; [nofiles] : HTML for the %files% symbol when the current folder is empty
; [comment] : HTML for the %comment% symbol for sections [file], [folder] and [link] if available in the VFS
; [folder-comment] : HTML for the %folder-comment% symbol if available in the VFS
; [newfile] : HTML for the %new% symbol if the item is marked as new
; [upload-link] : HTML for the %upload-link% symbol when the user has upload rights
; [upload] : HTML for the ~upload command
; [upload-file] : HTML for the upload form
; [upload-results] : HTML for the upload results page after upload has finished
; [upload-success] : HTML for the successfully uploaded files
; [upload-failed] : HTML for the unsuccessfully uploaded files
; [progress] : HTML for the %progress% symbol
; [progress-download-file] : HTML for ongoing download
; [progress-upload-file] : HTML for ongoing upload
; [progress-nofiles] : HTML when no file transfer is ongoing
; [upload-no-progress] : HTML for the ~upload-no-progress command
; [upload+progress] : HTML for the ~upload+progress command
; [error-page] : HTML in case of an error
; [overload] : HTML for the %content% symbol
; [unauthorized] : HTML for the %content% symbol
; [deny] : HTML for the %content% symbol
; [ban] : HTML for the %content% symbol
; [max contemp downloads] : HTML for the %content% symbol
; [not-found] : HTML for the %content% symbol
; [item-archive] : HTML for the %item-archive% symbol
; [sym-My_Section] : HTML for the %sym-My_Section% symbol ( %sym-test% <>[sym-test] )
; [protected] : HTML for the %protected% status, associate with <img src='/~img_lock'>


3. Press the "Help" button to list the available symbols to use in your HTML template.
== Section aliasing ==
You can specify 2 or more sections in brackets, and the same content will be assigned to all of them.


The syntax is '''[A = B = C = D]''' where A, B, C, etc, are sections.


== Template help ==
This is very useful when you are specifying the content for [file.EXT] sections, like images. '''[file.jpg = file.jpeg = file.png = file.gif]'''


== Customizing graph colors and size ==


The template is a model for HFS to build HTML pages.
'''Available since build #081.'''
It is divided in sections. Each section describes a part of the final HTML page.
The template should provide all sections for correct working.
Sections usually contains HTML code.
Since the final HTML page is built dinamically you must use symbols to get
a useful output. Symbols will be translated with right values at run-time.
Symbols are surrounded by %percent% characters.
A template is divided in sections. A section is labeled using [square brakets].
There is a main section, unlabeled, used for file showing.
In every section you can find symbols. Some symbols are limited to some section.
The best way to build a template is to edit an existing template.


You can customize graph colors inside the template. The graph address is ''~img_graph'', but you can append to the name several options separated by an <tt>x</tt>.


== Symbols list - by section ==
For example,  <tt>~img_graph190x40xx333x000</tt>


The full list of options, in order is: width, height, refresh rate, background color, grid color, out bandwidth color, in bandwidth color, text color.


'''Symbols available in all sections:'''
You can specify as many options as you want, even none.
%connections% current number of connections
Current default values for width/height/colors are the same as in HFS window.
%style% converts to [style] content
%timestamp% current time and date of the server
%version% HFS version
%uptime% how long HFS has been running without quitting
%speed-out% current outward throughput
%speed-in% current inward throughput
%total-out% total amount of bytes sent
%total-in% total amount of bytes received
%user% name of the authenticated user, void if no user is logged
%loggedin% converts to [loggedin] if a user is logged in,
void otherwise
%login-link% converts to [login-link] if no user is logged in,
void otherwise


'''Symbols available in the main section:'''
Colors can be specified in at least two forms: RGB, RRGGBB.
%host% the Host http header field, as sent by the browser
%upload-link% converts to [upload-link] if upload is available in the
current folders, void otherwise
%up% convers to [up] if the current folder is not the root,
void otherwise
%files% converts to [files] if at least an item is present in the
current folder, converts to [nofiles] otherwise
%number% number of items in the current folder
%number-files% number of files in the current folder
%number-folders% number of folders in the current folder
%total-size% amount of space occupied by items in the current folder
%total-bytes% as %total-size% but expressed in bytes
%total-kbytes% as %total-size% but expressed in kilobytes
%build-time% how long it took to generate the page
'''
Symbols available in [files]'''
%list% the full list of items in the current folder, got by gluing
each item after the pertinent section ([file] [folder] or
[link]) was converted


'''Symbols available in [file] [folder] [link]'''
''Refresh rate'' doesn't work inside template itself, but only if you access the graph alone, directly in your browser. If not specified, refresh is disabled.
%new% converts to [new] if the file is marked as new,
void otherwise
%item-url% URL to get the item
%item-name% label of the item
%item-added% when was the item added to the VFS
%comment% converts to [comment] if a comment is available for the
item, void otherwise


'''Symbols available in [file] [folder]'''
== Embedding pages inside a template ==
%item-dl-count% download counter (virtual folders totalize inner counters)
%item-modified% modification time as reported by


'''Symbols available in [file]'''
If you put a whole HTML page under '''[a_name_you_choose]''' section, then it will be available at
%item-size% amount of space occupied by the item
%item-size-b% as %item-size% but expressed in bytes
%item-size-kb% as %item-size% but expressed in kilobytes
'''
Symbols available in [upload] [upload+progress] [upload-results] and main section'''
%diskfree% total amount of available space in the drive containing
the current folder (makes sense only for real folders)
%folder% path to the current folder
%encoded-folder% encoded path to the current folder
%parent-folder% encoded path to the parent folder
%folder-comment% converts to [folder-comment] if a comment is available for
the current folder, void otherwise


'''Symbols available in [error-page]'''
<tt><nowiki>http://YOUR_ADDRESS/~a_name_you_choose</nowiki></tt>
%content% converts to [ban] [deny] [not found] [unauthorized]
[overload], depending on the error


'''Symbols available in [ban]'''
== Unicode support ==
%reason% ban description


'''Symbols available in [progress]'''
Normally HFS converts %symbols% to ANSI characters (not unicode).
%progress-files% converts to [progress-nofiles] if no file is transferred
But the default template itself uses unicode UTF-8 encoding, to easily support any character/glyph.
with the current client, otherwise the list of transferring
files got by gluing each file after the pertinent section
([progress-download-file] or [progress-upload-file]) was
converted


'''Symbols available in [progress-download-file] [progress-upload-file] related to the transferring file'''
HFS will know the template wants UTF-8 by searching for the string '''=UTF-8''' inside the template itself. This is supposed to be part of the string
%perc% percentage
<meta http-equiv="content-type" content="text/html; charset=UTF-8" />
%filename% name of the file
Then, when this is found, HFS will work accordingly.
%done-bytes% transferred bytes
%total-bytes% number of bytes of the complete job
%done% as %done-bytes% but using dynamic measure unit
%total% as %total-bytes% but using dynamic measure unit
%speed-kb% throughput


'''Symbols available in [upload]'''
The searching is made in the source of the template, far before any symbol or macro is expanded, so don't try to make this dynamic.
%upload-files% input boxes for files to be uploaded got by gluing
[upload-file] for each file
'''
Symbols available in [upload-file]'''
%idx% ordinal index of the input box


'''Symbols available in [upload-results]'''
== Section options ==
%uploaded-files% list of uploaded files got by gluing [upload-success] or
[upload-failed] for each file


'''Symbols available in [upload-success] [upload-failed]'''
'''Feature only available since version 2.3'''
%item-name% name of the file


'''Symbols available in [upload-success]'''
Sections can have some options specified by using the pipe "|" as separator.
%item-size% size of the file
%speed% avarage speed
'''
Symbols available in [upload-failed]'''
%reason% description of error occurred while uploading


________________________________________________________________________________
E.g. <tt>[options|a|b]</tt> is a section named ''options'' with 2 parameters, ''a'' and ''b''.
<br>These are just dummy options, there's no option named ''a'' or ''b''.


Here is a list of available options:


== Sections list ==
; private
: by default, sections are accessible via web, just by specifying the correct address. See [[#Embedding pages inside a template]] for more information.
: By specifying this options, you'll disable this feature, and the section content will not be accessible via web.


'''Some of the sections available in template:'''
; no log
[up] defines the %up% symbol when there's a parent folder
: this option will disable any logging for this section, when it's accessed via web.
[file] defines a link to a file
[folder] defines a link to a folder
[link] defines a link to an URL
[files] defines the %files% symbol when there's some file
[nofiles] defines the %files% symbol when there's no file
[comment] defines the %comment% symbol for [file] [folder] and [link]
[style] defines the %style% symbol
[login-link] defines the %login-link% symbol when no user is logged
[loggedin] defines the %loggedin% symbol when the user has logged in
[upload-link] defines the %upload-link% symbol when the user has upload rights
[up] defines the %up% symbol
[folder-comment] defines the %folder-comment% symbol when there's a comment for
the current folder
[error-page] the frame used for all error pages
[overload] defines %content% for the related error-page
[unauthorized] "
[deny] "
[ban] "
[not-found] "
[max contemporary downloads]
"
[upload] the upload page
[upload-file] form item for a single file
[upload-results] the upload results page
[newfile] defines the %new% symbol when the item is marked as new

Latest revision as of 03:45, 27 March 2013

Some of the procedural information in this section is now outdated. Although most of the details about sections and symbols etc. is still correct, you should obviously use the new HTML Template Editor.

Applying templates from the forum

You can download templates from the HFS templates forum or from the HFS Template Gallery. To apply a template, follow these steps:

  1. Open the "Menu" in HFS.
  2. Select "Other options" and open "Edit HTML template".
  3. Copy your HTML template and paste it over the HFS "HTML template".

Test your new HTML template by pressing the "apply" button and reloading the HFS web page into your browser.

Building your own HTML template

1. Open the "Menu" in HFS.

2. Select "Other options" and open "Edit HTML template".

3. Press the "Help" button to list the available symbols for your HTML template.

How templates work

HFS builds HTML pages dynamically by loading pieces of HTML code from a template. A template is text divided into sections. Each section describes a part of the final HTML page which will be served to the requesting browser. The template must provide all sections for correct working of the generated HTML, so a section usually contains HTML code. Since the final HTML page is built dynamically, symbols have to be used to get valid output. Symbols are surrounded by %percent% characters and define the corresponding sections. A section is labelled by using [square brackets]. Symbols will be translated into actual values at run-time. Some symbols return a string for the current variable, while others only get activated if a certain condition is met. Besides symbols, some defined address line operators can also call sections to generate HTML for output.

In the main section, which can be unlabeled or labeled simply with [], and in all other sections, symbols can be used to control the HTML output. Some symbols are limited to a specific section. Some symbols will produce the HTML from the corresponding sections, while others just return the corresponding actual string or value.

The best way to build a template is to edit an existing template.

Where is the template stored

The template is stored always "near" the options. If the options are saved in disk (file hfs.ini) then the template is also saved to disk (file named hfs.tpl). You can find these files in the same folder as hfs.exe (the software). More often, both the template and the options are saved in the registry (by default).

The template is loaded at HFS startup. If no template is found, then the default one is used.

Other useful things

If you are bustling with template editing, you will be interested in symbols, macros and address operators.

Sections list

Sections available in the template:

[style]
HTML for the %style% symbol
[login-link]
HTML for the %login-link% symbol when no user is logged in
[loggedin]
HTML for the %loggedin% symbol when the user has logged in
[up]
HTML for the %up% symbol when there's a parent folder (not root)
[link]
HTML for the a link to an URL
[folder]
HTML for the link to a folder
[file]
HTML for the link to a file
[file.<EXT>]
used in place of [file] when the file has the specified extention
[files]
HTML for the %files% symbol when the current folder is not empty
[nofiles]
HTML for the %files% symbol when the current folder is empty
[comment]
HTML for the %comment% symbol for sections [file], [folder] and [link] if available in the VFS
[folder-comment]
HTML for the %folder-comment% symbol if available in the VFS
[newfile]
HTML for the %new% symbol if the item is marked as new
[upload-link]
HTML for the %upload-link% symbol when the user has upload rights
[upload]
HTML for the ~upload command
[upload-file]
HTML for the upload form
[upload-results]
HTML for the upload results page after upload has finished
[upload-success]
HTML for the successfully uploaded files
[upload-failed]
HTML for the unsuccessfully uploaded files
[progress]
HTML for the %progress% symbol
[progress-download-file]
HTML for ongoing download
[progress-upload-file]
HTML for ongoing upload
[progress-nofiles]
HTML when no file transfer is ongoing
[upload-no-progress]
HTML for the ~upload-no-progress command
[upload+progress]
HTML for the ~upload+progress command
[error-page]
HTML in case of an error
[overload]
HTML for the %content% symbol
[unauthorized]
HTML for the %content% symbol
[deny]
HTML for the %content% symbol
[ban]
HTML for the %content% symbol
[max contemp downloads]
HTML for the %content% symbol
[not-found]
HTML for the %content% symbol
[item-archive]
HTML for the %item-archive% symbol
[sym-My_Section]
HTML for the %sym-My_Section% symbol ( %sym-test% <>[sym-test] )
[protected]
HTML for the %protected% status, associate with <img src='/~img_lock'>

Section aliasing

You can specify 2 or more sections in brackets, and the same content will be assigned to all of them.

The syntax is [A = B = C = D] where A, B, C, etc, are sections.

This is very useful when you are specifying the content for [file.EXT] sections, like images. [file.jpg = file.jpeg = file.png = file.gif]

Customizing graph colors and size

Available since build #081.

You can customize graph colors inside the template. The graph address is ~img_graph, but you can append to the name several options separated by an x.

For example, ~img_graph190x40xx333x000

The full list of options, in order is: width, height, refresh rate, background color, grid color, out bandwidth color, in bandwidth color, text color.

You can specify as many options as you want, even none. Current default values for width/height/colors are the same as in HFS window.

Colors can be specified in at least two forms: RGB, RRGGBB.

Refresh rate doesn't work inside template itself, but only if you access the graph alone, directly in your browser. If not specified, refresh is disabled.

Embedding pages inside a template

If you put a whole HTML page under [a_name_you_choose] section, then it will be available at

http://YOUR_ADDRESS/~a_name_you_choose

Unicode support

Normally HFS converts %symbols% to ANSI characters (not unicode). But the default template itself uses unicode UTF-8 encoding, to easily support any character/glyph.

HFS will know the template wants UTF-8 by searching for the string =UTF-8 inside the template itself. This is supposed to be part of the string 

<meta http-equiv="content-type" content="text/html; charset=UTF-8" />

Then, when this is found, HFS will work accordingly.

The searching is made in the source of the template, far before any symbol or macro is expanded, so don't try to make this dynamic.

Section options

Feature only available since version 2.3

Sections can have some options specified by using the pipe "|" as separator.

E.g. [options|a|b] is a section named options with 2 parameters, a and b.
These are just dummy options, there's no option named a or b.

Here is a list of available options:

private
by default, sections are accessible via web, just by specifying the correct address. See #Embedding pages inside a template for more information.
By specifying this options, you'll disable this feature, and the section content will not be accessible via web.
no log
this option will disable any logging for this section, when it's accessed via web.
Retrieved from ‘http://rejetto.com/wiki/index.php?title=HFS:_Template&oldid=5509’