Empty Block

CatMice Templates

Imagine 10 different CAT requests (<link>), all of them with 10 or more stylesheets concatenated with $ or % query prefix inside (<head>). How ugly that would look. And inefficient for complex layouts.

Now imagine those 10 ugly (hrefs) CAT requests hiding after just one double tilde ~~ as simple keyword, referencing to the job/template name.

In contrast to regular CatMice usage where parameters are sitting in url, templates are utilizing .json files with parameters defined inside. Templates also provide a good, old disk-caching feature/option. Globally. For each and every request toward particular template. That means Your server can really take a break while responding to requests.


Preparing the Field

Before using CatMice Templating feature for the first time, a little bit of preparation is required. Much like with first Setup/Test-Run. Assuming that root CatMice directory is /cm, and server public root is localhost with the 8000 port. If not, change according to Your own setup. Type the following in url bar: localhost:8000/cm/?cat=~~mytemplate Something like this should appear onscreen: Not a proper request. JSON missing or invalid! That's expected and all good. There is no such (nor any) template created yet. And if You take a look at your cm directory structure, You'll notice that there is one more .tpl directory created inside trademark directory, with blank index.php file inside. And if that's the actual case in your own scenario, we can say that the field for the CatMice templates is prepared at this point.

Defining a Template

Navigate/browse to a .tpl directory (automatically created a bit earlier) with Your favorite file manager. There should be one blank index.php file (gatekeeper) sitting there. There can be two types of templates. It is either css or js type. Let's assume that template identification name for our new template file is simply fonts and that we are talking about a style/css (CAT) template. That would be equal to: css.fonts.json filename. Pretty much straightforward. You can create one now from a command line, something alike: ~$ touch css.fonts.json Or create such file with a mouse, you know, .. right mouse click, new file ... Once created, it is time to populate it with some json data. Go to catmice source code page and copy the contents from css.template_name.json tab into newly created css.fonts.json file. Once when You did that, refer to the next section below in order to dig what's what in that .json blueprint.

Blueprint Keys

Both css and js blueprints have the same common names for primary key set. pack - an integer that defines how much hours for server disk-cache. -- this value should always be LESS than hours value. hours - an integer that defines how much hours for client browser-cache. sig - a boolean value that defines whether block comment templace signature will be printed, with common (non-precise) details, or won't be printed at all. concat - array with n ammount of secondary objects (link requests)

Concat Array

{ "cat": "$chainCollection" , "expandExternals": false , "blockCmt": false , "squeeze": true } Each concat array is a nested object where parameters differ a bit, depending on a template type. { "mice": "$chainCollection" , "comments": false , "blockCmt": false , "squeeze": true } The difference is in first two keys. As we already know, cat equals to CSS and mice equals to Javascript. The second key is either "expandExternals" for stylesheets or line "comments" for js. The last two keys are the same for both js and css templates, "blockCmt" and "squeeze" As it stands in the above examples, only cat or mice require string values, that is in other words, the main portion of the stanard CatMice url call. The remaining three are boolean values. --- Let's now get back to our css.fonts.json blueprint that is presumably already created, right ? Let's imagine that our fonts template should fetch and encode four font-faces. Let's imagine that each font request from within a template is actually a set of several css files. For each request of such type (multiple files), a chain collection (eg: dollar sign) is appropriate. Therefore, as mentioned in the beginning of this very page, instead of something like this: https://mywebsite.com/cm/?cat=$mycoolFont1~$veryCoolFont2~$AwesomeCoolFont3~$coolFont4&ex=1&sq=1 .. just this: https://mywebsite.com/cm/?cat=~~fonts { "pack": 54321, "hours": 54322, "sig": false, "concat": [ { "cat": "$mycoolFont1" , "expandExternals": true , "blockCmt": false , "squeeze": true } , { "cat": "$veryCoolFont2" , "expandExternals": true , "blockCmt": false , "squeeze": true } , { "cat": "$AwesomeCoolFont3" , "expandExternals": true , "blockCmt": true , "squeeze": false } , { "cat": "$coolFont4" , "expandExternals": true , "blockCmt": false , "squeeze": true } ] } And .. assuming that there actually are 4 chain.* directories in existance with all required css files named as described and explained on docs for query dialect, one more file will be automatically created, beside main css.fonts.json template, after first successfull response. It will be created under name like this css.fonts.packed.gz and its contents will be gzipped. This file will handle first pack key (disk-cache time) and will be read upon each and every upcoming fonts template request.

Summary

  1. Templates are ideal for serving huge static assets. Usually font files.
  2. Templates can minimize 20+ subsequental <link href> or <script src> requests,
    meaning, one can pull 100+ CSS files under just one: /?cat=~~myBogusTemplate
  3. Generated template responses can have mixed portions of embeded requests. A portion (concat query, cat or mice) without comments or squeezed, then, next query portion with comments and encoded assets, but not in one line, etc, etc.
  4. All additional GET parameters except main ones will be discarded, will have no effect. Those additional parameters are defined within .json blueprint it self. Desired, packed, gzipped outcome will be the same and will be served as intended.
  5. Although not recommended, templates do not need to be written to disk for later-on disk-cache/read. pack integer with value of 0 will bypass disk write.
  6. Template names MUST BE of alphanumeric (ctype_alnum) type.
  7. These are valid template names:
    ~~my1stTemplate, ~~template2, ~~2ndTemplate, ~~yabadabadooya, etc ..
  8. These are NOT valid template names and will produce - HALT (safe error with message instead of response):
    ~~my_template, ~~some-template, ~~a*template, etc..
Empty Block
Empty Block
Empty Block
Empty Block