+ + + +

Generating References

+ +

In Ponzu, users make connections between Content types using references. In order +to use the CLI to generate these references, a slightly different syntax is required. +In all cases, the Content type you wish to reference does not need to exist prior +to the "parent" type referencing it at generate-time, but in the following examples, +the referenced "child" type will be shown before the parent type for clarity.

+

Syntax¶

+

@¶

+

The @ symbol is used to declare that the following name is a reference. The +CLI will take care to parse the name and treat it as a Content type to which the +current type refers.

+

[]¶

+

The [], which if used, is always in front of the @ symbol. It signifies +that the reference type is a slice or a collection of references. When [] +is used, the CLI will automatically generate a reference.SelectRepeater() view +for you.

+

,arg1,arg2,argN¶

+

Immediately following the reference name (after the @ symbol), users may optionally +pass arguments to specify how the reference is displayed in the parent type's +editor. References are included in the parent types editor as a dropdown menu, with +each possible reference as an option. These arguments define what goes inside the +<option></option> text node, as would be seen by an Admin.

+

The arguments must be valid JSON struct tag names from the reference type's fields. +Notice in the example below, the title and price are formatted exactly as they +were in the generate command for the product type.

+

¶

+

Example¶

+

$ ponzu gen content product title:string price:int description:string:textarea
+$ ponzu gen content catalog year:int products:"[]@product",title,price
+

+ + +

The commands above output the following. For demonstration, we will omit the full +code generated for the Product, since the reference is in the Catalog type.

+

// content/product.go
+package content
+...
+
+type Product struct {
+    item.Item
+
+    Title       string `json:"title"`
+    Price       int    `json:"price"`
+    Description string `json:"description"`
+}
+
+...
+

+ + +

package content
+
+import (
+    "fmt"
+
+    "github.com/bosssauce/reference"
+
+    "github.com/ponzu-cms/ponzu/management/editor"
+    "github.com/ponzu-cms/ponzu/system/item"
+)
+
+type Catalog struct {
+    item.Item
+
+    Year     int      `json:"year"`
+    // all references are stored as []string or string types
+    Products []string `json:"products"` 
+}
+
+func (c *Catalog) MarshalEditor() ([]byte, error) {
+    view, err := editor.Form(c,
+        editor.Field{
+            View: editor.Input("Year", c, map[string]string{
+                "label":       "Year",
+                "type":        "text",
+                "placeholder": "Enter the Year here",
+            }),
+        },
+        editor.Field{
+            // reference.SelectRepeater since []@product was used
+            View: reference.SelectRepeater("Products", c, map[string]string{
+                "label": "Products",
+            },
+                "Product", // generated from @product
+                `{{ .title }} {{ .price }} `, // generated from ,title,price args
+            ),
+        },
+    )
+
+    if err != nil {
+        return nil, fmt.Errorf("Failed to render Catalog editor view: %s", err.Error())
+    }
+
+    return view, nil
+}
+
+func init() {
+    item.Types["Catalog"] = func() interface{} { return new(Catalog) }
+}
+

+ + +

Note: +If the reference should be only a single item, rather than a slice (or collection) +of items, omit the [], changing the command to:

+

$ ponzu gen content catalog year:int product:@product,title,price
+

+ + + + + + + +