locomotivemtl/charcoal-city-boilerplate

Boilerplate, a Charcoal City Project

Maintainers

Details

github.com/locomotivemtl/charcoal-city-boilerplate

Homepage

Source

Issues

Installs: 52

Dependents: 0

Suggesters: 0

Security: 0

Stars: 0

Watchers: 15

Forks: 0

Open Issues: 0

Language:JavaScript

Type:project

0.2 2017-04-03 18:16 UTC

Requires

Requires (Dev)

MIT f9694b1233cbc705154b474a91c2ac2a08f74700

boilerplateprojectcharcoal

This package is auto-updated.

Last update: 2024-12-06 10:09:48 UTC

README

The goal of this project is to provide a fully working "boilerplate" (empty skeleton project) for a City project using the Charcoal framework. The installation is fully automated.

Table of Content

How to Install

To start a Charcoal project with this Boilerplate, simply:

1. Create / clone the city boilerplate

$ composer create-project locomotivemtl/charcoal-city-boilerplate [path] --prefer-source -s dev

The --prefer-source argument ensure you have the possibility to edit vendors while the -s dev argument specifies composer to user the latest development boilerplate.

About the Document Root

👉 The project should not be cloned directly in a web-accessible directory. The web server should be configured to serve the www/ folder directly. The other folders (vendor/, src/, templates/, metadata/, config/, etc.) should therefore not be available from the web server (kept outside the document root).

2. Installation process

Create-project setup

  • Do you want to remove the existing VCS (.git, .svn..) history? [Y,n]?
    • Yes. This will remove the charcoal-city-boilerplate repository informations.

Project setup

The project setup uses the given name to rename all files to the currently choosen namespace.

Manual call:

$ ./vendor/bin/charcoal city/setup

  • What is the name of the project?

    • Could be bascily any valid string that is not charcoal or city which are the 2 already used namespaces.

  • What is the namespace of the project?

    • Default will be the name of the project with a capital letter. Everything will be renamed accordingly.

Composer setup

The composer setup updates the composer.json file to match the current project informations.

  • What is the VCS repository of the project? (let blank to use an already installed VCS)

    • The repository in which the project will be held. If specified, the script will ensure to git init and git remote add origin [specified repository]

  • What is the project website url? (optional)

    • Updates the composer.json file with the given information.

City config script

The city config script generates a database and a config.local.json file matching the given informations.

Manual call:

$ ./vendor/bin/charcoal city/config
  • Database name (Database will be created or overwritten, let blank to user another database)
    • Database name. If not specified, you will have to manually edit the config.local.json file automatically generated.
  • Database username : [default: root]
    • Database username (usually root)
  • Database password : [default: '']
    • Database password (default to empty string)
  • Database hostname : [default: 127.0.0.1]
    • Database hostname which could be either 127.0.0.1 or localhost.

3. Ready to go

You can now visit the local webpage and access the home template, default news and default events. Depending on your installation, you might have to update the hosts file.

4. Basic debug

If you can't see the home page with all these steps successfully completed, make sure you changed the hosts file accordingly. Then, you can manually composer update the project, which will rebuild the autoload and update to the latest package. When all else fails, ask for Joel or Bene.

5. Set up charcoal-admin

This step is now completely automated.

First, ensure the admin module (the backend) is properly set up and ready:

$ cd vendor/locomotivemtl/charcoal-admin
$ npm install
$ bower install
$ grunt
$ cd -

Then create the first admin user, to be able to login into the backend:

$ ./vendor/bin/charcoal admin/user/create

👉 The ./vendor/bin/charcoal CLI tool, provided by charcoal-app is required to run various scripts, many of which are provided by the charcoal-admin and charcoal-base modules.

Point your browser to http://localhost:8080/ and you should see the boilerplate's default home page.

Admin login

The next step to customize the backend is to configure the main menu, as well as the various

Dependencies and Requirements

  • PHP 5.5+
    • ext-json
    • ext-pdo
    • ext-spl
    • ext-mbstring

The Charcoal modules

Status matrix

What's inside this Boilerplate?

Like all Charcoal projects / modules, the main components are:

  • Autoloader
    • Provided by Composer.
  • Config
  • Front Controller
  • Script Controller (Charoal Binary)
    • Installed from charcoal-app as vendor/bin/charcoal.
  • PHP scripts
    • PSR-1, PSR2 and PSR-4 compliant scripts are located in src/
    • There are typically 3 types of controllers:
      • Templates
      • Actions
      • Scripts
    • ... 2 types of object
      • Objects based on Content
      • Objects based on UserData
    • ... and all other types of scripts (services, helpers, configs, factories, etc.)
  • Assets
    • Assets are files required to be on the webserver root
    • Scripts, in src/scripts/ and compiled in www/assets/scripts/
    • Styles , with Sass in src/styles/ and compiled CSS in www/assets/styles/
    • Images, in www/assets/images/

Development

To install the development environment:

★ composer install --prefer-source

To run the scripts (phplint, phpcs and phpunit):

★ composer test

API documentation

Development dependencies

  • phpunit/phpunit
  • squizlabs/php_codesniffer
  • satooshi/php-coveralls

Continuous Integration

Coding Style

The charcoal-base module follows the Charcoal coding-style:

Coding style validation / enforcement can be performed with composer phpcs. An auto-fixer is also available with composer phpcbf.

Authors

Changelog

Unreleased