Page File spec for v1

Meta tags

This is initiated by a '{{pagemeta' opening block, as is generally the first thing in the raw wiki file. Please [[see the example]] for specific syntax, it is copied from other wiki data structures.

The list of items in the meta section are self expanding, and should be written to be self-documenting. As with Apache config files, the platform is case-insensitive, but is written in camelCaps (also known as studlyCaps), to make semantics clear. This is a hash table, and the order the items are added is irrelevant.
The meta tags are for scalar items, there are other config blocks for more complex structures (see rest of this document).

As a single list, with notes ::
Every reference to “$English” also applies to other human languages, but I am emphasising computer limitations are not applicable. May have spaces, may be in Korean etc.

  1. 'AccessGroup' - Who should be able to view the resource, please read the relevant section.
  2. 'Author' - $English name of resource author, just flat text please this is embedded into HTML elements.
  3. 'CodeVersion' - What code version this resource requires to render, the platform will abort rendering on resources it can't support. Current edition is 0.2.2.
  4. 'DocVersion' - What edition of the resource this is, currently only for human facing notes. This controls what resource class will parse the file, currently supports 1.2 and 2.0. This section of the docs is for 1.2 only.
  5. 'Keywords' - List the most important nouns in the resource. Used in the HTML meta element “keywords”, to annotate the content for robots. Will be used for search extensions in future.
  6. 'Method' - Which HTTP requests may be performed on this resource, please see the section.
  7. 'Mime-encode' - This is auto-generated from the mime_encode list in the config. What encoding the file is in, when being transmitted to the webclient.
  8. 'Modified' - For use in HTTP proxies, how recent the resource is. This value is auto-generated from filesystem timestamp.
  9. 'Name' - $English name of resource. The filesystem and URL space name should be unique and as short as possible while still being descriptive. This name field is to allow UTF-8 names, and full descriptions. As this text is used in human read lists, conciseness is still a virtue.
  10. 'Robots' - Add a robots indexing meta element to the HTML output. Please refer to references section.
  11. 'Strapline' - A longer descriptive text to add below the resource title, held in the title. Used in branding. $English
  12. 'Title' - The complete title for the resource, this is normally longer than the Name, and may include repetitive text (i.e. 'Report into XXX') which you don't want in the URL or the Name. In $English, and the longest option.
  13. 'URL' - Currently unused, but references another document, for example to hold the full edition.
  14. 'GetOpts' - One of the locations a resource may specify it understands additional arguments. This is a coma separated list of GET names. Will be whitespace trimmed.

The following are in use in live resources ::

  1. 'AccessGroup'
  2. 'Author'
  3. 'CodeVersion'
  4. 'DocVersion'
  5. 'Keywords'
  6. 'Method'
  7. 'Name'
  8. 'Strapline'
  9. 'Title'
  10. 'URL'
  11. 'Status'
  12. 'postopts'
  13. 'getopts'

The following values configure the renderer, and so must be set ::

  1. 'DocVersion'
  2. 'AccessGroup'
  3. 'Method'
  4. 'CodeVersion'

In version 0.2.2 the following are emitted in the HTML sent to client, and so should be set sensibly ::

  1. 'Author'
  2. 'Robots'
  3. 'Keywords'
  4. 'Mime-encode'
  5. 'Modified'
  6. 'Strapline'
  7. 'Status'

The source currently manipulates the following (against version 0.2.2), so may not be removed or changed in the codebase, without due care. ::

  1. 'AccessGroup'
  2. 'Author'
  3. 'Robots'
  4. 'Keywords'
  5. 'Method'
  6. 'Mime-encode'
  7. 'Modified'
  8. 'Strapline'
  9. 'Status'
  10. 'postopts'
  11. 'getopts'

Next resource maps

