def undelete_category( self, trans, **kwd ):
     message = kwd.get( 'message', ''  )
     status = kwd.get( 'status', 'done' )
     id = kwd.get( 'id', None )
     if id:
         ids = util.listify( id )
         count = 0
         undeleted_categories = ""
         for category_id in ids:
             category = suc.get_category( trans.app, category_id )
             if category.deleted:
                 category.deleted = False
                 trans.sa_session.add( category )
                 trans.sa_session.flush()
                 # Update the Tool Shed's repository registry.
                 trans.app.repository_registry.add_category_entry( category )
                 count += 1
                 undeleted_categories += " %s" % category.name
         message = "Undeleted %d categories: %s" % ( count, undeleted_categories )
     else:
         message = "No category ids received for undeleting."
         status = 'error'
     trans.response.send_redirect( web.url_for( controller='admin',
                                                action='manage_categories',
                                                message=util.sanitize_text( message ),
                                                status='done' ) )

 def mark_category_deleted( self, trans, **kwd ):
     # TODO: We should probably eliminate the Category.deleted column since it really makes no
     # sense to mark a category as deleted (category names and descriptions can be changed instead).
     # If we do this, and the following 2 methods can be eliminated.
     message = kwd.get( 'message', ''  )
     status = kwd.get( 'status', 'done' )
     id = kwd.get( 'id', None )
     if id:
         ids = util.listify( id )
         message = "Deleted %d categories: " % len( ids )
         for category_id in ids:
             category = suc.get_category( trans.app, category_id )
             category.deleted = True
             trans.sa_session.add( category )
             trans.sa_session.flush()
             # Update the Tool Shed's repository registry.
             trans.app.repository_registry.remove_category_entry( category )
             message += " %s " % category.name
     else:
         message = "No category ids received for deleting."
         status = 'error'
     trans.response.send_redirect( web.url_for( controller='admin',
                                                action='manage_categories',
                                                message=util.sanitize_text( message ),
                                                status='done' ) )

 def purge_category( self, trans, **kwd ):
     # This method should only be called for a Category that has previously been deleted.
     # Purging a deleted Category deletes all of the following from the database:
     # - RepoitoryCategoryAssociations where category_id == Category.id
     message = kwd.get( 'message', ''  )
     status = kwd.get( 'status', 'done' )
     id = kwd.get( 'id', None )
     if id:
         ids = util.listify( id )
         count = 0
         purged_categories = ""
         message = "Purged %d categories: " % len( ids )
         for category_id in ids:
             category = suc.get_category( trans.app, category_id )
             if category.deleted:
                 # Delete RepositoryCategoryAssociations
                 for rca in category.repositories:
                     trans.sa_session.delete( rca )
                 trans.sa_session.flush()
                 purged_categories += " %s " % category.name
         message = "Purged %d categories: %s" % ( count, purged_categories )
     else:
         message = "No category ids received for purging."
         status = 'error'
     trans.response.send_redirect( web.url_for( controller='admin',
                                                action='manage_categories',
                                                message=util.sanitize_text( message ),
                                                status='done' ) )

 def undelete_category(self, trans, **kwd):
     message = escape(kwd.get("message", ""))
     id = kwd.get("id", None)
     if id:
         ids = util.listify(id)
         count = 0
         undeleted_categories = ""
         for category_id in ids:
             category = suc.get_category(trans.app, category_id)
             if category.deleted:
                 category.deleted = False
                 trans.sa_session.add(category)
                 trans.sa_session.flush()
                 # Update the Tool Shed's repository registry.
                 trans.app.repository_registry.add_category_entry(category)
                 count += 1
                 undeleted_categories += " %s" % category.name
         message = "Undeleted %d categories: %s" % (count, escape(undeleted_categories))
     else:
         message = "No category ids received for undeleting."
     trans.response.send_redirect(
         web.url_for(
             controller="admin", action="manage_categories", message=util.sanitize_text(message), status="done"
         )
     )

 def edit_category(self, trans, **kwd):
     '''Handle requests to edit TS category name or description'''
     message = escape(kwd.get('message', ''))
     status = kwd.get('status', 'done')
     id = kwd.get('id', None)
     if not id:
         message = "No category ids received for editing"
         trans.response.send_redirect(web.url_for(controller='admin',
                                                  action='manage_categories',
                                                  message=message,
                                                  status='error'))
     category = suc.get_category(trans.app, id)
     original_category_name = str(category.name)
     original_category_description = str(category.description)
     if kwd.get('edit_category_button', False):
         flush_needed = False
         new_name = kwd.get('name', '').strip()
         new_description = kwd.get('description', '').strip()
         if original_category_name != new_name:
             if not new_name:
                 message = 'Enter a valid name'
                 status = 'error'
             elif original_category_name != new_name and suc.get_category_by_name(trans.app, new_name):
                 message = 'A category with that name already exists'
                 status = 'error'
             else:
                 category.name = new_name
                 flush_needed = True
         if original_category_description != new_description:
             category.description = new_description
             if not flush_needed:
                 flush_needed = True
         if flush_needed:
             trans.sa_session.add(category)
             trans.sa_session.flush()
             if original_category_name != new_name:
                 # Update the Tool Shed's repository registry.
                 trans.app.repository_registry.edit_category_entry(original_category_name, new_name)
             message = "The information has been saved for category '%s'" % escape(category.name)
             status = 'done'
             return trans.response.send_redirect(web.url_for(controller='admin',
                                                             action='manage_categories',
                                                             message=message,
                                                             status=status))
     return trans.fill_template('/webapps/tool_shed/category/edit_category.mako',
                                category=category,
                                message=message,
                                status=status)

 def edit_category(self, trans, **kwd):
     message = escape(kwd.get("message", ""))
     status = kwd.get("status", "done")
     id = kwd.get("id", None)
     if not id:
         message = "No category ids received for editing"
         trans.response.send_redirect(
             web.url_for(controller="admin", action="manage_categories", message=message, status="error")
         )
     category = suc.get_category(trans.app, id)
     original_category_name = str(category.name)
     original_category_description = str(category.description)
     if kwd.get("edit_category_button", False):
         flush_needed = False
         new_name = kwd.get("name", "").strip()
         new_description = kwd.get("description", "").strip()
         if original_category_name != new_name:
             if not new_name:
                 message = "Enter a valid name"
                 status = "error"
             elif original_category_name != new_name and suc.get_category_by_name(trans.app, new_name):
                 message = "A category with that name already exists"
                 status = "error"
             else:
                 category.name = new_name
                 flush_needed = True
             if original_category_description != new_description:
                 category.description = new_description
                 if not flush_needed:
                     flush_needed = True
             if flush_needed:
                 trans.sa_session.add(category)
                 trans.sa_session.flush()
                 if original_category_name != new_name:
                     # Update the Tool Shed's repository registry.
                     trans.app.repository_registry.edit_category_entry(original_category_name, new_name)
                 message = "The information has been saved for category '%s'" % escape(category.name)
                 status = "done"
                 return trans.response.send_redirect(
                     web.url_for(controller="admin", action="manage_categories", message=message, status=status)
                 )
     return trans.fill_template(
         "/webapps/tool_shed/category/edit_category.mako", category=category, message=message, status=status
     )

    def show( self, trans, id, **kwd ):
        """
        GET /api/categories/{encoded_category_id}
        Returns a dictionary of information about a category.

        :param id: the encoded id of the Repository object
        """
        # Example URL: http://localhost:9009/api/categories/f9cad7b01a472135
        category = suc.get_category( trans.app, id )
        if category is None:
            category_dict = dict( message = 'Unable to locate category record for id %s.' % ( str( id ) ),
                                  status = 'error' )
            return category_dict
        category_dict = category.to_dict( view='element',
                                          value_mapper=self.__get_value_mapper( trans ) )
        category_dict[ 'url' ] = web.url_for( controller='categories',
                                              action='show',
                                              id=trans.security.encode_id( category.id ) )
        return category_dict

    def get_repositories( self, trans, category_id, **kwd ):
        """
        GET /api/categories/{encoded_category_id}/repositories
        Return information about the provided category and the repositories in that category.

        :param id: the encoded id of the Category object

        Example: GET localhost:9009/api/categories/f9cad7b01a472135/repositories
        """
        category = suc.get_category( self.app, category_id )
        if category is None:
            category_dict = dict( message='Unable to locate category record for id %s.' % ( str( id ) ),
                                  status='error' )
            return category_dict
        category_dict = category.to_dict( view='element',
                                          value_mapper=self.__get_value_mapper( trans ) )
        category_dict[ 'url' ] = web.url_for( controller='categories',
                                              action='show',
                                              id=trans.security.encode_id( category.id ) )
        repositories = suc.get_repositories_by_category( self.app, category.id )
        category_dict[ 'repositories' ] = repositories
        return category_dict

 def edit_category( self, trans, **kwd ):
     message = kwd.get( 'message', ''  )
     status = kwd.get( 'status', 'done' )
     id = kwd.get( 'id', None )
     if not id:
         message = "No category ids received for editing"
         trans.response.send_redirect( web.url_for( controller='admin',
                                                    action='manage_categories',
                                                    message=message,
                                                    status='error' ) )
     category = suc.get_category( trans, id )
     if kwd.get( 'edit_category_button', False ):
         new_name = kwd.get( 'name', '' ).strip()
         new_description = kwd.get( 'description', '' ).strip()
         if category.name != new_name or category.description != new_description:
             if not new_name:
                 message = 'Enter a valid name'
                 status = 'error'
             elif category.name != new_name and suc.get_category_by_name( trans, new_name ):
                 message = 'A category with that name already exists'
                 status = 'error'
             else:
                 category.name = new_name
                 category.description = new_description
                 trans.sa_session.add( category )
                 trans.sa_session.flush()
                 message = "The information has been saved for category '%s'" % ( category.name )
                 status = 'done'
                 return trans.response.send_redirect( web.url_for( controller='admin',
                                                                   action='manage_categories',
                                                                   message=message,
                                                                   status=status ) )
     return trans.fill_template( '/webapps/tool_shed/category/edit_category.mako',
                                 category=category,
                                 message=message,
                                 status=status )

 def browse_repositories( self, trans, **kwd ):
     # We add parameters to the keyword dict in this method in order to rename the param
     # with an "f-" prefix, simulating filtering by clicking a search link.  We have
     # to take this approach because the "-" character is illegal in HTTP requests.
     if 'operation' in kwd:
         operation = kwd[ 'operation' ].lower()
         if operation == "view_or_manage_repository":
             return trans.response.send_redirect( web.url_for( controller='repository',
                                                               action='browse_repositories',
                                                               **kwd ) )
         elif operation == "edit_repository":
             return trans.response.send_redirect( web.url_for( controller='repository',
                                                               action='edit_repository',
                                                               **kwd ) )
         elif operation == "repositories_by_user":
             # Eliminate the current filters if any exist.
             for k, v in kwd.items():
                 if k.startswith( 'f-' ):
                     del kwd[ k ]
             if 'user_id' in kwd:
                 user = suc.get_user( trans.app, kwd[ 'user_id' ] )
                 kwd[ 'f-email' ] = user.email
                 del kwd[ 'user_id' ]
             else:
                 # The received id is the repository id, so we need to get the id of the user
                 # that uploaded the repository.
                 repository_id = kwd.get( 'id', None )
                 repository = suc.get_repository_in_tool_shed( trans.app, repository_id )
                 kwd[ 'f-email' ] = repository.user.email
         elif operation == "repositories_by_category":
             # Eliminate the current filters if any exist.
             for k, v in kwd.items():
                 if k.startswith( 'f-' ):
                     del kwd[ k ]
             category_id = kwd.get( 'id', None )
             category = suc.get_category( trans.app, category_id )
             kwd[ 'f-Category.name' ] = category.name
         elif operation == "receive email alerts":
             if kwd[ 'id' ]:
                 kwd[ 'caller' ] = 'browse_repositories'
                 return trans.response.send_redirect( web.url_for( controller='repository',
                                                                   action='set_email_alerts',
                                                                   **kwd ) )
             else:
                 del kwd[ 'operation' ]
         elif operation == 'delete':
             return self.delete_repository( trans, **kwd )
         elif operation == "undelete":
             return self.undelete_repository( trans, **kwd )
     # The changeset_revision_select_field in the RepositoryGrid performs a refresh_on_change
     # which sends in request parameters like changeset_revison_1, changeset_revision_2, etc.  One
     # of the many select fields on the grid performed the refresh_on_change, so we loop through
     # all of the received values to see which value is not the repository tip.  If we find it, we
     # know the refresh_on_change occurred, and we have the necessary repository id and change set
     # revision to pass on.
     for k, v in kwd.items():
         changeset_revision_str = 'changeset_revision_'
         if k.startswith( changeset_revision_str ):
             repository_id = trans.security.encode_id( int( k.lstrip( changeset_revision_str ) ) )
             repository = suc.get_repository_in_tool_shed( tran.apps, repository_id )
             if repository.tip( trans.app ) != v:
                 return trans.response.send_redirect( web.url_for( controller='repository',
                                                                   action='browse_repositories',
                                                                   operation='view_or_manage_repository',
                                                                   id=trans.security.encode_id( repository.id ),
                                                                   changeset_revision=v ) )
     # Render the list view
     return self.repository_grid( trans, **kwd )