{ "info": { "author": "Zope Foundation and Contributors", "author_email": "zope-dev@zope.org", "bugtrack_url": null, "classifiers": [ "Development Status :: 6 - Mature", "Environment :: Web Environment", "Framework :: Zope :: 4", "Intended Audience :: Developers", "License :: OSI Approved :: Zope Public License", "Operating System :: OS Independent", "Programming Language :: Python :: 2.7", "Programming Language :: Python :: 2 :: Only", "Programming Language :: Python :: Implementation :: CPython", "Topic :: Internet :: WWW/HTTP :: Dynamic Content", "Topic :: Software Development", "Topic :: Text Editors :: Text Processing" ], "description": "Zope External Editor\n====================\n\nThe Zope External Editor is a new way to integrate Zope more seamlessly with\nclient-side tools. It has the following features:\n\n- Edit objects locally, directly from the ZMI.\n\n- Works with any graphical editor application that can open a file from the\n command line, including: emacs, gvim, xemacs, nedit, gimp, etc.\n\n- Automatically saves changes back to Zope without ending the editing\n session.\n\n- Associate any client-side editor application with any Zope object by\n meta-type or content-type. Both text and binary object content can be\n edited.\n\n- Locks objects while they are being edited. Automatically unlocks them\n when the editing session ends.\n\n- Can add file extensions automatically to improve syntax highlighting or\n file type detection.\n\n- Works with basic auth, cookie auth and Zope versions. Credentials are\n automatically passed down to the helper application. No need to\n reauthenticate.\n\n- https support (Openssl required)\n\nZope version compatibility\n--------------------------\n\nFor Zope 4, please use release 2.0 and upwards. For Zope releases prior to\n4.0, please use ExternalEditor releases from the 1.1 branch.\n\nUsing It\n--------\n\nUse of the application is about as easy as using the ZMI once your browser\nis configured (see the installation instructions). To edit an object\nexternally, just click on the pencil icon next to the object in the ZMI.\nThe object will be downloaded and opened using the editor application you\nhave chosen (you will be prompted the first time to choose an editor).\n\nYou edit the object just like any other file. When you save the changes in\nyour editor, they are automatically uploaded back to Zope in the\nbackground. While the object is open in your editor, it is locked in Zope\nto prevent concurrent editing. When you end your editing session (ie you\nclose your editor) the object is unlocked.\n\nHow it Works\n------------\n\nOk, so this all sounds a bit too good to be true, no? So how the heck does\nit work anyway? First I'll give you a block diagram::\n\n +------------+ +------------+ +---------+ +------+\n | Editor App | <-- | Helper App | <-- | Browser | <-/ /- | Zope |\n +------------+ +------------+ +---------+ +------+\n ^ ^ ^ ^\n \\ / \\ /\n v v -----------------------/ /----\n -------\n / Local \\\n \\ File /\n -------\n\nNow the key to getting this to work is solving the problem that the editor\ncannot know about Zope, and must only deal with local files. Also, there is\nno standard way to communication with editors, so the only communication\nchannel can be the local file which contains the object's content or code.\n\nIt is trivial to get the browser to fire up your editor when you download\na particular type of data with your browser. But that does you little good,\nsince the browser no longer involves itself once the data is downloaded. It\njust creates a temp file and fires off the registered application, passing\nit the file path. Once the editor is running, it is only aware of the local\nfile, and has no concept of where it originated from.\n\nTo solve this problem, I have developed a helper application whose job is\nessentially two-fold:\n\n- Determine the correct editor to launch for a given Zope object\n\n- Get the data back into Zope when the changes are saved\n\nSo, let's take a step by step look at how it works:\n\n1. You click on the external editor link (the pencil icon) in the Zope\n management interface.\n\n2. The product code on the server creates a response that encapsulates the\n necessary meta-data (URL, meta-type, content-type, cookies, etc) and the\n content of the Zope object, which can be text or binary data. The\n response has the contrived content-type \"application/x-zope-edit\".\n\n3. The browser receives the request, and finds our helper application\n registered for \"application/x-zope-edit\". It saves the response data\n locally to disk and spawns the helper app to process it.\n\n4. The helper app, reads its config file and the response data file. The\n meta-data from the file is parsed and the content is copied to a new\n temporary file. The appropriate editor program is determined based on\n the data file and the configuration.\n\n5. The editor is launched as a sub-process of the helper app, passing it the\n file containing the content data.\n\n6. If so configured, the helper app sends a WebDAV lock request back to Zope\n to lock the object.\n\n7. Every so often (if so configured), the helper app stats the content file\n to see if it has been changed. If so, it sends an HTTP PUT request\n back to Zope containing the new data.\n\n8. When the editor is closed, the content file is checked one more time and\n uploaded if it has changed. Then a WebDAV unlock request is sent to Zope.\n\n9. The helper application exits.\n\nConfiguration\n-------------\n\nThe helper application supports several configuration options, each of\nwhich can be triggered in any combination of object meta-type, content-type\nor domain. This allows you to create appropriate behavior for different\ntypes of Zope objects and content or even different servers. The\nconfiguration file is stored in the file \"~/.zope-external-edit\" (Unix) or\n\"~\\ZopeEdit.ini\" (Windows). If no configuration file is found when the\nhelper application starts, a default config file is created in your home\ndirectory.\n\nThe configuration file follows the standard Python ConfigParser format,\nwhich is pretty much like the old .ini file format from windows. The file\nconsists of sections and options in the following format:\n\n.. code-block:: ini\n\n [section 1]\n option1 = value\n option2 = value\n\n [section 2]\n ...\n\nOptions\n-------\n\nThe available options for all sections of the config file are:\n\n``editor``\n Command line or plugin name used to invoke the editor application. On\n Windows, if no editor setting is found for an object you edit, the\n helper app will search the file type registry for an appropriate editor\n based on the content-type or file extension of the object (which can be\n specified using the extension option below). By default, the file path\n of the local file being edited is appended to this command line. To\n insert the file path in the middle of your command, use \"$1\" for Unix\n and \"%1\" for Windows respectively.\n\n``save_interval``\n (float) The interval in seconds that the helper application checks the\n edited file for changes.\n\n``use_locks``\n (1 or 0) Whether to use WebDAV locking. The user editing must have the\n proper WebDAV related permissions for this to work.\n\n``always_borrow_locks``\n (1 or 0) When use_locks is enabled this features suppresses warnings\n when trying to edit an object you have already locked. When enabled,\n external editor will always \"borrow\" the existing lock token instead of\n doing the locking itself. This is useful when using CMFStaging for\n instance. If omitted, this option defaults to 0.\n\n``cleanup_files``\n (1 or 0) Whether to delete the temp files created. WARNING the temp\n file coming from the browser contains authentication information and\n therefore setting this to 0 is a security risk, especially on shared\n machines. If set to 1, that file is deleted at the earliest\n opportunity, before the editor is even spawned. Set to 0 for debugging\n only.\n\n``extension``\n (text) The file extension to add to the content file. Allows better\n handling of images and can improve syntax highlighting.\n\n``temp_dir``\n (path) Path to store local copies of object data being edited. Defaults\n to operating system temp directory. *Note: this setting has no apparent\n effect on Windows* 8^(\n\n``long_file_name``\n (1 or 0) Whether to include the whole path to the object including the\n hostname in the file name (the default) or just the id of the object\n being edited. Turn this option off for shorter file names in your\n editors, and for editors that don't like long names.\n\n``file_name_separator``\n (string) Character or characters used to separate path elements in long\n files names used by external editor. Defaults to a comma (,). This must\n be a legal character for use in file names on your platorm (i.e., don't\n use a path separator character!). This option is ignored if\n 'long_file_name' is set to 0.\n\nSections\n--------\n\nThe sections of the configuration file specify the types of objects and\ncontent that the options beneath them apply to.\n\nThere is only one mandatory section '[general]', which should define all\nof the above options that do not have a default value. If no other\nsection defines an option for a given object, the general settings are\nused.\n\nAdditional sections can apply to a particular domain, content-type or\nmeta-type. Since objects can have all these properties, the options are\napplied in this order of precedence:\n\n1. Options by whole content-type (e.g., `[content-type:text/html]`).\n\n2. Options by major content-type (e.g., `[content-type:text/*]`).\n\n3. Options by Zope meta-type (e.g., `[meta-type:File]`).\n\n4. Options by domain (e.g., `[domain:www.mydomain.com]`). Several\n sections can be added for each domain level if desired.\n\n5. General options (i.e., `[general]`).\n\nThis scheme allows you to specify an extension by content-type, the\neditor by meta-type, the locking settings by domain and the remaining\noptions under general for a given object.\n\nEditor Plugins\n--------------\n\nFor tighter client-side integration, external editor has a plugin system\nthat allows it to interact directly with supported applications.\n\nOn Windows this generally means using COM to invoke the application, open\nthe content file and wait for the user to save and close the file. Because\neach application has different remote scripting capabilities and APIs,\neditor specific plugins must be written tailored to each supported\napplication and platform.\n\nThis system allows external editor to efficiently connect to running\napplications without relaunching them and therefore fully support MDI\nenvironments. The following applications currently have plugin support::\n\n Application Platform Plugin Module Name(s)\n ===================================================\n HomeSite Windows homesite5, homesite\n Dreamweaver Windows dreamweaver\t\n Photoshop Windows photoshp, photoshop\n MS Word Windows winword, word\n MS Excel Windows excel\n MS Powerpoint Windows powerpnt, powerpoint\n\nExternal editor will attempt to load a plugin for any application before\nusing the general editor control method. It does this by matching the\nname of the application executable file (sans extension) in the editor\ncommand line with the available plugins.\n\nBecause plugins do not require the path of the editor application to work,\nyou can simply specify the plugin module name for your editor in the\nconfiguration file if desired. For example, to specify Photoshop for all\nimage files, use add the following section to your config file\n(ZopeEdit.ini on Windows)::\n\n [content-type:image/*]\n editor=photoshop\n\nThis is only a shortcut and specifying the full application path will\nstill use the plugin where possible.\n\nPlugin Notes\n------------\n\nPhotoshop\n Photoshop's COM API is quite limited, and external editor cannot detect\n that you have closed a file until you exit the entire application (it\n can still detect saves). Therefore you may want to turn off DAV locking\n (use_locks=0) or borrow locks (always_borrow_locks=1) when using it.\n\nDreamweaver\n External editor cannot detect when you have finished editing a single\n file. Objects edited with Dreamweaver will remain locked on the server\n until you exit the application. As with Photoshop above, you may want\n to turn off locking for Dreamweaver.\n\nIf your favorite editor needs a plugin because the general support is\nnot good enough, please let me know. Keep in mind that I must be able to\nrun a copy of the application in order to develop a plugin for it. So,\nunless the application is free, or a full demo is available for download\nI won't be able to help much. Plugins are not difficult to write, and I\nencourage you to write one for your favorite editor, start by reading\none of the existing ones. I am happy to include third-party plugins with\nthe distribution.\n\nPermissions\n-----------\n\nExternal editing is governed by the permission \"Use external editor\".\nUsers with this permission can launch external editor from editable\nobjects. In order to save changes, users will need additional permissions\nappropriate for the objects they are editing.\n\nIf users wish to use the built-in locking support, they must have the\n\"WebDAV access\", \"WebDAV Lock items\" and \"WebDAV Unlock items\" permissions\nfor the objects they are editing.\n\nIf these permissions are not set in Zope, then the helper application will\nreceive unauthorized errors from Zope which it will present to the user.\n\nIntegrating with External Editor\n--------------------------------\n\nThe external editor product in zope installs a globally available object\nthat can format objects accessible through FTP/DAV for use by the helper\napplication. You can take advantage of this functionality easily in your\nown content management applications.\n\nSay you have an FTP editable object, \"document\", in a Zope folder named\n\"my_stuff\". The URL to view the object would be::\n\n http://zopeserver/my_stuff/document\n\nThe URL to kick off the external editor on this document would be::\n\n http://zopeserver/my_stuff/externalEdit_/document\n\nNow, this may look a bit odd to you if you are used to tacking views on to\nthe end of the URL. Because `externalEdit_` is required to work on Python\nScripts and Page Templates, which swallow the remaining path segments on\nthe URL following themselves, you must put the call to `externalEdit_`\n*directly before* the object to be edited. You could do this in ZPT using\nsome TAL in a Page Template like:\n\n.. code-block:: html\n\n \n Edit Locally\n \n\nAs an alternative, you can also pass the path the object you want to edit\ndirectly to the `externalEdit_` object when you call its index_html method.\nIt can be called either directly by URL or from a python script.\n`externalEdit_` will return the proper response data for the object to edit.\nYou can invoke it via a URL::\n\n http://zopeserver/externalEdit_?path=/my_stuff/document\n\nor via Python:\n\n.. code-block:: python\n\n return context.externalEdit_.index_html(\n context.REQUEST, context.RESPONSE, path='/my_stuff/document')\n\nWhen integrating External Editor with a CMS that already uses DAV\nlocks, it will, by default allow users to borrow locks made on the server\nafter displaying a confirmation dialog box. Although you can make this\nautomatic by specifying 'always_borrow_locks = 1' in the External Editor\nconfig file, it may be desireable to make this the default behavior when\nusing that server. To facilitate this, you can specify that locks\nshould be automatically borrowed in the URL (New in 0.7), i.e::\n\n http://zopeserver/my_stuff/externalEdit_/document?borrow_lock=1\n\nExternal Editor also defines a global method that you can call to insert\npencil icon links for appropriate objects. The method automatically checks\nif the object supports external editing and whether the user has the \"Use\nexternal editor\" permission for that object. If both are true, it returns\nthe HTML code to insert the external editor icon link. Otherwise it returns\nan empty string.\n\nThe method is 'externalEditLink_(object)'. The object argument is the\nobject to create the link for if appropriate. Here is some example page\ntemplate code that inserts links to objects in the current folder and the\nexternal editor icon where appropriate:\n\n.. code-block:: html\n\n