nickdenardis / base-site

Starter repository for creating a new website.

Base Template

Branch	Build	Coverage
Master
Develop

Starter repository for creating a new website. Live demo can be found at https://base.wayne.edu/.

Features

• Backend built on Laravel/Lumen v5.2
• Frontend built on Foundation v6.3
• Task runner using Gulp
  • Fluent Gulp API using Laravel Elixir
• Fast navigation using SPF
• Zero downtime deployment using Envoy
• Configure multiple enviorments using PHPDotenv
• ES2015 support using Webpack
• SCSS support
• Automatically inject JS/CSS while developing using BrowserSync
• NewRelic support via the NewRelicMiddleware if the php extension is installed
• 100% test code coverage
• Public API documentation
• Commit hook that require the following to pass:
  • Tests using PHPUnit
  • PHP linting using PHPCSFixer
  • JS linting using ESLint
  • CSS/SCSS linting using Stylelint
• Menus
  • Top level menu carried across all pages that follows you down the page as you scroll
  • Left menu if a page has subitems, otherwise its a full width page
  • Offcanvas menu that is triggered on a variable breakpoint that includes
    • The top level menu grouped together
    • Left menu
    • Under menu promotions
• Full styleguide detailing out every available component using PHP faker data
• Single or rotating hero images using Slick Carousel
• Automatically lightbox youtube videos using Magnific Popup
• Easy integration with a CMS by writing custom .json files to the public directory which are matched by to a route and sent to the specified controller

Setup

1. Setup laravel homestead: http://laravel.com/docs/homestead
2. Clone the repository
3. run make install
4. run make build
5. run make watch
6. open https://domain.dev:3000/ (for BrowserySync)

Deployment

• Setup the following config variables in Envoy.blade.php
  • $appname
  • $server_map
  • $source_repo
  • $deploy_basepath
• Development: envoy run deploy or make deploy
• Production: envoy run deploy --on="production" or make deployproduction
• Any branch: envoy run deploy --branch=feature/feature

Run tests

phpunit

Run test coverage

1. make coverage
2. Open the coverages/index.html file in your browser

Check for outdated packages

make status

Update packages

make update

Configure the site

1. Open /config/app.php
2. Edit the options to configure the site, some values are present in the .env file.
3. Server specific configuration options come from the .env file which need to be manually created/updated on the servers the app is deployed to.

Request API key

Email [e-mail] with your request.

Developing global data that is passed down to all views via the $request->data variable

1. Open the folder /app/Repositories.
2. Create new class and implement the interface DataRepositoryContract.
3. Fill out the getRequestData method and return an array.

Developing controllers

1. Open the folder /app/Http/Controllers/
2. This folder contains all the selectable templates from the CMS.
3. Controllers should:
   • Dependency inject repositories into the constructor.
   • Call repositories to obtain data to send to the view.

Developing views

1. Open /resources/views/
2. This folder contains all the views for the front-end using the blade templating engine
3. Files must be saved in the format of: homepage.blade.php
4. Partials: Contains views that are only used once in the project
5. Components: Contains views that are reusable

Pages

Pages are written from the content management system automatically. To replicate what it writes you can use the following JSON format to create pages. Example homeage: storage/app/public/index.json.

{
    "site" : {
        "id" : 1,
        "title" : "Base Site",
        "subsite-folder" : null,
        "parent" : {
            "id" : null
        }
    },
    "page" : {
        "id" : 1,
        "controller" : "HomepageController",
        "title" : "Welcome!",
        "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed turpis lorem, malesuada eu tellus vel, pharetra consequat lacus. Vestibulum eu metus nec massa viverra iaculis. Pellentesque libero eros, varius non sem et, dapibus aliquam magna. Praesent ultri",
        "content" : {
            "main" : "<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed turpis lorem, malesuada eu tellus vel, pharetra consequat lacus. Vestibulum eu metus nec massa viverra iaculis. Pellentesque libero eros, varius non sem et, dapibus aliquam magna.</p>"
        },
        "keywords" : "",
        "updated-at" : ""
    },
    "menu" : {
        "id" : 1
    },
    "data" : {

    }
}

Menus

Menus are automatically pulled from the content management system. To replicate the structure you can use the following array and replace the code in App\Repositories\MenuRepository@getAllMenus.

<?php

$menus = [
    1 => [ // The menu_id specified from the .json file
        1 => [ // First menu item
            'menu_item_id' => '1', // Auto incrementing ID
            'is_active' => '1', // To output the menu item or not
            'page_id' => '1', // Page ID specified from the .json file
            'target' => '', // HTML <a target="">
            'display_name' => 'Home', // Title of the menu item
            'class_name' => '', // CSS class name to be appended to the menu item
            'relative_url' => '/', // The relative URL to this page
            'submenu' => [], // Subitems, follow same structure and include another submenu => []
        ],
        2 => [ // Second menu item...

        ],
    ],
];

News listing & view

1. Create a CMS page called news in the root of the site and select the NewsController as the template.
2. This will handle both the listing & view for this particular site. If you need news for a subsite, follow #1 while being within that subsite.

Profile listing & view

1. Create a CMS page for the profile listing page (ex: profiles) and select the ProfileController as the template.
2. Create a CMS page for the profile view, it must be: profile and select the ProfileController as the template.
3. You can now visit https://domain.dev/profiles and http://domain.dev/profile/{accessid}.

Style guide development for a new feature

1. Create repository contract: contracts/Repositories
2. Create repository: app/Repositories
   • implement the repository contract
3. Create fake repository: styleguide/Repositories
   • implement the repository contract
   • Extend the real repository from app/Repositories.
   • Overload any methods necessary and use or create factories/ to get fake data.
4. Create controller
   1. Create the controller in app/Http/Controllers. If the styleguide needs to show variations of the feature, you may need to build controllers within styleguide/Http/Controllers to achieve this.
   2. Point to your view file in resources/views.
   3. Dependency inject the repository contract(s) into the constructor.
   4. Call whatever method(s) necessary to get data from the repository and assign it to the view.
5. Create menu item: styleguide/Repositories/MenuRepository.php
   1. Set menu_item_id and page_id to be the same.
   2. Follow the pattern for setting menu_item_id
      • Root items, increment from previous.
      • Sub items, copy parent menu_item_id and append 100 and auto increment from there.
   3. Set menu_id to 1
6. Create page: styleguide/Pages/
   1. Set page_id from the menu.
      • If the page needs to be full width set page_id = null within the menu.
      • If the page is NOT within then menu then you need to specify the path to the page. Set var $path = '/path/to/your/page' inside your styleguide/Pages/ class.
   2. Set controller to the one you created in step #4.

Contributing

Please see CONTRIBUTING for details.

Licensing

Base Template is open-sourced software licensed under the MIT license.