{ "info": { "author": "Martin Aspeli", "author_email": "optilude@gmail.com", "bugtrack_url": null, "classifiers": [ "Development Status :: 5 - Production/Stable", "Framework :: Plone", "Framework :: Plone :: 5.2", "License :: OSI Approved :: GNU General Public License (GPL)", "Programming Language :: Python", "Programming Language :: Python :: 2.7", "Programming Language :: Python :: 3.6", "Programming Language :: Python :: 3.7", "Topic :: Software Development :: Libraries :: Python Modules" ], "description": "Introduction\n============\n\nThis package provides a ``zope.schema`` style field type called ``RichText`` which can be used to store a value with a related MIME type.\nThe value can be transformed to an output MIME type, for example to transform from structured text to HTML.\n\nBasic Usage\n===========\n\nTo use the field, place it in a schema like so::\n\n from plone.app.textfield import RichText\n from zope.interface import Interface\n\n class ITest(Interface):\n\n bodyText = RichText(\n title=u\"Body text\",\n default_mime_type='text/structured',\n output_mime_type='text/html',\n allowed_mime_types=('text/structured', 'text/plain',),\n default=u\"Default value\"\n )\n\nThis specifies the default MIME type of text content as well as the default output type,\nand a tuple of allowed types.\nAll these values are optional.\nThe default MIME type is 'text/html', and the default output type is 'text/x-html-safe'.\nBy default, ``allowed_mime_types`` is None,\nwhich means that the side-wide default set of allowable input MIME types will be permitted.\n\nNote that the default value here is set to a Unicode string,\nwhich will be considered to be of the default MIME type.\nThis value is converted to a ``RichTextValue`` object (see below) on field initialisation,\nso the ``default`` property will be an object of this type.\n\nThe field actually stores an immutable object of type `plone.app.textfield.value.RichTextValue`.\nThis object has the following attributes:\n\nraw\n The raw value as a Unicode string.\n\nmimeType\n The MIME type of the raw text.\n\noutput\n A Unicode string that represents the value transformed to the default output MIME type.\n Maybe None if the transformation could not be completed successfully,\n but will be cached after it has been successfully transformed once.\n\noutputMimeType\n The MIME type of the output string.\n This is normally copied from the field's ``output_mime_type`` property.\n\n\nStorage\n=======\n\nThe ``output``, ``mimeType`` and ``outputMimeType`` properties will be stored in the same _p_jar as the parent content object,\nwhilst the ``raw`` value is stored in a separate persistent object.\nThis is to optimize for the common case where the ``output`` is frequently accessed when the object is viewed\n(and thus should avoid a separate persistent object load),\nwhereas the ``raw`` value is infrequently accessed\n(and so should not take up memory unless specifically requested).\n\n\nTransformation\n==============\n\nTransformation takes place using an ``ITransformer`` adapter.\nThe default implementation uses Plone's ``portal_transforms`` tool to convert from one MIME type to another.\nNote that ``Products.PortalTransforms`` must be installed for this to work,\notherwise, no default ITransformer adapter is registered.\nYou can use the ``[portaltransforms]`` extra to add ``Products.PortralTransforms`` as a dependency.\n\nTo invoke alternative transformations from a page template,\nyou can use the following convenience syntax::\n\n
\n\nHere ``fieldName`` is the name of the field\n(which must be found on ``context`` and contain a ``RichTextValue``).\n``text/plain`` is the desired output MIME type.\n\n\nOptional Features\n=================\n\nThe package also contains a ``plone.supermodel`` export/import handler,\nwhich will be configured if plone.supermodel is installed.\nYou can use the ``[supermodel]`` extra to add a ``plone.supermodel`` dependency.\n\nA ``z3c.form`` widget will be installed if `z3c.form`` is installed.\nThe ``[widget]`` extra will pull this dependency in if nothing else does.\n\nA ``plone.rfc822`` field marshaler will be installed if ``plone.rfc822`` is installed.\nThe ``[marshaler]`` extra will pull this dependency in if nothing else does.\n\nA ``plone.schemaeditor`` field factory will be installed if ``plone.schemaeditor`` is installed.\nThe ``editor`` extra will pull this\ndependency if nothing else does.\n\n\nUsage with Simple TextArea\n==========================\n\nAlternatively, the RichText Field may be used without a WYSIWYG editor displaying a simple TextArea on input,\nand formatted output as HTML on display.\nIn this example, it is expected to have the ``plone.intelligenttext`` transform available.\nAlso expected is ``plone.autoform`` and ``plone.app.z3cform`` to be installed.\n\n::\n\n from z3c.form.browser.textarea import TextAreaFieldWidget\n from plone.autoform.directives import widget\n\n class ITest(Interface):\n\n bodyText = RichText(\n title=u\"Intelligent text\",\n default_mime_type='text/x-web-intelligent',\n allowed_mime_types=('text/x-web-intelligent', ),\n output_mime_type='text/x-html-safe',\n default=u\"Default value\"\n )\n widget(\n 'bodyText',\n TextAreaFieldWidget,\n )\n\nInput is a simple text.\nAt display, an HTML in rendered by the transform and shown.\nTo show HTML unescaped the output has to be 'text/x-html-safe'.\n\n\nFurther Reading\n===============\n\nSee field.txt for more details about the field's behavior,\nand handler.txt for more details about the plone.supermodel handler.\n\nIssue tracker\n=============\n\nPlease report issues via the `Plone issue tracker`_.\n\n.. _`Plone issue tracker`: https://github.com/plone/plone.app.textfield/issues\n\nSupport\n=======\n\nQuestions may be answered via `Plone's support channels`_.\n\n.. _`Plone's support channels`: http://plone.org/support\n\nContributing\n============\n\nSources are at the `Plone code repository hosted at Github