|
1 | | -[](https://travis-ci.org/el-cms/elabs) |
2 | | -[](https://codecov.io/gh/el-cms/elabs) |
3 | | - |
4 | | -[](https://gitter.im/elabs-cms/Lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)[as much as I can] |
| 1 | +[](https://github.com/el-cms/elabs/) [](https://travis-ci.org/el-cms/elabs) [](https://codecov.io/gh/el-cms/elabs) [](https://raw.githubusercontent.com/el-cms/elabs/master/LICENSE) [](https://gitter.im/elabs-cms/Lobby) |
5 | 2 |
|
6 | 3 | # ELabs |
7 | | -CMS for ExperimentsLabs.com based on CakePHP 3 |
| 4 | +CMS for ExperimentsLabs.com created with [CakePHP 3](https://cakephp.org) |
8 | 5 |
|
9 | 6 | ## What is it ? |
10 | | -It's a small website made to make a presentation of projects, files and some articles... for now. |
| 7 | +It's a small website made to make a presentation of projects, files and some articles... |
11 | 8 |
|
12 | 9 | **In any case, that's not a modular CMS, with plugins and lot of stuff** (as [Croogo](http://croogo.org)) |
13 | 10 |
|
14 | | -This structure allows : |
15 | | - |
16 | | - - multiple users |
17 | | - - a simple "project management system" (a page about your project) |
18 | | - - a simple article management system |
19 | | - - a simple file upload system. |
20 | | - - a report system for the visitors/users to report pages or items (may be extended as a way to leave comments to users too) |
21 | | - - licenses support for any item published on the site |
22 | | - |
23 | | -This structure does **not** have comments system (and will never have publicly shown comments) |
24 | | - |
25 | | -## Why ? |
26 | | - |
27 | | -I know there are a lot of tools existing around to make this kind of thing, but |
28 | | -that was a way for me to approach CakePHP3 and finally make my own website. |
| 11 | +## Features in v0.0.1 |
| 12 | +First notable version with all base features working: |
| 13 | + |
| 14 | + - User management |
| 15 | + - Administration section |
| 16 | + - User section to |
| 17 | + - Manage albums (groups of _files_) |
| 18 | + - Manage files (images, text, video, sounds) |
| 19 | + - Manage notes (short texts) |
| 20 | + - Manage posts (articles) |
| 21 | + - Manage projects (a project can have related albums, files, notes and posts) |
| 22 | + - "Safe For Work" state for the above items |
| 23 | + - Tagging system |
| 24 | + - Content reporting |
| 25 | + - Comments (private only) |
| 26 | + - Internationalization support |
| 27 | + - Licenses support |
29 | 28 |
|
30 | 29 | ## Get started: |
31 | | -First, download or clone the repository. Then, run setup.sh and follow the instructions. This will download extra js files, some sources if you want them, call `composer install` and populate the db. |
32 | | - |
33 | | -## Future evolutions ? |
34 | | -You're welcome to use/reuse the code, fork, make pull requests... |
35 | | - |
36 | | -I don't know yet how the website will evolve, but it will. |
37 | 30 |
|
38 | | -**Translations** are welcome :) |
| 31 | +### Dependencies |
| 32 | + - A web server wich can serve PHP files |
| 33 | + - You will need the following PHP dependencies: |
| 34 | + - gd |
| 35 | + - intl |
| 36 | + - xml |
| 37 | + - mbstring |
| 38 | + - gd |
| 39 | + - A database server. The following have been tested |
| 40 | + - MySql was used during development |
| 41 | + - Sqlite is used for tests, so it should _work_ |
| 42 | + - [Composer](https://getcomposer.org/) |
| 43 | + |
| 44 | +For now there is no package for Composer. |
| 45 | + |
| 46 | +There are many ways to get started with this CMS, i'll present two of them: |
| 47 | + |
| 48 | +### The easy way: A virtual machine |
| 49 | +I call this method the _easy way_ as there is nothing |
| 50 | + |
| 51 | +To get started quickly if you have a good internet connection and some coffee to relax: |
| 52 | + |
| 53 | +#### Quick install |
| 54 | +For people who know how it works. |
| 55 | + |
| 56 | + - Download this [PuPHPet configuration](https://github.com/mtancoigne/cake3-puphpet-vm) for vagrant |
| 57 | + - Configure it if you want. |
| 58 | + - Create the `data/html` subfolder |
| 59 | + - Launch `vagrant up` |
| 60 | + - Delete `data/html/index.php` and download/clone this repository in `data/html/` |
| 61 | + - Login on the machine and head to `/var/www/html` |
| 62 | + - Run `./setup.sh` |
| 63 | + - Configure the db access with: |
| 64 | + ```php |
| 65 | + 'username' => 'root, |
| 66 | + 'password' => '123', |
| 67 | + 'database' => 'vagrant', |
| 68 | + ``` |
| 69 | + - Done. Access `https://192.168.6.200`. |
| 70 | + |
| 71 | +### Step by step: |
| 72 | + - Download and install [Virtualbox](http://www.virtualbox.org/) and Vagrant(https://www.vagrantup.com/) and check that Vagrant is in your PATH variable (accessible from everywhere in a console) by running `vagrant -v`. |
| 73 | + - Download the [box configuration](https://github.com/mtancoigne/cake3-puphpet-vm) created with PuPHPet(https://puphpet.com/) and extract it somewhere. |
| 74 | + - Edit the `puphet/config.yml` to fit your needs: |
| 75 | + - Change all occurrences of `my-cake3-project` by something else (`elabs` is a nice choice). You'll have to change it on every new project with this vm. |
| 76 | + - If your system is a 32bit OS, change lines 6 and 7 by `puphpet/ubuntu1604-i386` |
| 77 | + - Change the `private_network` (line 26) value to something else. |
| 78 | + - **Note:** The vm is configured to have 768Mb memory (line 31). You can lower it to 512 if you have issues. |
| 79 | + - Create a `data` folder, in wich you will create an `html` one. This folder will be shared with the virtual machine. It's your project base. |
| 80 | + - Open a console in the vm folder and run `vagrant up`. It will download the virtual machine image and configure it. Here comes the coffee time. |
| 81 | + - When vagrant finished, remove the `data/html/index.html` file that has been created. |
| 82 | + - Clone or download this repository in `data/html`. `index.php` should be directly under `html/`. |
| 83 | + - Login on the virtual machine: `vagrant ssh`. You're in a linux machine, so now, it's linux commands. |
| 84 | + - Go to the webserver root directory: `cd /var/www/html`. |
| 85 | + - Launch the setup: `./setup.sh` and follow the instructions. |
| 86 | + - _Do you want to keep the sources needed to build the css ? [Y/n]_: If you select no, Sass sources will be deleted. This step downloads some JS files. |
| 87 | + - _Do you want to install the development dependencies ? [Y/n]_: If you select no, composer won't download the dev. dependencies. This step runs `composer install`. |
| 88 | + - Database setup: from your OS, edit `data/html/config/app.php` and change from the line 232: |
| 89 | + ```php |
| 90 | + 'username' => 'root, |
| 91 | + 'password' => '123', |
| 92 | + 'database' => 'vagrant', |
| 93 | + ``` |
| 94 | + - When it's done, hit return. The tables will be created with a default admin. |
| 95 | + - Open a browser to `https://192.168.6.200` if you haven't changed the IP address. |
| 96 | + |
| 97 | +**Notes**: I had some trouble with : |
| 98 | + - `phpcbf` in the vm: it changes the file mode of the fixed files. |
| 99 | + - git in the vm: Don't use it. Every file is marked as changed. Use git from your host. |
| 100 | + |
| 101 | +### The not so hard way: Locally under a Linux system |
| 102 | + |
| 103 | + - Check if your server have the good requirements. |
| 104 | + - For the setup to work, you should have [Composer](https://getcomposer.org/) installed globally. |
| 105 | + - Download/clone this repository in a folder accessible by your webserver |
| 106 | + - Edit `.htaccess` and `webroot/.htaccess` to add a [rewriteBase](https://httpd.apache.org/docs/current/mod/mod_rewrite.html#RewriteBase) option if needed. |
| 107 | + - Launch the setup: `./setup.sh` and follow the instructions. |
| 108 | + - _Do you want to keep the sources needed to build the css ? [Y/n]_: If you select no, Sass sources will be deleted. This step downloads some JS files. |
| 109 | + - _Do you want to install the development dependencies ? [Y/n]_: If you select no, composer won't download the dev. dependencies. This step runs `composer install`. |
| 110 | + - Database setup: edit `data/html/config/app.php` and change from the line 232: |
| 111 | + ```php |
| 112 | + 'username' => 'root, |
| 113 | + 'password' => '123', |
| 114 | + 'database' => 'vagrant', |
| 115 | + ``` |
| 116 | + - When it's done, hit return. The tables will be created with a default admin. |
| 117 | + - Done. |
| 118 | + |
| 119 | +### The insane way: Install under Windows |
| 120 | + - Check if your server have the good requirements. |
| 121 | + - Download/clone this repository in a folder accessible by your webserver |
| 122 | + - Edit `.htaccess` and `webroot/.htaccess` to add a [rewriteBase](https://httpd.apache.org/docs/current/mod/mod_rewrite.html#RewriteBase) option if needed. |
| 123 | + - If you want all the SCSS dependencies to build your css: |
| 124 | + - Follow step by step the content of `Sources/Sass/setup.sh`. And do it manually. |
| 125 | + - Strings with $XXX are variables. Check the first lines of the script, they are defined here. They are used for folder references. |
| 126 | + - _wget xxx_ = download xxx |
| 127 | + - _cp xxx yyy_ = copy xxx to yyy |
| 128 | + - _mv xxx yyy_ = move xxx to yyy (also used to rename the files) |
| 129 | + - Launch `composer install` to install the dependencies. Use the `--no-dev` option to ignore development dependencies. |
| 130 | + - Once it's done, edit `config/app.php` for the db configuration (line 232): |
| 131 | + ```php |
| 132 | + 'username' => 'root, |
| 133 | + 'password' => '123', |
| 134 | + 'database' => 'vagrant', |
| 135 | + ``` |
| 136 | + - Create the tables and the default user: |
| 137 | + - `bin/cake migrations migrate` |
| 138 | + - `bin/cake migrations seed` |
| 139 | + - Done. |
| 140 | + |
| 141 | +I'm sorry for you, windows user, as there is no _easy_ way for now. |
| 142 | + |
| 143 | +## Update |
| 144 | +As there is no composer package for elabs now, all you can do is run the `update.sh` script from the virtual machine or your linux system. It will clean and re-download sass/js files and run `composer update`. |
| 145 | + |
| 146 | +Again, for Windows, sorry. |
| 147 | + |
| 148 | +## Configuration |
| 149 | + |
| 150 | +Some configuration can be made in the files in `config/` folder: |
| 151 | + - app.php : is a file with CakePHP configuration |
| 152 | + - site_config.php : basic configuration for the CMS |
| 153 | + |
| 154 | +## Testing |
| 155 | + |
| 156 | +You can run the PHPUnit tests if you have installed the dev dependencies: `composer phpunit`. |
| 157 | +You can run the CodeSniffer tests too: `composer phpcs`. |
| 158 | +To automatically fix some of the CodeSniffer errors you can run `composer phpcbf`. But it may change the file mode too (orininally `644` on all files except the dirs: `bin/`, `log/`, `tmp/` and `vendor/bin`). |
| 159 | + |
| 160 | +## How to contribute |
| 161 | + |
| 162 | +### New ideas |
| 163 | +Ideas are welcome. Just open an issue to describe it. |
| 164 | + |
| 165 | +### Translations |
| 166 | +Translations of the cms are welcome. The translation system is the same as [CakePHP](https://book.cakephp.org/3.0/en/core-libraries/internationalization-and-localization.html) and located in `src/Locales`. |
| 167 | + |
| 168 | +All the files in this folder are extracted from the source files using `bin/cake i18n extract`: |
| 169 | + - Message from the core are extracted (file `cake.pot`) |
| 170 | + - Domain strings are **not** merged (other files) |
| 171 | + |
| 172 | +If you want to start a new translation: |
| 173 | + - Create a folder in `src/Locale` with the language name (i.e.: _fr_FR_) |
| 174 | + - Copy the `.pot` files in it. |
| 175 | + - Change the extension to `.po`. |
| 176 | + - Edit the translations with your preferred editor ([Virtaal](http://virtaal.translatehouse.org/) and [PoEdit](http://www.poedit.net/) are my choices). |
| 177 | + - Commit your changes with all new `.mo` files generated by the editor. |
| 178 | + |
| 179 | +### Design improvements |
| 180 | +Well... Design is not really my cup of tea. For now the website is not responsive (at least not _totally_). If you want to do something about that, it uses [Twitter Bootstrap v3.x](http://getbootstrap.com/), [BootFlat](https://bootflat.github.io/), [Font Awesome](http://fontawesome.io/) icons, [Bootstrap Tagsinput](http://bootstrap-tagsinput.github.io/), [Codemirror](http://codemirror.net/) and [Prism](http://prismjs.com/). |
| 181 | + |
| 182 | +#### CSS: Created with SCSS |
| 183 | +All the CSS is generated from custom scss files located in `Sources/Sass/`. The entry point is `style.scss`. No other files should be generated if you want to modify the core CSS. But if you want to create other CSS files, no problem, explain it. |
| 184 | + |
| 185 | +I usually use [Koala](http://koala-app.com/) to generate the CSS and there is a configuration file for it; all you have to do is to drag'n'drop the `Sources/Sass` folder in Koala. (**Notes:** Sometimes, Koala will tell you the build failed, but as long as there is no error message about this, it didn't. And sometimes, Koala will not build anything on file change, so you have to manually do it.) |
| 186 | + |
| 187 | +#### Templates |
| 188 | +All the templates are located in `src/Template`. For the majority of the folders, they represent a controller, except for the following (If you're familiar with CakePHP, you'll have no problem to understand): |
| 189 | + |
| 190 | +```text |
| 191 | +src/Template/ |
| 192 | +│ |
| 193 | +│ [ CakePHP Prefixes: ] |
| 194 | +│ |
| 195 | +├── Admin/ Views for the admin workspace |
| 196 | +│ └── <Controller>/ Views for admin/<controller>/<action> views |
| 197 | +│ └── .ctp files |
| 198 | +├── User/ Views for the user workspace |
| 199 | +│ └── <Controller>/ Views for user/<controller>/xxx views |
| 200 | +│ └── .ctp files |
| 201 | +│ |
| 202 | +│ [ Other folders: ] |
| 203 | +│ |
| 204 | +├── Cell/ Views for cells (special elements with their own controller-like logic) |
| 205 | +│ └── <Cell>/ |
| 206 | +│ └── .ctp files Views for the cell |
| 207 | +├── Element/ Small chunks of templates, included in other views |
| 208 | +│ ├── Flash/ Flash messages |
| 209 | +│ ├── layout/ Layout elements (menus, blocks that are not controller/action specific) |
| 210 | +│ ├── layouts/ Specific layouts (as a standard form, a standard index, ...) |
| 211 | +│ └── ...Other dirs/ Other elements related to controllers |
| 212 | +├── Email/ Email templates |
| 213 | +├── Error/ Error pages templates |
| 214 | +├── Layout/ Layouts for the public, user and admin workspaces |
| 215 | +├── Plugin/ Views to override plugins default views |
| 216 | +│ |
| 217 | +│ [ Other folders: ] |
| 218 | +│ |
| 219 | +└── <Controller>/ Views for the public workspace |
| 220 | + └── .ctp files |
| 221 | +``` |
| 222 | + |
| 223 | +For basic informations about the CakePHP templates, you should look in the [CakePHP Cookbook](https://book.cakephp.org/3.0/en/views.html). |
| 224 | + |
| 225 | +### Other |
| 226 | + |
| 227 | +All notable changes to this project will be documented in `CHANGELOG.md` : |
| 228 | + - The format is based on [Keep a Changelog](http://keepachangelog.com/) |
| 229 | + - This project adheres to [Semantic Versioning](http://semver.org/). |
| 230 | + |
| 231 | +You can check the issues too. |
| 232 | + |
| 233 | +## License |
| 234 | +The code is licensed under the MIT license except for files that have their own licenses. |
39 | 235 |
|
40 | | -**Design improvements** are really welcome |
41 | | - |
42 | | -**New ideas are welcome** |
| 236 | +## Why ? |
43 | 237 |
|
44 | | -**If you want to help**, check the TODO.md, and look at all the amount of work there is... |
| 238 | +This tool was created for the pleasure to make [experiments labs](https://experimentslabs.com) and use CakePHP. |
0 commit comments