This is a reference for v2 resources. Reading docs is a pre-requisite for this.

Version 2

There are notes about intended future developments.

In the style of PNG, a 'chunk' is a set of bytes; unlike PNG, these normally in UTF-8. The second generation will have a looser document type. This is the primary data type is logged in the structure rather than fixed as Wiki. It will have a better symbol expansion scheme, to dynamically swap the alternate data type chunks into each other. This will reduce the need for do_get function creating links in an otherwise complete document.

It is intended to keep the basic chunking structure and syntax, but extend the header to
{{<type> <name> <filter>
...
}}
The basic list of types is (lower case in the doc):

  1. JS *
  2. CSS *
  3. HTML *
  4. wiki *
  5. PHP5
  6. comment *
  7. file, include
  8. pagemeta
  9. plain *
  10. body
  11. form
  12. table
  13. tablist

The actions to render items marked with a * should not surprise anyone, and are self explanatory.

The filters are optional, and are copied from Symfony/twig. It is more useful to add a few features to the engine than need to alter every chunk via some complex PHP chunk. In time there will be range of filters, but only one I have needed at the moment is:

  1. 'nowrap' ~ this strips the opening and closing <p> tags from Wiki chunks, so they can be fitted into a HTML chunk.
  2. 'escape' ~ the chunk is passed through htmlentities, before being merged with the document.
  3. 'encode' ~ the chunk is passed through urlencode, before being merged with the document.
  4. 'json' ~ the outbound chunk should be encoded as JSON, via json_encode

Symbols are named chunks that are referenced inside other chunks. They are to be defined as
[[name]] .
this will not clash with any other content format I could think of, and shouldn't need escaping.

It is intended to support JS and CSS, but to discourage there use inside HTML body tags, they should be limited to the HTML head. These are verbatim texts, but the interpreter will inject the surrounding tag definitions to hold them. Comment chunks are obviously not processed. A file chunk will import the contents of the file at the supplied location. This lets one have common definitions of chunks. The meta chunk is the existing header structure. A plain chunk is for importing static text such as licence files. The requirements for a table or tablist chunk are listed in the end.
The PHP5 chunks are executed in the same fashion as the do_get and do_post are in v1. The PHP5 chunks may be the name of a procedural function, which is executed; or text to execute as a function body. 'include' is a synonym for PHP developers.
The form chunk type is documented below, this is likely to change in later versions. The current implementation is a minimal code import, to reduce code duplication (otherwise form writing code in the do_get functions in lots of places seems stupid).

The 'body' chunk is just a named chunk to make the templates simpler. This is treated as HTML or plain, in that no processing other than symbol replaced is performed. It is thought that designers would find this more intuitive than 'root'.

Under this structure the entire page is easy to put into templates. This reduces the amount of work in the renderer class by a large amount. The symbol lookup will need to be carefully defined. This supports branding and alternative formats such as AJAX/ JSON/ ReST better.

From a position of a structure that uses semantics to encode extensions, various features can be included as data (in the template). Firstly the menu in the page header, rather than a feature of the renderer. This flexibility is definitely beneficial for branding and contextual rendering. Additional proposed features are:

  1. Tag cloud;
  2. UI accessibility alterations;
  3. Translation;
  4. Client side debug monitors (for performance reasons, the live host has disabled logging);

Meta chunk

In v2 the following are identical to earlier v1, and are processed in identical fashion:

  1. docversion
  2. accessgroup
  3. method
  4. codeversion
  5. getopts
  6. postopts
  7. strapline
  8. author
  9. lang
  10. keywords
  11. modified

New features:

  1. alternativepost ~ allow normal procedural functions to be run rather than the do_post block. This process works by the name of the function is set in this attribute. This makes any contents of do_post be ignored. This feature is so complex source can be edited side a better editing environment than the wiki files. This is likely to be extended to normal OO code, when it is used more. Functions via here are given the same parameters as the do_post, please refer to iceline-v1.
    1. The primary business requirement of this small feature is to prohibit holding access credentials (to DB etc) in a location that customers will not be able to access. If the POST handler is in a separate file, access to the page content isn't a security problem.
  2. frame ~ set this to specify a frame. That is, a common page template holding all the HTML and other languages that is set on a per-site basis. This means the amount of work per resource is much smaller, and easier to manage. The platform will attempt to merge any substitution markers defined in the frame from data in the current resource. At the minima this should be “content”. Please read the appendix for more details. This is nothing to do with HTML3 framesets , I choose the name just after re-reading about stacker.
  3. mime-type ~ allows you to set the output Content-Type header. The literal text is applied to the headers, without editing.
  4. security ~ not yet implemented, see notes below.

