Charcoal CMS

The CMS Charcoal Module (Content Management System). Provides basic objects to build a website. Notably, Section (or page), News, Event and Faq as well as to ather user data, notably ContactInquiry.

This module is heavily dependant on charcoal-object (and therefore charcoal-core) which provides the base Content class the CMS objects are dependant on, as well as many trait / interface behaviors.

How to install

The preferred (and only supported) way of installing charcoal-cms is with composer:

★ composer require locomotivemtl/charcoal-cms

For a complete, ready-to-use project, start from the charcoal project boilerplate:

★ composer create-project locomotivemtl/charcoal-project-boilerplate:@dev --prefer-source

Dependencies

• PHP 5.6+
  • PHP 7 is recommended for security and performance reasons.
• locomotivemtl/charcoal-attachment
  • Content blocks are provided with attachments.
• locomotivemtl/charcoal-core
  • Core charcoal models and storage class.
  • Provides base Model, which depends on Storable and Describable.
• locomotivemtl/charcoal-object
  • CMS objects are based on \Charcoal\Object\Content.
• locomotivemtl/charcoal-translator
  • Localization is provided by symfony translator (charcoal).

Recommended dependencies

• locomotivemtl/charcoal-admin
  • The backend (admin panel).

Objects

• Core objects
  • Section
  • Tag
• CMS objects
  • Event
  • FAQ
  • News

Core objects

• Section
• Tag

Section object

A section, in Charcoal, is a reachable page on the website, as part of the full hierarchical site map. They can be displayed in menus or breadcrumbs and be reached with a unique URL (routable).

Types of sections:

• blocks
  • Blocks sections define their content as a structured map of blocks.
• content
  • Content sections define their content in a single, simple HTML property.
• empty
  • Empty sections are linked to a template but do not require any custom content.
• external
  • External sections are simply a redirect to an external (or internal) URL.

