[prev in list] [next in list] [prev in thread] [next in thread] 

List:       bricolage-devel
Subject:    [Bricolage-Devel] Re: [Bricolage-Commits] Lots of notes.
From:       Mark Jaroski <mark () geekhive ! net>
Date:       2003-04-07 8:10:36
[Download RAW message or body]

The odd thing is that when I wrote this piece in the first
place I didn't really mean for it to be the technical spec.
It was just the notes from a particular diagram.  I think
there are going to be something like 10 more of them before
we're done.

David Wheeler wrote:
> Log Message:
> -----------
> Lots of notes. I updated some of what was written before, and added some
> comments and questions. Then I added a whole new section that's just my
> thoughts. Please read over this stuff and look at the accompanying UML
> documents. We'll start work on integrating all this stuff this week.
> 
> Modified Files:
> --------------
>     /cvsroot/bricolage/design-docs/ElementRevision:
>         TechnicalSpec.pod
> Index: TechnicalSpec.pod
> ===================================================================
> RCS file: /cvsroot/bricolage/design-docs/ElementRevision/TechnicalSpec.pod,v
> retrieving revision 1.10
> retrieving revision 1.11
> diff -u -w -d -r1.10 -r1.11
> --- TechnicalSpec.pod	25 Mar 2003 18:33:51 -0000	1.10
> +++ TechnicalSpec.pod	6 Apr 2003 21:59:29 -0000	1.11
> @@ -172,7 +172,7 @@
>  
>  =item *
>  
> -*does not* inherit from Element or it's subclasses
> +I<does not> inherit from Element or its subclasses
>  
>  =item *
>  
> @@ -181,7 +181,7 @@
>  =item *
>  
>  declares an interface for managing upper and lower bound (and
> -possibly other) constraints for it's subclassed Field objects
> +possibly other) constraints for its subclassed Field objects
>  
>  =item *
>  
> @@ -223,6 +223,8 @@
>  
>  ignores (or throws an exception to) the publish operation
>  
> +[Huh? Why would it do that? -DW]
> +
>  =back
>  
>  =head3 NumberField
> @@ -260,6 +262,9 @@
>  
>  ignores (or throws an exception to) the publish operation
>  
> +[This object should essentially be a DateTime.pm object -- probably
> +a subclass. See L<http://datetime.perl.org/>. -DW]
> +
>  =back
>  
>  =head3 URLField
> @@ -281,10 +286,15 @@
>  =item *
>  
>  interprets validity as having URL data for which a UserAgent
> -receives an HTTP response code of 200
> +receives an HTTP response code of 200 [This should be configurable,
> +as it could be quite an expensive operation, or impossible behind
> +a firewall. -DW]
>  
>  =back
>  
> +[This object should essentially be a URI.pm object -- probably
> +a subclass. See L<http://search.cpan.org/dist/URI/>. -DW]
> +
>  =head3 FileField
>  
>  =over
> @@ -300,7 +310,9 @@
>  =item *
>  
>  stores actual file data, and accepts instructions to publish
> -according to the Field publish operation
> +according to the Field publish operation [Can also return the conents
> +of a file, or perhaps an interator object to gradually get the contents
> +of a file via a buffer. -DW]
>  
>  =item *
>  
> @@ -328,8 +340,19 @@
>  
>  FIXME: possibly implements the publish operation
>  
> +[Ah, I get why you have objects ignoring the publish operation -- because
> +they're not publshable objects. Only documents should be publishable. You
> +can publish a related object if that realted object happens to be a document.
> +-DW]
> +
>  =back
>  
> +[I'm looking at elements.png and reading this description, but would like to
> +see more. The description here is like comments in code that merely repeat
> +what the code is doing. We need more than that. I would appreciate a
> +blow-by-blow description of each method, how it works, and what its interface
> +is like. Such descriptions can later be used to document the classes.]
> +
>  =head2 COLLABORATIONS
>  
>  Clients use the Element class interface to interact with objects
> @@ -352,6 +375,12 @@
>  Makes it easy to add new kinds of Fields, by simple sub-classing
>  of Field.
>  
> +[Okay, this seems okay for element structures, though as I said, I'd like to
> +see a great deal more explanation of things. But where is the Element
> +Definition stuff? That needs to be defined, too, and then there needs to be an
> +interface defined to demonstrate how element trees will adhere to Element
> +Definitions. I think this needs to be worked out next. -DW]
> +
>  =head1 INPUT CHANNELS
>  
>  =head2 API CHANGES
> @@ -578,7 +607,222 @@
>  
>  =back
>  
> +[This is fine as far as it goes, but I think that there needs to be a
> +description of how imput channels relate to documents, that is, how there can
> +be multiple values for a given field in a given document, via input channels.
> +That relationship is not yet clear to me. -DW]
> +
> +=head1 NOTES FROM DAVID
> +
> +From here down to "AUTHORS" I include some notes on what I'm thinking of,
> +inspired in part by the above. I've also created some UML documents
> +illustrating some of these ideas. See L<ElementDef.png>, L<Element.png>,
> +L<Asset.png>, and L<Field.png>.
> +
> +=head1 CLASS HIERARCHY
> +
> +There needs to be two class hierachies based on the "Composite Pattern": one
> +to set up definitions for the other. Thus they're based on two base classes.
> +Bric::Biz::ElementDef is the "Component" base class for creating hierarchical
> +definitions. Bric::Biz::Element is the "Component base class" for an instance
> +of one of those definitions.
> +
> +=head2 Bric::Biz::Model
> +
> +This abstract class defines what models are like. It essentially replaces the
> +top-level element in the old model, and sets up the relationship between the
> +thing being modeled and its subelements. This class can define subelements and
> +field elelemets, but no parent elements. I make it an interface so that other
> +object models can eventually be based on it, such as contributors or
> +categories. May or may not be a subclass of Bric::Biz::ElementDef::Container
> +-- that's yet to be determined. In the parlance of the "Composite Pattern," it
> +does inherit from the "Component" class, but its parent-access methods are
> +op-ops (or throw exceptions).
> +
> +=head3 Bric::Biz::Model::Document
> +
> +Objects of this type define the element structure of documents.
> +
> +=head2 Bric::Biz::ElementDef
> +
> +Abstract class describing element defintions. This class corresponds to the
> +Component in the "Composite Pattern." Its tree-oriented methods throw
> +exceptions by default.
> +
> +=head3 Bric::Biz::ElementDef::Container
> +
> +Container elements. These can contain other Bric::Biz::ElementDef objects, and
> +may be subelements of either other container element definitions or of
> +models. They can access their parent or their children.
> +
> +=head3 Bric::Biz::ElementDef::Field
> +
> +Field elements. Attributes include a Bric::Biz::Field class ID and a
> +Bric::Biz::Widget object. The former is to indicate what kind of data can be
> +stored in the field, and the later is used to determine how to display
> +it. ElementDef::Field field objects can access their parent, but may contain
> +not children.
> +
> +=head2 Bric::Biz::Asset
> +
> +Abstract base class defining Bricolage objects that can be managed via workflow.
> +
> +=head3 Bric::Biz::Asset::Document
> +
> +Document objects. Each instance of a document object is constrained to the
> +structure defined for a document model.
> +
> +=head3 Bric::Biz::Asset::Template
> +
> +Template objects. Pretty much like the current Asset::Formatting object.
> +
> +=head2 Bric::Biz::Element
> +
> +An abstract class representing an instance of an element. Will be associated
> +with a single document (or other object defined by a model), and will be
> +constrained by a Bric::Biz::ElementDef object.
> +
> +=head3 Bric::Biz::Element::Container
> +
> +A container subclass.
> +
> +=head3 Bric::Biz::Element::Field
> +
> +A field subclass.
> +
> +=head2 Bric::Biz::InputChannel
> +
> +An object specifying that a different value can be stored for a single
> +field. Used mainly to pass to a C<< Bric::Biz::Field->get_value >> method call
> +to get back the approppriate value. Also used in Model objects to set up
> +default input channels for assets created based on those models.
> +
> +=head2 Bric::Biz::Field
> +
> +Defines the interface for various kinds of fields in Bricolage. It includes
> +validation restraints and stores a value. The value may be returned as an
> +object, though that object will be stringifiable. Its C<get_value()> method
> +takes an optional Bric::Biz::InputChannel object so that the correct value
> +object is returned.
> +
> +=head3 Bric::Biz::Field::Text
> +
> +The C<get_value()> method returns a string.
> +
> +=head3 Bric::Biz::Field::Number
> +
> +The C<get_value()> method returns a number.
> +
> +=head3 Bric::Biz::Field::Date
> +
> +The C<get_value()> method returns a DateTime.pm object.
> +
> +=head3 Bric::Biz::Field::DateTime
> +
> +The C<get_value()> method returns a DateTime.pm object.
> +
> +=head3 Bric::Biz::Field::URI
> +
> +The C<get_value()> method returns a URI.pm object.
> +
> +=head3 Bric::Biz::Field::ObjectRef
> +
> +The C<get_value()> method returns the appropriate Bricolage object.
> +
> +=head3 Bric::Biz::Field::File
> +
> +The C<get_value()> method returns a file name. Many other methods return
> +things like a URI, a file handle, C<stat> data, etc.
> +
> +=head3 Bric::Biz::Field::File::Image
> +
> +Adds metadata methods that are automatically populated, such as height, width,
> +colors, etc. -- Whatever Image::Info can provide.
> +
> +=head3 Bric::Biz::Field::File::Audio
> +
> +Adds metadata methods that are automatically populated, such as bit rate, play
> +length, etc. May not bee a good CPAN module for this, but many (See MP3::Info
> +for an example).
> +
> +=head3 Bric::Biz::Field::File::Video
> +
> +Adds metadata methods that are automatically populated, such as bit rate, play
> +length, resolution, etc. -- whatever can be provided by Video::Info.
> +
> +=head2 Bric::Biz::WidgetDef
> +
> +Abstract base class defining the interface for display widgets. It doesn't
> +actually display the widgets, but sets up the parameters that would be common
> +to such widgets. Examples include rows and cols for textarea widgets, length
> +for text widgets, and year spans for date widgets. Attributes that are common
> +to all fields can be defined here, such as "Name," "Label," "Help Text,"
> +"Required," "Default," etc. Each subclass includes a callback method that will
> +return the value entered in an actual instance of a widget.
> +
> +=head3 Bric::Biz::WidgetDef::Text
> +
> +Sets up the maximum length and minimum length of a text field, as well as the
> +size of the displayed field (how many characters).
> +
> +=head3 Bric::Biz::WidgetDef::Textarea
> +
> +Sets up the maximum length and minimum length of a text field, as well as the
> +size of the textarea field in rows and columns.
> +
> +=head3 Bric::Biz::WidgetDef::Select
> +
> +Sets up the Size of the widget, as well as a boolean indicating whether
> +multiple fields can be selected.
> +
> +=head3 Bric::Biz::WidgetDef::Checkbox
> +
> +Includes a boolean for whether or not it's checked by default.
> +
> +=head3 Bric::Biz::WidgetDef::Radio
> +
> +Includes settings for which values are selected by default.
> +
> +=head3 Bric::Biz::WidgetDef::File
> +
> +Does it need to include anything not defined in Bric::Biz::WidgetDef?
> +
> +=head3 Bric::Biz::WidgetDef::Date
> +
> +Does it need to include anything not defined in Bric::Biz::WidgetDef?
>  
> +=head3 Bric::Biz::WidgetDef::DateTime
> +
> +Does it need to include anything not defined in Bric::Biz::WidgetDef?
> +
> +=head3 Bric::Biz::WidgetDef::DoubleList
> +
> +Does it need to include anything not defined in Bric::Biz::WidgetDef?
> +
> +=head3 Bric::Biz::WidgetDef::Search
> +
> +Does it need to include anything not defined in Bric::Biz::WidgetDef?
> +
> +=head1 FIELDS
> +
> +We need to have a separation between the representation of field data and its
> +presentation. Obviously, a text field can be represented by any number of
> +different kind of display widgets, include text input fields, textarea fields,
> +a select list, etc. I think that Bric::Biz::Field and it subclasses should
> +just be concerned with the representation of the data and the constraints
> +necessary to a particular type. That means that it makes sure a number is a
> +number, but not, for example, that it's within a range.
> +
> +Bric::Biz::ElementDef::Field needs to be concerned with further constratints,
> +such as that a number or date falls within a given range, or that a text value
> +is less than a certain number of characters. But it should also point to a
> +type of display widget. Thus I think we need to introduce a new Widget:: class
> +hierarchy. It won't actually I<display> data, but it will define the type of
> +widget that's allowed. This is on the assumption that most UIs will have the
> +same basic types of widgets. We can name them all for HTML form widgets to
> +start with, since those are familiar to people and we can possibly include
> +some of the other widgets we have/need in Bricolage, such as the doubleList
> +manager or the search widget.
>  
>  =head1 AUTHORS
>  

-- 
--
=================================================================
-- mark at geekhive dot net --


-------------------------------------------------------
This SF.net email is sponsored by: ValueWeb: 
Dedicated Hosting for just $79/mo with 500 GB of bandwidth! 
No other company gives more support or power for your dedicated server
http://click.atdmt.com/AFF/go/sdnxxaff00300020aff/direct/01/
_______________________________________________
Bricolage-Devel mailing list
Bricolage-Devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/bricolage-devel
[prev in list] [next in list] [prev in thread] [next in thread]