Skip to content

Commit

Permalink
Readme update for the v0.7 version (#226)
Browse files Browse the repository at this point in the history 
* Adding note about default URL

* Explaining suggested admin name

* Linking to migrate DB wiki page

* Updating project file description

* Adding note about Chisel classes

* Default dev task also prefixes CSS

* Changing project development structure

* Updating WP development section

* Updating TOC

* Small fixes to the documentation
  • Loading branch information
@luboskmetko
luboskmetko authored Jul 21, 2017
1 parent a0c714d commit 38f9564
Showing 1 changed file with 95 additions and 38 deletions.
133 changes: 95 additions & 38 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -34,16 +34,20 @@
- [WordPress projects](#wordpress-projects-2)
- [Local WordPress configuration](#local-wordpress-configuration)
- [Moving src folder to theme folder](#moving-src-folder-to-theme-folder)
- [Project development](#project-development)
- [Front-end projects](#front-end-projects-3)
- [1. Add pages](#1-add-pages)
- [2. Develop](#2-develop)
- [3. Caveats](#3-caveats)
- [WordPress projects](#wordpress-projects-3)
- [1. Add pages](#1-add-pages-1)
- [2. Develop](#2-develop-1)
- [3. Front-end first](#3-front-end-first)
- [4. Develop with Timber](#4-develop-with-timber)
- [Front-end development](#front-end-development)
- [Adding pages](#adding-pages)
- [Development tasks](#development-tasks)
- [Caveats](#caveats)
- [Using jQuery plugins with Browserify](#using-jquery-plugins-with-browserify)
- [Library not available through npm](#library-not-available-through-npm)
- [WordPress development](#wordpress-development)
- [Adding pages](#adding-pages-1)
- [Development tasks](#development-tasks-1)
- [Creating front-end](#creating-front-end)
- [Developing theme functionality](#developing-theme-functionality)
- [Built-in extensions for Timber](#built-in-extensions-for-timber)
- [Good practices](#good-practices)
- [Security](#security)
- [Tutorials](#tutorials)
- [License](#license)

Expand Down Expand Up @@ -153,8 +157,8 @@ Insert project name (you can use the default one based on the working directory
Setup your WordPress as follows:

- *Enter title for the new site*: title of your WordPress website
- *Enter URL*: the URL at which your WordPress project run, leave it to the default value if you are using Wildcard virtual hosts
- *Enter admin user*: WordPress admin user
- *Enter URL*: the URL at which your WordPress project runs, currently Chisel only works with the default value
- *Enter admin user*: WordPress admin user, a different name than `admin` is suggested to increase security
- *Enter admin password*: WordPress admin user password
- *Enter admin email*:
- *Where do you want to place the 'src' folder*: position of the src folder with styles, scripts and assets - either the root folder or theme folder
Expand Down Expand Up @@ -190,7 +194,7 @@ If you are joining development of an existing WordPress project which was alread
2. Create database
3. Run `yo chisel:wp-config`, it will create _wp-config-local.php_ and generate _dev-vhost.conf_ (if you need it)
4. Run `npm install` or `yarn` and `npm run build`
5. Import DB dump or enable _Migrate DB_ plugin and use it to import database and files
5. Import DB dump or enable _WP Sync DB_ plugin and use it to import database and files. Check out the wiki page explaining how you case [use WP Sync DB plugin to migrate database](https://github.com/xfiveco/generator-chisel/wiki/Setting-up-WordPress-projects-at-Getfives).

## Project structure
Before starting actual development get familiar with the project structure generated by Chisel.
Expand Down Expand Up @@ -220,14 +224,20 @@ The file structure in front-end projects looks like this:
- `layouts/page.twig` - a template from which the other pages are generated
- `*.twig` - separate twig page templates
- **index** - images and styles for the project index
- `index.html` - project index with project pages listed
- `package.json` - npm packages dependencies
- `.yo-rc.json` - Yeoman generator configuration file
- `.babelrc` - Babel configuration file
- `.editorconfig` - [EditorConfig](http://editorconfig.org/) configuration file to achieve consistent coding style
- `.eslintignore` - [ESLint](http://eslint.org/) ignore file
- `.eslintrc.yml` - [ESLint](http://eslint.org/) configuration file to achieve consistent JavaScript coding style (you can update it to your preference)
- `.gitattributes` - [Git](http://git-scm.com/) configuration file to force Unix line ending in text files
- `.gitignore` - default Git ignore files and folders
- `.eslintrc.yml` - [ESLint](http://eslint.org/) configuration file to achieve consistent JavaScript coding style (you can update it to your preference)
- `.htmlhintrc` - [HTMLHint](https://github.com/yaniswang/HTMLHint) configuration file
- `.stylelintignore` - [stylelint](http://stylelint.io/) ignore file
- `.stylintrc.yml` - [stylelint](http://stylelint.io/) configuration file to achieve consistent CSS coding style (you can update it to your preference)
- `.yo-rc.json` - Yeoman generator configuration file
- `index.html` - project index with project pages listed
- `gulpfile.js` - Gulp configuration file
- `package.json` - project metadata and dependencies
- `README.md` - project readme, you can use it for the project documentation

On a typical project, you will work in `src` folder and check your work in `dist` folder so you don’t have to touch other files.

Expand All @@ -244,6 +254,7 @@ File structure in WordPress projects is almost identical to the front-end projec
- **themes**
- **your-theme**
- **dist** - dist folder where CSS, JS and assets files are built
- **Chisel** - various classes used to extend or add new functionality to your theme
- **templates** - Twig templates
- `index.php` - Chisel starter theme files
- `functions.php`
Expand All @@ -265,11 +276,9 @@ If you prefer having the `src` folder in your theme folder, choose this option w
1. Move the `src` folder to the theme folder - `wp/wp-content/themes/your-theme`
2. Change `chisel.src.base` property on line 13 in `package.json` to `wp/wp-content/themes/your-theme/src`

## Project development

### Front-end projects
## Front-end development

#### 1. Add pages
### Adding pages
Once your project is setup, you need to add pages you will be working on to it. From the command line type:

```bash
Expand All @@ -288,7 +297,7 @@ You can also create multiple pages at once by separating page names with space:
yo chisel:page "Home" "About Us" "Contact Us" "News"
```

#### 2. Develop
### Development tasks
When you have the basic setup done, you can start development. To re-compile Twig, SCSS and JavaScript files in real time you can use default task. Type

```bash
Expand Down Expand Up @@ -319,14 +328,14 @@ npm run build

When `npm run build` is run, first the `dist` folder is cleaned and then build tasks are run in particular order:

1. `styles-build` builds prefixed and minified styles and creates a stylesheet revision by appending content hash to the filename. Then it creates `rev-manifest.json` with original and revisioned file names
1. `styles-build` builds minified styles and creates a stylesheet revision by appending content hash to the filename. Then it creates `rev-manifest.json` with original and revisioned file names
2. `lint` runs EsLint
3. `scripts-build` runs Browserify bundler and creates `bundle.js` revision by appending content hash to the filename. Then it updates existing `rev-manifest.json` with the original and revisioned filename.
4. Finally, `templates-build` reads the newly created `rev-manifest.json` and builds HTML files from Twig templates, while linking revisioned files using the `revisionedPath` function.

#### 3. Caveats
### Caveats

**Using jQuery plugins with Browserify**
#### Using jQuery plugins with Browserify

One of the known issues we encounter while front-end development is usage of jQuery plugins like `flexslider` alongside Browserify module bundler.

Expand All @@ -347,20 +356,20 @@ The usual solution to that problem can be treated this way:
require('flexslider'); // Usually they bind to global jQuery object
```

**Library not available through npm**
#### Library not available through npm

Use [`browserify-shim`](https://github.com/thlorenz/browserify-shim#you-will-always).

### WordPress projects
## WordPress development

#### 1. Add pages
### Adding pages

You can use `yo chisel:page` command to add pages to your WordPress project in the same way as you do in front-end projects.

- Twig template is automatically created in `wp/wp-content/themes/[your-theme]/templates/page-{page-slug}.twig`
- Page is accessible at `project-name.dev/{page-slug}`

#### 2. Develop
### Development tasks
To re-compile SCSS and JavaScript files in real time you can use default task. Type:

```bash
Expand All @@ -373,30 +382,44 @@ Additionally, development server will be started and Browsersync scripts injecte

Depending on where you are looking at your project, different version of styles and scripts are used:

- `localhost:3000` - unminified and non-prefixed CSS
- `project-name.dev` - revisioned CSS and JS files (minified and prefixed)
- `localhost:3000` - unminified CSS
- `project-name.dev` - revisioned and minified CSS and JS files

To create new revisions of styles and scripts using [gulp-rev](https://github.com/sindresorhus/gulp-rev), use the build task:

``` bash
npm run build
```

During development you should occasionally build your styles and scripts to see how the site works with minified and prefixed CSS.

#### 3. Front-end first
### Creating front-end
Chisel allows easy front-end development prior to WordPress development. Suppose you have 3 pages to develop front-end for `Team`, `Team Member`, `Contact`.

1. Add these pages from the command line like described in the previous sections
2. Now your pages are accessible under `project-name.dev/team/`, `project-name.dev/team-member/` and `project-name.dev/contact/`.
3. Start adding HTML to relevant Twig templates. Where applicable try to use [Twig syntax](http://twig.sensiolabs.org/doc/templates.html)
4. Create styles in `src/styles`.
5. Once you are done with front-end development a WordPress developer will add required functionality to the templates
5. Once you are done with front-end development a WordPress developer will add required functionality

### Developing theme functionality

Inside the theme there is `Chisel` folder with various classes which extend WordPress or add theme functionality. It's recommended to follow the existing structure and update these classes or add new classes here instead of adding functionality directly to `functions.php`.

Classes you can work with:

- `\Chisel\WpExtensions` - use this class to extend Wordpress (register post types, taxonomies, etc.)
- `\Chisel\Security` - default security settings for Chisel, you can change or extend security settings here.

Classes you usually don't have to touch:

- `\Chisel\Site` - this class extends `\Timber\Site` class and is used to setup whole site
- `\Chisel\Post` - this class extends `\Timber\Post` class
- `\Chisel\TwigExtensions` - this class is used to extend Twig

If you want to add new custom class, you can copy and adjust one of the existing classes. Then load your class in `functions.php`

#### 4. Develop with Timber
Refer to [Timber](http://upstatement.com/timber/) documentation if you are new to WordPress development with Timber.

##### Chisel built-in extensions for Timber
#### Built-in extensions for Timber

* `ChiselPost`: you can use this function if you want to create a post class inside Twig file. As an argument you can pass post id, post object, or an array consisting of field values for the post. When creating fake post by passing an array of fields as an argument you can use `_fields` key to set post meta values loaded via `get_field` method to simulate for example ACF values. You can also load existing post that will have fake fields by passing post's id with `ID` key:

Expand Down Expand Up @@ -443,7 +466,7 @@ Refer to [Timber](http://upstatement.com/timber/) documentation if you are new t
<article class="c-some-post c-some-post--red c-some-post--type-post"></article>
```

##### Good practices
#### Good practices

* Try to always use `get_field` method of `Chisel\Post` instead of direct call to the field:

Expand All @@ -457,6 +480,40 @@ Refer to [Timber](http://upstatement.com/timber/) documentation if you are new t
{{ post.field_name }}
```

#### Security

In addition to default security settings you can also:

* Protect WP includes

Add `.htaccess` to the `wp-includes` folder with the following content:

```
<FilesMatch "\.(?i:php)$">
Order allow,deny
Deny from all
</FilesMatch>
<Files wp-tinymce.php>
Allow from all
</Files>
<Files ms-files.php>
Allow from all
</Files>
```

* Protect uploads folder

Add `.htaccess` to the `wp-content/uploads` folder with the following content:

```
<FilesMatch "\.(?i:php)$">
Order allow,deny
Deny from all
</FilesMatch>
```

Note: this can break some plugins

## Tutorials
- [Craft perfect websites with Chisel](https://www.xfive.co/blog/craft-perfect-websites-chisel/)
- [An MVC-like WordPress Development with ACF and Timber](https://www.xfive.co/blog/mvc-like-wordpress-development-acf-timber/)
Expand Down

0 comments on commit 38f9564

Please sign in to comment.