--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/src/source/developer_guide/howto-paragraph.rst Tue Dec 11 16:29:56 2018 +0100
@@ -0,0 +1,345 @@
+.. _paragraphhowto:
+
+
+How to create a Paragraph type?
+===============================
+
+Paragraphs or Blocks are components that contain elements/fields and provide one or many renderer methods to compose
+the front office website
+
+
+Create a Paragraph
+""""""""""""""""""
+
+In this example we will create a contact paragraph to display at the user, who to contact.
+
+1) Interface
+------------
+
+At first we create a new paragraph interface.
+
+.. code-block:: python
+
+ CONTACT_PHONE_PARAGRAPH_TYPE = 'PhoneContact'
+ CONTACT_PHONE_PARAGRAPH_RENDERERS = 'PyAMS.paragraph.contact.phone.renderers'
+
+
+ class IContactPhoneParagraph(IBaseParagraph):
+ """Contact with phone number paragraph interface"""
+
+ name = TextLine(title=_("Contact identity"),
+ description=_("Name of the contact"),
+ required=True)
+
+ photo = ImageField(title=_("Photo"),
+ description=_("Use 'browse' button to select contact picture"),
+ required=False)
+
+ phone = TextLine(title=_("Phone Number"),
+ description=_("Name of the contact", required=False))
+
+ renderer = Choice(title=_("Contact template"),
+ description=_("Presentation template used for this contact"),
+ vocabulary=CONTACT_PHONE_PARAGRAPH_RENDERERS,
+ default='default')
+
+
+
+
+2) Implement the interface
+--------------------------
+
+An implementation of the interface
+
+.. code-block:: python
+
+ @implementer(IContactPhoneParagraph)
+ @factory_config(provided=IContactPhoneParagraph)
+ class ContactPhoneParagraph(BaseParagraph):
+ """Contact paragraph"""
+
+
+ icon_class = 'fa-phone'
+ icon_hint = _("Phone number card")
+
+ name = FieldProperty(IContactPhoneParagraph['name'])
+ _photo = FileProperty(IContactPhoneParagraph['photo'])
+
+ renderer = FieldProperty(IContactParagraph['renderer'])
+
+ @property
+ def photo(self):
+ return self._photo
+
+ @photo.setter
+ def photo(self, value):
+ self._photo = value
+ if IImage.providedBy(self._photo):
+ alsoProvides(self._photo, IResponsiveImage)
+
+
+3) Renderers Vocabulary
+-----------------------
+
+The list of rendered available for a paragraph is build automatically and is based on adapters that provide this interface
+
+.. code-block:: python
+
+ @vocabulary_config(name=CONTACT_PARAGRAPH_RENDERERS)
+ class ContactParagraphRendererVocabulary(RenderersVocabulary):
+ """Contact Phone paragraph renderers vocabulary"""
+
+ content_interface = IContactPhoneParagraph
+
+
+.. seealso::
+
+ :ref:`rendererhowto`
+
+
+Paragraph in the ZMI
+""""""""""""""""""""
+
+
+To display and manage the new paragraph in the ZMI, you should create this associated forms
+
+1) Paragraph factory
+--------------------
+
+To create a new element instance inside the zodb, we need a container to this object. PyAMS provide
+`IParagraphContainerTarget`, it's the default container for all paragraphs. We could use this container interface
+as context to create a new paragraph.
+
+
+Declaration of the **factory** of `ContactPhoneParagraph`
+
+.. code-block:: python
+
+ @utility_config(name=CONTACT_PHONE_PARAGRAPH_TYPE, provides=IParagraphFactory)
+ class ContactPhoneParagraphFactory(BaseParagraphFactory):
+ """Contact paragraph factory"""
+
+ name = _("Contact Phone card")
+ content_type = ContactPhoneParagraph
+ secondary_menu = True
+
+
+Definition of a form to create a new ContactPhone instance
+
+.. code-block:: python
+
+ from pyams_form.form import ajax_config
+
+
+ @pagelet_config(name='add-contact-phone-paragraph.html', context=IParagraphContainerTarget, layer=IPyAMSLayer,
+ permission=MANAGE_CONTENT_PERMISSION)
+ @ajax_config(name='add-contact-phone-paragraph.json', context=IParagraphContainerTarget, layer=IPyAMSLayer,
+ base=BaseParagraphAJAXAddForm)
+ class ContactPhoneParagraphAddForm(AdminDialogAddForm):
+ """Contact phone paragraph add form"""
+
+ legend = _("Add new contact phone card")
+ dialog_class = 'modal-large'
+ icon_css_class = 'fa fa-fw fa-phone'
+
+ fields = field.Fields(IContactPhoneParagraph).omit('__parent__', '__name__', 'visible')
+ edit_permission = MANAGE_CONTENT_PERMISSION
+
+ def create(self, data):
+ return ContactPhoneParagraph()
+
+ def add(self, object):
+ IParagraphContainer(self.context).append(object)
+
+
+2) Create the Paragraph addform button in the menu
+--------------------------------------------------
+
+We have created a new form and we want add a quick access button to create a new paragraph
+
+.. code-block:: python
+
+ @viewlet_config(name='add-contact-phone-paragraph.menu', context=IParagraphContainerTarget, view=IParagraphContainerView,
+ layer=IPyAMSLayer, manager=IToolbarAddingMenu, weight=600)
+ class ContactPhoneParagraphAddMenu(BaseParagraphAddMenu):
+ """Contact paragraph add menu"""
+
+ label = _("Contact card...")
+ label_css_class = 'fa fa-fw fa-id-card-o'
+ url = 'add-contact-paragraph.html'
+ paragraph_type = CONTACT_PARAGRAPH_TYPE
+
+
+
+3) Create Edit inner form
+-------------------------
+
+.. code-block:: python
+
+ @adapter_config(context=(IContactPhoneParagraph, IPyAMSLayer), provides=IParagraphInnerEditor)
+ permission=MANAGE_CONTENT_PERMISSION)
+ @ajax_config(name='inner-properties.json', context=IContactPhoneParagraph, layer=IPyAMSLayer,
+ base=BaseParagraphAJAXEditForm)
+ @implementer(IInnerForm)
+ class ContactPhoneParagraphInnerEditForm(ContactPhoneParagraphPropertiesEditForm):
+ """Contact paragraph inner edit form"""
+
+ legend = None
+
+ @property
+ def buttons(self):
+ if self.mode == INPUT_MODE:
+ return button.Buttons(IParagraphEditFormButtons)
+ else:
+ return button.Buttons()
+
+ def get_ajax_output(self, changes):
+ output = super(ContactParagraphInnerAJAXEditForm, self).get_ajax_output(changes)
+ updated = changes.get(IBaseParagraph, ())
+ if 'title' in updated:
+ output.setdefault('events', []).append(get_json_paragraph_refresh_event(self.context, self.request))
+ updated = changes.get(IContactParagraph, ())
+ if ('photo' in updated) or ('renderer' in updated):
+ # we have to commit transaction to be able to handle blobs...
+ if 'photo' in updated:
+ ITransactionManager(self.context).get().commit()
+ output.setdefault('events', []).append(get_json_form_refresh_event(self.context, self.request,
+ ContactParagraphInnerEditForm))
+ return output
+
+
+4) Create an Edit modal form
+-----------------------------
+
+This form is used inside modals popup
+
+
+.. code-block:: python
+
+ @ajax_config(name='properties.json', context=IContactPhoneParagraph, request_type=IPyAMSLayer,
+ permission=MANAGE_CONTENT_PERMISSION, renderer='json', xhr=True)
+ @pagelet_config(name='properties.html', context=IContactParagraph, layer=IPyAMSLayer,
+ permission=MANAGE_CONTENT_PERMISSION)
+ class ContactPhoneParagraphPropertiesEditForm(BaseParagraphPropertiesEditForm):
+ """Contact phone paragraph properties edit form"""
+
+ prefix = 'contact_properties.'
+
+ legend = _("Edit contact card properties")
+ icon_css_class = 'fa fa-fw fa-id-card-o'
+
+ fields = field.Fields(IContactParagraph).omit('__parent__', '__name__', 'visible')
+ fields['renderer'].widgetFactory = RendererFieldWidget
+
+ edit_permission = MANAGE_CONTENT_PERMISSION
+
+
+.. note::
+
+ Select the new content block types in ZMI to make it available in tools
+
+ .. image:: _static/select_paragraph.png
+
+
+How to associate links or Illustrations to a Paragraph ?
+========================================================
+
+Adding the following marker interface, we add new behavior to the Paragraph `ContactPhoneParagraph` .
+
+
+Paragraph advanced
+""""""""""""""""""
+
+You can attach Associated files, links or illustration and manage them directly through the rubric `Links and Attachments`.
+
+.. image:: _static/select_links_n_attachment.png
+
+
+1) Paragraph with Links and Attachements
+----------------------------------------
+
+To "activate" this features the paragrath object must to implement specific interface
+
+
+.. code-block:: python
+
+ @implementer(IContactPhoneParagraph, IIllustrationTarget,ILinkContainerTarget,IExtFileContainerTarget))
+ @factory_config(provided=IContactPhoneParagraph)
+ class ContactPhoneParagraph(BaseParagraph):
+ """Contact paragraph"""
+ ...
+
+
+These interfaces will allow to link other data to the paragraph.
+
+**Marker interfaces:**
+
+ +--------------------------------+
+ |:py:class:`IIllustrationTarget` |
+ +===================+============+
+ | | |
+ +-------------------+------------+
+
+ +---------------------------------+
+ |:py:class:`ILinkContainerTarget` |
+ +==============+==================+
+ | | Add internal link|
+ | +------------------+
+ | | Add external link|
+ | +------------------+
+ | | Add mailto link |
+ +--------------+------------------+
+
+ +------------------------------------+
+ |:py:class:`IExtFileContainerTarget` |
+ +================+===================+
+ | | Add external file |
+ | +-------------------+
+ | | Add image |
+ | +-------------------+
+ | | Add video |
+ | +-------------------+
+ | | Add audio file |
+ +----------------+-------------------+
+
+
+**ZMI overview:**
+
+.. image:: _static/select_add_links.png
+
+
+
+2) Add link and association form
+--------------------------------
+
+You can add form to manage links and attachments directly in paragraph form to do that your form must implement
+``IPropertiesEditForm`` and/or ``IAssociationParentForm``
+
+
+.. code-block:: python
+
+ @adapter_config(context=(IContactPhoneParagraph, IPyAMSLayer), provides=IParagraphInnerEditor)
+ @implementer(IInnerForm, IPropertiesEditForm, IAssociationParentForm)
+ class ContactPhoneParagraphInnerEditForm(ContactPhoneParagraphPropertiesEditForm):
+ """Contact paragraph inner edit form"""
+
+ legend = None
+ ajax_handler = 'inner-properties.json'
+
+
+**Marker interfaces:**
+
++-----------------------------------+
+|:py:class:`IPropertiesEditForm` |
++=========+=========================+
+| | Add Illustration form |
++---------+-------------------------+
+
++-----------------------------------+
+|:py:class:`IAssociationParentForm` |
++===========+=======================+
+| | Add Association form |
++-----------+-----------------------+
+
+.. image:: _static/associations_form.png
+