Mar 07 2008

Documenting Castle - Proposed Structure

Tag: Open Source — Symon Rottem @ 2:17 pm

This documenting thing is something of a challenge. I’ve been working industriously away on groking the DocBook schema a little better, figuring out the transformation tools and how to automate them while also trying to come up with a structure that makes sense for presenting the data that already exists.

To get myself off the ground I’ve elected to restructure the existing MonoRail 1.0 RC2 documentation first since there are so many people out there currently using it and it makes sense for my team. Certainly it makes sense to get the trunk code documented quickly too, but I know the RC2 stuff better at the moment, so that’s my starting point, like it or not.

Below is the chapter/section layout I’m proposing for MonoRail. This layout covers pretty much everything that’s in the existing user guide documentation and getting started guide. I think it exposes most of the concepts and addresses the concerns of those who are getting to know MonoRail in a top down fashion so the simple stuff is presented first and the concepts follow each other in a relatively intuitive fashion and it can be expanded on fairly easily. Of course, that’s just my take and you may not agree - feel free to provide constructive feedback and I’ll take it into consideration.

I’ll be posting more on the the process I’m going to use for generating the documentation shortly and should have a draft HTML version of the content based on the layout below using the existing content from the website in the next few days, so stay tuned!

1. Introduction
 1.1. Overview
 1.2. Background
  1.2.1. What is MVC
  1.2.2. Convention Over Configuration
 1.3. Why Use MonoRail
 1.4. How It Works
 1.5. Licence Information
 1.6. Support
2. Getting Started
 2.1. Requirements
 2.2. Creating the Project Skeleton
  2.2.1. Using the MonoRail Project Wizard
  2.2.2. Creating the Project Manually
 2.3. Controllers and Views
  2.3.1. Your First Controller and View
  2.3.2. Setting the Layout and Resuce
  2.3.3. Creating the Index View and Action
  2.3.4. Creating the Layout
  2.3.5. Seeing the Results
  2.3.6. Passing Values to the View
  2.3.7. Creating a Rescue
 2.4. Data Binding
  2.4.1. Simple Parameters
  2.4.2. Complex Objects
 2.5. Integrating with ActiveRecord
  2.5.1. Adding Assemblies
  2.5.2. Configuration
  2.5.3. Building the Model
  2.5.4. Initializing the Handler
  2.5.5. ActiveRecord Sacffolding
  2.5.6. Creating a CRUD Page Using DataBind
 2.6. Final Comments
3. Installation
 3.1. Running Under IIS
 3.2. Using Casini
 3.3. Mono with XSP
 3.4. Mono with Apache
  3.4.1. Configuration
  3.4.2. Apache Httpd2
  3.4.3. Application Deployment
 3.5. Deploying to a Shared Host
4. Configuration
 4.1. Formal Definition
5. Controllers
 5.1. Naming Convention
 5.2. Areas
 5.3. Actions
  5.3.1. Default Action
 5.4. Redirecting
 5.5. Data Binding
  5.5.1. The SmartDispatchController
  5.5.2. Other Useful Properties
  5.5.3. Simple Parameter Binding
  5.5.4. Custom Binding
 5.6. Wizards
  5.6.1. Wizard Controllers
  5.6.2. Wizard Action Provider
  5.6.3. Steps
  5.6.4. Nested Actions
  5.6.5. DoNavigate
  5.6.6. Conditional Steps
  5.6.7. The WizardHelper
  5.6.8. Windsor Integration
6. Views
 6.1. Folder Structure Convention
 6.2. Selecting a View to Render
 6.3. Passing Values to a View
  6.3.1. The PropertyBag
  6.3.2. Flash
 6.4. Shared Views
 6.5. Cancelling a View
 6.6. Accessing Values Passed by the Controller
 6.7. View Engines
 6.8. Javascript and Ajax
7. View Components
 7.1. Creating a View Component
 7.2. Using View Components
 7.3. Passing Parameters
 7.4. Block and Nested Sections
 7.5. Built In View Components
  7.5.1. CaptureFor
  7.5.2. SecurityComponent
8. Filters
 8.1. Creating a Filter
 8.2. Ordering
 8.3. Skipping Filters
 8.4. Passing Parameters
 8.5. Block and Nested Sections
9. Layouts
10. Rescues
11. Authentication and Authorization
 11.1. Forms Authentication
 11.2. Filters
 11.3. Using PrincipalPermission
 11.4. The SecurityView Component
12. Helpers
 12.1. Built In Helpers
  12.1.1. AjaxHelper
  12.1.2. DateFormatHelper
  12.1.3. Effects2Helper
  12.1.4. FormHelper
  12.1.5. HtmlHelper
  12.1.6. PaginationHelper
  12.1.7. ValidationHelper
  12.1.8. WizardHelper
13. Resources and Localization
 13.1. Using Resources
 13.2. Setting Up the Current Culure
 13.3. Localization
14. Sending Email
15. Unit Testing
 15.1. The TestSupport Assembly
 15.2. Exposing the Website Application Directory
  15.2.1. Overriding GetPhysicalDir
  15.2.2. External Configuration
16. Integrations
 16.1. ActiveRecord
  16.1.1. Scaffolding
 16.2. Windsor Container
17. Advanced Topics
 17.1. Routing
  17.1.1. Routing
  17.1.2. Root Directory Mapping Workaround
 17.2. Dynamic Actions
  17.2.1. Dynamic Action Providers
 17.3. Scaffolding
 17.4. Extensions
  17.4.1. Custom Session Extension
  17.4.2. Exception Chaining Extension
  17.4.3. Creating Your Own Extensions
 17.5. Service Architecture
 17.6. Custom Bindable Parameters
 17.7. Using Resources to Store Views

Edit: After a comment on the mailing list from Erik Dahlstrand I noticed that somehow I’d forgotten to include the entire section on Helpers in the above structure so I’ve updated the list to include it.