Security

Before I detail objectives or process for this, I should mention references. I do read text from OWASP (e.g. 1 2), design notes from Zend (e.g. 3 4), general practice from Ars technica 5 6 7, and list of blogs 89. This section may also be written as “the new implementation of X windows” e.g. overview on X, an early RFC, on async messaging in XCB/X windows. The early AJAX and Xwindows have the same meme on “mechanism not policy” ~ a critical review . Everything that people at M.I.T. and similar Universities where discussing and designing is now happening again as a web framework.

As I am starting to publish this as a OSS product, I am backfilling alot of previously omitted process. I claim I have a secure design, but haven't demonstrated this. My input filters rules-table may noted as a barrier to entry; but does allow naif programming in the resources themselves. I thought this was likely to be a good feature.
When the test series will updated to a proper framework, so the tests can easily be run as a population; I will add a new series of tests aimed at what attackers would do, to get into a server.
The POST handler for the (authentication) resource will be created as part of the normal code base. There is no reason for a EU to be able to view source on how they login.
I would like this to pass OWASP standards.


The reason it is currently necessary to send your target resource while doing POSTs is to allow better granularity of POST configuration. Each POST is supposed to have a custom set of input rules. Doing it like this seemed the simplest way to manage it. Popular vote may later allow configuration via the SESSION.

With a test suite, I will add performance testscripts, and may need to rewrite some sections. That is several implementations of a particular feature, and benchmark them. I have alot more experience in performance optimising earlier versions of PHP and MySQL. This is scheduled for v3.

In the present design, output is sanitised inside “href” or “src” attributes. This means the resultant webpages pass wc3 validation. There is no mechanism to have anything user supplied in the responses, so nothing is currently validated (see 1). When this assertion fails, the code will need to be updated to clean the output input is cleaned via the [ValidationFilter] rulesets, and is documented in iceline-config. This may seem lack of forethought, but I am trying to get certified in various areas, rather than add new coding features (end of May2013 though Oct2013). In the first quarter I was pushing to stabilise format2, so the possible range of media was better.

