Index: openacs-4/packages/attachments/www/doc/index.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/attachments/www/doc/index.adp,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/attachments/www/doc/index.adp 7 Aug 2017 23:48:04 -0000 1.2 @@ -0,0 +1,126 @@ + +{/doc/attachments {Attachments}} {} + + +

Contents

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

+

Release Notes

+

Please file bugs in the Bug Tracker.