Merge pull request #5 from getkirby/texnixe/annotated-starterkit

Create annotated Starterkit

site/blueprints/files/image.yml

@@ -1,5 +1,11 @@
+# Each file blueprint must have a title, the title may be different from the file name
 title: Image
 
+# Like page blueprints, file blueprints can define a layout with tabs, columns, sections and fields
+# File blueprints define what sort of information should get stored in a file's meta data file
+# In addition to the fields defined in this example blueprint, you can also set what type of file is acceptable
+# when this blueprint is used, which allows you to control what users can upload.
+# More about file blueprints: https://getkirby.com/docs/reference/panel/blueprints/file
 columns:
   - width: 1/2
     sections:

site/blueprints/pages/about.yml

@@ -1,14 +1,25 @@
+# Each page blueprint must have a title, the title may be different from the file name
 title: About us
+
+# Each page can have an icon that is shown in page listings when no preview image is available.
 icon: ☎️
 
+# Limit the possible page statuses to `draft` and `listed`.
+# More about page statuses: https://getkirby.com/docs/reference/panel/blueprints/page#statuses
 status:
   draft: true
   listed: true
 
+# Page options allow you to control how users can interact with the page.
+# Here we prevent changing the page slug and page deletion
+# More about page options: https://getkirby.com/docs/reference/panel/blueprints/page#options
 options:
-  url: false
+  changeSlug: false
   delete: false
 
+# Define the form layout with two columns, each column has a set of fields
+# Columns are optional but help structure the form layout
+# More about columns: https://getkirby.com/docs/guide/blueprints/layout#defining-columns
 columns:
   - width: 1/2
     fields:
@@ -18,6 +29,8 @@ columns:
         size: huge
 
   - width: 1/2
+    # Kirby has many different field types, from simple text fields to the more complex structure field that contains subfields
+    # All available field types: https://getkirby.com/docs/reference/panel/fields
     fields:
       address:
         label: Address

site/blueprints/pages/album.yml

@@ -1,13 +1,25 @@
+# Each page blueprint must have a title, the title may be different from the file name
 title: Album
+
+# Each page can have an icon that is shown in page listings when no preview image is available.
 icon: 🖼
 
+# Page status can be limited, here to `draft` and `listed`.
+# More about page status: https://getkirby.com/docs/reference/panel/blueprints/page#statuses
 status:
   draft: true
   listed: true
 
+# Define the form layout with two columns
+# Columns are optional but help structure the form layout
+# The first column defines an files section, the second a set of fields
+# More about different types of sections: https://getkirby.com/docs/reference/panel/sections
+# More about columns: https://getkirby.com/docs/guide/blueprints/layout#defining-columns
+
 columns:
   - width: 2/3
     sections:
+      ## The `images` files section shows all images of the current page that use the `image` template
       images:
         type: files
         layout: cards
@@ -20,6 +32,8 @@ columns:
         size: small
 
   - width: 1/3
+    # The second column contains a set of fields
+    # List of all available field types: https://getkirby.com/docs/reference/panel/fields
     fields:
       cover:
         type: files

site/blueprints/pages/default.yml

@@ -1,7 +1,18 @@
+# Each page blueprint must have a title, the title may be different from the file name
+# This default blueprint is used to display a page in the Panel whenever a custom page blueprint is missing.
 title: Simple Page
+
+# Each page can have an icon that is shown in page listings when no preview image is available.
 icon: 📝
+
+# Page presets are a quick way to set up a standard page layout
+# More about page presets:
+# - https://getkirby.com/docs/guide/blueprints/presets and
+# - https://getkirby.com/docs/reference/panel/presets/page
 preset: page
 
+# Custom descriptions of page statuses depending on use case
+# More about page statuses: https://getkirby.com/docs/reference/panel/blueprints/page#statuses
 status:
   draft: true
   unlisted:
@@ -11,9 +22,12 @@ status:
     label: Menu Page
     text: The page is listed in the main menu
 
+# Limit subpage display to certain templates in a page preset
 pages:
   template: default
 
+# A page preset can have a freely defined set of fields
+# List of all available field types: https://getkirby.com/docs/reference/panel/fields
 fields:
   text:
     type: textarea

site/blueprints/pages/error.yml

@@ -1,4 +1,9 @@
+# Each page blueprint must have a title, the title may be different from the file name
 title: Error
 
+# Page options allow you to control how users can interact with the page.
+# Here we prevent reading of the page, so it is not shown to anyone in the Panel.
+# If you want to allow users to modify the error page content in the Panel, remove this option.
+# More about page options: https://getkirby.com/docs/reference/panel/blueprints/page#options
 options:
   read: false

site/blueprints/pages/home.yml

@@ -1,15 +1,24 @@
+# Each page blueprint must have a title, the title may be different from the file name
 title: Home
+
+# Each page can have an icon that is shown in page listings when no preview image is available.
 icon: 🏠
 
+# Page options allow you to control how users can interact with the page.
+# Here we prevent changing the page status (the home page cannot be renamed or deleted by default)
+# More about page options: https://getkirby.com/docs/reference/panel/blueprints/page#options
 options:
   status: false
 
+# Here we define an info section and a pages section (`photography`)
 sections:
   info:
     headline: Info
     type: info
     text: All content for the homepage is being pulled from the photography page.
 
+# The photography section extends a pages section defined in the `/site/blueprints/section/album.yml` blueprint
+# More about reusing and extending sections: https://getkirby.com/docs/guide/blueprints/extending-blueprints#reusing-and-extending-sectionss
   photography:
     headline: Photography
     extends: sections/albums

site/blueprints/pages/note.yml

@@ -1,7 +1,15 @@
+# Each page blueprint must have a title, the title may be different from the file name
 title: Note
+
+# Sorting number scheme that is applied when page status is changed to `listed`
+# More about page sorting: https://getkirby.com/docs/reference/panel/blueprints/page#sorting
 num: date
+
+# Each page can have an icon that is shown in page listings when no preview image is available.
 icon: 📖
 
+# Custom descriptions for each page status depending on use case
+# More about page status: https://getkirby.com/docs/reference/panel/blueprints/page#statuses
 status:
   draft:
     label: Draft
@@ -13,14 +21,20 @@ status:
     label: Published
     text: The note is online and listed in the blog
 
+# Define the form layout with two columns
+# Columns are optional but help structure the form layout
+# More about columns: https://getkirby.com/docs/guide/blueprints/layout#defining-columns
 columns:
   - width: 2/3
+    # This columns only has a single field
     fields:
       text:
         type: textarea
         size: large
 
   - width: 1/3
+    # This second column holds a fields section with multiple fields
+    # More about fields sections: https://getkirby.com/docs/reference/panel/sections/fields
     sections:
       meta:
         type: fields
@@ -31,6 +45,8 @@ columns:
             default: now
           author:
             type: users
+          # Fields types can be added using the shortcut `fieldname: true`
+          # (however, you can only use a fieldname once per page and this only makes sense for simple fields without configuration)
           tags: true
           gallery:
             type: pages
@@ -40,4 +56,5 @@ columns:
             empty: "No gallery selected"
             image:
               cover: true
+            # Use the `help` property of fields and section to provide editors with helpful information
             help: Place the {{ gallery }} tag anywhere in your text to add the selected gallery

site/blueprints/pages/notes.yml

@@ -1,8 +1,16 @@
+# Each page blueprint must have a title, the title may be different from the file name
 title: Notes
+
+# Each page can have an icon that is shown in page listings when no preview image is available.
 icon: 📖
 
+# Define the form layout with two columns
+# More about columns: https://getkirby.com/docs/guide/blueprints/layout#defining-columns
+
 columns:
   - width: 1/2
+    # In the first column, we reuse the `notes` section
+    # (defined in `/site/blueprints/sections/notes.yml` twice with different page status and headline
     sections:
       drafts:
         extends: sections/notes
@@ -15,8 +23,11 @@ columns:
         status: unlisted
 
   - width: 1/2
+    # In the second column, we reuse the same section, this time for listed pages and with a different headline
     sections:
       listed:
         extends: sections/notes
         headline: Published
         status: listed
+
+# More about pages sections: https://getkirby.com/docs/reference/panel/sections/pages

site/blueprints/pages/photography.yml

@@ -1,6 +1,11 @@
+# Each page blueprint must have a title, the title may be different from the file name
 title: Photos
+
+# Each page can have an icon that is shown in page listings when no preview image is available.
 icon: 🖼
 
+# Here we extend two sections which are defined in `/site/blueprints/sections/albums.yml`
+# They differ in their page status and the headline.
 sections:
   drafts:
     extends: sections/albums

site/blueprints/pages/sandbox.yml

@@ -1,10 +1,22 @@
+# Each page blueprint must have a title, the title may be different from the file name
 title: Sandbox
+
+# Page presets are a quick way to set up a standard page layout
+# More about page presets:
+# - https://getkirby.com/docs/guide/blueprints/presets and
+# - https://getkirby.com/docs/reference/panel/presets/page
 preset: page
+
+# Sorting number scheme that is applied when page status is changed to `listed`
+# More about page sorting: https://getkirby.com/docs/reference/panel/blueprints/page#sorting
 num: zero
 
+# Limit subpage display to certain templates in a page preset
 pages:
   template: sandbox
 
+# A page preset can have a freely defined set of fields
+# List of all available field types: https://getkirby.com/docs/reference/panel/fields
 fields:
   headline:
     type: text

site/blueprints/sections/albums.yml

@@ -1,3 +1,7 @@
+# This section blueprint defines a pages section that can be reused across multiple blueprints
+# or multiple times within the same blueprint, see `/site/blueprints/pages/photography.yml`  and `/site/blueprints/site.yml`
+# Sections can have different layouts and display additional information or a preview image
+# More about pages sections: https://getkirby.com/docs/reference/panel/sections/pages
 type: pages
 headline: Photography
 parent: kirby.page("photography")

site/blueprints/sections/notes.yml

@@ -1,3 +1,7 @@
+# This section blueprint defines a pages section that can be reused across multiple blueprints
+# or multiple times within the same blueprint, see `/site/blueprints/pages/notes.yml` and `/site/blueprints/site.yml`
+# Sections can have different layouts and display additional information or a preview image
+# More about pages sections: https://getkirby.com/docs/reference/panel/sections/pages
 type: pages
 headline: Notes
 parent: kirby.page("notes")

site/blueprints/site.yml

@@ -1,16 +1,34 @@
+# The site blueprint must have a title, the title may be different from the file name
+# The `site.yml` blueprint defines the look of the start page (Dashboard) of the Panel.
 title: Site
 
+# The site blueprint usually provides easy access to all main pages of the site.
+# In this example blueprint, we also show subpages of the `photography` and `notes` pages.
+# More about the site blueprint: https://getkirby.com/docs/reference/panel/blueprints/site
+
+# The layout of this form has two columns:
 columns:
+  # The first column has one section for the subpages of the `photography` page in card layout
+  # It reuses the pages section defined in `/site/blueprints/sections/albums.yml`
   - width: 1/2
     sections:
       albums: sections/albums
+
+  # The second column has two sections, `notes` and `pages`
   - width: 1/2
     sections:
+      # The `notes` section reuses the pages section defined in `/site/blueprints/sections/notes.yml`
       notes: sections/notes
+
+      # The `pages` pages section shows other main pages of the site
+      # Using the `templates` option, we limit which types of pages are shown
+      # Using the `create` option, we limit the type of page that can be created when a new page is created
+      # Note that the `sandbox` page and the `error` page that also exist in the content folder but use different blueprints thus do not show up in the list
+      # Since the error page's blueprint is set to `read: false`, it wouldn't show up here even if you added the error blueprint to the templates list
       pages:
         type: pages
         create: default
-        template:
+        templates:
           - about
           - home
           - default

site/blueprints/users/default.yml

@@ -1,3 +1,9 @@
+# User blueprints are used to create new user roles, define form fields for each user role and set role permissions.
+# By default, Kirby only has the `admin` role, a user role that is allowed to do anything.
+# The title is required, everything else is optional.
+# The default user blueprint does not define a role, but a standard set of fields
+# available for each defined user role with blueprints that only contain a title.
+# More about users, roles and permissions: https://getkirby.com/docs/guide/users/managing-users
 title: User
 
 columns:

site/config/config.php

@@ -1,5 +1,12 @@
 <?php
 
+/**
+ * The config file is optional. It accepts a return array with config options
+ * Note: Never include more than one return statement, all options go within this single return array
+ * In this example, we set debugging to true, so that errors are displayed onscreen. 
+ * This setting must be set to false in production.
+ * All config options: https://getkirby.com/docs/reference/system/options
+ */
 return [
     'debug' => true,
 ];

site/controllers/album.php

@@ -1,5 +1,12 @@
 <?php
 
+/**
+ * Controllers allow you to separate the logic of your templates from your markup.
+ * This is especially useful for complex logic, but also in general to keep your templates clean.
+ * In this example, we define the `$gallery` variable which is passed to the template
+ * More about controllers: https://getkirby.com/docs/guide/templates/controllers
+ */
+
 return function ($page) {
 
     $gallery = $page->images()->sortBy("sort");

site/models/album.php

@@ -1,5 +1,15 @@
 <?php
 
+/**
+ * Page models extend Kirby's default page object. 
+ * In page models you can define methods that are then available everywhere in Kirby where you call a page of the extended type.
+ * In this example, we define the cover method that either returns an image selected in the cover field
+ * or the first image in the folder.
+ * You can see the method in use in the `home.php`, `photography.php` and `album.php` templates 
+ * and in the `site/blueprints/sections/albums.yml` image query
+ * More about models: https://getkirby.com/docs/guide/templates/page-models
+ */
+
 class AlbumPage extends Page
 {
     public function cover()

site/plugins/gallery/index.php

@@ -1,5 +1,13 @@
 <?php
 
+/**
+ * Plugins extend Kirby's core functionality.
+ * You can extend/replace almost any system-relevant part.
+ * This plugin uses a hook to replace the `{{ gallery }}` placeholders used in the note pages
+ * with images from the selected album page that servers as gallery provider
+ * More about plugins: https://getkirby.com/docs/guide/plugins/plugin-basics
+ */
+
 Kirby::plugin('starterkit/gallery', [
     'hooks' => [
         'kirbytags:after' => function ($text, $data, $options) {

site/snippets/footer.php

@@ -1,3 +1,13 @@
+<?php
+/**
+ * Snippets are a great way to store code snippets for reuse or to keep your templates clean.
+ * in loops or simply to keep your templates clean.
+ * This footer snippet is reused in all templates. In fetches information from the `site.txt` content file
+ * and from the `about` page.
+ * More about snippets: https://getkirby.com/docs/guide/templates/snippets
+ */
+?>
+
   </div>
 
   <footer class="footer">

site/snippets/gallery.php

@@ -1,3 +1,12 @@
+<?php
+/**
+ * Snippets are a great way to store code snippets for reuse or to keep your templates clean.
+ * in loops or simply to keep your templates clean.
+ * This gallery snippet is used in the gallery plugin (`/site/plugins/gallery`)
+ * More about snippets: https://getkirby.com/docs/guide/templates/snippets
+ */
+?>
+
 <section class="gallery">
   <?php foreach ($gallery->images() as $image): ?>
   <figure>

site/snippets/header.php

@@ -1,3 +1,12 @@
+<?php
+/**
+ * Snippets are a great way to store code snippets for reuse or to keep your templates clean.
+ * This header snippet is reused in all templates. 
+ * It fetches information from the `site.txt` content file and contains the site navigation.
+ * More about snippets: https://getkirby.com/docs/guide/templates/snippets
+ */
+?>
+
 <!doctype html>
 <html lang="en">
 <head>
@@ -5,8 +14,11 @@
   <meta charset="utf-8">
   <meta name="viewport" content="width=device-width,initial-scale=1.0">
 
+  <!-- The title tag we show the title of our site and the title of the current page -->
   <title><?= $site->title() ?> | <?= $page->title() ?></title>
 
+  <!-- Stylesheets can be included using the `css()` helper. Kirby also provides the `js()` helper to include script file. 
+        More Kirby helpers: https://getkirby.com/docs/reference/templates/helpers -->
   <?= css(['assets/css/index.css', '@auto']) ?>
 
 </head>
@@ -14,10 +26,15 @@
 
   <div class="page">
     <header class="header">
+      <!-- In this link we call `$site->url()` to create a link back to the homepage -->
       <a class="logo" href="<?= $site->url() ?>"><?= $site->title() ?></a>
 
       <nav id="menu" class="menu">
-        <?php foreach ($site->children()->listed() as $item): ?>
+        <?php 
+        // In the menu, we only fetch listed pages, i.e. the pages that have a prepended number in their foldername
+        // We do not want to display links to unlisted `error`, `home`, or `sandbox` pages
+        // More about page status: https://getkirby.com/docs/reference/panel/blueprints/page#statuses
+        foreach ($site->children()->listed() as $item): ?>
         <?= $item->title()->link() ?>
         <?php endforeach ?>
       </nav>

site/snippets/intro.php

@@ -1,3 +1,13 @@
+<?php
+/**
+ * Snippets are a great way to store code snippets for reuse or to keep your templates clean.
+ * in loops or simply to keep your templates clean.
+ * This intro snippet is reused in multiple templates. While it does not contain much code,
+ * it helps to keep your code DRY and thus facilitate maintenance when you have to make changes.
+ * More about snippets: https://getkirby.com/docs/guide/templates/snippets
+ */
+?>
+
 <header class="intro">
   <h1><?= $page->title() ?></h1>
 </header>

site/templates/about.php

@@ -1,9 +1,19 @@
+<?php
+/**
+ * Templates render the content of your pages. 
+ * They contain the markup together with some control structures like loops or if-statements.
+ * The `$page` variable always refers to the currently active page. 
+ * To fetch the content from each field we call the field name as a method on the `$page` object, e.g. `$page->title()`.
+ * This example templates only echos the field values from the content file and doesn't need any special logic from a controller.
+ * Snippets like the header, footer and intro contain markup used in multiple templates. They also help to keep templates clean.
+ * More about templates: https://getkirby.com/docs/guide/templates/basics
+ */
+?>
+
 <?php snippet('header') ?>
 
 <main>
-  <header class="intro">
+    <?php snippet('intro') ?>
-    <h1><?= $page->title() ?></h1>
-  </header>
 
   <div class="layout">
 

site/templates/album.php

@@ -1,13 +1,29 @@
+<?php
+/**
+ * Templates render the content of your pages. 
+ * They contain the markup together with some control structures like loops or if-statements.
+ * The `$page` variable always refers to the currently active page. 
+ * To fetch the content from each field we call the field name as a method on the `$page` object, e.g. `$page->title()`. 
+ * This example template makes use of the `$gallery` variable defined in the `album.php` controller 
+ * and the `cover()` method defined in the `album.php` page model.
+ * Snippets like the header and footer contain markup used in multiple templates. They also help to keep templates clean.
+ * More about templates: https://getkirby.com/docs/guide/templates/basics
+ */
+?>
 <?php snippet('header') ?>
 
 <main class="album">
   <article>
 
     <header>
-      <?php if ($cover = $page->cover()): ?>
+      <?php 
+      // in this line of code, `cover` does not call the field of the same name but the `cover` method defined in the page model
+      // before we use the `crop()` file method, we make sure to check if the file exists to prevent errors
+      if ($cover = $page->cover()): ?>
       <figure class="album-cover">
         <?= $cover->crop(1024, 768) ?>
         <figcaption>
+          <!-- The `or()` method is great to provide a fallback value if a field is empty -->
           <h1><?= $page->headline()->or($page->title()) ?></h1>
         </figcaption>
       </figure>

site/templates/default.php

@@ -1,9 +1,19 @@
+<?php
+/**
+ * Templates render the content of your pages. 
+ * They contain the markup together with some control structures like loops or if-statements.
+ * The `$page` variable always refers to the currently active page. 
+ * To fetch the content from each field we call the field name as a method on the `$page` object, e.g. `$page->title()`. * 
+ * This default template must not be removed. It is used whenever Kirby cannot find a template with the name of the content file.
+ * Snippets like the header, footer and intro contain markup used in multiple templates. They also help to keep templates clean.
+ * More about templates: https://getkirby.com/docs/guide/templates/basics
+ */
+?>
 <?php snippet('header') ?>
 
 <main>
-  <header class="intro">
+  <?php snippet('intro') ?>
-    <h1><?= $page->title() ?></h1>
+
-  </header>
   <div class="text">
     <?= $page->text()->kt() ?>
   </div>

site/templates/home.php

@@ -1,17 +1,34 @@
+<?php
+/**
+ * Templates render the content of your pages. 
+ * They contain the markup together with some control structures like loops or if-statements.
+ * The `$page` variable always refers to the currently active page. 
+ * To fetch the content from each field we call the field name as a method on the `$page` object, e.g. `$page->title()`. 
+ * This home template renders content from others pages, the children of the `photography` page to display a nice gallery grid.
+ * Snippets like the header and footer contain markup used in multiple templates. They also help to keep templates clean.
+ * More about templates: https://getkirby.com/docs/guide/templates/basics
+ */
+?>
+
 <?php snippet('header') ?>
 
 <main>
-  <header class="intro">
+  <?php snippet('intro') ?>
-    <h1><?= $site->title() ?></h1>
-  </header>
 
-  <?php if ($photographyPage = page('photography')): ?>
+
+  <?php 
+  // we always use an if-statement to check if a page exists to prevent errors 
+  // in case the page was deleted or renamed before we call a method like `children()` in this case
+  if ($photographyPage = page('photography')): ?>
   <ul class="grid">
     <?php foreach ($photographyPage->children()->listed() as $album): ?>
     <li>
       <a href="<?= $album->url() ?>">
         <figure>
-          <?php if ($cover = $album->cover()): ?>
+          <?php 
+          // the `cover()` method defined in the `album.php` page model can be used 
+          // everywhere across the site for this type of page
+          if ($cover = $album->cover()): ?>
           <?= $cover->resize(1024, 1024) ?>
           <?php endif ?>
           <figcaption>

site/templates/note.php

@@ -1,3 +1,15 @@
+<?php
+/**
+ * Templates render the content of your pages. 
+ * They contain the markup together with some control structures like loops or if-statements.
+ * This template is responsible for rendering all the subpages of the `notes` page.
+ * The `$page` variable always refers to the currently active page. 
+ * To fetch the content from each field we call the field name as a method on the `$page` object, e.g. `$page->title()`.
+ * Snippets like the header and footer contain markup used in multiple templates. They also help to keep templates clean.
+ * More about templates: https://getkirby.com/docs/guide/templates/basics
+ */
+?>
+
 <?php snippet('header') ?>
 
 <main>

site/templates/notes.php

@@ -1,9 +1,20 @@
+<?php
+/**
+ * Templates render the content of your pages. 
+ * They contain the markup together with some control structures like loops or if-statements.
+ * The `$page` variable always refers to the currently active page. 
+ * To fetch the content from each field we call the field name as a method on the `$page` object, e.g. `$page->title()`.
+ * This template lists all all the subpages of the `notes` page with their title date sorted by date and links to each subpage.
+ * Snippets like the header, footer and intro contain markup used in multiple templates. They also help to keep templates clean.
+ * More about templates: https://getkirby.com/docs/guide/templates/basics
+ */
+?>
+
 <?php snippet('header') ?>
 
 <main>
-  <header class="intro">
+  <?php snippet('intro') ?>
-    <h1><?= $page->title() ?></h1>
+
-  </header>
 
   <div class="notes">
     <?php foreach ($page->children()->listed()->sortBy('date', 'desc') as $note): ?>

site/templates/photography.php

@@ -1,9 +1,20 @@
+<?php
+/**
+ * Templates render the content of your pages. 
+ * They contain the markup together with some control structures like loops or if-statements.
+ * The `$page` variable always refers to the currently active page. 
+ * To fetch the content from each field we call the field name as a method on the `$page` object, e.g. `$page->title()`.
+ * This template lists all all the subpages of the `phototography` page with title and cover image.
+ * Snippets like the header, footer and intro contain markup used in multiple templates. They also help to keep templates clean.
+ * More about templates: https://getkirby.com/docs/guide/templates/basics
+ */
+?>
+
 <?php snippet('header') ?>
 
 <main>
-  <header class="intro">
+  <?php snippet('intro') ?>
-    <h1><?= $page->title() ?></h1>
+
-  </header>
 
   <ul class="albums"<?= attr(['data-even' => $page->children()->listed()->isEven()], ' ') ?>>
     <?php foreach ($page->children()->listed() as $album): ?>