Lessons and documentation todos

dnsl48 commented 5 years ago

@dnsl48 commented on Tue Feb 05 2019

Affected Version

4

Description

Some suggestions to improve the lessons and the documentation on https://silverstripe.org

[x] Index links are broken - #84
[ ] Learners experience could be improved with docker. E.g. we could use prepared database containers rather than ask people to roll SQL dumps manually.
[ ] The app from the Lesson 0 is not the one which we work on in Lesson 1
[ ] Might be worth explicitly asking to checkout lesson source codes and not reuse the ones from previous lessons
[ ] Could be much handier to copy stuff straight from snippets rather than go to the github repository and look up for a file (e.g. templates)
[ ] Code snippets do not contain opening <?php tags
[ ] lesson 1 - mysite/code/ folder instead of mysite/src/
[ ] lesson 2 - broken link to the "Code repository"
[ ] lesson 2 - does not explicitly ask to checkout the app, rather than use stuff from previous lessons
[ ] lesson 5 - does not state the files static/article-holder.html and static/article-page.html are actually in __assets folder
[ ] lesson 7 - add the link to the other tutorial covering the image resampling functions
[ ] lesson 7 - $Image.FixMax(width, height) - typo, should be FitMax
[ ] lesson 9 - Attached to this lesson is a download link to a new static template - not clear that I have to look into the Code Repository __assets folder
[ ] lesson 11 - rewrite the example with validating length of a field not in the controller, but a Validator attached to the field itself
[ ] lesson 11 - add an example how to leverage HTML5 minlength/maxlength attributes
[ ] lesson 11 - Form::addErrorMessage has been deleted [https://github.com/silverstripe/silverstripe-framework/blob/4/docs/en/04_Changelogs/4.0.0.md] (#77)
[ ] lesson 11 - rewrite the example to use $comment = ArticleComment::create($data) rather than assigning each field separately
[ ] lesson 11 - rewrite the example to "include" comments block in the template
[ ] lesson 11 - handleComment on ArticlePage.php instead of ArticlePageController.php (a typo)
[ ] lesson 11 - Controller gets the same fields as the Model... nothing said about that in the prior lessons
[ ] lesson 12 - the first part of the lesson leaves you with hard feelings, the second part clarifies that Extensions is not a reinvented wheel (DI+Traits), but also solves "events" and "hooks" use cases. Potentially could be rewritten.
[ ] lesson 12 - _app/config/app.yml does not exist, it's app/_config/app.yml
[ ] lesson 13 - app/src/Property.php snippet doesn't have peculiarity ->setEmptyString(). It appears below in the next one.
[ ] lesson 14 - $Photo.SetWidth(750) does not work. Should be ScaleWidth (typo)
[ ] lesson 14 - lack of use SilverStripe\Forms\HTMLEditor\HTMLEditorField; in the snippet where we update the Region's getCMSFields method
[ ] lesson 14 - class sidebar with the simple theme concealed the Regions section and it wouldn't appear. May be confusing for beginners.
[ ] lesson 14 - MetaTags(false) + title bit could be irrelevant as it comes with the theme in the Lesson 0
[ ] lessons 15 and further - To be checked
[ ] https://docs.silverstripe.org/en/4/contributing/code/ - supported versions link is broken
[ ] https://docs.silverstripe.org/en/4/developer_guides/testing/ - Documentation on unit and integration testing is too old (https://www.slideshare.net/maetl/getting-to-grips-with-silverstripe-testing)
[ ] add a lesson around YAML configuration
[ ] add a lesson about routing
[ ] add a lesson about caching
[ ] add a lesson about logging

@robbieaverill commented on Tue Feb 05 2019

I've adjusted the impact rating since these are documentation issues.

Also FYI, the lessons issues could be tracked on the https://github.com/silverstripe/silverstripe-lessons-v4 repository if we want to move them out of framework

dnsl48 commented 5 years ago

@robbieaverill sorry, I still believe this is impact/high as it has Broken functionality with workarounds available, affecting major usage flows accordingly to the impact rating Those are broken snippets, recommendations to use non-existing functionality etc.

robbieaverill commented 5 years ago

Fair enough =)

ScopeyNZ commented 5 years ago

There was discussion on community Slack today about an issue with Lesson 6:

Good morning all! I am working on Lesson 6, all the way through it. The problem is, $Author is not showing the author and $Content.FirstSentence doesn't seem to be working either. Anyone have a similar issue?

