Metadata-Version: 1.1
Name: uwosh.snippets
Version: 2.0.3
Summary: Adds reusable dynamically-rendered rich-text snippets
Home-page: https://github.com/collective/uwosh.snippets
Author: Sam Schwartz
Author-email: sam.schwartz@wildcardcorp.com
License: gpl
Description: ==============
        uwosh.snippets
        ==============
        
        Adds dynamically-updated rich text snippets to Plone. Update a 
        snippet to display the change everywhere the snippet is used 
        (pages, news items, events, anywhere rich text and TinyMCE 
        appear).
        
        Plone Version Compatibility
        ---------------------------
        
        Version 2.x is compatible with Plone 5.0+
        
        Earlier versions are compatible with Plone 4
        
        Introduction
        ------------
        
        The uwosh.snippets package allows you to include dynamically updated
        rich text snippets (chunks of rich text) anywhere in your site that
        uses the TinyMCE editor (i.e., any rich text field), including
        Pages, News Items, and Events.
        
        Snippets can be used anywhere that rich text can be used. They are
        inserted into a page much like you would an image or hyperlink.
        
        Because snippets are dynamically rendered, if you edit the snippet,
        its updated rich text is shown everywhere you had inserted the
        snippet.
        
        This is much more efficient and less error prone than copying and
        pasting rich text in multiple places in your site.
        
        Example
        -------
        
        A university wants to display its number of enrolled students
        consistently across its web site. Instead of manually updating each
        page that mentions the number of enrolled students and having to
        remember to change each of these pages whenever the enrollment number
        changes (e.g. annually), a content editor would create a snippet
        called "Enrollment Number" containing the rich text "13,491 students"
        and would insert that snippet wherever the enrollment number needed to
        be displayed.
        
        Whenever the official enrollment number changes, the content editor
        edits the "Enrollment Number" snippet to update the count,
        e.g. "14,120 students", and saves the change. All subsequent views of
        pages that contained that snippet will display the updated number.
        
        How to use
        ----------
        
        - Edit your buildout.cfg to add uwosh.snippets to your eggs.
        - Run buildout.
        - Restart your instance or clients.
        - Go to Site Setup -> Add-ons
        - Activate uwosh.snippets
        
        A new folder called "Snippets" (with ID ".snippets") will be created
        at the root of your site; that is the default location where the
        add-on will look for snippets.
        
        To add a snippet:
        
        - Navigate to the Snippets folder.
        - Add a Page. Give it a meaningful title and summary to
          help you and other content editors locate the snippet most
          easily. In the body, enter any rich text. You can use TinyMCE's
          Tools -> Source Code (HTML) view to insert arbitrarily complex HTML,
          as long as it satisfies your site's HTML Filtering settings.
        - Click the Save button.
        
        You have created your first snippet! You can use this snippet in one
        or more places on your site, anywhere TinyMCE is used as the editor.
        
        To insert a snippet:
        
        - Add or edit a Page (or Event or News Item or any other content
          item that has a rich text field that uses the TinyMCE editor).
        - In the TinyMCE editor, place your cursor where you will want to have
          the snippet's rich text appear.
        - Click on TinyMCE's new "{{}}" toolbar icon to bring up the snippet
          search dialog, which by default looks in your site's Snippets
          folder.
        - Use the search dialog to locate the snippet you want to
          insert. Click in the search dialog's text field. You will see a list
          of all snippets in your snippets folder. If you enter text in the
          search field, you will see only the snippets that match the search
          term you entered.
        - Click on the snippet you want to insert. The Snippet Preview will
          show you the contents of the snippet you selected. Use the "Select
          section" drop down to choose the portion of the snippet you want to
          preview (this is useful if you have particularly long snippets).
        - Click the Insert button. A reference to the snippet (a "plug") will
          be inserted into the rich text at the cursor location. It will look
          something like "Snippet:[ID=82341234bcda]".
        - Click the Save button.
        
        Instead of seeing the snippet plug you will now see the rich text
        contents of the snippet.
        
        Settings
        --------
        
        uwosh.snippets includes a control panel, available at Site Setup ->
        Snippets ('@@snippets-controlpanel').
        
        Related items settings:
        
        - Use this to change the directory in which to look for snippets (by
          default, a folder with the ID `.snippets` and title `Snippets`). For
          example, to look for snippets in a folder with the ID `blabla` at
          the root of your site, change the value of `basePath` from `/.snippets` to `/blabla`.
        - You can also modify the content type you use as snippets. By
          default, this is Pages (Documents). For example, to use the rich
          text field of a News Item, change the value of `selectableTypes`
          from `[Document]` to `[News Item]`.
        
        Code display expression:
        
        - Use this to modify the way a snippet reference ("plug") is displayed
          inside the TinyMCE editing area. Defaults to
          `string:Snippet:[ID=${context/@@uuid}]`. This is probably not a
          setting you will want to change.
        
        Render expression:
        
        - Use this to specify the TAL expression that renders a
          snippet. Defaults to
          `context/text/output|context/getText|nothing`. This is probably not
          a setting you will want to change. See the `TAL expression
          documentation
          <https://docs.plone.org/develop/plone/functionality/expressions.html>`_.
        
        Requirements
        ------------
        
        The TinyMCE WYSIWYG editor needs to be installed and enabled. A basic
        understanding of its use is also highly recommended. For more
        information about TinyMCE, visit their `website
        <http://www.tinymce.com>`_.
        
        
        TODO
        ----
        
        - would be nice: re-add support for add/edit/delete snippets in the modal
        - doesn't fit as well into how we're allowing snippets from anywhere on the site now
          
        Credits
        -------
        
        The original concept was developed by Sam Schwartz for the Office of International Education at University of Wisconsin Oshkosh.
        
        Plone 5 compatibility was developed by Nathan Van Gheem / Wildcard Corp. for Philip Bauer / Starzel.de.
        
        Maintainers
        -----------
        
        This add-on is maintained by Wildcard Corp., https://wildcardcorp.com,
        developers of the Castle CMS enhanced distribution of Plone,
        https://castlecms.io
        
        Contributors
        ============
        
        
        - Sam Schwartz, Author
        - Nathan Van Gheem
        - Gil Forcada
        - T. Kim Nguyen
        
        Changelog
        =========
        
        2.0.3 (2017-08-29)
        ------------------
        
        - more step by step user documentation
          [tkimnguyen]
        
        
        2.0.2 (2017-08-27)
        ------------------
        
        - enhance user doc in README
          [tkimnguyen]
        
        
        2.0.1 (2017-08-27)
        ------------------
        
        - fix MANIFEST to include missing marker file to enable creation of
          .snippets folder on activation
          [tkimnguyen]
        
        
        2.0.0 (2017-06-13)
        ------------------
        
        - Add site setup configuration
          [vangheem]
        
        - Integrate link integrity
          [vangheem]
        
        - Be able to add any content for a snippet
          [vangheem]
        
        - Use lxml to parse doc
          [vangheem]
        
        
        0.9.29 (12/19/2014)
        -------------------
        - Users can now reenable tinyMCE after disabling it
        - Fixed issue causing the backend regex from grabbing normal
          (non-snippet) span tags
        
        0.9.27 (12/17/2014)
        -------------------
        - Added link to disable tinyMCE when creating a snippet
        
        0.9.26 (8/26/2014)
        ------------------
        - Changed wording on several links/buttons to make them more understandable
        - Fixed broken preview system
        - Snippet plugs are now removed from the current page when the respective snippet is deleted.
        
        0.9.24 (8/21/2014)
        ------------------
        - Changed user-role requirements for different parts of the snippet UI
        - Fixed issue causing XMLSyntaxError...for real this time.
        - UI no longer displays add/edit/delete buttons if the user lacks the permissions to use them.
        - Updated README
        - Additional robot tests
        
        0.9.2 (8/13/2014)
        -----------------
        - Re-factored and rearraged code to make it complient to Plone's JS standards
        - Made JS jslint complient
        
        0.9.18 (8/13/2014)
        ------------------
        - Tweaked some of the robot tests, added a few others
        - Added exception for the XMLSyntaxError error
        - Fixed bug causing AJAX requests to be sent when they didn't need to
        
        0.9.15 (8/8/2014)
        -----------------
        - moved robot tests over from another branch
        - Changed JS on edit page load to get all snippets it needs at once, instead of one at a time
        - Reworked SnippetList class to accomodate aforementioned JS change
        
        0.9.11 (8/8/2014)
        -----------------
        - "Remove" button no long remains after removing a snippet plug
        - HTML View no longer breaks ALL the things.
        
        0.9.10 (8/6/2014)
        -----------------
        - Added button to allow the user to remove snippet plugs from the current page
        
        0.9.03 (8/5/2014)
        -----------------
        - Fixed bug preventing images from showing in preview window
        - Fixed bug breaking click-to-open when a snippet contains an image
        
        0.9.01 (8/5/2014)
        -----------------
        - Fixed useless uninstall profile
        
        0.8.9 (8/4/2014)
        ----------------
        - Fixed small JS bug introduced in 0.8.8
        
        0.8.9b (8/4/2014)
        -----------------
        - Browser UI no longer breaks when a snippet has no desc.
        
        0.8.9a (8/4/2014)
        -----------------
        - Fixed missing .snippet folder issue...again
        - Fixed issue with tinymce icon not showing up
        
        0.8.8 (8/4/2014)
        ----------------
        - Missing .snippets folder issue fixed.
        - Description field now longer required.
        - Broken click-to-open functionality now fixed.
        
        0.8.6a (6/5/2014)
        -----------------
        - Snippet ID's now aren't allowed to have any CSS-ID unsafe characters
        - Snippet plugs are now automatically updated when the base snippet is edited
        - The text inside snippet plugs can no longer be edited (that I'm aware of?)
        - Fixed numerous bugs preventing the "Selected snippet" box from populating
        
        0.8.5a (05/27/14)
        ------------------
        - Added contenteditable tag to prevent users from editing snippets inline
        
        
        0.8.4a (05/21/14)
        ------------------
        - Added snippet delete functionality
        - Added JS to polish delete
        
        
        .8.3a
        ------------------
        - Fixed issue with the new regex
        
        .8.2a
        ------------------
        - Remade the regex used by the snippet parser.
        
        .8a
        ------------------
        - Added a Create/Edit extension to the TinyMCE plugin
        - Inumerable bug fixes I've neglected to document :(
        - Added layer to prevent premature execution
        - Reworked JS to be more flexible
        
        .3
        -------------------
        - Extended TinyMCE plugin to make snippets "clickable" in the edit page.
        - Added snippet browser window to TinyMCE plugin.
        - Removed support for YouTube embedding (other products handle this better).
        
        .2
        -------------------
        - Added ability to embed youtube videos.
        
        .1
        -------------------
        - Basic proof-of-concept implementation
        - Added TinyMCE plugin
        
        
Keywords: snippet,dynamic,reusable,fragment
Platform: UNKNOWN
Classifier: Environment :: Web Environment
Classifier: Framework :: Plone
Classifier: Framework :: Plone :: 5.0
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2.7
Classifier: Topic :: Software Development :: Libraries :: Python Modules
