uwosh.snippets 2.0.2

Adds reusable dynamically-rendered rich-text snippets

.. raw::html

==============
uwosh.snippets
==============

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
Documents (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
- Install 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.

Navigate to the Snippets folder. Add a Document (Page); give it a
meaningful title and summary to help you and other content editors
locate the snippet most easily; in the body of the Document, enter any
rich text. You can use any TinyMCE formatting tools you wish, and you
can even use the HTML view to add and modify arbitrarily complex
HTML. Save the Document. You have created your first snippet! You can
use this snippet in one or more places on your site.

When you create or edit a Document ("Page"), TinyMCE will have a new
"{{}}" toolbar icon. When you click it, you will see a list of all
snippets found in the Snippets folder. When you click on a snippet, a
reference to it (a "plug") will be inserted into the rich text at the
cursor location. When you press Save, instead of seeing the snippet
plug you will see the rich text contents of the snippet.

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.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