new-content-feature.md 13.7 KB
Newer Older
1
2
3
4
# How to produce a new content feature 

These instructions will use the example of a yet to be built “resource”  feature.

benjamin melançon's avatar
benjamin melançon committed
5

6
## Naming conventions: 
benjamin melançon's avatar
benjamin melançon committed
7

8
9
10
11
12
* See also the technical guide section on [naming and namespaces](http://docs.drutopia.org/en/latest/technical-guide.html#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.

benjamin melançon's avatar
benjamin melançon committed
13

14
## Fields: what fields are re-used, what are required
benjamin melançon's avatar
benjamin melançon committed
15

16
17
18
19
20
* Many of the core field are reused between features.
* These include
 * `field_summary` (required)
 * `field_body_paragraph`
 * `field_image`
21
 * `field_topics`
22
23
24
25
26
 * `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.

benjamin melançon's avatar
benjamin melançon committed
27

28
### Paragraph types:
benjamin melançon's avatar
benjamin melançon committed
29

30
31
32
* 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.

benjamin melançon's avatar
benjamin melançon committed
33

34
### Metatag
benjamin melançon's avatar
benjamin melançon committed
35

36
37
38
* The metatag field (`field_meta_tags`) should be included in every content type feature.

### Form display
benjamin melançon's avatar
benjamin melançon committed
39

40
* The traditional Body field (`field_body`) has been maintained for migration purposes. It should always be hidden on the form display.
41
* Refer to another content feature such as `drutopia_article` as a model for the general ordering and setting guidelines.
42
43
44
45
46
* For the Body paragraph field, ensure the following settings are set:
 * Edit mode: Open
 * Add mode: Buttons
 * Default paragraph type: Text

benjamin melançon's avatar
benjamin melançon committed
47

48
### Display
benjamin melançon's avatar
benjamin melançon committed
49

50
51
52
53
* 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.
54
* If you want a Promoted block for the home page, you will need to format a Card view mode, see below for further details.
55
56
57
58
* 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.
59
* Enable and configure the search_index view mode with all labels hidden.
benjamin melançon's avatar
benjamin melançon committed
60
61


62
#### Formatting guidelines for card view mode
benjamin melançon's avatar
benjamin melançon committed
63

64
65
66
67
68
69
70
71
72
73
74
* Enable `card` in Custom display settings.
* Ensure this view mode is using the Display Suite one column layout.
* Add the image field to the content area, selecting responsive image, narrow and linked to content.
* Next, create a field group for the card view mode.
* This is a group of type HTML element and must be named Card content, `card_content`. Settings can be left at default.
* Add this field group to the content area.
* Then place into it the desired fields:
 * Title, linked to content.
 * Summary, trimmed to 180 characters.
 * Add a `type` field or `tags` as desired.
* Save your card settings.
benjamin melançon's avatar
benjamin melançon committed
75

76
Note: When using the card view mode in a view, ensure that the field “Add views row classes” under setting is unchecked.
77

benjamin melançon's avatar
benjamin melançon committed
78

79
80
81
82
83
84
85
86
87
88
89
#### Display Suite fields

Where there is a need for specialized display in a view mode, we rely on Display Suite fields. Examples:

* To concatenate two fields, add a Display Suite token field and use tokens to concatenate the fields.
* If there is a need to place a block in the view mode:
    * Create the block as e.g. a view.
    * Add a Display Suite block field, selecting the block in question.

Whenever creating a Display Suite field, configure to limit it to only the particular entity bundles that are applicable. For example, if the field is only for events, limit it to the `event` bundle.

benjamin melançon's avatar
benjamin melançon committed
90

91
## Pathauto
benjamin melançon's avatar
benjamin melançon committed
92

93
94
95
96
97
98
99
* 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

benjamin melançon's avatar
benjamin melançon committed
100

101
## Views
benjamin melançon's avatar
benjamin melançon committed
102

103
104
* As of the alpha5 release, content type views are based on a search index for that content type. Eventually we'll be adding facets to these listing pages.

benjamin melançon's avatar
benjamin melançon committed
105

106
### Create an index for your content type
benjamin melançon's avatar
benjamin melançon committed
107

108
109
110
111
112
113
* Ensure you have `drutopia_dev` and `entity_clone` installed and enabled.
* Clone the node_dev index to create a search index for each content type limiting it to that one content type. Give it the same name as the content type and update the description.
* Configure the search_index view mode for your content type and use it in the rendered HTML field on the search index.
* Add any fields that are specific to the content type, for example a type vocabulary. This will be needed for any field that we want to use for facets.
* Flush caches before proceeding.

benjamin melançon's avatar
benjamin melançon committed
114

115
### Create a view
benjamin melançon's avatar
benjamin melançon committed
116

117
* Create a new view based on the search index for your content type using the singular name of the content, for example `resource`.
118
119
* 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.

benjamin melançon's avatar
benjamin melançon committed
120

121
### Page display
benjamin melançon's avatar
benjamin melançon committed
122

123
124
125
126
* 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.”
127
128
* Under format settings, ensure that Add views row classes is unchecked.
* Under format, show, use the rendered entity selecting an appropriate view mode (often card).
129
* Sort criteria
130
131
132
133
 * Sticky
 * Content: Authored on (desc)
* Set the machine name to `page_listing`
* Set caching to none.
134

benjamin melançon's avatar
benjamin melançon committed
135

136
### Block display
benjamin melançon's avatar
benjamin melançon committed
137

138
139
140
141
142
143
144
* 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`

Rosemary Mann's avatar
Rosemary Mann committed
145
## Facets for your listing page
Rosemary Mann's avatar
Rosemary Mann committed
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170

* To add a facet you need to ensure that the field has been added to your search index.
* Create your facet at (admin/config/search/facets) choosing the appropriate Views display as your data source, for example View Resource, display Page
* Give it the name for the content type and the field. For example, `resource_topics` or `resource_type`.
* Update the following configuration items:  (everything else can be left at default)
    * Configure your facet to use checkboxes.
    * Show the amount of results.
    * Soft limit 10.
    * Show less should read “Show fewer”
    * Transform entity ID to label.
    * Hide facet when facet source is not rendered.
    * For most facets, sort by Display value, ascending.
    * For any facet with a sequential dimension,sort by taxonomy term weight, ascending.

### Block visibility group

* Create a new block visibility group such as `resource_listing` and add your facet or add to an existing block visibility group.
* Set this visibility group and add your facet block to the sidebar.
* Edit the machine name to include facet, such as `resource_topics_facet` or `resource_type_facet`.
* Update the title to only show the field not the content type, so “Topics” or "Type".
* Use row weights to order your facets. Tip, if you always only use even numbers, an odd number can be inserted if you need to add in a new item.

### When packaging into features (see below)
* The facet itself will go into your corresponding content type feature.
* The blocks need to go into an optional folder in the install profile.
benjamin melançon's avatar
benjamin melançon committed
171

172
## Creating feature and determining where fields go
benjamin melançon's avatar
benjamin melançon committed
173

174
175
176
177
178
179
180
* 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.
181
* The machine name of the feature will be `resource`. (Question: This is because it's automatic or should it be edited to `drutopia_resource` by convention?)
182
183
184
* Edit the **Description** if needed.
* Ensure Drutopia is set as the **Bundle**.
* Set the **Version** to `8.x-1.0-alpha1` if it's the first time.  Once accepted into Drutopia, it should match the stability of the Drutopia distribution.
185
* To add the search_index view mode you will need to edit the feature, allow conflicts (as this view mode will be added to the seach feature by deafault) and manually add.
186
* Export your feature.  (If using **Write**, you can set the **Path** to `modules/contrib` presuming you intend to contribute it.)
187
188
* After export, manually edit the info file to give it the name ‘Drutopia Resource’.

benjamin melançon's avatar
benjamin melançon committed
189

190
## Adding .json file
benjamin melançon's avatar
benjamin melançon committed
191

192
193
194
* 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.
195

benjamin melançon's avatar
benjamin melançon committed
196

197
198
## Contribute the feature module

199
* Initialize a git repository in the feature module.  For example, `cd modules/contrib/drutopia_resource`, `git init`, `git checkout -b 8.x-1.x`, `git branch -d master`, `git add .`, `git commit -m "Create the Drutopia Resource feature"`.
200
* Go to the [Drutopia organization on GitLab](https://gitlab.com/drutopia/) and create a new project with the same folder/machine name as your feature module (or, if you do not have permissions in the Drutopia organization, start the project in your own namespace).  Make it a public project (**Visibility Level** Public).
201
* Follow GitLab's instructions for an existing folder which we haven't already done; for example `git remote add origin git@gitlab.com:drutopia/drutopia_resource.git` and `git push -u origin 8.x-1.x`.
202

benjamin melançon's avatar
benjamin melançon committed
203

204
## Adding permissions via config_actions
benjamin melançon's avatar
benjamin melançon committed
205

206
* Permissions are not directly exportable so they need to exported via config_actions.
207
* See the page on [adding user permissions](add-user-permissions.html).
208

benjamin melançon's avatar
benjamin melançon committed
209

210
## Default content
benjamin melançon's avatar
benjamin melançon committed
211

212
* Ideally a content type includes default content.
benjamin melançon's avatar
benjamin melançon committed
213
* See detailed instructions: [Producing and exporting default content for Drutopia](development/producing-and-exporting-default-content).
214

benjamin melançon's avatar
benjamin melançon committed
215

216
## Settings provided by other modules
benjamin melançon's avatar
benjamin melançon committed
217

218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
As a general guideline, we can export to regular features _only custom configuration that we have ourselves created_, such as a view mode or a field. If we're configuring using a settings form, that configuration will already be provided elsewhere (for example, by the `chosen` module). A hint that this may be occurring is that the name of the configuration includes another module's name, such as `chosen.settings.yml`. Another hint is if the configuration does not show up by default as available for adding to your feature (that is, you have to check the option to allow conflicts before it will show up).

We have two options for such configuration:

* The first is to add it to the install profile, which is allowed to override configuration provided by other modules. This option is appropriate if:
    * The configuration should always be active on all sites; and
    * The configuration is not required by other configuration or functionality. This consideration is because the install profile is typically installed last and nothing should require the install profile.
* Otherwise, we can add it as a config action per the `config_actions` module. See the [Config Actions documentation](http://config-actions.readthedocs.io/en/latest/plugins.html).


For example, to change a configuration option provided by the `realname` module, you might add a file `config/actions/realname.settings.yml` with the following content:

```yml
path:
  - pattern
plugin: change
actions:
  'full name':
    value: '[user:field_user_first_name] [user:field_user_last_name]'
```
benjamin melançon's avatar
benjamin melançon committed
238

239
240
(where `full name` is an arbitrary key identifying the change).