Category: Configure

To return JSON types, you need to define few extra fields:

"json":{
    "Content_type":"application/json; charset=UTF-8",
    "Short":"json",
    "Challenge":"challenge",
    "Logged":"logged",
    "Logout":"logout",
    "Failed":"failed",
    "Case":1
  }

where Challenge, Logged, Logout and Failed are mandatory. Their meaning are:

• Challenge: if visitor has no valid login ticket, instead of redirecting to a login screen, Genelet returns you {“data”:”challenge”}
• Logged: after a successful login, Genelet returns you {“data”:”logged”}
• Logout: after a successful logout, Genelet returns you {“data”:”logout”}
• Failed: if an error is found, Genelet returns you {“data”:”failed”}

Finally, Case=1 is for JSON only.

 

For HTML or TEXT types, which need templates to render, you define only two keys. For example,

"Chartags": {
  "html": {
    "Content_type":"text/html; charset=UTF-8",
    "Short":"html"
  },
  "p": {
    "Content_type":"text/plain; charset=UTF-8",
    "Short":"txt"
  }
}

where Content_type is for the returned HTTP header Content-Type; and Short is optional. There are two templates, one is associated with component/action.html and the other component/action.p.

If you access an URL whose tag is not defined or whose template does not exist, an error message will be displayed.

1. config.js
   1. HTML Types
   2. JSON
   3. JSONP
   4. XML
2. Authentication & Authorization
3. URL Handling 
4. Tasks

The mime tag in the URL indicates which type of content, HMTL, JSON or XML, should be returned to the visitor. It lets you easily present your website in different foreign languages too.

For example, if you visit
http://WEBSITE/HANDLER/role/e/component?action=string&query….
where e is defined to be English HTMl. Genelet will render the English page using the template Template/role/component/action.e.

You can define s to be Spanish HTML, so
http://WEBSITE/HANDLER/role/s/component?action=string&query….
will render the same page in Spanish using Template/role/component/action.s.

Furthermore, you may define tag j for JSON. In case of JSON (and XML), no template is needed. Genelet internally make JSON data structure.

There are 4 blocks in JSON:

• “data” : the main data structure, presented as an array of objects;
• “relationships” : the associated data structures, presented as an object;
• “incoming“: original requesting variables, presented as a hash map;
• “included“: any extra requesting variables such as those from cookie.

The mime type definition is in Chartag:

"Chartags" : {
  "e":{
    "Content_type":"text/html; charset=\"UTF-8\""
  },
  "s" : {
    "Content_type":"text/html; charset=\"UTF-8\""
  },
  "j" : {
    "Content_type":"application/json; charset=\"UTF-8\"",
    "Short":"json",
    "Challenge":"challenge",
    "Logged":"logged",
    "Logout":"logout",
    "Failed":"failed",
    "Case":1
  }
}

where for JSON type, you need to define Challenge, Logged, Logout, Failed to indicate (a) this is a protect page, a login is needed; (b) a login is successful; (c) logged out; and (d) a login is failed. You can use different strings to indicate the status by changing the content in Chartag.

Log    {"Minlevel": "Emergency", "Filename": "/tmp/debug.log"}

If key Log is defined,  logging messages will be dumped to disk file Filename. There are seven levels of logs: emergency, alert, critical, error, warning, notice, info, debug. The higher the level is, the more the messages it dumps.

When something goes wrong, Genelet reports an error code and has the error string in HTML page or JSON data.  Since http Status Code lies between 100 and 999, Genelet error code lies between 1001 and 1999.

For your specific project, define your customized error code in config.json, just to make sure they are above 2000.  Genelet will report the errors in the same way as the built-in errors.

Errors       {"2001": "some error1", "2002": "some error2", ...}

If a visitor passes action=STRING in the request, Genelet will run corresponding function named STRING on component. So you may develop unlimited number of actions on the component.

If no action is passed,  a RESTful action (also called verbs) will be determined from the Request Method. This one defines the mapping:

