Index: openacs-4/packages/attachments/www/doc/index.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/attachments/www/doc/index.html,v
diff -u
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ openacs-4/packages/attachments/www/doc/index.html 12 Nov 2002 22:13:55 -0000 1.1
@@ -0,0 +1,96 @@
+
+
+
+
+
+
+
+
+
+- 1 Attachments
+- 1.1 Basics
+- 1.1.1 What does attachments do?
+- 1.1.2 At a high level, how does attachments
+work?
+
+- 1.2 Using attachments
+- 1.2.1 Mount attachments under your package
+- 1.2.2 Map an file-storage root folder to your package
+instance
+- 1.2.3 Attaching files to your objects
+- 1.2.3.1 Have your package check if attachments is
+mounted properly
+- 1.2.3.2 Get the attachment Url
+
+- 1.2.4 Viewing attached files
+
+
+
+1
+Attachments
+1.1 Basics
+1.1.1 What does attachments
+do?
+attachments is a service package that allows you to attach one or
+more file-storage files to any acs_object. attachments is
+mounted below a package that uses it, and the application provides links into
+the attachments package's UI.
1.1.2
+At a high level, how does attachments work?
+Before you can use the attachments package, each instance of your package
+must be mapped to a file-storage root folder.
The root folder
+is a "super folder" for all the files in that specific instance of
+file-storage, and it is created automatically when the file-storage pacakge is
+instanciated.
When a user wants to make an attachment to an object in
+your package, she is shown the contents of the file-storage root folder mapped
+to your package instance. The user is also given the option to upload a new
+file into file-storage to attach.
1.2
+Using attachments
+1.2.1 Mount attachments under your
+package
+The first step is to mount the attachments package under your
+package. In the site-map, you should create a new site-node
+(sub-folder) under your package called "attach".
+
"attach" is the standard URL, however URL this can be changed
+on a site-wide basis by changing the "RelativeUrl" parameter of
+any of the attachments packages (this works since there's only one
+instance of attachments in the entire system. The same instance is just
+re-mounted)
1.2.2 Map an
+file-storage root folder to your package instance
+First, you must select a file-storage instance that will provide the files
+you can attach. If you do not already have an instance of file-storage that
+you want to use for your pacakge instance, you must create one using the
+site-map.
Once you have a file-storage instance you wish to use, you
+must map the root folder of that file-storage instance with the package_id of
+the instance of your package.
Two utility procs to help you do
+this:
fs::get_root_folder and
+attachments::map_root_folder
1.2.3
+Attaching files to your objects
+1.2.3.1 Have your package check
+if attachments is mounted properly
+Most likely, you want your package to work even if the attachments package
+is not installed on the system or if attachments is not properly mounted. To
+do this, add the following proc to your package's API and wrap all calls to
+the attachments package with
+it:
ad_proc -private attachments_enabled_p {} {
+ set package_id [site_node_apm_integration::child_package_exists_p \
+ -package_key attachments
+ ]
+ }1.2.3.2 Get
+the attachment Url
+When you want to set up the link that the user can click on to attach
+something to an object, use the attachments::add_attachment_url proc, which
+will return the correct Url into the attachments package mounted under your
+package.
if {$attachments_enabled_p} {
+ if {$attach_p} {
+ set redirect_url [attachments::add_attachment_url \
+ -object_id $message_id \
+ -return_url $redirect_url \
+ -pretty_name "$subject"]
+ }
+ }forums redirects the user to the redirect_url, if the user
+chose to add an attachment to their
+posting.
1.2.4 Viewing attached
+files
+You can use the "attachments::get_attachments" proc to see the
+list of attachments to a given object.
+
Index: openacs-4/packages/attachments/www/doc/src/README.txt
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/attachments/www/doc/src/README.txt,v
diff -u
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ openacs-4/packages/attachments/www/doc/src/README.txt 12 Nov 2002 22:14:15 -0000 1.1
@@ -0,0 +1,30 @@
+
+What is this?
+-------------
+
+http://www.xmlmind.com/aptconvert.html
+
+
+How do I write APT?
+-------------------
+
+http://www.xmlmind.com/aptconvert/distrib/docs/userguidetoc.html
+
+
+I want to edit the documentation
+--------------------------------
+
+If you want to edit this documentation, please edit the APT source and
+either:
+
+1. get the "aptconvert" program, re-generate the html using the makefile,
+ and commit the new html
+
+or
+
+2. send the package maintainer(s) the edited APT source
+
+
+ thanks,
+
+ arjun
Index: openacs-4/packages/attachments/www/doc/src/attachments.apt
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/attachments/www/doc/src/attachments.apt,v
diff -u
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ openacs-4/packages/attachments/www/doc/src/attachments.apt 12 Nov 2002 22:14:15 -0000 1.1
@@ -0,0 +1,116 @@
+Attachments
+~~~~~~~~~~~
+
+* Basics
+~~~~~~~~
+
+** What does attachments do?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+ <<>> is a service package that allows you to attach one or more
+ file-storage files to any <<>>. <<>> is mounted below
+ a package that uses it, and the application provides links into the attachments
+ package's UI.
+
+
+
+** At a high level, how does attachments work?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+ Before you can use the attachments package, each instance of your package must be
+ mapped to a <<>>.
+
+ The root folder is a "super folder" for all the files in that specific instance of
+ file-storage, and it is created automatically when the file-storage
+ pacakge is instanciated.
+
+ When a user wants to make an attachment to an object in your package,
+ she is shown the contents of the file-storage root folder mapped to your
+ package instance. The user is also given the option to upload a new file
+ into file-storage to attach.
+
+
+* Using attachments
+~~~~~~~~~~~~~~~~~~~
+
+** Mount attachments under your package
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+ The first step is to mount the attachments package <> your
+ package. In the <<>>, you should create a new site-node
+ (sub-folder) under your package called "attach".
+
+ "attach" is the standard URL, however URL this can be changed on a
+ site-wide basis by changing the "RelativeUrl" parameter of <> of
+ the attachments packages (this works since there's only one instance
+ of attachments in the entire system. The same instance is just
+ re-mounted)
+
+
+** Map an file-storage root folder to your package instance
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+ First, you must select a file-storage instance that will provide
+ the files you can attach. If you do not already have an instance of file-storage
+ that you want to use for your pacakge instance, you must create one using the
+ site-map.
+
+ Once you have a file-storage instance you wish to use, you must map the
+ root folder of that file-storage instance with the package_id of the
+ instance of your package.
+
+ Two utility procs to help you do this:
+
+ <<>> and <<>>
+
+
+** Attaching files to your objects
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+*** Have your package check if attachments is mounted properly
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+ Most likely, you want your package to work even if the attachments
+ package is not installed on the system or if attachments is not
+ properly mounted. To do this, add the following proc to your package's
+ API and wrap all calls to the attachments package with it:
+
++-------------------------------------------------------------------------------
+ ad_proc -private attachments_enabled_p {} {
+ set package_id [site_node_apm_integration::child_package_exists_p \
+ -package_key attachments
+ ]
+ }
++-------------------------------------------------------------------------------
+
+*** Get the attachment Url
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+ When you want to set up the link that the user can click on to attach something
+ to an object, use the attachments::add_attachment_url proc, which will return
+ the correct Url into the attachments package mounted under your package.
+
++-------------------------------------------------------------------------------
+ if {$attachments_enabled_p} {
+ if {$attach_p} {
+ set redirect_url [attachments::add_attachment_url \
+ -object_id $message_id \
+ -return_url $redirect_url \
+ -pretty_name "$subject"]
+ }
+ }
++-------------------------------------------------------------------------------
+
+ forums redirects the user to the redirect_url, if the user chose to add an
+ attachment to their posting.
+
+
+** Viewing attached files
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+ You can use the "attachments::get_attachments" proc to see the list of attachments
+ to a given object.
+
+
+~~ $Id: attachments.apt,v 1.1 2002/11/12 22:14:15 arjun Exp $
+
Index: openacs-4/packages/attachments/www/doc/src/makefile
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/attachments/www/doc/src/makefile,v
diff -u
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ openacs-4/packages/attachments/www/doc/src/makefile 12 Nov 2002 22:14:15 -0000 1.1
@@ -0,0 +1,16 @@
+# $Id: makefile,v 1.1 2002/11/12 22:14:15 arjun Exp $
+
+TARGET=index
+SOURCES=attachments.apt
+
+$(TARGET): html
+
+html:
+ aptconvert -toc -pi html strict yes ../$(TARGET).html $(SOURCES)
+
+htmlclean:
+ rm -rf ../$(TARGET)*.html ../apt_*.gif ../*.css
+
+clean: htmlclean
+
+distclean: clean