Package: collective.jsconfiguration
Table of contentsIntroductionHow it worksIJSONDataProviderIDOMDataProviderIJSObjectDataProviderRegistering a new configurationExample applicationChangelog0.1.1 (2015-08-25)0.1.0 (2014-05-02)IntroductionThis product is targeted to developer who need to distribute JavaScript configuration data or
i18n strings with their Plone products.Data injected in the page could be taken from whatever server side configuration setting you want
but most of the time you want to read application configuration from the Plone registry and translations
from page templates.How it worksA new viewlet will be registered in the HTML head of the site. This viewlet is normally empty and will
do nothing until a 3rd party product will register newIJSDataProvideradapters.There are three subtypes of adapters, choosing one of them depends on what you want to reach in your
add-on.Registeringnamed adaptersis recommended, in that way override the registration with a more
specific ones will be possible.
In the case ofIJSObjectDataProviderthe name is required because it’s used as name of the defined
variable (see below).IJSONDataProviderUse it when you want to add new JavaScript data in the form of a JSONtemplate.The adapter must be a callable object that return a string that could be threat as a JSON
string. It will be added to the page in ascriptof type “text/collective.jsconfiguration.json”.For example:<scripttype="text/collective.jsconfiguration.json"id="your_adapter_name_if_any">{"foo":...}</script>It’s not a duty of this package telling you how to read the data, but for example you could do something
like this:varconfiguration=$.parseJSON($('#your_adapter_name_if_any').text());IDOMDataProviderUse it when you want to add new JavaScript data in the form of XML nodes.The adapter must be a callable object that return something you want to be put inside the page.
It will be added to the page in ascriptof type “text/collective.jsconfiguration.xml”.An example:<scripttype="text/collective.jsconfiguration.xml"id="your_adapter_name_if_any"><foodata-i18n-label1="Benvenuto"data-i18n-label2="Questo è un esempio di traduzione">...</foo></script>Although there’s no real limitation in using this provider, it has been designed for injecting
XML sub-DOM.
If the callable use a template to render it’s content you can use a browser view.
This can bereallyuseful for internationalization of your JavaScript interface (because
you can then rely on Zope i18n support and tools likei18ndude).Reading the translation string from JavaScript will be really simple:varlabel1=$($('#your_adapter_name_if_any').text()).attr('data-i18n-label1');varlabel2=$($('#your_adapter_name_if_any').text()).attr('data-i18n-label2');IJSObjectDataProviderUse it when you want to add new JavaScript data in the form of a plain JavaScript object
assigned to a variable. For this reason the data will be used in a standardscripttag.This is very similar to theIJSONDataProviderabove (the callable must return a valid JSON string)
but with some important differences:a name for the adapter is requiredthe name of the adapter will be used as variable name to which the data will be assignedIf the name will be dotted, a nested JavaScript objects structure will be created.An example for an adapter called “foo.bar”:<scripttype="text/javascript">if(typeoffoo==='undefined'){foo={};}foo.bar={"baz":"Hello World"};</script>While the use ofIJSONDataProviderwill not include new JavaScript data in the JavaScript global
namespace but leave to developer the access to the new data, usingIJSObjectDataProvideryou are
directly adding new data to the JavaScript environment:alert(foo.bar.baz);// whil be "Hello World"Registering a new configurationWhatever is your choice, you simply need to register an adapter that adapts thecurrent context,
therequestand thecurrent view.An example:<adapterfactory="your.package.adapter.YourXMLAdapter"provides="collective.jsconfiguration.interfaces.IDOMDataProvider"for="* * *"name="your_zml_configuration"/>In the example above the configuration will be added to every page of the site.<adapterfactory="your.package.adapter.AnotherXMLAdapter"provides="collective.jsconfiguration.interfaces.IDOMDataProvider"for="Products.CMFPlone.interfaces.siteroot.IPloneSiteRoot
         your.package.browser.interfaces.IYourProductLayer
         your.package.browser.interfaces.IYourSpecialView"name="your_zml_configuration"/>In the last example another configuration will only added to the site root, only when a 3rd party browser
layers is registered (commonly: your add-on product is installed) and only when a specific view is called.As far as the adapter registration is using the same name of the first example, the last registration will
override the first when applicable.Finally, there’s the adapter class:classYourXMLAdapter(object):implements(IDOMDataProvider)def__init__(self,context,request,view):self.context=contextself.request=requestself.view=viewdef__call__(self):...When usingIJSONDataProviderorIJSObjectDataProviderand you want to directly read data from the
Plone registry, you can rely oncollective.regjsonifypackage, that can quickly help you in this task:fromcollective.regjsonify.interfacesimportIJSONifierfromcollective.jsconfiguration.interfacesimportIJSONDataProviderfromplone.registry.interfacesimportIRegistryfromzope.interfaceimportimplementsclassYourXMLAdapter(object):implements(IJSONDataProvider)def__init__(self,context,request,view):self.context=contextself.request=requestself.view=viewdef__call__(self):registry=queryUtility(IRegistry)settings=registry.forInterface(IMyRegistrySettings)returnIJSONifier(settings).json()Example applicationYou can find all those features in action in thecollective.externalizelinkPlone add-on.Changelog0.1.1 (2015-08-25)IJSONDataProviderwas masking HTML like output
[keul]Tests were broken
[keul]0.1.0 (2014-05-02)Initial release