As of version 2.0.1, this may not run very well on older versions of MS windows. I have removed some mock code, and am using a stronger/ more random session-key. This is now 128 chars long. I am not certain that MS windows supports 133 char file names (ISO960 doesn't, fat12 doesn't, fat16 won't work, fat32 probably will be okay, EXT2 ~ not that that is used anymore ~ will also fail). A work round is to wait for the DB backed sessions, so the data isn't stored on a disk.

As another feature for applications, rather than publishing; I have implemented prevention for CSRF 2. Specifically the formbuilder will append a 'new-hsh', that acts like a SESSION key. To provide a balance of “usefullness” vs “secureness”, I intend to add a 'security' meta item to the format. This is a weighting value, and the higher value, the greater number of checks are run before the response is returned to the EU. If you have a simple non-interactive article (say iceline-v2 ), it doesn't need any security, or a known identity. Conversally data submission to important things ~ a new single signon platform ~ is alot more constrained. I will probably rewrite the error message templates again at this point, to not issue too much information inside secured scenarios.

Appendices

Form definition

In v2.0. a form chunk is a PHP array, with string AVPs for the definition of the form element; and int AVPs (of further arrays) for the items.

The form element attributes (string array keys) supported in v2.0 are :

  1. 'method'
  2. 'encoding'
  3. 'action'
  4. 'name'
  5. 'protect-csrf' ~ add a tracking id so forms must be submitted back to the same server, from the same client inside a reasonable period. This is appended as a hidden form element, so session jacking will have no effect. Upon successful receipt, the csrf key is invalidated. If you are using this, it is necessary to set the name of the page chunk, or the data cannot be correlated. The lifespan is controlled via 'max_post_wait' config item. Please read 3 4 5 6 7 for a theory overview.

Usage to match standard HTML4.0 definitions.

AVPs for each form element (these match the HTML attributes):
Most of these are needed in an array, for each form item.

  1. value
  2. type
  3. id
  4. name ~ will auto-populate from ID if absent.
  5. display ~ optional, human visible text to describe the form element/ its label.
  6. style ~ optional, define the CSS class name.
  7. selected ~ optional, only used in selects. Set an item to selected, via the array key

Currently supported 'type's for form elements are

  1. datetime
  2. email ~ renders the same as text, but has appropriate validation rules
  3. text
  4. textarea
  5. button
  6. hidden
  7. select
  8. radio
  9. checkbox
  10. grouping ~ there is partial item grouping present

Intended further supported types (v2.1)

  1. better visualisation for item grouping
  2. fileupload
  3. ajax triggers

The HTML ids are generated as follows (this is important for making applications interactive) :

  1. The form items will have the supplied $id, which is mandatory.
  2. The auto created <p> elements when enabled, will will be $id.'Wrapper'.
  3. All of the <label> elements for radio and checkboxes are $id.'Label'.
  4. Future builds will support multiple forms per resource better, by prefixing the formname into the elements.

There is a list of CSS styles that may be passed into the form builder, stored in the site-config. The following names are looked up for the CSS class definitions.

  1. formp
  2. formlabel
  3. formtext ~ applies for all other input element types
  4. formtextarea
  5. formbuttons

There will be more development on CSS management. This will probably require an additional language, as large scale CSS is hard to manage.

CSS Classes can be set on a per-form-item basis from the input array, this is generally more useful.

Details for frames

Frames are added as a feature for format2, to reduce the amount of typing needed to make resources. They are a frame for the resource (think like an oil painting), and should hold common content across the site. Future builds will alter the active frame depending on requested response format (i.e. JSON doesn't want HTML elements).

The following replacements are defined in the compat-frame. This is a basic frame, to provide exactly the same features as the minimal skin I built first.

  1. 'resourcelang',
  2. 'resourcekeywords',
  3. 'menublock',
  4. 'resourcename',
  5. 'modifieddate',
  6. 'rendereddate',

I am moving all the code out of the PHP classes and into more templates. This means the designers have more flexibility. This will lead to a more complex execution time initially, as there will be alot more templates parsed. The actual time to convert a piece of string, into one of the [Page] objects isn't that big, and disk read time is probably more important. Where same templates read over and over, on busy site, the OS's disk-caching should improve performance. All the chunks could be put into a single template file, which would avoid that.


NB If you create a page using a frame, and absolutely no content is displayed, check the capitalisation on the names. The system ~ like a programming language ~ is currently case sensitive. Popular vote may make me change this.

NB2 The sitemap or site-chart resources are the fastest way to see if there are any syntax errors in your site. As both of these need to parse all the files in the site.

Table definition

A chunk of type 'table' can be in the resource. The version currently imported is to reduce the need for typing tags. Later and improved editions will be organised. It is possible to add a table via the wiki chunks, but doing it this way is much less effort.

Tables are basically a two dimensional array, very similar to an SQL resultset. The first set of keys are for each row, and the second each column. Additionally 'styles' and 'titles' may be set on a per table basis as keys in the first index. Titles when not set, are pulled from the keys of first row of data. To suppress titles entirely, set 'titles' to a value of false. All the values must be strings (or typecastable to strings), or they don't work in the HTML. Technically as long the 'titles' item is set, there is no need to manually set the array keys in the main table array yourself.

The following keys are understood in the styles array:

  1. 'table'
  2. 'table-tr'
  3. 'table-td'
  4. 'table-th'
  5. 'table-thr'
  6. 'thead-thr'
  7. 'thead-td'
  8. 'want-stripe' ~ sets a background tone, on alternating rows; so its easier to read tabula data.
  9. 'odd', 'even' ~ used to annotate the stripes.

Tablist definition

This feature hasn't been released yet.
A widget is to simplify the creation of sites, and is mostly convenience. This adds HTML to the outcomes, and is presented via CSS.

This takes a PHP array, with the following keys, and renders it.
For the entire tablist chunk:

  1. tab-main-class
  2. first-tab
  3. render-local

For each tab:

  1. button-id
  2. summary-class
  3. summary-id
  4. tab-class
  5. tab-id
  6. title

One may set the following chunks in the frame or similar templates (use HTML type) :

  1. tab-body
  2. tab-summary

Widget definition

This is a necessary feature, but I haven't built it yet.

Behaviour for 'security' meta item.

This hasn't been implemented yet.

References

This is technical resource, and built on top of standards and protocols. Here are some references, which are mentioned in the text.

  1. w3c URL spec
  2. RFC1738
  3. RFC3629
  4. XML and HTML char entities
  5. RFC2616
  6. Robots.txt
  7. Robots exclusions

Many of the references are now embedded Harvard style in the text. I think this second approach is better for web-resources.


Technical documentation for iceline v2

RSS. Share: Share this resource on your twitter account. Share this resource on your linked-in account. G+

Technical documentation for iceline v2

RSS. Share: Share this resource on your linked-in account. Share this resource on your twitter account. G+ ­ Follow edited