Raccoon WordPress starter
Raccoon is a WordPress starter theme based on Composer & NPM & Babel (ES 2015 preset) & Gulp & Knacss., (*1)
, (*2)
Summary
Requirements
For its development, Raccoon requires:
- PHP >= 5.6
- Composer
- Node.js with npm for package management
- WordPress >= 4.4, (*3)
Installation
It's pretty simple: you just have to clone the repository and run composer install
to start all required jobs., (*4)
git clone https://github.com/hiwelo/raccoon.git
composer install
How to work with a raccoon
Before to work
Before any modification, please run:, (*5)
composer work
With this command you verify that your repository is up to date and it starts all
watch jobs., (*6)
Vendor update
Regularly, don't forget to update all dependencies (composer & npm) with:, (*7)
composer update
Before to commit
After any modification and before you commit anything, I strongly advice to run:, (*8)
composer test
And if there's no errors, you can commit your modifications., (*9)
If there's some errors and you absolutely want to commit, you've got to run this command
to avoid pre-commit verifications:, (*10)
git commit --no-verify
Documentation
If you want to parse all PHP files to generate the documentation, please run:, (*11)
composer documentation
The generated documentation is available in the ./docs/api/ folder., (*12)
How to code with a raccoon
OOP PHP Class
Raccoon is an OOP-based WordPress template.
All Raccoon's classes are placed within the namespace Hwlo\Raccoon\ and you can find them in the ./lib directory., (*13)
Any custom class that you can create should be placed in a specific namespace.
For example, you can use a namespace like Hwlo\Raccoon\Custom\., (*14)
When you create a new namespace, you have to add it in the composer.json file, in the autoload section.
I strongly advice to use a PSR-4 namespace., (*15)
For example, if you want to register a custom namespace like Hwlo\Raccoon\Custom\, you have to write custom classes in ./custom-lib/ and update composer.json like that:, (*16)
{
"autoload": {
"psr-4": {
"Hwlo\\Raccoon\\": "./lib/",
"Hwlo\\Raccoon\\Custom\\": "./custom-lib/"
}
}
}
For each new created class, you may need to regenerate the ./vendor/autoload.php file. For this operation, please run:, (*17)
composer autoload
When a raccoon work, he likes to make sure his work can be understood by all. So he writes scripts which are conform to standards used by the PHP community., (*18)
Raccoon uses PSR-2 Coding Standards for its tests.
Each modification must make a successful PSR-2 syntax check to be committed.
So, Raccoon have got just a little modification : scripts documentation is required by the ruleset.xml for PHP CS validation., (*19)
You can run at any time a test control on all PHP & JavaScript files with:, (*20)
composer test
Some errors on PHP files can be automatically fixed by phpcbf. To do so, run:, (*21)
composer phpcbf
So don't forget: to make Raccoon happy, document your _f**king_ code! :D, (*22)
How a raccoon can help you with WordPress
Configuration manifest
To avoid multiple initialization functions, Raccoon uses a JSON configuration file: manifest.json.
In this file you can set all features proposed by WordPress to its themes., (*23)
WordPress theme namespace
With Raccoon, you can define a specific namespace for this theme.
This namespace will be mainly used by string translation methods like __() or _e() or _x() or _n()., (*24)
To define a specific namespace, you have to update manifest.json like that:, (*25)
{
"namespace": "raccoon"
}
If empty or undefined, the default namespace will be raccoon., (*26)
Theme support
With Raccoon, you can easily set up all theme features with the manifest.json file., (*27)
All features described in the WordPress documentation can be registered with or without arguments.
Considering the JSON format, a feature requires a least a boolean., (*28)
Here is the kind of statements that you can set up in the manifest.json file:, (*29)
{
"theme-support": {
"title-tag": true,
"post-thumbnail": true,
"automatic-feed-links": true,
"post-formats": [
"link",
"quote",
"audio",
"video"
],
"html5": [
"caption",
"comment-form",
"comment-list",
"gallery",
"search-form"
]
}
}
Theme features
Raccoon has a feature which allows you to disable some Wordpress features like widgets or comments.
In the manifest.json file you can easily (de-)activate these features with:, (*30)
{
"theme-features": {
"comments": false,
"widget": false
}
}
Navigations
With Raccoon, you can easily set up navigations with the manifest.json file., (*31)
Each navigation must have a location and a readable description like in the WordPress documentation., (*32)
For example if you want to register two navigations (a primary navigation and a list of social networks), you have to update manifest.json like that:, (*33)
{
"navigations": {
"primary": "Main navigation",
"social": "Social links"
}
}
Post Types
Create a custom post type
With Raccoon, you can easily set up custom post types with the manifest.json file., (*34)
Each custom post type must have a title and an array of arguments. All arguments described in the WordPress documentation can be used in the manifest.json file., (*35)
For example if you want to register the same post type as the WordPress documentation, you have to update manifest.json like that:, (*36)
{
"post-types": {
"books": {
"labels": {
"name": "Books",
"singular_name": "Book",
"menu_name": "Books",
"name_admin_bar": "Book",
"add_new": "Add New",
"add_new_item": "Add New Book",
"new_item": "New Book",
"edit_item": "Edit Book",
"view_item": "View Book",
"all_items": "All Books",
"search_items": "Search Books",
"parent_item_colon": "Parent Books:",
"not_found": "No books found.",
"not_found_in_trash": "No books found in Trash."
},
"description": "Description.",
"public": "true",
"publicly_queryable": "true",
"query_var": "true",
"rewrite": {
"slug": "book"
},
"menu_icon": "dashicons-editor-paragraph",
"supports": [
"title",
"editor",
"author",
"thumbnail",
"excerpt",
"custom-fields",
"revisions",
"post-formats"
]
}
}
}
Good to know, you can't declare in manifest.json a custom post type named remove., (*37)
Post type unregistration
With Raccoon, you can alse easily unregister an existing post type with the manifest.json file., (*38)
Each existing post type, event post or pages can be unregister with this manifest.json functionality.
You just have to add in your manifest.json:, (*39)
{
"post-types": {
"remove": ["post"]
}
}
For example if you want to register the same post type as the WordPress documentation, you have to update manifest.json like that:, (*40)
Post Status
With Raccoon, you can easily set up custom post status with the manifest.json file.
Each custom post status will be automatically added into each admin panel page inside post status selectboxes., (*41)
Each custom post status can have all arguments described for the WordPress register_post_status() method., (*42)
For example, if you want to register a new custom post status, you have to update manifest.json like that:, (*43)
{
"post-status": {
"archive": {
"label": "Archive",
"exclude_from_search": false,
"public": false,
"internal": false,
"protected": true,
"private": false,
"publicly_queryable": false,
"show_in_admin_all_list": true,
"show_in_admin_status_list": true,
"_builtin": true,
"label_count": [
"Archive <span class=\"count\">(%s)</span>",
"Archives <span class=\"count\">(%s)</span>"
]
}
}
}
Good to know, you can't declare in manifest.json a custom post status named remove., (*44)
With Raccoon, you can easily set up sidebars with the manifest.json file., (*45)
Each sidebar must have an array of arguments. All arguments described in the WordPress documentation can be used in the manifest.json file., (*46)
For example if you want to register the same sidebar as the WordPress documentation, you have to update manifest.json like that:, (*47)
{
"sidebars": [
{
"name": "Sidebar name",
"id": "unique-sidebar-id",
"description": "Description.",
"class": "sidebarClassName",
"before_widget": "<li id=\"%1$s\" class=\"widget %2$s\">",
"after_widget": "</li>",
"before_title": "<h2 class=\"widget__title\">",
"after_title": "</h2>"
}
]
}
With Raccoon, you can easily set up widgets with the manifest.json file., (*48)
Each widget must consist of a specific OOP PHP Class like described in the WordPress documentation.
So, for a widget registration you just have to add the widget classname in the manifest.json, with its complete namespace like that:, (*49)
{
"widgets": [
"Hwlo\\Raccoon\\WidgetExample"
]
}
Third-part features
Raccoon loves Bedrock
Bedrock is a WordPress boilerplate which create a better projet structure mainly with a new wp-content/ folder renamed app/.
Bedrock use Composer and environments variables., (*50)
By example, Raccoon can use environments variables from Bedrocks to know the environment status (development, production, staging) and manage which debug informations has to be returned by the theme.
If you don't use Bedrock, you can manually set environment status in the manifest.json file like this :, (*51)
{
"environment-status": "development"
}
Wallogit.com
