[Checkins] SVN: zope2book/trunk/ Converted ExternalTools to rest
Hanno Schlichting
plone at hannosch.info
Mon Feb 16 17:55:10 EST 2009
Log message for revision 96611:
Converted ExternalTools to rest
Changed:
D zope2book/trunk/ExternalTools.stx
U zope2book/trunk/source/AppendixE.rst
A zope2book/trunk/source/ExternalTools.rst
U zope2book/trunk/source/index.rst
-=-
Deleted: zope2book/trunk/ExternalTools.stx
===================================================================
--- zope2book/trunk/ExternalTools.stx 2009-02-16 22:26:42 UTC (rev 96610)
+++ zope2book/trunk/ExternalTools.stx 2009-02-16 22:55:10 UTC (rev 96611)
@@ -1,643 +0,0 @@
-Managing Zope Objects Using External Tools
-
- So far, you've been working with Zope objects in your web browser
- via the Zope Management Interface. This chapter details how to use
- common non-browser-based common to access and modify your Zope
- content.
-
- Editing Zope content and code in the Zope Management Interface is
- sometimes painful, especially when dealing with Python code, DTML,
- ZPT, or even just HTML. The standard TEXTAREA text manipulation
- widget provided by most browsers has an extremely limited feature
- set: no syntax highlighting, no autoindent, no key rebindings, no
- WYSIWYG HTML editing, and sometimes not even a search and replace
- function!
-
- In short, people want to use their own tools, or at least more
- featureful tools, to work with Zope content.
-
- It is possible under most operating systems to use the text "cut and
- paste" facility (Ctrl-C, Ctrl-V under Windows, for example) to move
- text between traditional text/HTML editors and your browser, copying
- data back and forth between the Zope Management interface and your
- other tools. This is, at best, cumbersome.
-
- Luckily, Zope provides features that may allow you to interface Zope
- directly with your existing tools. This chapter describes these
- features, as well as the caveats for working with them.
-
- General Caveats
-
- Most external tools expect to deal with "file-like" content. Zope
- objects are not really files in the strict sense of the word so
- there are caveats to using external tools with Zope:
-
- - Zope data is not stored in files in the filesystem. Thus, tools
- which only work on files will not work with Zope without
- providing a "bridge" between the tool and Zope's file-like
- representation of its object database. This "bridge" is
- typically accomplished using Zope's FTP or WebDAV features.
-
- - Zope doesn't enforce any file extension rules when creating
- objects. Some tools don't deal well with objects that don't
- have file extensions in their names (notably Macromedia
- Dreamweaver). To avoid this issue, you may name your objects
- with file extensions according to their type (e.g. name all of
- your ZPT objects with an '.html' file extension), or use a tool
- that understands extensionless "files". However, this approach
- has numerous drawbacks.
-
- - Creating new objects can sometimes be problematic. Because Zope
- doesn't have a default object-type-to-file-extension policy, new
- content will often be created as the wrong "kind" of object.
- For example, if you upload an HTML file "foo.html" via FTP to a
- place where "foo.html" did not previously exist, it will be
- created (by default) as a DTML Document object, whereas you may
- want it to be created as a Zope Page Template. Zope provides a
- facility to specify the object type created on a per-folder and
- per-request basis (PUT_factory) that is detailed in this
- chapter.
-
- - External tools don't know about Zope object properties. If you
- modify an object in an external tool, it may forget its property
- list.
-
- - Some external tools have semantics that can drive Zope crazy.
- For instance, some like to create backup files with an id that
- is invalid for Zope. Also, some tools will do a move-then-copy
- when saving, which creates a new Zope object that is divorced
- from the history of the original object.
-
- - There is nowhere to send meaningful error messages. These
- integration features expect a finite set of errors defined by
- the protocol. Thus, the actual problem reported by Zope, such
- as a syntax error in a page template, cannot be displayed to the
- user.
-
- - The interactions between the tools and Zope can vary widely. On
- the client side, different versions of software have different
- bugs and features. For instance, using FTP under Emacs will
- sometimes work by default, but sometimes it needs to be
- configured. Also, Microsoft has many different implementations
- of DAV in Windows and Office, each with changes that make life
- difficult. Finally, Zope itself has substantially improved
- support between Zope 2.3 and Zope 2.7.
-
- - Finally, the semantics of Zope can interfere with the
- experience. The same file on your hardrive, when copied into
- www.zope.org and your local copy of Zope, will have different
- results. In the case of the CMF, Zope will actually alter what
- you saved (to add metadata).
-
- These caveats aside, you may use traditional file manipulation
- tools to manage most kinds of Zope objects.
-
- FTP and WebDAV
-
- Most Zope "file-like" objects like DTML Methods, DTML Documents,
- Zope Page Templates, Script (Python) objects and others can be
- edited with FTP and WebDAV. Many HTML and text editors support
- these protocols for editing documents on remote servers. Each of
- these protocols has advantages and disadvantages:
-
- FTP -- FTP is the File Transfer Protocol. FTP is used to
- transfer files from one computer to another. Many text editors
- and HTML editors support FTP.
-
- Some examples of editors and applications that support FTP are
- Homesite, KDE suite of applications (Kate, Quanta, Kwrite,
- Konqueror), Bluefish, and Dreamweaver.
-
- WebDAV -- "WebDAV":http://www.webdav.org/ is a new Internet
- protocol based on the Web's underlying protocol, HTTP. DAV
- stands for Distributed Authoring and Versioning. Because DAV is
- new, it may not be supported by as many text and HTML editors as
- FTP.
-
-
- Greg Stein's excellent 'webdav.org' site has an
- "FAQ":http://www.webdav.org/other/faq.html that introduces WebDAV.
- The FAQ provides a "comparison of DAV to
- FTP":http://www.webdav.org/other/faq.html#Q19.
-
- Using FTP to Manage Zope Content
-
- There are many popular FTP clients, and many web browsers like
- Netscape and Microsoft Internet Explorer come with FTP clients.
- Many text and HTML editors also directly support FTP. You can
- make use of these clients to manipulate Zope objects via FTP.
-
- Determining Your Zope's FTP Port
-
- In the chapter entitled "Using the Zope Management Interface", you
- determined the HTTP port of your Zope system by looking at Zope's
- start-up output. You can find your Zope's FTP port by following
- the same process::
-
- ------
- 2000-08-07T23:00:53 INFO(0) ZServer Medusa (V1.18) started at Mon Aug 7
- 16:00:53 2000
- Hostname: peanut
- Port:8080
-
- ------
- 2000-08-07T23:00:53 INFO(0) ZServer FTP server started at Mon Aug 7 16:00:53 2000
- Authorizer:None
- Hostname: peanut
- Port: 8021
- ------
- 2000-08-07T23:00:53 INFO(0) ZServer Monitor Server (V1.9) started on port 8099
-
- The startup log says that the Zope FTP server is listening to
- port 8021 on the machine named *peanut*. If Zope doesn't report
- an "FTP server started", it likely means that you need to turn
- Zope's FTP server on by editing the necessary incantation in your
- INSTANCE_HOME/etc/zope.conf as detailed in the chapter entitled
- "Installing and Starting Zope":InstallingZope.stx.
-
- Transferring Files with WS_FTP
-
- *WS_FTP* is a popular FTP client for Windows that you can use to
- transfer documents and files between Zope and your local
- computer. WS_FTP can be downloaded from the "Ipswitch Home
- Page":http://www.ipswitch.com/.
-
- Too transfer objects between your Zope server and local computer:
-
- - start WS_FTP and enter the Zope IP address or machine name
- and port information.
-
- - Click the "Connect" button.
-
- - Enter your management username and password for the
- Zope management interface.
-
- If you type in your username and password correctly, WS_FTP
- shows you what your Zope site looks like through FTP. There are
- folders and documents that correspond exactly to what your root
- Zope folder looks like through the web, as shown in the figure
- below.
-
- "Viewing the Zope object hierarchy through FTP":img:5-1:Figures/3-3.png
-
- Transferring files to and from Zope is straightforward when
- using WS_FTP. On the left-hand side of the WS_FTP window is a
- file selection box that represents files on your local machine.
-
- The file selection box on the right-hand side of the WS_FTP
- window represents objects in your Zope system. Transferring
- files from your computer to Zope or back again is a matter of
- selecting the file you want to transfer and clicking either the
- left arrow (download) or the right arrow (upload).
-
- You may transfer Zope objects to your local computer as files
- using WS_FTP. You may then edit them and upload them to Zope
- again when you're finished.
-
- Transferring files with KDE's Konqueror
-
- KDE is one of the many popular window manager for *nix. KDE
- comes with many applications that is FTP enabled. One such
- application is Konqueror. Konqueror is a file manager, and also
- works as a browser.
-
- To use Konqueror to transfer files to your zope site:
-
- - enter ftp://username@your.server.com:port
-
- - Enter your username and password when prompted.
-
- Once the correct password is presented, you can now transfer
- files to and from your zope site.
-
- With Konqueror, you can split the Konqueror view, and make it to
- mimic WS_FTP, or Midnight Commander (a popular menu based file
- manager), as shown in the figure below.
-
- "Viewing the Zope object hierarchy with Konqueror":img:5-2:Figures/konq.png
-
- We can also edit, create or delete some known Zope objects like
- folder or ZPT. For instance, to edit a file-like object, right
- click > Open With > Choose Application > Kate. You can start
- editing away. Kate will do the necessary when you save your
- edits.
-
- Transferring files with MS Internet Explorer 6+
-
- MS Internet Explorer version 6 and above can also do FTP. To use MS
- Internet Explorer to move files between your desktop and Zope:
-
- - enter ftp://your.server.com:port
-
- - click "File" > "Login as".
-
- - Enter your username and password when prompted.
-
- You can then create new Folders and transfer files between Zope
- and your desktop, as shown in the figure below.
-
- "Viewing the Zope object hierarchy with Konqueror":img:5-3:Figures/ie.png
-
-
- Remote Editing with FTP/DAV-Aware Editors
-
- Editing Zope Objects with Emacs FTP Modes
-
- Emacs is a very popular text editor. Emacs comes in two major
- "flavors", GNU Emacs and XEmacs. Both of these flavors of
- Emacs can work directly over FTP to manipulate Zope documents
- and other textual content.
-
- Emacs will let you treat any remote FTP system like any other
- local filesystem, making remote management of Zope content a
- fairly straightforward matter. More importantly, you need not
- leave Emacs in order to edit content that lives inside your
- Zope.
-
- To log into Zope, run Emacs. The file you visit to open an
- FTP connection depends on which text editor you are running:
- XEmacs or Emacs:
-
- Xemacs -- To visit a remote directory in XEmacs, press
- Ctrl-X D and enter a directory specification in the form::
-
- /user at server#port:/
-
- This will open a "dired" window to the / folder of the FTP
- server running on *server* and listening on port *port*.
-
- Emacs -- To visit a remote directory in Emacs, press
- Ctrl-X D and enter a directory specification in the form::
-
- /user at server port:/
-
- The literal space is inserted by holding down the
- Control key and the Q key, and then pressing the space "C-Q ".
-
- For the typical Zope installation with XEmacs, the filename to
- open up an FTP session with Zope is */user at localhost#8021:/*.
-
- Emacs will ask you for a password before displaying the
- directory contents. The directory contents of the root folder
- will look a little like the picture below:
-
- "Viewing the Zope Root Folder via
- ange-ftp":img:5-2:Figures/emacsftp.png
-
- You can visit any of these "files" (which are really Zope
- objects) by selecting them in the usual Emacs way: enter to
- select, modify the file, Ctrl-X S to save, etc. You can even
- create new "files" by visiting a file via "Ctrl-X Ctrl-F".
- New files will be created as DTML Document objects unless you
- have a PUT_factory (described below) installed to specify a
- different kind of initial object.
-
- The ftp program that ships with Microsoft Windows is
- incompatible with NTEmacs (the Windows NT version of GNU
- Emacs). To edit Zope objects via "ange-ftp" under NTEmacs, it
- requires that you have a special FTP program. This program
- ships with "Cygwin", a UNIX implementation for Windows. To
- use NTEmacs download and install
- "Cygwin":http://www.cygwin.org and add the following to your
- '.emacs' configuration file::
-
- (setq ange-ftp-ftp-program-name "/cygwin/bin/ftp.exe")
- (setq ange-ftp-try-passive-mode t)
- (setq ange-ftp-ftp-program-args '("-i" "-n" "-g" "-v" "--prompt" ""))
-
- For another perspective on using Emacs with Zope, see the
- "Zope.org HowTo written by Miklos
- Nemeth":http://www.zope.org/Members/nemeth/usingEmacsWithZope
- . There's even a "DTML mode for
- XEmacs":http://www.zope.org/Members/alburt/dtml_mode.html and
- a "ZWiki mode for
- Xemacs":http://www.zope.org/Members/alburt/zwiki_mode, both by
- "alburt".
-
- Caveats With FTP
-
- In addition to the general caveats listed above, using FTP
- with Zope has some unique caveats:
-
- - You need to be aware of passive mode for connecting to Zope.
-
- - The "move-then-copy" problem is most apparent when using
- Emacs' ange-ftp.
-
- Editing Zope objects with KDE Desktop
-
- KDE comes with many applications that is FTP aware. For example,
- Kate, Kwrite, Quanta, Konqueror, and many more.
-
- To start editing objects with Kate:
-
- - Click "File" > "Open".
-
- - Enter the location "ftp://user@server:port/"
-
- - Browse and select the zope object you want to edit.
-
- Once selected, you can edit to your heart's content, and click "File" >
- "Save" when done. Kate will save your edit to your zope server.
-
- "Viewing the Zope Root Folder via Kate/KDE desktop":img:5-2:Figures/kateftp.png
-
- With KDE, you can also mount zope onto your dialog box. To do that:
-
- - click "File" > "Open".
-
- - Right click on the listed locations in the "Open" dialog box
-
- - Click "Add Entry".
-
- - Fill in "Zope ftp" or any other description
- in the description field.
-
- - Enter the URL "ftp://user@server:port/" in the
- location field.
-
- - Select your icon.
-
- Now, you can edit zope objects in a single click.
-
- "Zope root exposed to KDE desktop":img:5-2:Figures/kdeopen.png
-
-
- Editing Zope Objects with WebDAV
-
- WebDAV is an extension to the HTTP protocol that provides
- features that allow users to concurrently author and edit
- content on websites. WebDAV offers features like locking,
- revision control, and the tagging of objects with properties.
- Because WebDAV's goals of through the web editing match some
- of the goals of Zope, Zope has supported the WebDAV protocol
- for a fairly long time.
-
- WebDAV is a newer Internet protocol compared to HTTP or FTP,
- so there are fewer clients that support it. There is,
- however, growing momentum behind the WebDAV movement and more
- clients are being developed rapidly.
-
- The WebDAV protocol is evolving quickly, and new features are
- being added all the time. You can use any WebDAV client to
- edit your Zope objects by simply pointing the client at your
- object's URL and editing it. For most clients, however, this
- will cause them to try to edit the *result* of rendering the
- document, not the *source*. For DTML or ZPT objects, this can
- be a problem.
-
- Until clients catch up to the latest WebDAV standard and
- understand the difference between the source of a document and
- its result, Zope offers a special HTTP server you can enable.
- To enable Zope's WebDAV source server, enter the following in zope.conf::
-
- <webdav-source-server>
- # valid keys are "address" and "force-connection-close"
- address 8022
- force-connection-close off
- </webdav-source-server>
-
-
- This server listens on a different port than your normal HTTP
- server and returns different, special source content for
- WebDAV requests that come in on that port.
-
- For more information about starting Zope with a WebDAV source
- port turned on, see the chapter entitled "Installing and
- Starting Zope":InstallingZope.stx. The "standard" WebDAV
- source port number (according to IANA) is 9800.
-
- Unfortunately, this entire discussion of source vs. rendered
- requests is too esoteric for most users, who will try the regular
- port. Instead of breaking, it will work in very unexpected
- ways, leading to confusion. Until DAV clients support the
- standard's provision for discovering the source URL, this
- distinction will have to be confronted.
-
- Note
-
- Zope 2.7 has optional support for returning the source
- version of a resource on the normal HTTP port. It does this
- by inspecting the user agent header of the HTTP request. If
- the user agent matches a string you have configured into
- your server settings, the source is returned.
-
- This is quite useful, as there are few cases in which
- authoring tools such as cadaver or Dreamweaver will want the
- rendered version. For more information on this optional
- support, read the section "Environment Variables That Affect
- Zope At Runtime" in "Installing and Starting
- Zope":InstallingZope.stx.
-
- Editing Zope objects with cadaver
-
- One program that supports WebDAV is a command-line tool named
- 'cadaver'. It is available for most UNIX systems (and Cygwin
- under Windows) from "WebDAV.org":http://www.webdav.org/cadaver/.
-
- It is typically invoked from a command-line using the command
- 'cadaver' against Zope's WebDAV "source port"::
-
- $ cadaver
- dav:!> open http://saints.homeunix.com:9800/
- Looking up hostname... Connecting to server... connected.
- Connecting to server... connected.
- dav:/> ls
- Listing collection `/': (reconnecting...done) succeeded.
- Coll: Control_Panel 0 Jun 14:03
- Coll: Examples 0 Jun 14:01
- Coll: ZopeBook 0 Jul 22:57
- Coll: temp 0 Jul 2002
- Coll: temp_folder 0 Jul 19:47
- Coll: tutorial 0 Jun 00:42
- acl_users 0 Dec 1998
- browser_id_manager 0 Jun 14:01
- index_html 93 Jul 01:01
- session_data_manager 0 Jun 14:01
- standard_error_message 1365 Jan 2001
- standard_html_footer 53 Jan 2001
- standard_html_header 80 Jan 2001
- standard_template.pt 282 Jun 14:02
- dav:/>
-
- Cadaver allows you to invoke an editor against files while
- inside the command-line facility::
-
- dav:/> edit index_html
- Connecting to server... connected.
- Locking `index_html': Authentication required for Zope on server `saints.homeunix.com':
- Username: admin
- Password:
- Retrying: succeeded.
- Downloading `/index_html' to /tmp/cadaver-edit-001320
- Progress: [=============================>] 100.0% of 93 bytes succeeded.
- Running editor: `vi /tmp/cadaver-edit-001320'...
-
- In this case, the 'index_html' object was pulled up for
- editing inside of the 'vi' text editor. You can specify your
- editor of choice on most UNIX-like systems by changing the
- EDITOR environment variable.
-
- You can also use cadaver to transfer files between your local
- directory and remote Zope, as described above for WS_FTP. For
- more advanced synchronization of data, the 'sitecopy' program
- can inspect your local and remote data and only transfer the
- changes, using FTP or DAV.
-
- Editing Zope objects with KDE applications
-
- KDE applications are WebDAV aware. Therefore, we can actually
- edit Zope objects from any of the KDE applications, such as konqueror, quanta, kate, et cetera.
-
- Using konqueror:
-
- - enter::
- webdav://your.server:port/
- in the konqueror location.
-
- - enter the username and password when prompted.
-
- - start editing when konqueror presents the Zope workspace.
-
- "Viewing the Zope object hierarchy with konquerorWebDAV":img:Figures/webdavkonq.png
-
- Using Kate:
-
- - Open Kate
-
- - Click File > Open
-
- - Enter::
- webdav://your.server:port/
- in "Open File dialog" "Location"
-
- - Browse for your file or start editing.
-
- "Kate Open File dialog box WebDAV":img:Figures/webdavkate.png
-
- Mounting WebDAV with Webdrive
-
- Webdrive is a commercial product that can mount WebDAV enable servers.
-
- To mount Zope with Webdrive:
-
- - start Webdrive, and fill in the necessary fields:
-
- - Enter server address and port number in the "Site Address/URL"
-
- - Enter username and password.
-
- - Uncheck Anonymous/Public login
-
- "webdrive connect dialog":img:Figures/webdav.png
-
- - start editing with your favorite application when presented with the Webdrive explorer/file manager. You can also browse the mounted
- zope drive using Microsoft explorer or file manager.
-
- "webdrive file manager":img:Figures/webdav1.png
-
-
- Other commercial applications, such as Macromedia Dreamweaver
- and Microsoft Office also support WebDAV. However, Microsoft products comes with a caveat; it may or may not work.
-
- For more information regarding programs which support the WebDAV
- protocol, see "WebDAV.org":http://www.webdav.org/.
-
- % Anonymous User - Feb. 20, 2004 9:50 am:
- The <a href="http://bluefish.openoffice.nl">Bluefish</a> free HTML editor also supports WebDAV.
-
- Using a PUT_factory to Specify the Type of Objects Created With FTP and DAV
-
- Because Zope is an "file-extensionless" system, it is often
- necessary to tell Zope to create a specific kind of object when
- an FTP or WebDAV client causes a new object to be entered into
- the Zope system. This action is typically called a "PUT" (the
- name of the FTP and DAV command that causes a file to be
- uploaded).
-
- The default policy for new Zope object creation is as follows::
-
- If the content type is Create this kind of object
- ---------------------- --------------------------
- 'text/{anything}' create a DTML Document
-
- 'image/{anything}' create an Image object
-
- '{anything else}' create a File object
-
- Zope allows you to override its default behavior by creating a
- Python Script or External Method named "PUT_factory" in the folder
- in and under which you want the new behavior to take effect.
-
- Creating Zope Page Templates and Script (Python) instead of DTML Document:
-
- - Create a file with the following::
-
- from Products.PageTemplates.ZopePageTemplate import ZopePageTemplate
- from Products.PythonScripts.PythonScript import PythonScript
-
- def PUT_factory( self, name, typ, body ):
- if typ=='text/x-python' or (body and body[0]=='#'):
- ob = PythonScript( name )
- elif typ.startswith('text'):
- ob = ZopePageTemplate(name, body, content_type='text/html')
- return ob
-
- - Save this file as 'PUT_factory.py' in Zope installation's 'Extensions' folder.
-
- - Create an External Method object in your root folder with::
-
- 'id' of 'PUT_factory'
- 'title' of "PUT factory for Page Templates"
- 'Module Name' of 'PUT_factory'
- 'Function Name' of 'PUT_factory'
-
- Once this External Method has been created in the root folder, any new file that is uploaded via FTP or DAV with a content-type of 'text/x-python ' will be created as a Script (Python) and anything else that has a content-type of 'text/{anything}' will be a Zope Page Template.
-
- Other kinds of objects, such as images, will continue to be created as
- specified by the default policy.
-
- Note that different PUT_factories may be created in different folders; each folder (and its subfolders) will inherit the policy of its particular
- PUT_factory.
-
- Using The External Editor Product
-
- Casey Duncan has created a useful Zope product named External
- Editor.
-
- It allows Zope users to use their browsers to navigate
- the Zope object hierarchy using the ZMI, launching the editor of
- their choice (for example, vim, Emacs, or Dreamweaver) for that
- particular object when you click a "pencil" icon next to the
- object's name.
-
- It has both a "client" component, which installs
- on your local machine and a "server" component, which installs on
- the server from which you run Zope.
-
- External Editor offers a bit of the "best of both worlds" when it
- comes to editing Zope content. You can use your existing text and
- HTML editing tools, manipulated by navigating the Zope Management
- Interface. It is available for download in "Casey's Zope.org
- area":http://www.zope.org/Members/Caseman/ExternalEditor.
-
- "A Zope With External Editor Installed":img:5-2:Figures/externaleditor.jpg
-
- Other Integration Facilities
-
- This chapter focused on FTP, DAV, and External Editor. These are
- the most popular and mature approaches for integration. However,
- other choices are available.
-
- For instance, Zope has long supported the use of HTTP PUT,
- originally implemented by Netscape as "Netscape Publishing". This
- allows Netscape Composer, Mozilla Composer, and Amaya to edit and
- create new pages, along with associated elements such as images
- and stylesheets.
-
- Also, Zope provides command-line tools such as 'load_site' that
- can interact with your Zope server.
-
- "Boa Constructor":http://boa-constructor.sourceforge.net/ is a
- Python IDE that has dedicated Zope support.
-
Modified: zope2book/trunk/source/AppendixE.rst
===================================================================
--- zope2book/trunk/source/AppendixE.rst 2009-02-16 22:26:42 UTC (rev 96610)
+++ zope2book/trunk/source/AppendixE.rst 2009-02-16 22:55:10 UTC (rev 96611)
@@ -1,5 +1,5 @@
-DTML Name Lookup Rules
-######################
+Appendix E: DTML Name Lookup Rules
+##################################
These are the rules which DTML uses to resolve names mentioned in `name=` and
`expr=` tags. The rules are in order from first to last in the search path.
Added: zope2book/trunk/source/ExternalTools.rst
===================================================================
--- zope2book/trunk/source/ExternalTools.rst (rev 0)
+++ zope2book/trunk/source/ExternalTools.rst 2009-02-16 22:55:10 UTC (rev 96611)
@@ -0,0 +1,480 @@
+Managing Zope Objects Using External Tools
+##########################################
+
+So far, you've been working with Zope objects in your web browser via the Zope
+Management Interface. This chapter details how to use common non-browser-based
+common to access and modify your Zope content.
+
+Editing Zope content and code in the Zope Management Interface is sometimes
+painful, especially when dealing with Python code, DTML, ZPT, or even just
+HTML. The standard TEXTAREA text manipulation widget provided by most browsers
+has an extremely limited feature set: no syntax highlighting, no auto-indent, no
+key re-bindings, no WYSIWYG HTML editing, and sometimes not even a search and
+replace function!
+
+In short, people want to use their own tools, or at least more feature-rich
+tools, to work with Zope content.
+
+It is possible under most operating systems to use the text "cut and paste"
+facility (Ctrl-C, Ctrl-V under Windows, for example) to move text between
+traditional text/HTML editors and your browser, copying data back and forth
+between the Zope Management interface and your other tools. This is, at best,
+cumbersome.
+
+Luckily, Zope provides features that may allow you to interface Zope directly
+with your existing tools. This chapter describes these features, as well as the
+caveats for working with them.
+
+General Caveats
+===============
+
+Most external tools expect to deal with "file-like" content. Zope objects are
+not really files in the strict sense of the word so there are caveats to using
+external tools with Zope:
+
+- Zope data is not stored in files in the filesystem. Thus, tools which only
+ work on files will not work with Zope without providing a "bridge" between
+ the tool and Zope's file-like representation of its object database. This
+ "bridge" is typically accomplished using Zope's FTP or WebDAV features.
+
+- Zope doesn't enforce any file extension rules when creating objects. Some
+ tools don't deal well with objects that don't have file extensions in their
+ names (notably Macromedia Dreamweaver). To avoid this issue, you may name
+ your objects with file extensions according to their type (e.g. name all of
+ your ZPT objects with an `.html` file extension), or use a tool that
+ understands extension-less "files". However, this approach has numerous
+ drawbacks.
+
+- Creating new objects can sometimes be problematic. Because Zope doesn't have
+ a default object-type-to-file-extension policy, new content will often be
+ created as the wrong "kind" of object. For example, if you upload an HTML
+ file "foo.html" via FTP to a place where "foo.html" did not previously exist,
+ it will be created (by default) as a DTML Document object, whereas you may
+ want it to be created as a Zope Page Template. Zope provides a facility to
+ specify the object type created on a per-folder and per-request basis
+ (PUT_factory) that is detailed in this chapter.
+
+- External tools don't know about Zope object properties. If you modify an
+ object in an external tool, it may forget its property list.
+
+- Some external tools have semantics that can drive Zope crazy. For instance,
+ some like to create backup files with an id that is invalid for Zope. Also,
+ some tools will do a move-then-copy when saving, which creates a new Zope
+ object that is divorced from the history of the original object.
+
+- There is nowhere to send meaningful error messages. These integration
+ features expect a finite set of errors defined by the protocol. Thus, the
+ actual problem reported by Zope, such as a syntax error in a page template,
+ cannot be displayed to the user.
+
+- The interactions between the tools and Zope can vary widely. On the client
+ side, different versions of software have different bugs and features. For
+ instance, using FTP under Emacs will sometimes work by default, but sometimes
+ it needs to be configured. Also, Microsoft has many different implementations
+ of DAV in Windows and Office, each with changes that make life difficult.
+
+- Finally, the semantics of Zope can interfere with the experience. The same
+ file on your hard drive, when copied into www.zope.org and your local copy of
+ Zope, will have different results. In the case of the CMF, Zope will actually
+ alter what you saved (to add metadata).
+
+These caveats aside, you may use traditional file manipulation tools to manage
+most kinds of Zope objects.
+
+FTP and WebDAV
+==============
+
+Most Zope "file-like" objects like DTML Methods, DTML Documents, Zope Page
+Templates, Script (Python) objects and others can be edited with FTP and
+WebDAV. Many HTML and text editors support these protocols for editing
+documents on remote servers. Each of these protocols has advantages and
+disadvantages:
+
+- FTP
+
+ FTP is the File Transfer Protocol. FTP is used to transfer files from one
+ computer to another. Many text editors and HTML editors support FTP.
+
+ Some examples of editors and applications that support FTP are Homesite,
+ KDE suite of applications (Kate, Quanta, Kwrite, Konqueror), Bluefish, and
+ Dreamweaver.
+
+- WebDAV
+
+ `WebDAV <http://www.webdav.org/>`_ is a new Internet protocol based on the
+ Web's underlying protocol, HTTP. DAV stands for Distributed Authoring and
+ Versioning. Because DAV is new, it may not be supported by as many text and
+ HTML editors as FTP.
+
+Using FTP to Manage Zope Content
+================================
+
+There are many popular FTP clients, and many web browsers like Netscape and
+Microsoft Internet Explorer come with FTP clients. Many text and HTML editors
+also directly support FTP. You can make use of these clients to manipulate Zope
+objects via FTP.
+
+Determining Your Zope's FTP Port
+++++++++++++++++++++++++++++++++
+
+In the chapter entitled "Using the Zope Management Interface", you determined
+the HTTP port of your Zope system by looking at Zope's start-up output. You can
+find your Zope's FTP port by following the same process::
+
+ ------
+ 2000-08-07T23:00:53 INFO(0) ZServer Medusa (V1.18) started at Mon Aug 7
+ 16:00:53 2000
+ Hostname: peanut
+ Port:8080
+
+ ------
+ 2000-08-07T23:00:53 INFO(0) ZServer FTP server started at Mon Aug 7 16:00:53 2000
+ Authorizer:None
+ Hostname: peanut
+ Port: 8021
+ ------
+ 2000-08-07T23:00:53 INFO(0) ZServer Monitor Server (V1.9) started on port 8099
+
+The startup log says that the Zope FTP server is listening to port 8021 on the
+machine named *peanut*>. If Zope doesn't report an "FTP server started", it
+likely means that you need to turn Zope's FTP server on by editing the
+necessary incantation in your INSTANCE_HOME/etc/zope.conf as detailed in the
+chapter entitled `Installing and Starting Zope <InstallingZope.stx>`_.
+
+Transferring Files with WS_FTP
+++++++++++++++++++++++++++++++
+
+*WS_FTP* is a popular FTP client for Windows that you can use to transfer
+documents and files between Zope and your local computer. WS_FTP can be
+downloaded from the `Ipswitch Home Page <http://www.ipswitch.com/>`_.
+
+Too transfer objects between your Zope server and local computer:
+
+- start WS_FTP and enter the Zope IP address or machine name and port
+ information.
+
+- Click the "Connect" button.
+
+- Enter your management username and password for the Zope management
+ interface.
+
+If you type in your username and password correctly, WS_FTP shows you what your
+Zope site looks like through FTP. There are folders and documents that
+correspond exactly to what your root Zope folder looks like through the web, as
+shown in the figure below.
+
+`Viewing the Zope object hierarchy through FTP <img:5-1:Figures/3-3.png>`_
+
+Transferring files to and from Zope is straightforward when using WS_FTP. On
+the left-hand side of the WS_FTP window is a file selection box that represents
+files on your local machine.
+
+The file selection box on the right-hand side of the WS_FTP window represents
+objects in your Zope system. Transferring files from your computer to Zope or
+back again is a matter of selecting the file you want to transfer and clicking
+either the left arrow (download) or the right arrow (upload).
+
+You may transfer Zope objects to your local computer as files using WS_FTP. You
+may then edit them and upload them to Zope again when you're finished.
+
+Transferring files with KDE's Konqueror
++++++++++++++++++++++++++++++++++++++++
+
+KDE is one of the many popular window manager for Unix. KDE comes with many
+applications that is FTP enabled. One such application is Konqueror. Konqueror
+is a file manager, and also works as a browser.
+
+To use Konqueror to transfer files to your zope site:
+
+- enter ftp://username@your.server.com:port
+
+- Enter your username and password when prompted.
+
+Once the correct password is presented, you can now transfer files to and from
+your zope site.
+
+With Konqueror, you can split the Konqueror view, and make it to mimic WS_FTP,
+or Midnight Commander (a popular menu based file manager), as shown in the
+figure below.
+
+`Viewing the Zope object hierarchy with Konqueror <img:5-2:Figures/konq.png>`_
+
+We can also edit, create or delete some known Zope objects like folder or ZPT.
+For instance, to edit a file-like object, right click > Open With > Choose
+Application > Kate. You can start editing away. Kate will do the necessary when
+you save your edits.
+
+Transferring files with MS Internet Explorer 6+
++++++++++++++++++++++++++++++++++++++++++++++++
+
+MS Internet Explorer version 6 and above can also do FTP. To use MS Internet
+Explorer to move files between your desktop and Zope:
+
+- enter ftp://your.server.com:port
+
+- click "File" > "Login as".
+
+- Enter your username and password when prompted.
+
+You can then create new Folders and transfer files between Zope and your
+desktop, as shown in the figure below.
+
+`Viewing the Zope object hierarchy with IE <img:5-3:Figures/ie.png>`_
+
+Remote Editing with FTP/DAV-Aware Editors
++++++++++++++++++++++++++++++++++++++++++
+
+Editing Zope Objects with Emacs FTP Modes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Emacs is a very popular text editor. Emacs comes in two major "flavors", GNU
+Emacs and XEmacs. Both of these flavors of Emacs can work directly over FTP to
+manipulate Zope documents and other textual content.
+
+Emacs will let you treat any remote FTP system like any other local filesystem,
+making remote management of Zope content a fairly straightforward matter. More
+importantly, you need not leave Emacs in order to edit content that lives
+inside your Zope.
+
+To log into Zope, run Emacs. The file you visit to open an FTP connection
+depends on which text editor you are running: XEmacs or Emacs:
+
+Xemacs
+ To visit a remote directory in XEmacs, press Ctrl-X D and enter a directory
+ specification in the form: `/user at server#port:/` This will open a "dired"
+ window to the / folder of the FTP server running on *server* and listening on
+ port *port*.
+
+Emacs
+ To visit a remote directory in Emacs, press Ctrl-X D and enter a directory
+ specification in the form: `/user at server port:/` The literal space is
+ inserted by holding down the Control key and the Q key, and then pressing the
+ space "C-Q".
+
+For the typical Zope installation with XEmacs, the filename to open up an FTP
+session with Zope is */user at localhost#8021:/*.
+
+Emacs will ask you for a password before displaying the directory contents. The
+directory contents of the root folder will look a little like the picture
+below:
+
+`Viewing the Zope Root Folder via ange-ftp <img:5-2:Figures/emacsftp.png>`_
+
+You can visit any of these "files" (which are really Zope objects) by selecting
+them in the usual Emacs way: enter to select, modify the file, Ctrl-X S to
+save, etc. You can even create new "files" by visiting a file via "Ctrl-X
+Ctrl-F". New files will be created as DTML Document objects unless you have a
+PUT_factory (described below) installed to specify a different kind of initial
+object.
+
+The ftp program that ships with Microsoft Windows is incompatible with NTEmacs
+(the Windows NT version of GNU Emacs). To edit Zope objects via "ange-ftp"
+under NTEmacs, it requires that you have a special FTP program. This program
+ships with "Cygwin", a UNIX implementation for Windows. To use NTEmacs download
+and install `Cygwin <http://www.cygwin.org>`_ and add the following to your
+`.emacs` configuration file::
+
+ (setq ange-ftp-ftp-program-name "/cygwin/bin/ftp.exe")
+ (setq ange-ftp-try-passive-mode t)
+ (setq ange-ftp-ftp-program-args '("-i" "-n" "-g" "-v" "--prompt" ""))
+
+Caveats With FTP
+~~~~~~~~~~~~~~~~
+
+In addition to the general caveats listed above, using FTP with Zope has some
+unique caveats:
+
+- You need to be aware of passive mode for connecting to Zope.
+
+- The "move-then-copy" problem is most apparent when using Emacs' ange-ftp.
+
+Editing Zope objects with KDE Desktop
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+KDE comes with many applications that is FTP aware. For example, Kate, Kwrite,
+Quanta, Konqueror, and many more.
+
+To start editing objects with Kate:
+
+- Click "File" > "Open".
+
+- Enter the location "ftp://user@server:port/"
+
+- Browse and select the zope object you want to edit.
+
+Once selected, you can edit to your heart's content, and click "File" > "Save"
+when done. Kate will save your edit to your zope server.
+
+`Viewing the Zope Root Folder via Kate/KDE desktop <img:5-2:Figures/kateftp.png>`_
+
+With KDE, you can also mount zope onto your dialog box. To do that:
+
+- click "File" > "Open".
+
+- Right click on the listed locations in the "Open" dialog box
+
+- Click "Add Entry".
+
+- Fill in "Zope ftp" or any other description in the description field.
+
+- Enter the URL "ftp://user@server:port/" in the location field.
+
+- Select your icon.
+
+Now, you can edit zope objects in a single click.
+
+`Zope root exposed to KDE desktop <img:5-2:Figures/kdeopen.png>`_
+
+
+Editing Zope Objects with WebDAV
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+WebDAV is an extension to the HTTP protocol that provides features that allow
+users to concurrently author and edit content on websites. WebDAV offers
+features like locking, revision control, and the tagging of objects with
+properties. Because WebDAV's goals of through the web editing match some of the
+goals of Zope, Zope has supported the WebDAV protocol for a fairly long time.
+
+WebDAV is a newer Internet protocol compared to HTTP or FTP, so there are fewer
+clients that support it. There is, however, growing momentum behind the WebDAV
+movement and more clients are being developed rapidly.
+
+The WebDAV protocol is evolving quickly, and new features are being added all
+the time. You can use any WebDAV client to edit your Zope objects by simply
+pointing the client at your object's URL and editing it. For most clients,
+however, this will cause them to try to edit the *result* of rendering the
+document, not the *source*>. For DTML or ZPT objects, this can be a problem.
+
+Until clients catch up to the latest WebDAV standard and understand the
+difference between the source of a document and its result, Zope offers a
+special HTTP server you can enable. To enable Zope's WebDAV source server,
+enter the following in zope.conf::
+
+ <webdav-source-server>
+ # valid keys are "address" and "force-connection-close"
+ address 8022
+ force-connection-close off
+ </webdav-source-server>
+
+This server listens on a different port than your normal HTTP server and
+returns different, special source content for WebDAV requests that come in on
+that port.
+
+For more information about starting Zope with a WebDAV source port turned on,
+see the chapter entitled `Installing and Starting Zope <InstallingZope.stx>`_.
+The "standard" WebDAV source port number (according to IANA) is 9800.
+
+Unfortunately, this entire discussion of source vs. rendered requests is too
+esoteric for most users, who will try the regular port. Instead of breaking, it
+will work in very unexpected ways, leading to confusion. Until DAV clients
+support the standard's provision for discovering the source URL, this
+distinction will have to be confronted.
+
+Note
+----
+
+Zope has optional support for returning the source version of a resource on the
+normal HTTP port. It does this by inspecting the user agent header of the HTTP
+request. If the user agent matches a string you have configured into your
+server settings, the source is returned.
+
+This is quite useful, as there are few cases in which authoring tools such as
+cadaver or Dreamweaver will want the rendered version. For more information on
+this optional support, read the section "Environment Variables That Affect Zope
+At Runtime" in `Installing and Starting Zope <InstallingZope.stx>`_.
+
+Editing Zope objects with cadaver
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+One program that supports WebDAV is a command-line tool named `cadaver`. It is
+available for most UNIX systems (and Cygwin under Windows) from `WebDAV.org
+<http://www.webdav.org/cadaver/>`_.
+
+It is typically invoked from a command-line using the command `cadaver` against
+Zope's WebDAV "source port"::
+
+ $ cadaver
+ dav:!> open http://saints.homeunix.com:9800/
+ Looking up hostname... Connecting to server... connected.
+ Connecting to server... connected.
+ dav:/> ls
+ Listing collection `/': (reconnecting...done) succeeded.
+ Coll: Control_Panel 0 Jun 14:03
+ Coll: ZopeBook 0 Jul 22:57
+ Coll: temp_folder 0 Jul 19:47
+ Coll: tutorial 0 Jun 00:42
+ acl_users 0 Dec 2009
+ browser_id_manager 0 Jun 14:01
+ index_html 93 Jul 01:01
+ session_data_manager 0 Jun 14:01
+ standard_error_message 1365 Jan 2009
+ dav:/>
+
+Cadaver allows you to invoke an editor against files while inside the
+command-line facility::
+
+ dav:/> edit index_html
+ Connecting to server... connected.
+ Locking `index_html': Authentication required for Zope on server `saints.homeunix.com':
+ Username: admin
+ Password:
+ Retrying: succeeded.
+ Downloading `/index_html' to /tmp/cadaver-edit-001320
+ Progress: [=============================>] 100.0% of 93 bytes succeeded.
+ Running editor: `vi /tmp/cadaver-edit-001320'...
+
+In this case, the `index_html` object was pulled up for editing inside of the
+`vi` text editor. You can specify your editor of choice on most UNIX-like
+systems by changing the EDITOR environment variable.
+
+You can also use cadaver to transfer files between your local directory and
+remote Zope, as described above for WS_FTP. For more advanced synchronization
+of data, the `sitecopy` program can inspect your local and remote data and only
+transfer the changes, using FTP or DAV.
+
+Editing Zope objects with KDE applications
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+KDE applications are WebDAV aware. Therefore, we can actually edit Zope objects
+from any of the KDE applications, such as konqueror, quanta, kate, et cetera.
+
+Using konqueror:
+
+- enter::
+
+ webdav://your.server:port/ in the konqueror location.
+
+- enter the username and password when prompted.
+
+- start editing when konqueror presents the Zope workspace.
+
+`Viewing the Zope object hierarchy with konquerorWebDAV <img:Figures/webdavkonq.png>`_
+
+
+Using Kate:
+
+- Open Kate
+
+- Click File > Open
+
+- Enter::
+
+ webdav://your.server:port/
+
+ in "Open File dialog" "Location"
+
+- Browse for your file or start editing.
+
+`Kate Open File dialog box WebDAV <img:Figures/webdavkate.png>`_
+
+
+Other Integration Facilities
+============================
+
+This chapter focused on FTP and DAV. These are the most popular and mature
+approaches for integration. However, other choices are available.
+
+For instance, Zope has long supported the use of HTTP PUT, originally
+implemented by Netscape as "Netscape Publishing". This allows Netscape
+Composer, Mozilla Composer, and Amaya to edit and create new pages, along with
+associated elements such as images and stylesheets.
Modified: zope2book/trunk/source/index.rst
===================================================================
--- zope2book/trunk/source/index.rst 2009-02-16 22:26:42 UTC (rev 96610)
+++ zope2book/trunk/source/index.rst 2009-02-16 22:55:10 UTC (rev 96611)
@@ -33,6 +33,7 @@
VirtualHosting.rst
Sessions.rst
ZEO.rst
+ ExternalTools.rst
MaintainingZope.rst
AppendixA.rst
AppendixB.rst
More information about the Checkins
mailing list