Topics that need documenting...

[rhukster]

These are some topics I have on my big-list-of-grav-things that need to get documented in the docs. Some are clarifications, some are new features that have been added to the Grav core and just not documented yet.

Please consider digging in and helping to knock these out. It's an easy way you can contribute back to Grav :)

Grav Core

• [x] Full breakdown of each item system.yaml that explains each in more detail rather than just the copy of the file we currently have.

• [x] system.errors.verbosity needs more detailed explaination

• [x] Better .htaccess help. Bolt has some great docs in this regard: https://docs.bolt.cm/3.0/howto/making-sure-htaccess-works

• [x] Provide explanation on how to get a Grav running 100% correctly with 775/664 permissions including a PHP umask() call in setup.php

• [x] Document template_format: json in page frontmatter

• [x] Document login_redirect_here: false in page frontmatter (for login page redirect control)

• [x] Retina images and derivatives need a detailed rewrite and explanation with examples of each type. - https://github.com/getgrav/grav/pull/1133

• [x] Document ContentMeta. Used in Shortcode Plugin, e.g. $page->addContentMeta('shortcodeMeta', $meta);

• [x] Document new media streaming capabilities via Markdown and Twig. { media['user://media/bird.png'].resize(50, 50).rotate(90).html() }}

• [x] Provide more in depth documentation for Browser object.

• [ ] More in depth documentation and examples of Multi-site usage including examples of stream setups with setup.php

• [x] Document ability to be run with built-in PHP webserver utilizing router.php

• [x] Document improved Theme variables - https://github.com/getgrav/grav/pull/1232

• [x] Document hash page check type - https://github.com/getgrav/grav-plugin-admin/issues/923

• [x] Document new never_cache_twig system and page option.

• [x] Document using Wellington app to compile/watch SCSS

• [x] Document how media methods generally 'reset' previous actions. so either assign to a varable, or pass false - https://github.com/getgrav/grav/issues/1247

• [x] Update nginx.conf entries with updated value from webserver-configs

• [x] Document the new allow_webserver_gzip option and implications

• [x] Document page collection order.custom and order.sort_flags on Collections page

• [x] Document Redis + Memcached server/port options

• [x] Document how to run the Grav tests (and add new tests) -> vendor/bin/codecept run

• [x] Document honeypot field for forms

• [x] Document debugger: false in the page frontmatter

• [x] Document in languages section, the ability to get current logged in user {{ grav.user.username }} etc.

• [x] Added inline CSS and JS via Asset manager https://github.com/getgrav/grav/pull/1377

• [x] Added isajaxrequest twig funciton https://github.com/getgrav/grav/issues/1400

• [x] Quickly add twig function - https://github.com/getgrav/grav-plugin-star-ratings/blob/develop/star-ratings.php#L166-L171

• [x] Document media_directory, vardump, and base32, base64 twig functions/filters

• [x] Document media twig object and accessing arbitrary images as media:

• [x] Document optional collection ordering PHP flags https://github.com/getgrav/grav/issues/1640

  {{ media['user://media/bird.png'].resize(50, 50).rotate(90).html() }}

• [x] New methods: Twig::addPath() and Twig::prependPath()

• [x] Document expires: in page frontmatter

• [x] Document gaussianBlur media method

• [x] Document issues with W3C and Linkedin that are fixed with gzip - https://github.com/getgrav/grav/issues/1639

• [x] Added cache_control system and page override https://github.com/getgrav/grav/issues/1591

• [x] clear_images_by_default cache option https://github.com/getgrav/grav/pull/1481

• [x] Collection::intersect() https://github.com/getgrav/grav/issues/1605

• [x] Collection::merge() method

• [x] Page::collection() filtering

  content:
  items: '@self.siblings'
  filter: 
      type: item

• [x] Document EXIF support in Grav (and in capabilities)

• [x] Document Pages::baseUrl(), Pages::homeUrl() and Pages::url() functions

