Views and devlove

This article explains the connection between ShimmerCat QS main configuration file, the devlove.yaml, and the views.

What are the views

Views are like doors for dynamic HTML generated by an application.

They are how ShimmerCat links a request with the backend application.

They have a say on how the request travels to the application backend, and how the response that comes back is used.

How do views look?

View files have one of two names: either index.html, or __index.html. Because they can only have those two names, we can only fit at most two in a single directory. All views are inside a special directory in ShimmerCat, called the views-dir (which we can be set indepdently for each domain).

This way, the relative path of a view file, taken from the views-dir, gives us a unique view "identifier".

The first file, index.html, is used for when a request path matches exactly that relative directory. For example, if the user requests /supershoes/brown/, ShimmerCat will use a view at <views-dir>/supershoes/brown/index.html … easy right?

The second file, __index.html, is used when a request path matches a directory inside the directory of the view, if nothing more specific could be used. That is, if you request /supershoes/brown/high-heels/, ShimmerCat will use /supershoes/__index.html if none of the following files exist:

What do view files contain?

If you don’t have a backend application, and just static HTML, then you could use the views to write that HTML. If you have a backend application, then the linking aspect of the view is needed.

Views contain:

Sometimes you need only one of those two aspects, sometimes you need both. How they are mixed is controlled by something called content-disposition.

HTML code is the default content in the view file. To give special instructions on what to do with the HTML, we use a special HTML comment syntax:

<!--
shimmercat:
…
-->

where the three dots represent entries in a YAML dictionary. For example, the content-disposition is written like this:

<!--
shimmercat:
content-disposition: ….
-->

How are views and parts of the devlove.yaml connected

Views are located by URL path, but the URL path of a request can be changed just before looking up a view. For that, we use a special section in the devlove.yaml file, called change-url.

So, we could go from a pretty URL like this one: /super-shoes/bright-pink/ to a technical one like this:

…
change-url:
-   /super-shoes/bright-pink/ -> /shoes/quality/high/color/lightness/255/saturation/120/
…

or, if combining with our accelerator product:

…
change-url:
-   /super-shoes/bright-pink/ -> /target/+common/shoes-page-structure/
…

Now, the examples above are pretty simple, but ShimmerCat supports all sorts of tricks for re-writing URLs, see the page on URL handling and re-writes.

Views can re-write URLs before passing them to the backend

Suppose that you are using a PHP application, and that your request will be handled by a file called /admin/login.php … In that case, PHP expects a request to that precise URL path… but as we explained before, views always expect a request to something that looks like a directory. To please PHP and languages like PHP, views have the super-power of reusing the re-write engine to write the URL path just before passing it down to the application engine. Just add a change-url stanza in our special place.

Say that we have placed the view file under /admin/login/, as /admin/login/index.html. Then you just need to write a change-url section like this one:

<!--
shimmercat:
content-disposition: …
change-url:
  - /admin/login/ -> /admin/login.php
-->

The view above will work if your users expect to login by using the URL /admin/login/, but what happens in you invested a lot of time training your users and your search engines to use /admin/login.php instead? Then you need the help of the change-url section at the devlove.yaml file!

shimmercat-devlove:
  domains:
    elec www.supershoes.com:
       ...  
       change-url:  
          - /admin/login.php -> /admin/login/

Sure, it’s a bit of a contortion for CGI applications like PHP sites, but it sits just fine with more modern application frameworks that don’t route requests to files directly.