From 78de7ed98abff93fe5fef94907bcfa4f76dcef07 Mon Sep 17 00:00:00 2001 From: Steve Manuel Date: Sat, 27 May 2017 10:27:51 -0700 Subject: adding docs to repo --- docs/build/CLI/General-Usage/index.html | 1254 +++++++++++++++++++++++ docs/build/CLI/Generating-References/index.html | 1055 +++++++++++++++++++ 2 files changed, 2309 insertions(+) create mode 100644 docs/build/CLI/General-Usage/index.html create mode 100644 docs/build/CLI/Generating-References/index.html (limited to 'docs/build/CLI') diff --git a/docs/build/CLI/General-Usage/index.html b/docs/build/CLI/General-Usage/index.html new file mode 100644 index 0000000..884336a --- /dev/null +++ b/docs/build/CLI/General-Usage/index.html @@ -0,0 +1,1254 @@ + + + + + + + + + + + + + + + + + + Using the Ponzu Command Line Interface (CLI) + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ +
+ + +
+
+ + +
+
+
+ +
+
+
+ + +
+
+
+ + +
+
+
+ + +
+
+ + + +

General Usage

+ + 
$ ponzu [flags] command <params>
+
+ + +

Commands

+

new

+

Creates a project directory of the name supplied as a parameter immediately +following the 'new' option in the $GOPATH/src directory. Note: 'new' depends on +the program 'git' and possibly a network connection. If there is no local +repository to clone from at the local machine's $GOPATH, 'new' will attempt to +clone the 'github.com/ponzu-cms/ponzu' package from over the network.

+

Example:

+
$ ponzu new github.com/nilslice/proj
+> New ponzu project created at $GOPATH/src/github.com/nilslice/proj
+
+ + +
+

generate, gen, g

+

Generate boilerplate code for various Ponzu components, such as content.

+

Example:

+
            generator      struct fields and built-in types...
+             |              |
+             v              v    
+$ ponzu gen content review title:"string" body:"string":richtext rating:"int"
+                     ^                                   ^
+                     |                                   |
+                    struct type                         (optional) input view specifier
+
+ + +

The command above will generate the file content/review.go with boilerplate +methods, as well as struct definition, and corresponding field tags like:

+
type Review struct {
+    item.Item
+
+    Title  string   `json:"title"`
+    Body   string   `json:"body"`
+    Rating int      `json:"rating"`
+    Tags   []string `json:"tags"`
+}
+
+ + +

The generate command will intelligently parse more sophisticated field names +such as 'field_name' and convert it to 'FieldName' and vice versa, only where +appropriate as per common Go idioms. Errors will be reported, but successful +generate commands return nothing.

+

Input View Specifiers (optional)

+

The CLI can optionally parse a third parameter on the fields provided to generate +the type of HTML view an editor field is presented within. If no third parameter +is added, a plain text HTML input will be generated. In the example above, the +argument shown as body:string:richtext would show the Richtext input instead +of a plain text HTML input (as shown in the screenshot). The following input +view specifiers are implemented:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CLI parameterGenerates
checkboxeditor.Checkbox()
customgenerates a pre-styled empty div to fill with HTML
fileeditor.File()
hiddeneditor.Input() + uses type=hidden
input, texteditor.Input()
richtexteditor.Richtext()
selecteditor.Select()
textareaeditor.Textarea()
tagseditor.Tags()
+

Generate Content References

+

It's also possible to generate all of the code needed to create references between +your content types. The syntax to do so is below, but refer to the documentation +for more details:

+
$ ponzu gen c author name:string genre:string:select
+$ ponzu gen c book title:string author:@author,name,genre 
+
+ + +

The commands above will generate a Book Content type with a reference to an +Author item, by also generating a reference.Select +as the view for the author field.

+
+

build

+

From within your Ponzu project directory, running build will copy and move +the necessary files from your workspace into the vendored directory, and +will build/compile the project to then be run.

+

Optional flags: +- --gocmd sets the binary used when executing go build within ponzu build step

+

Example:

+
$ ponzu build
+(or)
+$ ponzu build --gocmd=go1.8rc1 # useful for testing
+
+ + +

Errors will be reported, but successful build commands return nothing.

+
+

run

+

Starts the HTTP server for the JSON API, Admin System, or both. +The segments, separated by a comma, describe which services to start, either +'admin' (Admin System / CMS backend) or 'api' (JSON API), and, optionally, +if the server should utilize TLS encryption - served over HTTPS, which is +automatically managed using Let's Encrypt (https://letsencrypt.org)

+

