-
Notifications
You must be signed in to change notification settings - Fork 24
2015 Documentation
Welcome to the CMPD wiki!
CMPD uses a mixture of various libraries and APIs. This document will discuss how these libraries and APIs mesh and how to use them to add-on to the existing system.
Before delving too deep into the framework check out the "Adding & Updating" sections at the bottom to get a better feel for how to manage with the individual components of the system.
Laravel is a common PHP MVVC Framework. It's designed to enforce a set of rules that should make projects quicker to develop for and more predictable. To an outsider it can look complicated and messy, but once you know where to look it becomes simpler to work with. This section will breakdown how to work with Laravel as well as how to extend the CMPD project with new code.
This is a quick breakdown of the need-to-know paths of Laravel as it relates to the CMPD project. There are plenty more directories available than are listed here, but they are generally only for Laravel's use and are not normally accessed.
- /app - Models are stored in the root of this directory
- /app/Base/Controllers - Custom base controllers for all pages. Other controllers can inherit from these
- /app/Base/Forms - Custom base forms for all pages. Other forms can inherit from these
- /app/Base/Helpers - Customer functions that take an input and generate output
- /app/Base/Services - Custom functions that can be used to perform some action
- /app/Forms/* - Forms for the "Create" pages
- /app/Http/Controllers - Controllers used for managing how pages load and deal with models
- /app/Http/Middleware - Classes used to control/format data between the REQUEST, Controller and Views (not actively used right now)
- /app/Http/Requests - Classes used to customize, restrict and modify REQUEST objects
- /public - Publically accessible files. Anything put in this folder can be accessed through the web
- /resources/assets/js - JavaScript files commonly used for the application
- /resources/assets/less (and sass) - Stylesheet files commonly used for the application
- /resources/assets/views - HTML View files used to display data on the site
In order for Laravel to know what actions to perform or what pages to show, a route needs to be specified. Routes can be used to specify 'pretty path' names in the URL where certain actions can be performed or pages shown.
Routes can be configured in the file /app/Http/routes.php. Routes are separated into groups. Groups are assigned a prefix - in the browser, this is the first part of the url. For example, the "Admin" group has the prefix "admin", so when you hit "http://192.168.33.10/admin" it takes you to the dashboard.
Inside of each group there are additional routes. These can be specified as "get", "post", "patch", "push", "delete" or "resource". The first parameter is the URL (with respect to the prefix), and the second parameter is the controller[@method] that should be invoked. In the case of the URL, it will always be the prefix + URL. So, if the group prefix is "admin" and the url is "test", you would invoke this route by hitting "/admin/test".
Controllers can be added in /app/Base/Controllers or /app/Http/Controllers.
Models can be added in /app.
Views can be added in /resources/views
Creating a new section requires creating a new controller and setting up the appropriate menu item for it to be accessible.
- Create a new PHP file under
/app/Http/Controllers/[route prefix]- All controllers are named CamelCase with the format: [section]Controller.php
- Have that controller extend the appropriate [route prefix]Controller
- Implement the base methods "index", "store", "show", "edit", "update" and "destroy"
- Compare to existing controllers for anything missing
- Setup access to controller in routes
Modify /app/Http/Middleware/Custom/MakeMenu.php to add a new menu item
Typically, each section will be broken down into the following kind of setup:
- List all [section] - This will list all items associated with this section
- This commonly refer uses the "index" method on the associated controller
- This table will normally have "Show", "Edit" and "Delete" buttons, which are associated with the method of the same name on the controller
- Add new [section] - This will provide the "Create"/"Edit" form page to add a new instance of this [section]
There are two methods being used to build forms right now. Blade & Vue or the Kris library. Each has its own pros and cons that should be reviewed before developing a form.
Using the Blade engine and Vue you can make much more dynamic custom forms. These require more work than a Kris setup but can be used to do more unique or complicated data collecting.
... example section ...
Laravel Form Builder is the name of the default form builder that comes standard with Laravel. It can be used to build standard forms in a very simple manner using PHP. It makes developing simple forms extremely easy, but it lacks the ability to do custom forms. If all you're doing is collecting basic information, using a Kris form may be the way to go.
... example section ...
Composer is a package manager for PHP, similar to pip, npm and bower. You can use it to install external PHP libraries and have them automatically include into the project. All libraries that have already been download can be viewed in the composer.json file.
To install a new library, find the package you wish to install on Packgist and execute composer require [package-name]. This will download and install the package to the folder /vendor. As long as the library supports it, you can now access it by its namespace throughout the project.
Gulp, as far as this project is concerned, is used to combine JavaScript and CSS into single files to be included as needed throughout the site. Every JS file and stylesheet that needs to be combine should be listed in gulpfile.js in the project root directory. If you need to update a stylesheet or JS file, navigate to the root directory of the project and execute gulp in the command line.
For development purposes, for now, JavaScript should be developed inline or in a separate file that is loaded in on the page during development. Once development on that page is done the code should be merged into the main stylesheet or linked to in gulpfile.js and gulp should be execute.
Bower is essentially composer, npm or even pip for the web. It's sole purpose is to make various JavaScript and style libraries easy to download and keep up-to-date. All libraries that have currently been download can be reviewed in the bower.json file. This is syntactically similar to the package.json files that NodeJS/NPM are known to use.
To install a new library, find the package you wish to install on Bower Search and execute bower install --save [package-name]. This will download and install the package to the folder /resources/assets/vendor. By default it should install to /bower_components/, but there is a hidden file .bowerrc that changes the default save path.
Now that your library is installed, edit gulpfile.js and add your file to the appropriate build section. Once you execute gulp, your library will be automatically included in the generated output.
Most files that are going to be modified will be in the resources/assets folders. Typically you'll modify the files:
- /resources/assets/js - admin.js & application.js
- /resources/assets/less - admin.less, application.less & skin-cmpd.less
Remember: Making any changes to the above files requires running gulp in the root directory to compile them.