• [x] More video control options https://github.com/getgrav/grav/pull/1442

• [x] Document Page ancestor methods https://github.com/getgrav/grav/pull/1362

• [x] Document Page cache id method Pages::getPagesCacheId()

• [x] Document how to use Cache object in plugins

Core Events

• [x] onPageFallbackUrl()

• [x] onFallbackUrl()

• [x] onMarkdownInitialized()

• [x] onMediaLocate()

• [x] onGetPageTemplates()

• [x] onGetPageBlueprints()

• [x] onTwigLoader

• [ ] onActionX

• [ ] onPageActionX

• [ ] onTaskX

Admin Plugin

• [ ] Document how to extend site.yaml and others with config blueprint override https://gist.github.com/rhukster/89429cc5738b9201c4fd5a6057fe1596

• [x] Document how to create and use a custom page blueprint to provide "Custom Page Types" functionality

• [x] Document how to create a custom field

• [x] Document the Dashboard and Notifications setting with explanation on how to stop the notifications requests to be sent by disabling the 4 places it's needed. (fix to in admin to support this is pending)

• [ ] Document the volatile nature of APCu/Xcache and how you can't populate cache from CLI because these are destroyed after every CLI php call. File works best, but memcached/redis should also be fine (after Grav 1.1.16 which has the fix)

• [x] document not being able to scroll caused by cloudlare. https://github.com/getgrav/grav-plugin-admin/issues/808#issuecomment-276824595

• [x] Update user profile screenshot documentation to mention user-uploadable avatar

• [x] Document new "Tools" menu option for direct install

• [x] Document fieldset form field for admin: https://github.com/getgrav/grav-plugin-admin/pull/210

• [ ] Document parents field which extends pages - https://gist.github.com/rhukster/6df3bdb106e2b06242b10ae549e5e021

• [ ] Document the security: option on Section and Tab field to limit access

• [x] Document the password REGEX requirements

• [ ] Document $this->grav['twig']->plugins_quick_tray via onAdminMenu event

• [ ] Document icon quick-tray and how to use it in plugins

• [x] Mention offline mode?

• [ ] Document multilevel and mediapicker field

Admin Events

• [x] onAdminTaskExecute()

• [x] onAdminCreatePageFrontmatter()

• [x] onAdminAfterSave

• [x] onAdminAfterSaveAs

• [x] onAdminAfterDelete

• [x] onAdminAfterMedia

• [x] onAdminAfterDelMedia

Forms

• [x] Explain how to enable inline errors in forms (inline_errors: true in form.yaml or form definition)

• [x] Custom error message support in validate: message:

• [x] Disable client validation with client_side_validation: false in form.yaml or in form definition

• [ ] Document adding custom form fields with examples..

• [ ] Document adding custom actions with examples..

• [x] Document conditional - https://gist.github.com/rhukster/7e83c40e906e92a5acf91a80303c034d

• [x] Document fieldset fields

• [ ] Document missing file options random_name and avoid_overwriting - AdminBaseController line 218

• [x] Document Taxonomy field: https://github.com/getgrav/grav-plugin-admin/pull/1364

• [ ] Document classes in forms: https://gist.github.com/rhukster/09b8841087e2376f962bf9adf2745d85 - Another example: https://gist.github.com/rhukster/13b0232c29482f3f473168f6b98110e5 - Perhaps an example that styles forms to bootstrap would be good?? Also with a Twig variables to set them once: https://gist.github.com/rhukster/133b1576d190cfe8d38058bc2dd32ff4

• [ ] Document range field

• [X] Document remember action - https://github.com/getgrav/grav-plugin-form/pull/200

• [ ] Document how to properly setup a YAML field (yaml: true and validate: type: yaml) - See media.yaml blueprint example.

• [ ] Document the array field (just like in admin)

Cookbook

• [x] Tutorial on how to create a split menu system (vertical menu?)

• [x] Tutorial on how to create a split menu system (vertical menu?)