Optional flags: +- --port sets the port on which the server listens for HTTP requests [defaults to 8080] +- --https-port sets the port on which the server listens for HTTPS requests [defaults to 443] +- --https enables auto HTTPS management via Let's Encrypt (port is always 443) +- --dev-https generates self-signed SSL certificates for development-only (port is 10443)

+

Example:

+
$ ponzu run
+(or)
+$ ponzu run --port=8080 --https admin,api
+(or) 
+$ ponzu run admin
+(or)
+$ ponzu run --port=8888 api
+(or)
+$ ponzu --dev-https run
+
+ + +

Defaults to $ ponzu run --port=8080 admin,api (running Admin & API on port 8080, without TLS)

+

Note: +Admin and API cannot run on separate processes unless you use a copy of the +database, since the first process to open it receives a lock. If you intend +to run the Admin and API on separate processes, you must call them with the +'ponzu' command independently.

+
+

upgrade

+

Will backup your own custom project code (like content, addons, uploads, etc) so +we can safely re-clone Ponzu from the latest version you have or from the network +if necessary. Before running $ ponzu upgrade, you should update the ponzu +package by running $ go get -u github.com/ponzu-cms/ponzu/...

+

Example:

+
$ ponzu upgrade
+
+ + +
+

add, a

+

Downloads an addon to GOPATH/src and copies it to the current Ponzu project's +/addons directory.

+

Example:

+
$ ponzu add github.com/bosssauce/fbscheduler
+
+ + +

Errors will be reported, but successful add commands return nothing.

+
+

version, v

+

Prints the version of Ponzu your project is using. Must be called from within a +Ponzu project directory. By passing the --cli flag, the version command will +print the version of the Ponzu CLI you have installed.

+

Example:

+
$ ponzu version
+Ponzu v0.8.2
+# (or)
+$ ponzu version --cli
+Ponzu v0.9.2
+
+ + +
+

Contributing

+
    +
  1. Checkout branch ponzu-dev
    2. +
  2. Make code changes
    3. +
  3. Test changes to ponzu-dev branch
      +
    • make a commit to ponzu-dev
      • +
    • to manually test, you will need to use a new copy (ponzu new path/to/code), +but pass the --dev flag so that ponzu generates a new copy from the ponzu-dev +branch, not master by default (i.e. $ponzu new --dev /path/to/code)
      • +
    • build and run with $ ponzu build and $ ponzu run
      • +
    +
    4. +
  4. To add back to master:
      +
    • first push to origin ponzu-dev
      • +
    • create a pull request
      • +
    • will then be merged into master
      • +
    +
    5. +
+

A typical contribution workflow might look like:

+
# clone the repository and checkout ponzu-dev
+$ git clone https://github.com/ponzu-cms/ponzu path/to/local/ponzu # (or your fork)
+$ git checkout ponzu-dev
+
+# install ponzu with go get or from your own local path
+$ go get github.com/ponzu-cms/ponzu/...
+# or
+$ cd /path/to/local/ponzu 
+$ go install ./...
+
+# edit files, add features, etc
+$ git add -A
+$ git commit -m 'edited files, added features, etc'
+
+# now you need to test the feature.. make a new ponzu project, but pass --dev flag
+$ ponzu --dev new /path/to/new/project # will create $GOPATH/src/path/to/new/project
+
+# build & run ponzu from the new project directory
+$ cd /path/to/new/project
+$ ponzu build && ponzu run
+
+# push to your origin:ponzu-dev branch and create a PR at ponzu-cms/ponzu
+$ git push origin ponzu-dev
+# ... go to https://github.com/ponzu-cms/ponzu and create a PR
+
+ + +

Note: if you intend to work on your own fork and contribute from it, you will +need to also pass --fork=path/to/your/fork (using OS-standard filepath structure), +where path/to/your/fork must be within $GOPATH/src, and you are working from a branch +called ponzu-dev.

+

For example:

+
# ($GOPATH/src is implied in the fork path, do not add it yourself)
+$ ponzu new --dev --fork=github.com/nilslice/ponzu /path/to/new/project
+
+ + + + + + + +
+
+
+
+ + + + +
+ + + + + + + + + + + + \ No newline at end of file diff --git a/docs/build/CLI/Generating-References/index.html b/docs/build/CLI/Generating-References/index.html new file mode 100644 index 0000000..38c50a6 --- /dev/null +++ b/docs/build/CLI/Generating-References/index.html @@ -0,0 +1,1055 @@ + + + + + + + + + + + + + + + + + + How to Generate References using Ponzu CLI + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+ +
+ + +
+
+ + +
+
+
+ +
+
+
+ + +
+
+
+ + +
+
+
+ + +
+
+ + + +

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
+
+ + + + + + + +
+
+
+
+ + + + +
+ + + + + + + + + + + + \ No newline at end of file -- cgit v1.2.3