hypothetical/readme.md

Hypothetical Template

The Hypothetical website template based on Laravel 5.6

Utilities

Language

The default language is set by the DEFAULT_LANGUAGE variable in the .env file. This will be the language used until it is changed, which can be done using the /language/{lang} route or directly using Language::setSessionLanguage($lang) where in both cases lang is the language code for a given language.

In the view, a block of text can be configured with multiple languages using the following syntax:

    @lang([
        'en' => "This is a sentence",
        'fr' => "C'est une phrase"
    ])

or

    {{ Language::select([ 'en' => "This is a sentence", 'fr' => "C'est une phrase" ]) }}

Public

The default public facing website uses vue.js. To configure a non-SPA traditional website, look at the files in traditional-bootstrap.

The following list of files and directories are where various pieces of the public website are located:

• resources/views/templates/base.blade.php: The outer template for the entire website
• resources/views/templates/public.blade.php: The inner template for the public site
• resources/assets/fonts: The folder containing website fonts (these get loaded into public/fonts/ by the gulpfile)
• resources/assets/js/app.js: The main javascript file that loads the public site
• resources/assets/js/mixins: The folder containing vue.js mixins that can be applied globally in resources/assets/js/app.js or in individual components
• resources/assets/js/mixins/base-page.js: The base-page mixin with page functionality that should be imported into all page components
• resources/components: The folder containing vue.js components
  • resources/components/pages: Page components that should be imported into vue-router in resources/assets/js/app.js
  • resources/components/sections: Section components (single-use per page) that should be imported into mixins or page components
  • resources/components/partials: Partial components (multi-use per page or section) that should be imported into mixins and/or page and section components
• resources/assets/sass/app.scss: The main sass file for the public site
• resources/assets/sass/_fonts.scss: Stylesheet containing font declarations and mixins declared to use those fonts in other stylesheets
• resources/assets/sass/_var.scss: Stylesheet containing variables to be used in other stylesheets
• resources/assets/sass/pages: Stylesheets for page-specific styles wrapped in the respective page component class
• resources/assets/sass/sections: Stylesheets for section-specific styles wrapped in the respective section component class
• resources/assets/sass/partials: Stylessheets for partial-specific styles wrapped in the respective partial component class
• resources/assets/sass/classes: General stylesheets for classes that can be used anywhere
• resources/assets/sass/mixins: Stylesheets declaring SCSS mixins for use in other stylesheets

Dependencies can be included with bower or npm and loaded either into the jsPublicLibs array in the gulpfile or imported in the javascript.

Other information about database interaction, routing, controllers, etc can be viewed in the Laravel Documentation.

Dashboard

Unless otherwise stated all examples in this section are to be added to app/Http/Controllers/DashboardController.php.

Adding a Viewable Model to the Dashboard

Viewable List of Rows

First add a function to generate the page:

    public function getContact()
    {
        return view('dashboard.view', [
            'heading' => 'Contact Form Submissions',
            'model'   => 'contact',
            'rows'    => Contact::getContactSubmissions(),
            'columns' => Contact::$dashboard_columns
        ]);
    }

• heading: The title that will appear for this page
• model: The model that will be accessed on this page
• rows: A function returning an array containing the data to be shown on this page
• columns: Expects a variable called $dashboard_columns in the respective model that contains an array:

    public static $dashboard_columns = [
        [ 'Date', 'created_at' ],
        [ 'Name', 'name' ],
        [ 'Email', 'email' ],
        [ 'Message', 'message' ]
    ];

Adding an Editable Model to the Dashboard

Editable List of Rows

Editable List for Unsortable Model

    public function getShows()
    {
        return view('dashboard.edit-list', [
            'heading' => 'Shows',
            'model'   => 'shows',
            'path'    => 'shows-page',
            'rows'    => Shows::getShowsList(),
            'column'  => 'title',
            'button'  => [ 'Email Show', 'Are you sure you want to send an email?', 'Email successfully sent', 'Failed to send email', '/email-show' ],
            'sortcol' => false,
            'delete'  => true,
            'create'  => true,
            'export'  => true,
            'filter'  => true
        ]);
    }

Editable List for Sortable Model

NOTE: Sortable models must have an entry configured in the postReorder function (details below)

    public function getNews()
    {
        return view('dashboard.edit-list', [
            'heading' => 'News',
            'model'   => 'news',
            'rows'    => News::getNewsList(),
            'column'  => 'title',
            'button'  => [ 'Email Show', 'Are you sure you want to send an email?', 'Email successfully sent', 'Failed to send email', '/email-show' ],
            'sortcol' => 'order',
            'delete'  => false,
            'create'  => true,
            'export'  => true,
            'filter'  => true
        ]);
    }

• heading: The title that will appear for this page
• model: The model that will be accessed on this page
• path: (optional) This can be used to set a different URL path than the default of the model name
• rows: A function returning an array containing the data to be shown on this page
• column: The column name in the array that contains the data to display in each row (an array can be used to specify multiple columns)
• button: Add a button with a title, confirmation, success and error messages, and a post request path that takes an id and returns success on success
• sortcol: The name of the column containing the sort order or false to disable
• delete: A delete button will appear in the list if this is set to true
• create: A new button will appear in the heading if this is set to true
• export: An export button will appear in the heading if this is set to true
• filter: An input box will appear below the heading that can filter rows by input if this is set to true