Default_actions   {"GET":"topics", "GET_item":"edit", "PUT":"update", "POST":"insert", "DELETE":"delete"}

Here the keys are http’s Request Methods. The GET_item is a special type of GET Method with item id attached in the URL:
http://WEBSITE/HANDLER/role/mime/component/id?query…

You can change the default behavior by changing Default_actions.

The 5 verbs correspond to the following CRUD operations.

• topics: to SELECT all items without specifying the primary key
• edit: to get detail of one specific item by PK: WHERE id=
• update: to update item, usually UPDATE in SQL
• insert: to add new item, usually INSERT in SQL
• delete: to delete item, usually DELETE in SQL

You need coding function (or object method, or subroutine) for every action. However, these five specific actions are always inherited from Genelet. Just define model parameters in component.json and it will work properly.

All webpage templates are placed under one top directory called Template.  You should defined it in config.js. E.g.

Template          "/home/user1/views"

Assume that a visitor is accessing URL:
http://WEBSITE/HANDLER/ROLE/TAG/COMPONENT?action=ACTION&query…

Then the specific template looked for is located at:

 Template
         /ROLE
               /COMPONENT
                         /ACTION.TAG
                         /action2.tag2
                         ...
               /component2
               ...
         /role2
         ...

For example, if ROLE is public, TAG is html, COMPONENT is cart and ACTION is topics, the template will be

/home/user1/views/public/cart/topics.html

Parameters to access database are defined in array object Db, which depends on the programming language.

Db              ["mysql", "dbuser:dbpass@/dbname"]

The above example is for accessing MySQL database dbname using account name dbuser and password dbpass in GO. 

To access the same database in Perl, use

 "Db": ["DBI:mysql:dbname", "dbuser", "dbpass"]

and in Php, use

 "Db": ["mysql:dbname=dbname", "dbuser", "dbpass"]

Special Names in URL

These names have special meanings in URL. If you have to use different ones for whatever reason, you may change them in config.js.

Action_name       default:"action"

Variable name for action, e.g. action=topics defining an topics action. You can change the name to verb and pass the same action by: verb=topics.

Login_name        default:"login"

If component in the URL equals to this string, we interpret it as a login request.

Logout_name       default:"logout"

If component equals to this string, we interpret it as a logout request.

Provider_name     default:"provider"

Name for login’s issuer. E.g. provider=google.

Go_uri_name       default:"go_uri"

When visitor hits a protected page, one would be redirected to login screen. The original URL will be assigned to variable go_uri. After successful login, one would be redirected to the original page.

Go_probe_name     default:"go_probe"

Some browsers blocks cookie. A probing cookie of this name is used to detect the case.

Go_err_name       default:"go_err"

Name to record failed login code.

Variables

(NAME)             (EXAMPLE)
Document_root      "/home/user1/www"

The root directory for “index.html”.

Project           "myproject"

Your project name.

Script           "/cgi-bin/myscript"

The name of HANDLER , as a relative URL path.

Pubrole          "pubic"

Name of the public role.

Uploaddir        "/home/website/www/uploads"

Top directory for uploading files.

Cachetop         "/home/website/www/caches"

Top directory for cached pages.

In Genelet, URL has the fixed format:

http://WEBSITE/HANDLER/role/mime/component?action=string&query...

where HANDLER is handler name. A web project should use one and only one handler. role is name for group of visitors, e.g. public or member. Genelet supports user-account authentication and OAuth. mime is the mime type of pages, e.g. json, xml and html.  Switching mimes will turn a page from one mime format to another. For example, replacing html by json in the URL will bring you the JSON view of the same HTML page. component is an object name, usually mapping to a database table. Finally, action=string defines action (i.e. function, or object method) on the component. And query contains additional query parameters.

A web project will consist of many components and actions.

You may use the URL routing tool in Chapter 4.1 to customize URLs. But in most cases, you should stick with the fixed format URL principle.

By inspecting the URL, Genelet knows how to process authentication, which componenet to dispatch, and which data type should be returned back to visitor.