Index: openacs-4/packages/acs-core-docs/www/tutorial-categories.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-categories.html,v diff -u -N -r1.15 -r1.16 --- openacs-4/packages/acs-core-docs/www/tutorial-categories.html 7 Aug 2017 23:47:52 -0000 1.15 +++ openacs-4/packages/acs-core-docs/www/tutorial-categories.html 8 Nov 2017 09:42:12 -0000 1.16 @@ -1,22 +1,27 @@ -
You can associate any ACS Object with one or more categories. +
extended by Nima Mazloumi
+ </authorblurb> +You can associate any ACS Object with one or more categories. In this tutorial we'll show how to equip your application with user interface to take advantage of the Categories service. -
+
+
We'll start by installing the Categories service. Go to
/acs/admin
and install it. This step
won't be necessary for the users of your applications because you'll create
a dependency with the Package Manager which will take care that the
Categories service always gets installed when your application gets
installed.
-
+
+Now that we have installed the Categories service we can proceed to modifying our application so that it can take advantage of it. We'll do it in three steps: -
+
+The Categories service provides a mechanism to associate one or more category trees that are relevant to your application. One example of such tree is a tree of @@ -26,20 +31,25 @@ can take advantage of the Categories service there needs to be a way for administrators of your application to choose which category trees are applicable for the application. -
+
+
The way to achieve this is is to provide a link
to the Category Management pages. Add the following snippet to your
- /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/www/admin/index.tcl
+ /var/lib/aolserver/
file:
- $OPENACS_SERVICE_NAME
/packages/myfirstpackage/www/admin/index.tcl
+ ++set category_map_url [export_vars -base "[site_node::get_package_url -package_key categories]cadmin/one-object" { { object_id $package_id } }] -+
and the following snippet to your
- /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/www/admin/index.adp
+ /var/lib/aolserver/
file:
- $OPENACS_SERVICE_NAME
/packages/myfirstpackage/www/admin/index.adp
+ ++<a href="@category_map_url@">#categories.Site_wide_Categories#</a> -The link created by the above code (
category_map_url
) +
The link created by the above code (category_map_url
)
will take the admin to the generic
admin UI where he can pick category trees that make sense for this
application. The same UI also includes facilities to build and edit
@@ -61,7 +71,8 @@
form builder to note-edit.tcl
.
To achieve this we'll need to use the -extend
switch to the ad_form
command. Here's the "meat" of the
- note-edit.tcl
page:
++note-edit.tcl
page: +# extend the form to support categories set package_id [ad_conn package_id] @@ -81,15 +92,18 @@ ad_returnredirect "." ad_script_abort } -While the
category::ad_form::add_widgets
proc is taking +
While the category::ad_form::add_widgets
proc is taking
care to extend your form with associated categories you need to ensure that your items are mapped
to the corresponding category object yourself. Also since the categories package knows nothing from
your objects you have to keep the acs_named_objects
table updated with
any changes taking place. We use the items title so that they are listed in the categories browser by
title.
Make sure that you also delete these entries if your item is delete. Add this to - your corresponding delete page:
+ your corresponding delete page: ++db_dml delete_named_object "delete from acs_named_objects where object_id = :item_id" -
note-edit.tcl
requires a +
note-edit.tcl
requires a
note_id
to determine which record
should be deleted. It also looks for a confirmation variable, which
should initially be absert. If it is absent, we create a form to
@@ -101,7 +115,11 @@
note_id
and
confirm_p
. If confirm_p is present,
we delete the record, set redirection back to the index, and abort
-script execution.
The database commands:
[$OPENACS_SERVICE_NAME@yourserver www]$ emacs note-delete.xql
<?xml version="1.0"?> +script execution. + ++The database commands:
+[$OPENACS_SERVICE_NAME@yourserver www]$+emacs note-delete.xql
<?xml version="1.0"?> <queryset> <fullquery name="do_delete"> <querytext> @@ -113,29 +131,41 @@ select samplenote__name(:note_id) </querytext> </fullquery> -</queryset>And the adp page:
[$OPENACS_SERVICE_NAME@yourserver www]$emacs note-delete.adp
+</queryset>+And the adp page:
+[$OPENACS_SERVICE_NAME@yourserver www]$+emacs note-delete.adp
<master> <property name="title">@title@</property> <property name="context">{@title@}</property> <h2>@title@</h2> <formtemplate id="note-del-confirm"></formtemplate> -</form>The ADP is very simple. The +</form>
The ADP is very simple. The
formtemplate
tag outputs the HTML
form generated by the ad_form command with the matching name. Test it
by adding the new files in the APM and then deleting a few
- samplenotes.
We will now make categories optional on package instance level and + samplenotes.
+We will now make categories optional on package instance level and also add a configuration page to allow the package admin to enable/disable categories for his package. -
Go to the APM and create a number parameter with the name "EnableCategoriesP
"
- and the default value "0
".
Add the following lines to your index.tcl
:
+ +Go to the APM and create a number parameter with the name "
+EnableCategoriesP
" + and the default value "0
".Add the following lines to your
+index.tcl
:set return_url [ns_conn url] set use_categories_p [parameter::get -parameter "EnableCategoriesP"] -Change your to this:
++Change your to this:
+<a href=configure?<%=[export_vars -url {return_url}]%>>Configure</a> <if @use_categories_p@> <a href="@category_map_url@">#categories.Site_wide_Categories#</a> </if> -Now create a configure page
++Now create a configure page
+ad_page_contract { This page allows an admin to change the categories usage mode. } { @@ -160,41 +190,51 @@ ns_returnredirect $return_url } } -and add this to its corresponding ADP page
++and add this to its corresponding ADP page
+<master> <property name="title">@title@</property> <property name="context">@context@</property> <formtemplate id="categories_mode"></formtemplate> -Reference this page from your admin page
++Reference this page from your admin page
+#TCL: set return_url [ad_conn url] #ADP: <a href=configure?<%=[export_vars -url {return_url}]%>>Configure</a> -Change the
note-edit.tcl
:++Change the
+note-edit.tcl
:# Use Categories? set use_categories_p [parameter::get -parameter "EnableCategoriesP" -default 0] if { $use_categories_p == 1 } { # YOUR NEW FORM DEFINITION } else { # YOUR OLD FORM DEFINITION } -
You can filter your notes using categories. The below example does not support multiple + +
You can filter your notes using categories. The below example does not support multiple filters and displays a category in a flat format.
The first step is to
define the optional parameter category_id
for
- index.tcl
:
++index.tcl
: +ad_page_contract { YOUR TEXT } { YOURPARAMS {category_id:integer,optional {}} } -Now you have to check whether categories are enabled or not. If this is the case and a +
Now you have to check whether categories are enabled or not. If this is the case and a
category id is passed you need to extend your sql select query to support filtering. One
way would be to extend the mfp::note::get
proc to
support two more swiches -where_clause
and
- -from_clause
.
+-from_clause
. +set use_categories_p [parameter::get -parameter "EnableCategoriesP" -default 0] if { $use_categories_p == 1 && $category_id ne "" } { @@ -217,8 +257,10 @@ } else { # OLD STUFF } -Also you need to make sure that the user can see the corresponding categories. Add the following - snippet to the end of your index page:
++Also you need to make sure that the user can see the corresponding categories. Add the following + snippet to the end of your index page:
+# Site-Wide Categories if { $use_categories_p == 1} { set package_url [ad_conn package_url] @@ -250,7 +292,9 @@ set tree_name [category_tree::get_name $tree_id] } } -and to the corresponding index ADP page:
++and to the corresponding index ADP page:
+<if @use_categories_p@> <multiple name="categories"> <h2>@categories.tree_name@ @@ -259,12 +303,17 @@ </group> </multiple> <a href="@package_url@view?@YOURPARAMS@">All Items</if> -Finally you need a an
index.vuh
in your - www folder to rewrite the URLs correctly, the section called “Using .vuh files for pretty urls”:++Finally you need a an
+index.vuh
in your + www folder to rewrite the URLs correctly, the section called “Using .vuh files for pretty urls”:set url /[ad_conn extra_url] if {[regexp {^/+cat/+([^/]+)/*} $url ignore_whole category_id]} { rp_form_put category_id $category_id } rp_internal_redirect "/packages/YOURPACKAGE/www/index" -Now when ever the user select a category only notes that belong to this category are displayed.
Now when ever the user select a category only notes that belong to this category are displayed.
+