README.rdoc in fcrepo_admin-0.4.1 vs README.rdoc in fcrepo_admin-0.5.0

- old
+ new

@@ -1,20 +1,20 @@ -= Hydra Administrative Tool for a Fedora Repository +== Hydra Administrative Tool for a Fedora Repository A Rails engine providing an administrative interface to a Fedora Commons repository built on the Hydra project framework. -== Status +=== Status This project should be considered *experimental* and not ready for production deployment. Versions earlier than 1.0 may change API and/or UI without notice or regard for backward compatibility. -== Requirements +=== Requirements fcrepo_admin is designed for installation on hydra-head 6.0 or higher (requires active-fedora 6.1 or higher). See https://github.com/projecthydra/hydra-head/wiki/Installation-Prerequisites. -== Installation +=== Installation (In the future, we hope to automate some of these tasks with a generator.) * Add to gemfile @@ -36,11 +36,11 @@ mount FcrepoAdmin::Engine => '/', :as=> 'fcrepo_admin' You may use any mount point (except perhaps <code>'/catalog'</code>). All routes include <code>objects</code> as a subpath. -* Add CanCan action aliases (version >= 0.4.0) +* Add CanCan action aliases (fcrepo_admin >= 0.4.0) In your Ability class (app/models/ability.rb) include the FcrepoAdmin::Ability module, for example: class Ability include Hydra::Ability @@ -49,11 +49,11 @@ end FcrepoAdmin::Ability defines action aliases for permissions which are enforced on (ActiveFedora::Base) objects. If your application defines action aliases, please check FcrepoAdmin::Ability for conflicts as aliases are global. -* Add Javascript (not required for version >= 0.4.0) +* Add Javascript (fcrepo_admin < 0.4.0) In app/assets/javascripts/application.js add: //= require bootstrap-tab @@ -73,16 +73,33 @@ To enable access to the Fedora audit trail data through the fcrepo_admin UI, include the ActiveFedora::Auditable mixin in your ActiveFedora models: include ActiveFedora::Auditable -== Overriding fcrepo_admin behaviors +=== Overriding fcrepo_admin behaviors -The following are examples of possible customizations. This list is not necessarily exhaustive. +==== Configurable settings (fcrepo_admin >= 0.5.0) -=== Helpers +To override default configurable settings for fcrepo_admin, create an initializer at config/initializers/fcrepo_admin.rb. +You should start with this content: + module YourApp + class Application < Rails::Application + config.before_initialize do + # Customized settings will go here + end + end + end + +Refer to the default configuration settings at https://github.com/projecthydra/fcrepo-admin/blob/master/lib/fcrepo_admin.rb. + +All configuration options are set by module methods prefixed by FcrepoAdmin, for example: + + FcrepoAdmin.read_only = true + +==== Helpers + Override objects helpers by creating app/helpers/fcrepo_admin/objects_helper.rb with this content: module FcrepoAdmin::ObjectsHelper include FcrepoAdmin::Helpers::ObjectsHelperBehavior # override methods here @@ -95,19 +112,40 @@ module FcrepoAdmin::DatastreamsHelper include FcrepoAdmin::Helpers::DatastreamsHelperBehavior # override methods here end -=== Context Navigation Menus +==== Context Navigation Menus +===== fcrepo_admin >= 0.5.0 + +The configuration settings that control the items on the context menus are: + + FcrepoAdmin.object_nav_items = [:pid, :summary, :datastreams, :permissions, :associations, :audit_trail] + FcrepoAdmin.datastream_nav_items = [:dsid, :version, :current_version, :summary, :content, :download, :edit, :upload, :history] + +Each setting takes an array of symbols representing the items. You can start by copying the default values shown above. +If you simply want to rearrange or remove items, then just modify the default arrays. + +To add a custom navigation item, start by adding your own symbol to the approriate array setting. Then override the +appropriate helper method (see section above on overriding fcrepo_admin helpers) -- for object context nav, override +#custom_object_nav_item in ObjectsHelper; for datastream context nav, override #custom_datastream_nav_item +in DatastreamsHelper. + +Each method takes a single symbol argument and should return either nil (meaning no menu item is to be added) or the *content* +of a menu item. Do not include the <li></li> wrapper. You may want to use link_to_unless_current and/or put a condition on +the menu item (i.e., so that nil is returned if the condition is not met). + +===== fcrepo_admin < 0.5.0 + The contents of the object context navigation menu can be customized by overriding the #object_context_nav_items helper method, or by copying and modifying the partial fcrepo_admin/objects/context_nav_items. The contents of the datastream context navigation menu can be customized by overriding the #datastream_context_nav_items helper method, or by copying and modifying the partial fcrepo_admin/datastreams/context_nav_items. -=== Controllers +==== Controllers To override or extend controller behaviors, please consult Rails engine documentation and guides, such as http://edgeguides.rubyonrails.org/engines.html. IMPORTANT: If you add a non-RESTful action to a controller, you will probably have to add a CanCan action alias @@ -122,24 +160,31 @@ alias_action :my_method, :to => :read end end -== Internationalization (i18n) +==== Read-only mode +To suppress mutating behaviors (i.e, routes, nav items, etc.) regardless of user permissions, +add this configuration setting: + + FcrepoAdmin.read_only = true + +=== Internationalization (i18n) + An effort has been made to support i18n on headings, menus, etc. See https://github.com/projecthydra/fcrepo-admin/blob/master/config/locales/fcrepo_admin.en.yml for the keys and consult the Rails documentation on how to provide your own translations or alternate text values. -== Contributing +=== Contributing * Consider first posting to hydra-tech@googlegroups.com with a question or bug report, or submit an issue to the Github issue tracker at https://github.com/projecthydra/fcrepo-admin/issues. * Fork the git repository, create a feature branch, make your changes, and submit a pull request. It is preferable for all changes to be made in one commit, if possible. Thanks! -== License +=== License See the LICENSE file in the root directory of the project for copyright and license information. Licenses for code copied from other projects will be included in source files as required.