This section is to specify where the platform should go “next” as a state machine. In many cases this is unset, that is any resource is valid, or a '*'
This section repeats for every request type (see method options).

  1. {{nextresource GET
  2. {{nextresource POST

This is bar separated AVPs of new state and what resource is rendered in this situation. For an “any” state, omit the state name. The list of states in incomplete but here

Example 1 : Simple GET

You may do anything.


    ``{{``nextresource GET
        |*
    ``}}``

Example 2 : More complex GET

A site that directs you to the current sales offer depending on what day of the week it is.


  ``{{``nextresource GET
   |=sales|monday=tidyup|wednesday=this-weeks-offers|friday=new-sales|saturday=new-sales
  ``}}``

Example 3 : Simple POST

On success of your form, go to the stock listings, otherwise back to the form. The ampersand is a special marker for the GET version of the current resource, see the complete documentation.


  ``{{``nextresource GET
   |success=stock-listing|fail_post=&
  ``}}``

Local params

To build applications, one must do data submission to the resource. To ensure that the resource has clean/safe data, there are validation filters available. To configure these one must specify known parameters (these may be either 'get' or 'post'). The param list can either the chunk “Xopts” or the meta entry 'Xargs'. It no functional difference which you favour. Example:


  ``{{``getargs
   |firstname|lastname|age
  ``}}``

  ``{{``pagemeta
     ....
   getopts=firstname|lastname|age
     ....
  ``}}``

Adjustment functions

This site is written in PHP which is a scripting language to make websites dynamic. This platform strongly encourages a structured approach, with data validation, name-space provision, output format all being setup previous to the resource being rendered. The state machine for what resource to redirect to is supported by in-page hyperlinks or via the nextresource blocks. To support content rewriting (trivial example output the current date in the resource) and /or make any render time decisions (it is April fools day, issue the cheaper sale rates), there is do_* function for each HTTP action. There is also a do_validate for any business logic requirements, which need to occur before the resource can be built (for example a catalogue resource would need to confirm stock levels).

Text inside the blocks should be straight PHP, which gets executed as a function. The platform does not require the opening/closing PHP delimiters or the opening/closing function brackets. The function is passed the following variables :

  • $log - A reference to the [Log object], the important function function is debug, see following the example.
  • $request - The data from the client, after it has been washed and reformatted. This array is configured by [request building]. The data in this array is likely to be different with each resource.
  • $ses - A reference to the [Session object], used to store data between HTTP requests. See docs.
  • $page - A reference to the [resource] being rendered.

Inside the same HTTP request, data can be added and removed from the [Session object] at no cost.

HTML inserts

The newer builds of format1 system allow prefabricated sections of content to be injected into resources. The prebuilt content is stored in the same file (for efficiency) and in 'htmlnsert' blocks. There may be only 1 htmlinsert block per file, as meeting larger scale requirements would be more sensible to use v2. Although this is called 'htmlinsert', there are no technical limits on what textual content may be inserted. The htmlinsert text is merged into the document at the [html-insert] marker.
This is the last feature like this before I move to a better abstraction. There will be no more feature creep. Resource format 2 will use a different underlying language and technology tree. For comparative analysis, have a look at the view-source resource (this is listed in the footer for each page, it is stable to run against itself.)

Current access groups

The access groups are to categorise the content, but the underlying platform reserves some of them (zero through ten specifically). Accessgroups are positive integers, I have currently created no aliasing scheme.

  • 0 - ungrouped - For items like the home page, global free-access.
  • 1 - system - Assorted system resources, open access for all accounts, but resources are in a separate group so it will be omitted from the site-map
  • 2 - test data - Category to isolate again, I would like to limit this to developer access, but need to think this through.
  • 3 - communications - The resource is using one or more of the communication features. Currently unused.
  • 4 - users - This group holds resources that create and modify user accounts. Currently unused.
  • 5 - indexes - Resources that are just indexes, not intended to be read by humans. Being able to attach meta data about your indexes is really useful.
  • 6 - admin - Currently unused, any resource that alters the site.
  • 666 - a testing value

Content owners are encouraged to create additional access groups as part of the content creation.

Method options

This meta tag holds what HTTP requests the resource supports. The platform doesn't support any of the requests which fail to return a web-page, as this would be illogical. To make the system readable, the request types are typed in the same fashion as the HTTP protocol:

  1. GET
  2. POST
  3. EITHER - this is for a resource that may run either type. The do_get and do_post functions will need to be present to configure the output.

States

The next state blocks hold a list of which resource is relevant for a given situation. Should the user fail to supply correct data they are likely to be returned to the same data capture form, for example. To annotate what is happening the following states are known to the current version of the software (0.2.2).
State machines are more relevant for POST operations, as the user is telling you things you need to respond to.

State names

  1. The most common usage is the any state, this is a zero char string on the left side of the equals.
  2. 'fail_post'
  3. 'success'

Special state values
Generally this lists the resources which should be rendered. The platform understands some additional values for redirecting special cases.

  1. '*' - anything
  2. '&' - back to the GET version of the current resource, used for bouncing incomplete forms on POSTs
  3. '$' - A new resource. Currently unused.

Example files

In future I will add “test resources” which are resources demonstrating and documenting features of the platform. They will be named 'test-*', and be access group 2. This is to allow other less technical designers create sites within this platform.

References

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

  1. http://www.robotstxt.org/orig.html
  2. http://en.wikipedia.org/wiki/Robots_exclusion_standard
  3. http://www.w3.org/Addressing/URL/url-spec.txt
  4. http://tools.ietf.org/html/rfc1738
  5. https://tools.ietf.org/html/rfc3629
  6. http://en.wikipedia.org/wiki/List_of_XML_and_HTML_character_entity_references
  7. http://www.w3.org/Protocols/rfc2616/rfc2616.html

Technical documentation for iceline v1

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

Technical documentation for iceline v1

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