github.com/rpdict/ponzu@v0.10.1-0.20190226054626-477f29d6bf5e/docs/src/CLI/Generating-References.md (about)

     1  title: How to Generate References using Ponzu CLI
     2  
     3  In Ponzu, users make connections between Content types using references. In order 
     4  to use the CLI to generate these references, a slightly different syntax is required. 
     5  In all cases, the Content type you wish to reference does not need to exist prior
     6  to the "parent" type referencing it at generate-time, but in the following examples,
     7  the referenced "child" type will be shown before the parent type for clarity.
     8  
     9  ## Syntax
    10  
    11  ### @
    12  
    13  The **@** symbol is used to declare that the following name is a reference. The 
    14  CLI will take care to parse the name and treat it as a Content type to which the 
    15  current type refers.
    16  
    17  ### []
    18  
    19  The `[]`, which if used, is always in front of the **@** symbol. It signifies 
    20  that the reference type is a slice or a collection of references. When `[]`
    21  is used, the CLI will automatically generate a `reference.SelectRepeater()` view 
    22  for you.
    23  
    24  ### ,arg1,arg2,argN
    25  
    26  Immediately following the reference name (after the @ symbol), users may optionally
    27  pass arguments to specify how the reference is displayed in the parent type's
    28  editor. References are included in the parent types editor as a dropdown menu, with
    29  each possible reference as an option. These arguments define what goes inside the
    30  `<option></option>` text node, as would be seen by an Admin.
    31  
    32  The arguments must be valid JSON struct tag names from the reference type's fields. 
    33  Notice in the example below, the `title` and `price` are formatted exactly as they 
    34  were in the generate command for the `product` type.
    35  
    36  ---
    37  ###
    38  
    39  ##### Example
    40  
    41  ```bash
    42  $ ponzu gen content product title:string price:int description:string:textarea
    43  $ ponzu gen content catalog year:int products:"[]@product",title,price
    44  ```
    45  
    46  The commands above output the following. For demonstration, we will omit the full
    47  code generated for the `Product`, since the reference is in the `Catalog` type.
    48  
    49  ```go
    50  // content/product.go
    51  package content
    52  ...
    53  
    54  type Product struct {
    55  	item.Item
    56  
    57  	Title       string `json:"title"`
    58  	Price       int    `json:"price"`
    59  	Description string `json:"description"`
    60  }
    61  
    62  ...
    63  ```
    64  
    65  ```go
    66  package content
    67  
    68  import (
    69  	"fmt"
    70  
    71  	"github.com/bosssauce/reference"
    72  
    73  	"github.com/rpdict/ponzu/management/editor"
    74  	"github.com/rpdict/ponzu/system/item"
    75  )
    76  
    77  type Catalog struct {
    78  	item.Item
    79  
    80  	Year     int      `json:"year"`
    81      // all references are stored as []string or string types
    82  	Products []string `json:"products"` 
    83  }
    84  
    85  func (c *Catalog) MarshalEditor() ([]byte, error) {
    86  	view, err := editor.Form(c,
    87  		editor.Field{
    88  			View: editor.Input("Year", c, map[string]string{
    89  				"label":       "Year",
    90  				"type":        "text",
    91  				"placeholder": "Enter the Year here",
    92  			}),
    93  		},
    94  		editor.Field{
    95              // reference.SelectRepeater since []@product was used
    96  			View: reference.SelectRepeater("Products", c, map[string]string{
    97  				"label": "Products",
    98  			},
    99  				"Product", // generated from @product
   100  				`{{ .title }} {{ .price }} `, // generated from ,title,price args
   101  			),
   102  		},
   103  	)
   104  
   105  	if err != nil {
   106  		return nil, fmt.Errorf("Failed to render Catalog editor view: %s", err.Error())
   107  	}
   108  
   109  	return view, nil
   110  }
   111  
   112  func init() {
   113  	item.Types["Catalog"] = func() interface{} { return new(Catalog) }
   114  }
   115  ```
   116  
   117  **Note:**
   118  If the reference should be only a single item, rather than a slice (or collection)
   119  of items, omit the `[]`, changing the command to:
   120  
   121  ```bash
   122  $ ponzu gen content catalog year:int product:@product,title,price
   123  ```