Editable Item

This function should be named the same as the one above except with Edit at the end

Editable Item for Unsortable Model

    public function getShowsEdit($id = 'new')
    {
        if ($id != 'new') {
            if (Shows::where('id', $id)->exists()) {
                $item = Shows::where('id', $id)->first();
            } else {
                return view('errors.no-such-record');
            }
        } else {
            $item = null;
        }

        return view('dashboard.edit-item', [
            'heading' => 'Shows',
            'model'   => 'shows',
            'id'      => $id,
            'item'    => $item,
            'help_text' => '<strong>NOTE:</strong> This is some help text for the current page',
            'columns' => $dashboard_columns
        ]);
    }

Editable Item for Sortable Model

    public function getNewsEdit($id = 'new')
    {
        if ($id != 'new') {
            if (News::where('id', $id)->exists()) {
                $item = News::where('id', $id)->first();
            } else {
                return view('errors.no-such-record');
            }
        } else {
            $item = new News();
            $item['order'] = News::count();
        }

        return view('dashboard.edit-item', [
            'heading' => 'News',
            'model'   => 'news',
            'id'      => $id,
            'item'    => $item,
            'columns' => News::$dashboard_columns
        ]);
    }

• heading: The title that will appear for this page
• model: The model that will be accessed on this page
• id: Always set this to $id
• item: Always set this to $item
• help_text: An optional value that will add a box containing help text above the form if set
• columns: Expects a variable called $dashboard_columns in the respective model that contains an array:
  • name is the name of the column to be edited
  • type is the type of column (details below)
  • label is an optional value that overrides the visible column name

    public static $dashboard_columns = [
        [ 'name' => 'title',  'type' => 'text', 'label' => 'The Title' ],
        [ 'name' => 'iframe', 'type' => 'text' ],
        [ 'name' => 'halign', 'type' => 'select', 'options' => [ 'left', 'center', 'right' ] ],
        [ 'name' => 'story',  'type' => 'mkd' ],
        [ 'label' => 'Header Image', 'name' => 'headerimage', 'type' => 'image' ],
        [ 'name' => 'order',  'type' => 'hidden' ],
        [ 'label' => 'PDF File', 'name' => 'pdf', 'type' => 'file', 'ext' => 'pdf' ]
    ];

Editable Column Types

The following is a list of possible types in the columns array for Editable Items:

• text: Text input field for text data
• mkd: Markdown editor for text data containing markdown
• date: Date and time selection tool for date/time data
• select: Text input via option select with possible options in an options array
• hidden: Fields that will contain values to pass to the update function but won't appear on the page (this must be used for the sort column)
• image: Fields that contain image uploads
  • name: not part of the database and is instead used in the filename
  • delete: (optional) if true then uploaded images can be deleted
• file: Fields that contains file uploads
  • name: not part of the database and is instead used in the filename
  • ext required key containing the file extension
  • delete: (optional) if true then uploaded files can be deleted
• display: Displayed information that can't be edited

Edit Item Functionality

Editable models must have an entry in the switch statement of the postEdit function to make create and edit functionality work:

    switch ($request['model']) {
        case 'shows':
            $item = $id == 'new' ? new Shows : Shows::find($id);
            break;
        case 'news':
            $item = $id == 'new' ? new News : News::find($id);
            break;
        default:
            return 'model-access-fail';
    }

Additional Requirement for Sortable Models

Sortable models must have an entry in the switch statement of the postReorder function to make sorting functionality work:

    switch ($request['model']) {
        case 'news':
            $items = new News();
            break;
        default:
            return 'model-access-fail';
    }

Additional Requirements for Image Upload

If the value of imgup has been set to true, ensure public/uploads/model_name exists (where model_name is the name of the given model) and contains a .gitkeep that exists in version control.

By default, uploaded images are saved in JPEG format with the value of the id column of the respective row as its name and .jpg as its file extension.

When a row is deleted, its respective image will be deleted as well if it exists.

Adding to the Dashboard Menu

Edit the $menu array in app/Models/DashboardMenu.php where the first column of each item is the title and the second is either a path, or an array of submenu items.

    public static $menu = [
        [ 'Contact', 'contact' ],
        [ 'Subscriptions', 'subscriptions' ],

        [
            'Projects', [
                [ 'Residential', 'projects-residential' ],
                [ 'Commercial', 'projects-commercial' ]
            ]
        ]
    ];

Additional Requirement for Delete Functionality

Editable models with delete set to true must have an entry in the switch statement of the deleteDelete function to make deletion functionality work:

    switch ($request['model']) {
        case 'shows':
            $items = new Shows();
            break;
        case 'news':
            $items = new News();
            break;
        default:
            return 'model-access-fail';
    }

Additional Requirement for Export Functionality

Viewable models and editable models with export set to true must have an entry in the switch statement of the getExport function to make the export button work:

    switch ($model) {
        case 'contact':
            $headings = [ 'Date', 'Name', 'Email', 'Message' ];
            $items = Contact::select('created_at', 'name', 'email', 'message')->get()->toArray();
            break;
        default:
            abort(404);
    }

• $headings: The visible column names in the same order as the array containing the items to be exported
• $items: A function returning an array containing the data to be exported