https://slackarchive.silverstripe.org/slack-archive/message/253871

I didn't have time to look into it myself but I'm tagging here for records.

dnsl48 commented 5 years ago

he problem is, $Author is not showing the author and $Content.FirstSentence

For some reasons I didn't encounter this one when was doing the lessons. I'll verify and add it to the list.

https://silverstripe-users.slack.com/archives/C0QSDASKT/p1549550392530100

Hubenet commented 5 years ago

Lesson 6: Adding custom fields to a page

class ArticlePage extends Page { private static $db = [ 'Date' => 'Date', 'Teaser' => 'Text', 'AuthorName' => 'Varchar' ]; }

When running dev/build/ this message appears in the Environment Builder:

Please note: It is strongly recommended to define a table_name for all namespaced models. Not defining a table_name may cause generated table names to be too long and may not be supported by your current database engine. The generated naming scheme will also change when upgrading to SilverStripe 5.0 and potentially break.
table_name not set for class Hamaka\Pages\WorkPage

class ArticlePage extends Page { private static $table_name = 'ArticlePage'; private static $db = [ 'Date' => 'Date', 'Teaser' => 'Text', 'AuthorName' => 'Varchar' ]; }

Ps. Lesson numbers should be used in the Title as well.. Pss. As @ScopeyNZ mentioned before, Author is not working so I use AuthorName instead..

Firesphere commented 5 years ago

For reference, the comment @dnsl48 is talking about can be found in the archive here: https://slackarchive.silverstripe.org/slack-archive/message/253879

As the Slack community doesn't have full history, using the archive instead :)

robbieaverill commented 5 years ago

https://github.com/silverstripe/silverstripe-lessons-v4/issues/84 has been fixed which probably resolves some of these action points

ScopeyNZ commented 5 years ago

I think only the first item can be ticked off the list. The PR for #84 only modified index.md.

ssimo3lsuhsc commented 5 years ago

Hello! I'm working on Lesson 4. When I follow the section entitled "Injecting Assets through the Controller," no CSS or JavaScript assets get loaded.

I have tried both of the following, both individually and at once:

Inserting the text $Requirements as a placeholder
In accordance with the Requirements page, adding the following to composer.json: "extra": { "expose": [ "public/css", "public/javascript" ] }

robbieaverill commented 5 years ago

Could you please share the code you’re trying to use? As for the second- have you run composer vendor-expose?

ssimo3lsuhsc commented 5 years ago

I ran composer vendor-expose. The error still persists.

My code for templates/Pages.ss:

<!DOCTYPE html>
<!--[if lt IE 7 ]><html class="ie ie6" lang="en"> <![endif]-->
<!--[if IE 7 ]><html class="ie ie7" lang="en"> <![endif]-->
<!--[if IE 8 ]><html class="ie ie8" lang="en"> <![endif]-->
<!--[if (gte IE 9)|!(IE)]><!--><html lang="en"> <!--<![endif]-->
<head>
    <% base_tag %>
    $MetaTags

    <meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1" />

    <!-- IE6-8 support of HTML5 elements -->
    <!--[if lt IE 9]>
    <script src="http://html5shim.googlecode.com/svn/trunk/html5.js"></script>
    <![endif]-->

    <!-- Google Web Font -->
    <link href="http://fonts.googleapis.com/css?family=Raleway:300,500,900%7COpen+Sans:400,700,400italic" rel="stylesheet" type="text/css" />
