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

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

• system.errors.verbosity needs more detailed explaination

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

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

• Document template_format: json in page frontmatter

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

• Retina images and derivatives need a detailed rewrite and explanation with examples of each type. - Added ability to pass an array of explicit widths to ImageMedium#derivatives grav#1133

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

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

• 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

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

• Document improved Theme variables - Feature/theme dev improvements grav#1232

• Document hash page check type - Add 'hash' configuration option for cache check method grav-plugin-admin#923

• Document new never_cache_twig system and page option.

• Document using Wellington app to compile/watch SCSS

• Document how media methods generally 'reset' previous actions. so either assign to a varable, or pass false - Problem when outputting images with twig. Incorrect url. grav#1247

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

• Document the new allow_webserver_gzip option and implications

• Document page collection order.custom and order.sort_flags on Collections page

• Document Redis + Memcached server/port options

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

• Document honeypot field for forms

• Document debugger: false in the page frontmatter

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

• Added inline CSS and JS via Asset manager Adding the ability to inline CSS and Js code via Asset Manager grav#1377

• Added isajaxrequest twig funciton add function isajaxrequest() grav#1400

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

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

• Document media twig object and accessing arbitrary images as media:

• Document optional collection ordering PHP flags Strange behavior on ordering collection grav#1640

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

• New methods: Twig::addPath() and Twig::prependPath()

• Document expires: in page frontmatter

• Document gaussianBlur media method

• Document issues with W3C and Linkedin that are fixed with gzip - Linkedin, Wayback Machine, and W3C Validator issues - no indexing grav#1639

• Added cache_control system and page override set headers by page grav#1591

• clear_images_by_default cache option Avoid to delete images/ folder after using GPM grav#1481

• Collection::intersect() Add option to use AND rather than OR for multi-item collections grav#1605

• Collection::merge() method

• Page::collection() filtering

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

• Document EXIF support in Grav (and in capabilities)

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

• More video control options Add more controls over HTML5 video attributes (autoplay, poster, loop, controls) grav#1442

• Document Page ancestor methods Ancestor and Inherited functions for Page & Pages grav#1362

• Document Page cache id method Pages::getPagesCacheId()

• Document how to use Cache object in plugins

Core Events

• onPageFallbackUrl()

• onFallbackUrl()

• onMarkdownInitialized()

• onMediaLocate()

• onGetPageTemplates()

• onGetPageBlueprints()

• onTwigLoader

• onActionX

• onPageActionX

• onTaskX

Admin Plugin

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

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

• Document how to create a custom field

• 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)

• document not being able to scroll caused by cloudlare. Can't scroll on any of the admin panel pages grav-plugin-admin#808 (comment)

• Update user profile screenshot documentation to mention user-uploadable avatar

• Document new "Tools" menu option for direct install

• Document fieldset form field for admin: Add fieldset form field grav-plugin-admin#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

• 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

• Mention offline mode?

• Document multilevel and mediapicker field

Admin Events

• onAdminTaskExecute()

• onAdminCreatePageFrontmatter()

• onAdminAfterSave

• onAdminAfterSaveAs

• onAdminAfterDelete

• onAdminAfterMedia

• onAdminAfterDelMedia

Forms

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

• Custom error message support in validate: message:

• 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..

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

• Document fieldset fields

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

• Document Taxonomy field: Add support for 'default' and 'options' for taxonomy field grav-plugin-admin#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

• Document remember action - Remembered fields feature grav-plugin-form#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

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

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

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

• 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.

• Custom select field - How to add whole countries select list in grav forms grav-plugin-form#187 (comment)

• Document not being able to scroll caused by cloudlare. Can't scroll on any of the admin panel pages grav-plugin-admin#808 (comment)

Hosting

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

• Add Runcloud to Hosting?

[RyanMPierson]

onPageFallBackURL was documented: 6915ed6

[RyanMPierson]

htaccess documented: 8d168d1

[RyanMPierson]

Expanded on System Config documentation: ac42d1d

[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

[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 d473200

[hughbris]

• 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 getgrav/grav-plugin-admin#808 (comment)

[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:
getgrav/grav#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.