Commit a2ef8519 authored by Rosemary Mann's avatar Rosemary Mann

Issue #14: Add new content feature documentation.

parent 8c085b49
......@@ -56,6 +56,7 @@ Drutopia's main documentation is organized into a few sections:
.. _platform-cooperatives:
# How to produce a new content feature
These instructions will use the example of a yet to be built “resource” feature.
## Naming conventions:
* See also the technical guide section on [naming and namespaces](
* The content type will be called: `resource` (singular)
* Any field that is specific to this feature will be prefixed with `resource_`, so for example a reference field to a vocabulary specific to resource might be called `field_resource_type`.
* More naming conventions will be discussed in the relevant sections such as Pathauto, Views and Creating your feature.
## Fields: what fields are re-used, what are required
* Many of the core field are reused between features.
* These include
* `field_summary` (required)
* `field_body_paragraph`
* `field_image`
* `field_tags`
* These fields should be added and configured as needed. Because we are using paragraphs for our main body, a required summary field is necessary for many display purposes and should always be included.
* When adding a new field, first determine if it will be specific to your feature or is perhaps a more generic field. If you think it is more generic, talk to a tech lead to consult. If it is specific, give it a name that includes the content type name, e.g. `field_resource_type`.
* When adding reused fields, if you have queries about any configuration, look at another content type feature for guidance.
### Paragraph types:
* Drutopia features use paragraphs as the main body field (`field_body_paragraph`). For each feature you can set what paragraph types should be included. All `field_body_paragraph` fields should have at least text, image and file paragraphs. Other paragraph types can be included if they seem useful to your content type.
* If you think you need a new paragraph type, discuss with a tech lead.
### Metatag
* The metatag field (`field_meta_tags`) should be included in every content type feature.
### Form display
* The traditional Body field (`field_body`) has been maintained for migration purposes. It should always be hidden on the form display.
* Refer to another content feature such as `drutopia_articlee` as a model for the general ordering and setting guidelines.
* For the Body paragraph field, ensure the following settings are set:
* Edit mode: Open
* Add mode: Buttons
* Default paragraph type: Text
### Display
* We do not use the default view mode, so ensure there are no fields showing.
* Enable the view modes that you envision using. At the very least there needs to be a full view mode and a teaser.
* We are using Display Suite so you need to set a Display Suite view mode before doing the configuration. The full content display is often using the “Three column stacked – 25/50/25” layout.
* Look to other content types to see how they are using some of the other more specialized view modes and which Display Suite layout they are using.
* If you want a Promoted block for the home page, you will need to format a Card view mode.
* For some of the view modes, you will need to add one or more field groups so that the theming will work correctly. Drutopia Article has the most developed view modes so it is a good example to work from.
* Where labels should be hidden, please use “Visually hidden” wherever possible.
* For the Image field, use Responsive image and set to wide or narrow as seems appropriate for your view mode.
* If you feel that you require a new view mode for your content type, please consult a tech lead.
## Pathauto
* A content type should always have an associated Pathauto pattern.
* Create a new pattern:
* Type: Content
* Path: `resources/[node:title]`
* Select the content type it applies to (for example Resource)
* Label: Node resource
## Views
* Create a view using the singular name of the content, for example `resource`.
* Most content types will need a page display and ideally a block display for promoted content. Other displays may be needed for a particular content type use case.
### Page display
* The page display should use the plural in the path, for example `/resources`.
* A menu item should also be set here for easy export.
* Give it a normal menu entry, with the parent menu <main navigation>
* Give it a title, for example “Resources”, and a description, such as “Get connected with our resources.”
* Under format, show, use Display Suite Content and format to use the view mode you desire. You can choose to use the alternating view mode so that the top items show in a larger format. Again, follow the view of an existing content type as an example.
* Filter criteria
* Content: Publishing status (= Yes)
* Content: Content type (= Resource)
* Sort criteria
* Content: Authored on (desc)
### Block display
* Create a block display for promoted content.
* Display name: Block Promoted
* Under Format choose Content and the Card view mode.
* Add a filter Content: Promoted to front page (= Yes)
* Limit to 4 items.
* Under Advanced, give it the machine name: `block_promoted`
## Creating feature and determining where fields go
* To create a Drutopia feature you need to enable the Features and Feature UI modules.
* Via the features interface (`admin/config/development/features`), start by ensuring that you have Drutopia selected as your features bundle.
* In Drupal 8 much of the features bundling happens automatically. By using the assignment plugins at their default, your configuration should be assigned to a new feature that will be shown as unexported.
* The included configuration link will show what is included in a general way.
* The link to the feature itself will take you to a page where you can review the configuration in more detail, adding or removing any items if necessary.
* The most important areas to review are the field storage and field instance. Field storage should only include fields that are unique to your content type. Field instance will include all field used.
* If you have added a new shared field (after consultation) that field storage will need to be added to Drutopia Core and this needs to be done ahead of creating the new feature.
* The machine name of the feature will be `resource`.
* Edit the description if needed.
* Ensure Drutopia is set as the bundle.
* Export your feature.
* After export, manually edit the info file to give it the name ‘Drutopia Resource’.
## Adding .json file
* Drutopia uses Composer so each feature needs a `.json` file.
* The `.json` file needs to includes direct dependencies only.
* Use another feature as a model and be sure to include any new modules you have needed for your feature.
## Adding permissions via config_actions
* Permissions are not directly exportable so they need to exported via config_actions.
* See the detailed instructions:
## Default content
* Ideally a content type includes default content.
* See detailed instructions:
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment