diff --git a/README.txt b/README.txt index e2eff04..1fa4cf5 100644 --- a/README.txt +++ b/README.txt @@ -1,21 +1,86 @@ -README.txt -========== +CONTENTS OF THIS FILE +--------------------- -Paragraph is a module to create paragraphs in your content. -You can create types(with own display and fields) as Paragraph types. + * Introduction + * Requirements + * Installation + * Configuration + * Widgets + * Drag & Drop + * Limitations -When you use the Entity Reference Paragraphs widget + Entity Reference selection -type on your node/entity, you can select the allowed types, and when using the -widget, you can select a paragraph type from the allowed types to use -different fields/display per paragraph. -* Different fields per paragraph type -* Using different Paragraph types in a single Paragraph field -* Displays per paragraph type +INTRODUCTION +------------ -WIDGETS +Paragraphs is the new way of content creation! It allows you — Site Builders — +to make things cleaner so that you can give more editing power to your +end-users. + +Instead of putting all their content in one WYSIWYG body field including images +and videos, end-users can now choose on-the-fly between pre-defined Paragraph +Types independent from one another. Paragraph Types can be anything you want +from a simple text block or image to a complex and configurable slideshow. + +Paragraphs module comes with a new "paragraphs" field type that works like +Entity References. Simply add a new paragraphs field on any Content Type you +want and choose which Paragraph Types should be available to end-users. They can +then add as many Paragraph items as you allowed them to and reorder them at +will. + +Paragraphs module does not come with any default Paragraph Types but since they +are basic Drupal Entities you can have complete control over what fields they +should be composed of and what they should look like through the typical Drupal +Manage Fields and Manage Display screens. + +You can also add custom option fields and do conditional coding in your CSS, JS +and preprocess functions so that end-users can have more control over the look +and feel of each item. This is way much cleaner and stable than adding inline +CSS or classes inside the body field's source. + +* For a full description of the module, visit the project page: + https://www.drupal.org/project/paragraphs + +* To submit bug reports and feature suggestions, or track changes: + https://www.drupal.org/project/issues/paragraphs + + +REQUIREMENTS +------------ + +This module requires the following module: + + * [Entity Reference Revisions](https://www.drupal.org/project/entity_reference_revisions) + + +INSTALLATION +------------ + + * Install as you would normally install a contributed Drupal module. Visit + https://www.drupal.org/node/1897420 for further information. + + +CONFIGURATION ------------- +Paragraphs has two configuration locations: + + * Configure User permissions for administration of Paragraphs settings, + entity types, and unpublished entity visibility. + * Configure settings for unpublished Paragraphs at Administration > + Configuration > Content Authoring > Paragraphs settings + (admin/config/content/paragraphs). + +Once configured, Paragraphs can be used in the following ways: + + * Widgets + * Drag & Drop + * Multilingual + + +WIDGETS +------- + Paragraphs currently provides two different widgets that can be used. * Legacy (formerly Classic): a stable UI with limited features that will not be @@ -27,33 +92,36 @@ Paragraphs currently provides two different widgets that can be used. between versions are to be expected and customizations might need to be updated. -Drag & drop -------------- + +DRAG & DROP +----------- The stable widget offers a separate mode that allows to re-sort paragraphs not just within the same level but it is also possible to change the hierarchy and move paragraphs including their children around and into other paragraphs. -During drag & drop mode, paragraphs are also displayed as a summary only, which -results in a very compact display that makes it easier to move them around. +When using Drag & Drop mode, paragraphs are also displayed only as a summary, +which results in a very compact display that makes it easier to move them +around. -Starting with Drupal 8.8.0, the necessary library is part of Drupal core and -this feature is always available. +Starting with Drupal 8.8.0, the required library for this functionality is +available in Drupal core, making this feature always available. If the file +exists, the feature will automatically be available. -Use the version 1.10+ as it's tested and approved. Older versions may introduce -bugs with nested drag & drop functionality. -If the file exists, the feature will automatically be available. +Drag & Drop is recommended for usage in versions 1.10+, as older versions may +introduce bugs with nested drag & drop functionality. + MULTILINGUAL CONFIGURATION -------------- - * Enable the Paragraph module. +-------------------------- + + * Enable the Paragraphs module. * Add new languages for the translation in Configuration » Languages. * Enable any custom content type with a paragraph field to be translatable in - Configuration » Content language - and translation: + Configuration » Content language and translation: - Under Custom language settings check Content. @@ -64,15 +132,15 @@ MULTILINGUAL CONFIGURATION - Set the fields of each paragraph type to translatable as required. * Check Paragraphs as the embedded reference in Configuration » Translation - Management settings. + Management settings. - * Create a new content - Paragraphed article and translate it. + * Create a new content - paragraphed article and translate it. -LIMITATION -------------- -For now, this module does not support switching entity reference revision field -of the paragraph itself into multilingual mode. This would raise complexity -significantly. -Check #2461695: Support translatable paragraph entity reference revision field -(https://www.drupal.org/node/2461695). +LIMITATIONS +----------- + + * For now, this module does not support switching entity reference revision + field of the paragraph itself into multilingual mode. This would raise + complexity significantly. Check #2461695: Support translatable paragraph + entity reference revision field (https://www.drupal.org/node/2461695).