<body>
<!-- BEGIN WRAPPER -->
<div id="wrapper">

    <!-- BEGIN HEADER -->
    <header id="header">
        <div id="top-bar">
            <div class="container">
                <div class="row">
                    <div class="col-sm-12">
                        <ul id="top-buttons">
                            <li><a href="#"><i class="fa fa-sign-in"></i> Login</a></li>
                            <li><a href="#"><i class="fa fa-pencil-square-o"></i> Register</a></li>
                            <li class="divider"></li>
                            <li>
                                <div class="language-switcher">
                                    <span><i class="fa fa-globe"></i> English</span>
                                    <ul>
                                        <li><a href="#">Deutsch</a></li>
                                        <li><a href="#">Espa&ntilde;ol</a></li>
                                        <li><a href="#">Fran&ccedil;ais</a></li>
                                        <li><a href="#">Portugu&ecirc;s</a></li>
                                    </ul>
                                </div>
                            </li>
                        </ul>
                    </div>
                </div>
            </div>
        </div>

        <div id="nav-section">
            <div class="container">
                <div class="row">
                    <div class="col-sm-12">
                        <a href="$AbsoluteBaseURL" class="nav-logo"><img src="images/logo.png" alt="One Ring Rentals" /></a>

                        <!-- BEGIN MAIN MENU -->
                        <nav class="navbar">
                            <button id="nav-mobile-btn"><i class="fa fa-bars"></i></button>

                            <ul class="nav navbar-nav">
                                <% loop $Menu(1) %>
                                    <li><a class="$LinkingMode" href="$Link" title="Go to the $Title page">$MenuTitle</a></li>
                                <% end_loop %>
                            </ul>

                        </nav>
                        <!-- END MAIN MENU -->

                    </div>
                </div>
            </div>
        </div>
    </header>
    $Layout
    <footer id="footer">
        <div id="footer-top" class="container">
            <div class="row">
                <div class="block col-sm-3">
                    <a href="#"><img src="images/logo.png" alt="One Ring Rentals" /></a>
                    <br><br>
                    <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nam commodo eros nibh, et dictum elit tincidunt eget. Pellentesque volutpat quam dignissim, convallis elit id, efficitur sem. Vivamus ac scelerisque sem. Aliquam sed enim rutrum nibh gravida pellentesque nec at metus. In hac habitasse platea dictumst. Etiam in rhoncus mi. In hac habitasse platea dictumst. Mauris congue blandit venenatis.</p>
                </div>
                <div class="block col-sm-3">
                    <h3>Helpful Links</h3>
                    <ul class="footer-links">
                        <li><a href="#">All rentals</a></li>
                        <li><a href="#">List your rental</a></li>
                        <li><a href="#">Read our FAQs</a></li>
                    </ul>
                </div>
                <div class="block col-sm-6">
                    <h3>Popular regions</h3>
                    <div class="row">
                        <div class="col-sm-6">
                            <ul class="footer-listings">
                                <li>
                                    <div class="image">
                                        <a href="properties-detail.html"><img src="http://placehold.it/760x670" alt="" /></a>
                                    </div>
                                    <p><a href="properties-detail.html">Rhovanion</a></p>
                                </li>
                                <li>
                                    <div class="image">
                                        <a href="properties-detail.html"><img src="http://placehold.it/760x670" alt="" /></a>
                                    </div>
                                    <p><a href="properties-detail.html">Eriador</a></p>
                                </li>
                                <li>
                                    <div class="image">
                                        <a href="properties-detail.html"><img src="http://placehold.it/760x670" alt="" /></a>
                                    </div>
                                    <p><a href="properties-detail.html">Bay of Belfalas</a></p>
                                </li>
                            </ul>
                        </div>
                        <div class="col-sm-6">
                            <ul class="footer-listings">
                                <li>
                                    <div class="image">
                                        <a href="properties-detail.html"><img src="http://placehold.it/760x670" alt="" /></a>
                                    </div>
                                    <p><a href="properties-detail.html">Mordor</a></p>
                                </li>
                                <li>
                                    <div class="image">
                                        <a href="properties-detail.html"><img src="http://placehold.it/760x670" alt="" /></a>
                                    </div>
                                    <p><a href="properties-detail.html">Arnor</a></p>
                                </li>
                                <li>
                                    <div class="image">
                                        <a href="properties-detail.html"><img src="http://placehold.it/760x670" alt="" /></a>
                                    </div>
                                    <p><a href="properties-detail.html">Forlindon</a></p>
                                </li>
                            </ul>
                        </div>
                    </div>
                </div>
            </div>
        </div>

        <!-- BEGIN COPYRIGHT -->
        <div id="copyright">
            <div class="container">
                <div class="row">
                    <div class="col-sm-12">
                        &copy; 2014 One Ring Rentals

                        <!-- BEGIN SOCIAL NETWORKS -->
                        <ul class="social-networks">
                            <li><a href="#"><i class="fa fa-facebook"></i></a></li>
                            <li><a href="#"><i class="fa fa-twitter"></i></a></li>
                            <li><a href="#"><i class="fa fa-google"></i></a></li>
                            <li><a href="#"><i class="fa fa-pinterest"></i></a></li>
                            <li><a href="#"><i class="fa fa-youtube"></i></a></li>
                            <li><a href="#"><i class="fa fa-rss"></i></a></li>
                        </ul>
                        <!-- END SOCIAL NETWORKS -->

                    </div>
                </div>
            </div>
        </div>
        <!-- END COPYRIGHT -->

    </footer>

    <!-- END FOOTER -->

