diff options
Diffstat (limited to 'docs/src/CLI')
| -rw-r--r-- | docs/src/CLI/General-Usage.md | 248 | ||||
| -rw-r--r-- | docs/src/CLI/Generating-References.md | 123 |
2 files changed, 371 insertions, 0 deletions
diff --git a/docs/src/CLI/General-Usage.md b/docs/src/CLI/General-Usage.md new file mode 100644 index 0000000..3a4544f --- /dev/null +++ b/docs/src/CLI/General-Usage.md @@ -0,0 +1,248 @@ +title: Using the Ponzu Command Line Interface (CLI) + +```bash +$ 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: +```bash +$ 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: +```bash + 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: + +```go +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 parameter | Generates | +|---------------|-----------| +| checkbox | [`editor.Checkbox()`](/Form-Fields/HTML-Inputs/#editorcheckbox) | +| custom | generates a pre-styled empty div to fill with HTML | +| file | [`editor.File()`](/Form-Fields/HTML-Inputs/#editorfile) | +| hidden | [`editor.Input()`](/Form-Fields/HTML-Inputs/#editorinput) + uses type=hidden | +| input, text | [`editor.Input()`](/Form-Fields/HTML-Inputs/#editorinput) | +| richtext | [`editor.Richtext()`](/Form-Fields/HTML-Inputs/#editorrichtext) | +| select | [`editor.Select()`](/Form-Fields/HTML-Inputs/#editorselect) | +| textarea | [`editor.Textarea()`](/Form-Fields/HTML-Inputs/#editortextarea) | +| tags | [`editor.Tags()`](/Form-Fields/HTML-Inputs/#editortags) | + +**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](/CLI/Generating-References) +for more details: + +```bash +$ 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`](/Form-Fields/HTML-Inputs/#referenceselect) +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: +```bash +$ 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: +```bash +$ 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: +```bash +$ ponzu upgrade +``` + +--- + +### add, a + +Downloads an addon to GOPATH/src and copies it to the current Ponzu project's +`/addons` directory. + +Example: +```bash +$ 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: +```bash +$ ponzu version +Ponzu v0.8.2 +# (or) +$ ponzu version --cli +Ponzu v0.9.2 +``` + +--- + +## Contributing + +1. Checkout branch ponzu-dev +2. Make code changes +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. To add back to master: + - first push to origin ponzu-dev + - create a pull request + - will then be merged into master + +_A typical contribution workflow might look like:_ +```bash +# 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: +```bash +# ($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 +``` diff --git a/docs/src/CLI/Generating-References.md b/docs/src/CLI/Generating-References.md new file mode 100644 index 0000000..77cd16a --- /dev/null +++ b/docs/src/CLI/Generating-References.md @@ -0,0 +1,123 @@ +title: How to Generate References using Ponzu CLI + +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 + +```bash +$ 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. + +```go +// content/product.go +package content +... + +type Product struct { + item.Item + + Title string `json:"title"` + Price int `json:"price"` + Description string `json:"description"` +} + +... +``` + +```go +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: + +```bash +$ ponzu gen content catalog year:int product:@product,title,price +``` |