• [x] Tutorial walkthrough covering going from and HTML site/design to Grav theme

• [x] Tutorial walkthrough covering going from and HTML site/design to Grav theme

• [ ] How to add a page specific CSS file via a custom page template - block stylesheets, parent(), then {% do assets.addCss('theme://css/custom-page.css') %}

• [ ] Add simple CSS stylesheet to the simple gallery example.

• [ ] Simple plugin/events to get all users in accounts/ and add them as a twig variable for use on frontend.

• [x] Custom select field - https://github.com/getgrav/grav-plugin-form/issues/187#issuecomment-327552725

• [x] Document not being able to scroll caused by cloudlare. getgrav/grav-plugin-admin#808 (comment)

Hosting

• [ ] Tutorial on best custom hosting with VPS + Serverpilot.io

• [ ] Add Runcloud to Hosting?

[RyanMPierson]

onPageFallBackURL was documented: https://github.com/getgrav/grav-learn/commit/6915ed69675e13cb0df5aefbc8fcfa23895e90df

[RyanMPierson]

htaccess documented: https://github.com/getgrav/grav-learn/commit/8d168d15e06d05da230830645f0bc930450f6eb0

[RyanMPierson]

Expanded on System Config documentation: https://github.com/getgrav/grav-learn/commit/ac42d1dfa630fe21ba38f1359b29efba514d2334

[RyanMPierson]

https://learn.getgrav.org/content/content-pages#contentmeta

[OleVik]

In regards to "Cookbook" -> "Tutorial on how to create a split menu system (vertical menu?)", is the idea to split menu items by category, subcategory, and item? Ie., a hierarchical menu.

[rhukster]

In regards to the split menu cookbook entry @OleVik, what i had in mind was the main menu shows only the 1st level items. Then when you click on say 'services' top level, and it has a series of items under there: 'consulting', ' development', etc, those show up underneath as a horizontal menu. This is what I consider a 2 level split-menu.

[RyanMPierson]

Dashboard options documented: https://learn.getgrav.org/admin-panel/plugin-options

[RyanMPierson]

Documented Tools Menu Option for Direct Install: https://learn.getgrav.org/admin-panel/tools

[paulmassen]

Should we add documentation to the number field ?

[paulmassen]

Added Custom select field cookbook entry https://github.com/getgrav/grav-learn/pull/497

[paulmassen]

Documented conditional field https://github.com/getgrav/grav-learn/pull/490

[RyanMPierson]

onFallbackUrl() and onMarkdownInitialized() documented here:

https://github.com/getgrav/grav-learn/commit/6915ed69675e13cb0df5aefbc8fcfa23895e90df

[RyanMPierson]

onGetPageTemplates and onGetPageBlueprints were documented: abed30d4

[hughbris]

Great issue. Subscribing to this, learned heaps of stuff just scanning through.

I'll help where I can too.

[rhukster]

Thanks @hughbris contributions are always welcome!

[paulmassen]

Memo to remember to add docs to select_optgroup: https://github.com/getgrav/grav-plugin-form/pull/166

[paulmassen]

Created a cookbook entry for:

• [x] How to add a page specific CSS file via a custom page template - block stylesheets, parent(), then {% do assets.addCss('theme://css/custom-page.css') %} https://github.com/getgrav/grav-learn/pull/512

[hughbris]

Another one for collections page:

• [ ] Document page collection order.publish_date and order.unpublish_date

[rhukster]

Thanks @jgonyea for your PRs today! It's been a huge help!

[artemartemov]

these two would be amazing to have if anyone has some time. still struggling!

Document media twig object and accessing arbitrary images as media:

How to add a page specific CSS file via a custom page template - block stylesheets, parent(), then {% do assets.addCss('theme://css/custom-page.css') %}

[paulmassen]

@artemartemov The 2nd one is already documented here: https://learn.getgrav.org/cookbook/general-recipes#add-an-asset-to-a-specific-page