</div>
<!-- END WRAPPER -->

</body>
</html>

My code for app/src/PageController.php:

<?php

namespace {

    use SilverStripe\CMS\Controllers\ContentController;
    use SilverStripe\View\Requirements;

    class PageController extends ContentController
    {
        /**
         * An array of actions that can be accessed via a request. Each array element should be an action name, and the
         * permissions or conditions required to allow the user to access it.
         *
         * <code>
         * [
         *     'action', // anyone can access this action
         *     'action' => true, // same as above
         *     'action' => 'ADMIN', // you must have ADMIN permissions to access this action
         *     'action' => '->checkAction' // you can only access this action if $this->checkAction() returns true
         * ];
         * </code>
         *
         * @var array
         */
        private static $allowed_actions = [];

        protected function init()
        {
            parent::init();
            Requirements::css('css/bootstrap.min.css');
            Requirements::css('css/style.css');
            Requirements::javascript('javascript/common/modernizr.js');
            Requirements::javascript('javascript/common/jquery-1.11.1.min.js');
            Requirements::javascript('javascript/common/bootstrap.min.js');
            Requirements::javascript('javascript/common/bootstrap-datepicker.js');
            Requirements::javascript('javascript/common/chosen.min.js');
            Requirements::javascript('javascript/common/bootstrap-checkbox.js');
            Requirements::javascript('javascript/common/nice-scroll.js');
            Requirements::javascript('javascript/common/jquery-browser.js');
            Requirements::javascript('javascript/scripts.js');
        }

    }
}

robbieaverill commented 5 years ago

Requirements::javascript('javascript/scripts.js'); (for example) needs to be Requirements::javascript('your/project:javascript/scripts.js');, where your/project is the name value in your project's composer.json file. If the lesson doesn't state this, we'd welcome a pull request to update it =)

ssimo3lsuhsc commented 5 years ago

It does not work. I get a nondescript error and get redirected to the login page. The key thing to remember about the lessons is that they assume that the assets are kept in the public folder and not in a theme or the project root.

My structure is:

root
   app
      _config
      src
      templates
         Includes
         Layout
         SilverStripe
            Lessons
               Layout
   public
      _resources
      assets
         .protected
      css
      fonts
      images
      javascript
         common

You can see for yourself that the folders lesson-4-begin (or is it lesson-4-start?) and lesson-4-end have the same structure. Now that you know that, can you tell me what will work? Thank you!

Q: What do I get with the following code in PageController.php?

protected function init()
        {
            parent::init();
            Requirements::css('silverstripe/installer:css/bootstrap.min.css');
            Requirements::css('css/style.css');
            Requirements::javascript('javascript/common/modernizr.js');
            Requirements::javascript('javascript/common/jquery-1.11.1.min.js');
            Requirements::javascript('javascript/common/bootstrap.min.js');
            Requirements::javascript('javascript/common/bootstrap-datepicker.js');
            Requirements::javascript('javascript/common/chosen.min.js');
            Requirements::javascript('javascript/common/bootstrap-checkbox.js');
            Requirements::javascript('javascript/common/nice-scroll.js');
            Requirements::javascript('javascript/common/jquery-browser.js');
            Requirements::javascript('javascript/scripts.js');
        }

A: AwesomeScreenshot-Server-error-Your-Site-Name-2019-07-23-09-07-00

Q: What about the following code?

protected function init()
        {
            parent::init();
            Requirements::css('css/bootstrap.min.css');
            Requirements::css('css/style.css');
            Requirements::javascript('silverstripe/installer:javascript/common/modernizr.js');
            Requirements::javascript('javascript/common/jquery-1.11.1.min.js');
            Requirements::javascript('javascript/common/bootstrap.min.js');
            Requirements::javascript('javascript/common/bootstrap-datepicker.js');
            Requirements::javascript('javascript/common/chosen.min.js');
            Requirements::javascript('javascript/common/bootstrap-checkbox.js');
            Requirements::javascript('javascript/common/nice-scroll.js');
            Requirements::javascript('javascript/common/jquery-browser.js');
            Requirements::javascript('javascript/scripts.js');
        }

A: Exactly the same thing.

GuySartorelli commented 1 year ago

@maxime-rainville This is looking a bit ahead of where we're at right now but this is a really good list for when we're ready to look at this

silverstripe / silverstripe-lessons-v4

Lessons and documentation todos #83

Affected Version

Description