Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update widget docs #876

Merged
merged 10 commits into from
Dec 7, 2017
Merged

Update widget docs #876

merged 10 commits into from
Dec 7, 2017

Conversation

verythorough
Copy link
Contributor

- Summary
Adds a complete reference for each type of built-in widget. Covers most of the outline in #619 (comment), but still needs screenshots, and could probably use some improvements in the Custom Widgets (formerly Extending) page. Provides a temporary improvement until @hcavalieri finished the bigger improvements he's working on in #866.

Closes #157.

- Test plan
I've based the configuration samples on the widget code and existing configs where available, but I haven't had a chance to actually apply and test all of them. Adding them all to a single collection in the cms-demo config could be an option for testing them directly.

You can check rendering by visiting the updated pages:

- Description for the changelog
Updated widget configuration docs

@verythorough
Copy link
Contributor Author

verythorough commented Dec 6, 2017

Deploy preview ready!

Built with commit 942ad06

https://deploy-preview-876--netlify-cms-www.netlify.com

@tech4him1
Copy link
Contributor

@verythorough Maybe add something about how you can use either object format for any of the widgets, i.e.:

  - {label: "Draft", name: "draft", widget: "boolean", default: true}

or

  - label: "Draft"
    name: "draft"
    widget: "boolean"
    default: true

Right now it kind-of looks like you can only use one type for some, and the other type for others.

@verythorough
Copy link
Contributor Author

verythorough commented Dec 6, 2017

@tech4him1 Yeah, I know what you mean. I debated including it, though, because it's really a matter of yaml syntax, and applies to any place where implementers are using yaml.

What do you think about if I add a sentence to the intro about how all fields are in yaml, and can be written in block or inline form, with a link to a yaml syntax reference?

For references, Ansible has a nicely formatted doc, but could cause confusion. The description on wikipedia is nearly as clear, and probably a better reference. (The actual YAML page is not that helpful.) I can also link (here, and in other config docs) the YAML linter.

@verythorough
Copy link
Contributor Author

Added this new note:

Widgets are specified as collection fields in the config.yml file. Note that YAML syntax allows lists and objects to be written in block or inline style, and the code samples below include a mix of both.

@tech4him1
Copy link
Contributor

tech4him1 commented Dec 6, 2017

What do you think about if I add a sentence to the intro about how all fields are in yaml, and can be written in block or inline form, with a link to a yaml syntax reference?

That sounds good, and I don't know if we even need a reference link, just something to the effect of "Some of the examples are in a block format, and some are in a YAML inline format, but either works the same."

EDIT: Yes, I think that note looks good (and your Internet must be faster :)).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants