From 89e4201b67f25613d96558e64c89c8ece5b9ed3b Mon Sep 17 00:00:00 2001
From: kirrg001 <katharina.irrgang@googlemail.com>
Date: Fri, 6 Apr 2018 13:32:10 +0200
Subject: [PATCH] Clarify the behaviour of `defaultColumnsToFetch` in the post
 model

no issue

- add a big comment
- describe:
  - how this works
  - why this is in place
  - what does currently not work
  - and why it will work with channels
- @TODO:
  - figure out how to disallow:
  - `models.Post.findAll({columns: id})`
  - `post.save(data)`
  - this will trigger bookshelf events and model events
  - url generation currently needs a set of attributes (e.g. slug, published_at)
    - will be auto-fixed with channels, because you can call `urlService.getUrl(post.id)`
  - but what doesn't get solved is our model events
    - e.g. `emitChange` needs `post.get('page')` to determine if it's a page
---
 core/server/models/post.js | 37 ++++++++++++++++++++++++++++++++++++-
 1 file changed, 36 insertions(+), 1 deletion(-)

diff --git a/core/server/models/post.js b/core/server/models/post.js
index 16c4c95ff7..645ae89fce 100644
--- a/core/server/models/post.js
+++ b/core/server/models/post.js
@@ -351,7 +351,42 @@ Post = ghostBookshelf.Model.extend({
     fields: function fields() {
         return this.morphMany('AppField', 'relatable');
     },
-
+    /**
+     * @NOTE:
+     * If you are requesting models with `columns`, you try to only receive some fields of the model/s.
+     * But the model layer is complex and needs specific fields in specific situations.
+     *
+     * ### url generation
+     *   - it needs the following attrs for permalinks
+     *     - `slug`: /:slug/
+     *     - `published_at`: /:year/:slug
+     *     - `author_id`: /:author/:slug, /:primary_author/:slug
+     *   - @TODO: with channels, we no longer need these
+     *     - because the url service pre-generates urls based on the resources
+     *     - you can ask `urlService.getUrl(post.id)`
+     *   - @TODO: there is currently a bug in here
+     *     - you request `fields=title,url`
+     *     - you don't use `include=tags`
+     *     - your permalink is `/:primary_tag/:slug/`
+     *     - we won't fetch the primary tag, ends in `url = /all/my-slug/`
+     *     - will be auto fixed when merging channels
+     *   - url generator when using `findAll` or `findOne` doesn't work either when using e.g. `columns: title`
+     *      - this is because both functions don't make use of `defaultColumnsToFetch`
+     *      - will be auto fixed when merging channels
+     *
+     * ### events
+     *   - you call `findAll` with `columns: id`
+     *   - then you trigger `post.save()`
+     *   - bookshelf events (`onSaving`) and model events (`emitChange`) are triggered
+     *   - @TODO: we need to disallow this
+     *   - you should use `models.Post.edit(..)`
+     *   - editing resources denies `columns`
+     *   - same for destroy - you should use `models.Post.destroy(...)`
+     *
+     * @IMPORTANT: This fn should **never** be used when updating models (models.Post.edit)!
+     *            Because the events for updating a resource require most of the fields.
+     *            This is protected by the fn `permittedOptions`.
+     */
     defaultColumnsToFetch: function defaultColumnsToFetch() {
         return ['id', 'published_at', 'slug', 'author_id'];
     },