All section types, except external, make use of a Template object to be rendered. Typically, a charcoal view make sure of linking the template (by default, mustache

Sections are standard Charcoal Model, meaning they are describable with a Metadata object (which define a map of properties) and storable with a Source object.

Base section properties:

Interface	Name	L10n	Type	Description
Section	section_type		choice
Section	title	✔	string
Section	subtitle	✔	html
Section	summary	✔	html
Section	image	✔	image
Section	template_ident		string
Section	template_options		structure
Section	content	✔	html
Section	attachments	✔	multi-object
Section	external_url	✔	url	For external URLs. Note that all content-related properties are ignored if this property is set.
Content	id		id	The model's key.
Content	active		bool	Inactive events should not appear in public API / frontend.
Content	position		int	Default order property.
Authorable	created_by		string	Admin user.
Authorable	last_modified_by		string	Admin user.
Authorable	required_acl_permissions	array	To do...
Timestampable	created		date-time
Timestampable	last_modified		date-time
Hierarchical	master		object	SectionInterface.
Routable	slug	✔	string	Permalink. Auto-generated from title.

Interfaces

From model:

• Describable: The objects can be defined by Metadata.
• Storable: Objects have unique IDs and can be stored in storage / database.

From content:

• Content: A "managed" charcoal model (describable with metadata / storable).
• Authorable: Creation and modification user (admin) are kept in the storage.
• Revisionable: Copy of changes will be kept upon each object update in the storage.
• Timestampable: Creation and modification time are kept into the storage.

From charcoal-object

• Hierarchicale: The objects can be stacked hierarchically.
• Publishable: Objects have publish status, date and expiry. Allows moderation.
• Routable: Objects are reachable through a URL.

From charcoal-cms:

• Metatag: The objects have meta-information for SEO purpose.
• Searchable: Extra keywords can be used to help search engine.
• Templateable: The objects can be rendered with a template / controller / config combo.

Extending the section object

The \Charcoal\Cms\Section\* objects are final. To extend, use the \Charcoal\Cms\AbstractSection base object instead, to make sure no metadata conflicts arise.

Tag object

Tag objects link any objects together by providing an extra taxonomy layer. Tags may also be used to enhance internal search engines.

CMS objects

• Event
• FAQ
• News

Event object

Charcoal Event is a specialized content object to describe an event, which typically happens at a given date in a certain location.

Base events properties:

Interface	Name	L10n	Type	Description
Event	title	✔	string
Event	subtitle	✔	html
Event	summary	✔	html
Event	content	✔	html
Event	image	✔	image
Event	start_date		date-time
Event	end_date		date-time
Event	info_url	✔	image
Content	id		id	The model's key.
Content	active		bool	Inactive events should not appear in public API / frontend.
Content	position		int	Default order property.
Authorable	created_by		string	Admin user.
Authorable	last_modified_by		string	Admin user.
Authorable	required_acl_permissions	array	To do...
Timestampable	created		date-time
Timestampable	last_modified		date-time
Categorizable	category	✔	object	EventCategory, or custom.
Publishable	publishDate		date-time
Publishable	expiryDate		date-time
Publishable	publishStatus		string	draft, pending, or published.
Routable	slug	✔	string	Permalink. Auto-generated from title.
Metatag	meta_title	✔	string
Metatag	meta_description	✔	string
Metatag	meta_image	✔	image
Metatag	meta_author	✔	string
Templateable	controller_ident		string
Templateable	template_ident		string
Templateable	template_options		structure

Interfaces

From model:

• Describable: The objects can be defined by Metadata.
• Storable: Objects have unique IDs and can be stored in storage / database.

From content:

• Content: A "managed" charcoal model (describable with metadata / storable).
• Authorable: Creation and modification user (admin) are kept in the storage.
• Revisionable: Copy of changes will be kept upon each object update in the storage.
• Timestampable: Creation and modification time are kept into the storage.

From charcoal-object:

• Categorizable: The objects can be put into a category.
• Publishable: Objects have publish status, date and expiry. Allows moderation.
• Routable: Objects are reachable through a URL.

From charcoal-cms:

• Metatag: The objects have meta-information for SEO purpose.
• Searchable: Extra keywords can be used to help search engine.
• Templateable: The objects can be rendered with a template / controller / config combo.

Extending the event object

The \Charcoal\Cms\Event object is final. To extend, use the \Charcoal\Cms\AbstractEvent base object instead, to make sure no metadata conflicts arise.

Event categories

Event category objects are simple charcoal/object/category used to group / categorize events. The default type is Charcoal\Cms\EventCategory.

Events implement the Categorizable interface, from charcoal-object.

FAQ object

FAQ objects are a special content type that is split in a "question" / "answer" format.

FAQ categories

FAQ category objects are simple charcoal/object/category used to group / categorize FAQ objects. The default type is Charcoal\Cms\FaqCategory.

FAQs implement the Categorizable interface, from charcoal-object.

News object

News object are a special content type that with a specific news date.

Base news properties:

Interface	Name	L10n	Type	Description
News	title	✔	string
News	subtitle	✔	html
News	summary	✔	html
News	content	✔	html
News	image	✔	image
News	news_date		date-time
News	info_url	✔	image
Content	id		id	The model's key.
Content	active		bool	Inactive news should not appear in public API / frontend.
Content	position		int	Default order property.
Authorable	created_by		string	Admin user.
Authorable	last_modified_by		string	Admin user.
Authorable	required_acl_permissions	array	To do...
Timestampable	created		date-time
Timestampable	last_modified		date-time
Categorizable	category	✔	object	NewsCategory, or custom.
Publishable	publishDate		date-time
Publishable	expiryDate		date-time
Publishable	publishStatus		string	draft, pending, or published.
Routable	slug	✔	string	Permalink. Auto-generated from title.
Metatag	meta_title	✔	string
Metatag	meta_description	✔	string
Metatag	meta_image	✔	image
Metatag	meta_author	✔	string
Templateable	controller_ident		string
Templateable	template_ident		string
Templateable	template_options		structure

Interfaces

From model:

• Describable: The objects can be defined by Metadata.
• Storable: Objects have unique IDs and can be stored in storage / database.

From content:

• Content: A "managed" charcoal model (describable with metadata / storable).
• Authorable: Creation and modification user (admin) are kept in the storage.
• Revisionable: Copy of changes will be kept upon each object update in the storage.
• Timestampable: Creation and modification time are kept into the storage.

From charcoal-object:

• Categorizable: The objects can be put into a category.
• Publishable: Objects have publish status, date and expiry. Allows moderation.
• Routable: Objects are reachable through a URL.

From charcoal-cms:

• Metatag: The objects have meta-information for SEO purpose.
• Searchable: Extra keywords can be used to help search engine.
• Templateable: The objects can be rendered with a template / controller / config combo.

Extending the news object

The \Charcoal\Cms\News object is final. To extend, use the \Charcoal\Cms\AbstractNews base object instead, to make sure no metadata conflicts arise.

News categories

News category objects are simple charcoal/object/category used to group / categorize events. The default type is Charcoal\Cms\NewsCategory.

News implement the Categorizable interface, from charcoal-object.

Development

To install the development environment:

$ composer install --prefer-source

API documentation

• The auto-generated phpDocumentor API documentation is available at https://locomotivemtl.github.io/charcoal-cms/docs/master/
• The auto-generated apigen API documentation is available at https://codedoc.pub/locomotivemtl/charcoal-cms/master/

Development dependencies

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

Continuous Integration

Service	Badge	Description
Travis		Runs code sniff check and unit tests. Auto-generates API documentation.
Scrutinizer		Code quality checker. Also validates API documentation quality.
Coveralls		Unit Tests code coverage.
Sensiolabs		Another code quality checker, focused on PHP.

Coding Style

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

• PSR-1
• PSR-2
• PSR-4, autoloading is therefore provided by Composer.
• phpDocumentor comments.
• Read the phpcs.xml file for all the details on code style.

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

Authors

• Locomotive

License

Charcoal is licensed under the MIT license. See LICENSE for details.