github.com/machinebox/remoto@v0.1.2-0.20191024144331-eff21a7d321f/templates/README.md (about)

     1  # Remoto templates
     2  
     3  * [Introduction](#introduction)
     4  * [Writing templates](#writing-templates)
     5  
     6  ## Introduction
     7  
     8  Remoto generates code by processing a [Plush](https://github.com/gobuffalo/plush) template with a data structure describing the services.
     9  
    10  A goal of the project is to keep and maintain all Remoto templates in this repository, although it is
    11  possible to render with any template for advanced cases, the wider community will benefit from a
    12  carefully maintained experience.
    13  
    14  # Writing templates
    15  
    16  Remoto templates are used to generate code; clients, server stubs, SDKs, etc.
    17  
    18  ### Introduction
    19  
    20  You will generate code for one or more services, accessible via `def.Services`:
    21  
    22  ```c
    23  <%= for (service) in def.Services { %>
    24  	// rendered for each service
    25  	<%= for (method) in service.Methods %>
    26  		// rendered for each method
    27  	<% } %>
    28  <% } %>
    29  ```
    30  
    31  You will also generate code for the list of structures, and the `unique_structures` helper 
    32  gives you the complete list:
    33  
    34  ```c
    35  <%= for (structure) in unique_structures(def) { %>
    36  	// rendered for each structure
    37  <% } %>
    38  ```
    39  
    40  The structure comes with a list of fields.
    41  
    42  Templates aren't the nicest of things to look at and work with, but the pain here means
    43  we can generate human-readable code for our users.
    44  
    45  For example, in Go you might have template code that looks like this:
    46  
    47  ```go
    48  <%= for (structure) in unique_structures(def) { %>
    49  <%= print_comment(structure.Comment) %>type <%= structure.Name %> struct {
    50  	<%= for (field) in structure.Fields { %>
    51  	<%= print_comment(field.Comment) %><%= field.Name %> <%= go_type_string(field.Type) %> `json:"<%= underscore(field.Name) %>"`
    52  	<% } %>
    53  }
    54  <% } %>
    55  ```
    56  
    57  The above template will generate a Go `struct` matching the data structure of the object.
    58  
    59  ### Templating language
    60  
    61  Templates are written using [Plush](https://github.com/gobuffalo/plush), a templating package
    62  from the [Buffalo project](https://gobuffalo.io/).
    63  
    64  Plush uses `<%= tagsLikeThese %>` to inject data and provide conditional output and loops.
    65  
    66  * See [Usage of the Plush Package](https://github.com/gobuffalo/plush#usage)
    67  
    68  ### Template helpers
    69  
    70  Remoto inherits all of the [Plush helpers](https://github.com/gobuffalo/plush#helpers) and adds some
    71  specific ones in the [generator/template_helpers.go](https://github.com/machinebox/remoto/blob/master/generator/template_helpers.go) file.
    72  
    73  ### Template data structure
    74  
    75  The data structure for the templates is best expressed through the godoc online documentation:
    76  
    77  * [https://godoc.org/github.com/machinebox/remoto/generator/definition](https://godoc.org/github.com/machinebox/remoto/generator/definition)
    78  
    79  ### Dealing with repsonse files
    80  
    81  Some endpoints can return a file, these have the `*remototypes.FileResponse` return type.
    82  
    83  Plush templates can check if a method has this return type:
    84  
    85  ```c
    86  // general code
    87  
    88  <%= if (method.ResponseStructure.Name == "remototypes.FileResponse") { %>
    89  	// file specific response code
    90  <% } else { %>
    91  	// Data structure response code
    92  <% } %>
    93  ```