doc/templates.md in power_stencil-0.6.3 vs doc/templates.md in power_stencil-0.7.0

- old
+ new

@@ -25,34 +25,35 @@ The default templating engine being [ERB], your templates should be written using the [ERB] syntax, like most templates are written in the [Ruby On Rails] framework. This is basically some [Ruby] inside some ERB tags. Templates are always associated to some [buildable entities][buildable]. -When a [buildable entity][buildable] has some templates associated, they will be located in a directory `<entity_type>/<entity_name>/`. For some entity types, when you will create a new entity of this type, some default templates will be created in that directory (this is the case of the `simple_exec` entity type as you will see in the next paragraph). This is what is called `templates-templates`. +When a [buildable entity][buildable] has some templates associated, they will be initially generated in a directory `templates/<entity_type>/<entity_name>/` (unless they are [unversioned]). For some entity types, when you will create a new entity of this type, some default templates will be created in that directory (this is the case of the `simple_exec` entity type as you will see in the next paragraph) from some kind of "_meta-templates_". This is what is called `templates-templates` in `PowerStencil`. In this document, you will learn how to create your own templates, as well as your own templates-templates. # Templates discovery with `simple_exec` entity type In the basic entity types, the only one providing default templates is the `simple_exec` entity type. So let's try with it: ```shell $ power_stencil create simple_exec/demo_templates -Created 'simple_exec/demo_templates' +Creating 'simple_exec/demo_templates'... +Generated templates in '/tmp/tst3/templates/simple_exec/demo_templates'. $ power_stencil check simple_exec/demo_templates RAW ENTITIES 'simple_exec/demo_templates': - Storage path : '/tmp/tst3/.ps_project/entities/simple_exec/demo_templates.yaml' - Provided by : 'PowerStencil core' - - Templates path : '/tmp/tst3/simple_exec/demo_templates' + - Templates path : '/tmp/tst3/templates/simple_exec/demo_templates' - Status : Valid - Buildable : true ``` As you can see the output of `power_stencil check` shows more information than entities we created so far. First we see that this entity is `buildable`, and we'll detail that in the [builds] document, but for the moment what we will focus on the `Templates path` information. -And it's true if we have a look in the `simple_exec/demo_templates/` directory from the root of the project, a file appeared there: +And it's true if we have a look in the `templates/simple_exec/demo_templates/` directory from the root of the project, a file appeared there: ```shell $ ls -l simple_exec/demo_templates total 4 -rwxrwxr-x 1 laurent laurent 57 août 23 16:44 main.sh @@ -77,18 +78,18 @@ - 'simple_exec/demo_templates' has been correctly built ``` What can we see there ? -The first line is the most interesting one for us. It says "De-templating ... into ...", and it's true that a brand new directory named `build` appeared at the root of the project. Again we won't focus too much on the name of the sub-directory as we will see that in the [builds], but if we have a look in the generated directory we see the same content as what we had in `simple_exec/demo_templates`... +The first line is the most interesting one for us. It says "De-templating ... into ...", and it's true that a brand new directory named `build` appeared at the root of the project. Again we won't focus too much on the name of the sub-directory as we will see that in the [builds], but if we have a look in the generated directory we see the same content as what we had in `templates/simple_exec/demo_templates`... And by the way the generated script seems to have been run, as we can see in the output. :warning: If bash is not installed on your system, the output will obviously be different as `PowerStencil` won't be able to run the script, yet all the files should have been generated correctly. -Ok is it possible, that everything inside `simple_exec/demo_templates` is actually considered as templates ? **The answer is yes !!** +Ok is it possible, that everything inside `templates/simple_exec/demo_templates` is actually considered as templates ? **The answer is yes !!** -Let prove it and replace the content of `simple_exec/demo_templates/main.sh` by the following: +Let prove it and replace the content of `templates/simple_exec/demo_templates/main.sh` by the following: ```shell #!/usr/bin/env bash echo "This script has been generated on <%= Time.now %>" @@ -121,11 +122,11 @@ echo "It was done in the scope of 'demo_templates' (which is of the type 'simple_exec')..." ``` The content has been "de-templated"... :+1: sooo cool ! -:information_source: Here the template directory of the `simple_exec/demo_templates` was containing only on file (the bash script), but **any file in any sub-directory of that directory would have been considered as a template** (yet there are some mechanism to control and limit which files have to be processed, like for example imagine there would be images, or zip files, probably you don't want them to be processed. All of this will be covered in the [builds] document). +:information_source: Here the template directory of the `simple_exec/demo_templates` entity was containing only on file (the bash script), but **any file in any sub-directory of that directory would have been considered as a template** (yet there are some mechanism to control and limit which files have to be processed, like for example imagine there would be images, or zip files, probably you don't want them to be processed. All of this will be covered in the [builds] document). # What can I do within templates ? ## ERB for newbies @@ -174,11 +175,11 @@ This should be self explanatory, there is another part that could be displayed in case you defined complex relation using the [reverse methods] mechanism... # Where do I create templates ? -**When an entity is [buildable] you can find its templates in the `<entity_type>/<entity_name>` from the root of the project.** +**When an entity is [buildable] you can find its templates in the `templates/<entity_type>/<entity_name>` from the root of the project.** But by default, that directory is not created, and if no templates is created at this place for a [buildable] entity, the build will fail saying it didn't find any template... Yet, you probably noticed that when we created an entity of `simple_exec` type, a file (the bash script `main.sh`) _automagically_ appeared in the right place so that we could immediatelly build it. How can you achieve that with entity types of your own ? **This is what is called _templates-templates_**... @@ -187,22 +188,22 @@ ```shell $ power_stencil info . . . - - Type 'simple_exec' --> PowerStencil::SystemEntityDefinitions::SimpleExec (template-template path: '/opt/rbenv/versions/2.3.1/lib/ruby/gems/2.3.0/gems/power_stencil-0.2.18/etc/templates/simple_exec') + - Type 'simple_exec' --> PowerStencil::SystemEntityDefinitions::SimpleExec (provided by 'PowerStencil core') template-template path: '/opt/rbenv/versions/2.3.1/lib/ruby/gems/2.3.0/gems/power_stencil-0.6.3/etc/templates/simple_exec' ``` `simple_exec` is an entity type coming with `PowerStencil`, and you can see that it takes its _template-template_ from within the `PowerStencil` gem itself ! But within the `PowerStencil` project, there is a place to create _templates-templates_ of your own: `.ps_projet/templates-templates/<entity_type>`. To summarize about templates and _templates-templates_: ![entity-creation-flow] -:information_source: There is actually a third place where you could find entity types and _templates-templates_, this is within [plugins], but we will cover that in the [plugins] part... +:information_source: As you can see, there is actually a third place where you could find entity types and _templates-templates_, this is within [plugins], but we will cover that in the [plugins] part... # Creating templates-templates of your own ## basics @@ -229,24 +230,25 @@ Let's now create an entity of this type: ```shell $ power_stencil create custom_buildable_entity/test1 -Created 'custom_buildable_entity/test1' +Creating 'custom_buildable_entity/test1'... +Generated templates in '/tmp/tst3/templates/custom_buildable_entity/test1'. -$ ll custom_buildable_entity/test1 +$ ll templates/custom_buildable_entity/test1 total 12 drwxrwxr-x 2 laurent laurent 4096 août 26 13:40 ./ drwxrwxr-x 3 laurent laurent 4096 août 26 13:40 ../ -rw-rw-r-- 1 laurent laurent 26 août 26 13:40 a_useless_text_file.txt ``` -Everything, seems ok. The entity `custom_buildable_entity/test1` has been created and there is now a new folder at the root of the project named `custom_buildable_entity/test1` and which content is a text file named `a_useless_text_file.txt`... So far so good. +Everything, seems ok. The entity `custom_buildable_entity/test1` has been created and there is now a new folder named `templates/custom_buildable_entity/test1` and which content is a text file named `a_useless_text_file.txt`... So far so good. And what is the content of this file ? ```shell -$ cat custom_buildable_entity/test1/a_useless_text_file.txt +$ cat templates/custom_buildable_entity/test1/a_useless_text_file.txt This text has been generated on the 2019-08-26 13:50:35 +0200 Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt .... ``` @@ -307,19 +309,20 @@ Et voilà, let's verify: ```shell $ power_stencil create custom_buildable_entity/test2 -Created 'custom_buildable_entity/test2' +Creating 'custom_buildable_entity/test2'... +Generated templates in '/tmp/tst3/templates/custom_buildable_entity/test2'. -$ ls -la custom_buildable_entity/test2 +$ ls -la templates/custom_buildable_entity/test2 total 12 drwxrwxr-x 2 laurent laurent 4096 août 26 18:37 . drwxrwxr-x 4 laurent laurent 4096 août 26 18:37 .. -rw-rw-r-- 1 laurent laurent 148 août 26 18:37 a_useless_text_file.txt -$ cat custom_buildable_entity/test2/a_useless_text_file.txt +$ cat templates/custom_buildable_entity/test2/a_useless_text_file.txt This text has been generated on the <%= Time.now %> Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt .... ``` @@ -350,9 +353,10 @@ [plugins]: plugins.md "Plugins in PowerStencil" [example use cases]: example_use_cases.md "Example uses cases using PowerStencil" [buildable]: entities.md#buildable-and-buildable_by "How to make an entity buildable ?" [entity field]: entities.md#field "How to access basic entity data" [reverse methods]: entities.md#has_one "Check reverse methods" +[unversioned]: entities.md#local-unversioned-entities "Unversioned/developer entities" <!-- Code links --> <!-- Illustrations --> [entity-creation-flow]: images/power-stencil-entity-creation.svg \ No newline at end of file