I'm not sure I understand the first one though

[RyanMPierson]

Documented Inline Errors in forms: https://github.com/getgrav/grav-learn/commit/a77c110ff9d9a3f49ef63dec70926b29fd09a9c5

[RyanMPierson]

Documented validation message: https://github.com/getgrav/grav-learn/commit/ca4e3c8ea342ca03ea454c5d0e06f831919ecf28

[RyanMPierson]

Documented fieldsets, client-side validation. https://github.com/getgrav/grav-learn/commit/a6b6317b4fb5bc78ca98d86984ba1990997fb17c

[hughbris]

Form email action header/option:

• [x] Document adding reply_to field to form email action

Update: Covered by https://github.com/getgrav/grav-learn/pull/633

[hughbris]

• [ ] Explain what media thumbnail options page, default, and media actually do/mean

default seems to be the default thumbnail from system folder for media type e.g. /system/images/media/thumb-jpg.png

page is taken from the media folder with pattern [media-name].[media-extension].thumb.[thumb-extension], and seems to fall back to the media itself

media is the (image) medium itself

[RyanMPierson]

Offline Mode Documented d473200ea149480d740e6e6626204833ce71840a

[hughbris]

• [x] Document precise regex format required for form field validate.pattern or provide an example.

Update: decent examples are provided under blueprints as it happens. Having missed this completely when I needed it, perhaps we should be talking about better cross-referencing of shared content between the blueprints and user forms sections.

[OleVik]

On my wishlist:

• [ ] Expand programmatic creation of blueprints with PHP, and write a cookbook entry showing how to do this.

@mahagr and @RyanMPierson know a lot about this process, and I imagine there are some underused abilities of blueprints that would allow for easier debugging of structure and implementation, which is a sticky, reoccurring issue people ask for help with.

[RyanMPierson]

Added CloudFlare workaround via https://github.com/getgrav/grav-plugin-admin/issues/808#issuecomment-276824595

[hughbris]

• [ ] document Medium::thumbnailExists() method

[NicoHood]

The message API is not documented or mentioned anywhere:

$this->grav['messages']->add($message, 'warning');

[NicoHood]

grav.user.access.admin.login Is undocumented (used to check if the admin panel is opened or not, equivalent to $this->isAdmin().

Should be added here: https://learn.getgrav.org/16/themes/theme-vars#user-object

--> I've document this thing, however I dont know what else the object is used for, maybe there are other permissions worth to document. Also I dont know if this is still valid for 1.7.

[mahagr]

Above does not work, it never has. You should not be using grav.user.access for anything, it is just a raw list of user access and there is a method to get the same information in a normalized format. Also, it is not $this->isAdmin(), not even close (which checks if admin plugin is active).

[NicoHood]

GRAV_VERSION is not documented: https://github.com/getgrav/grav/issues/3142

[james0r]

From a suggestion I made in the Discord server:

I'm seeing the blueprint admin fields available in the docs, then if we want to find text field information we have to navigate to frontend fields, I think it would be best to just list all fields that are available for the admin and create another table column to denote which ones are only available in the admin. That way the dev doesn't have to navigate back and forth from frontend/admin fields. Something like this:

I was told this was the case before but that there were "issues". I'd be interested to know if they couldn't be addressed while still, what I feel is improving this page.

[NoNoNo]

In images.defaults (in config system.yaml), you can list methods, that get called by default on object of class Grav\Common\Page\Medium\Medium, e.g.

images.defaults.derivatives: '320, 3200, 320' will invoke derivatives(320, 3200, 320)

https://github.com/getgrav/grav/blob/490bdd6ce7aaae315c033ca5af112a778a42455a/system/src/Grav/Common/Page/Markdown/Excerpts.php#L283-L306

This feature should be documented in https://learn.getgrav.org/17/basics/grav-configuration#images

[rhukster]

Please submit a pull request by clicking "edit" button on the docs site.