7.6Learning Canvas and Brush APIs
As we proceed and introduce new brushes, we will provide a table describing the parts of the Brush API that are essential for this book. Once you’ve used the table to find the brush to use for a given tag, you can read the source code for that brush class to find out how to use it. For example, if you want to produce a heading such as <h1>Something great</h1>
you’ll see that you should use the WAHtmlCanvas>>heading
message which produces a brush instance of WAHeadingTag
which has the following API:
Methods in WAHeadingTag | Description |
---|---|
level: | Specify anInteger as the heading level for this brush. |
with: | Render this heading tag with anObject as its body. |
To help you to find the correct brush, the brushes are presented from the perspective of the HTML tags in the following table:
HTML Factory Selector Brush Class ---------------------------------------------------------- a anchor WAAnchorTag a map WAImageMapTag a popupAnchor WAPopupAnchorTag abbr abbreviated WAGenericTag acronym acronym WAGenericTag address address WAGenericTag big big WAGenericTag blockquote blockquote WAGenericTag br break WABreakTag button button WAButtonTag caption tableCaption WAGenericTag cite citation WAGenericTag code code WAGenericTag col tableColumn WATableColumnTag colgroup tableColumnGroup WATableColumnGroupTag dd definitionData WAGenericTag del deleted WAEditTag dfn definition WAGenericTag div div WADivTag dl definitionList WAGenericTag dt definitionTerm WAGenericTag em emphasis WAGenericTag fieldset fieldSet WAFieldSetTag form form WAGenericTag h1 heading WAHeadingTag hr horizontalRule WAHorizontalRuleTag iframe iframe WAIframeTag img image WAImageTag input cancelButton WACancelButtonTag input checkbox WACheckboxTag input fileUpload WAFileUploadTag input hiddenInput WAHiddenInputTag input imageButton WAImageButtonTag input passwordInput WAPasswordInputTag input radioButton WARadioButtonTag input submitButton WASubmitButtonTag input textInput WATextInputTag ins inserted WAEditTag kbd keyboard WAGenericTag label label WALabelTag legend legend WAGenericTag li listItem WAGenericTag object object WAObjectTag ol orderedList WAOrderedListTag optgroup optionGroup WAOptionGroupTag option option WAOptionTag p paragraph WAGenericTag param parameter WAParameterTag pre preformatted WAGenericTag q quote WAGenericTag rb rubyBase WAGenericTag rbc rubyBaseContainer WAGenericTag rp rubyParentheses WAGenericTag rt rubyText WARubyTextTag rtc rubyTextContainer WAGenericTag ruby ruby WAGenericTag samp sample WAGenericTag script script WAScriptTag select multiSelect WAMultiSelectTag select select WASelectTag small small WAGenericTag span span WAGenericTag strong strong WAGenericTag sub subscript WAGenericTag sup superscript WAGenericTag table table WATableTag tag: tag: WAGenericTag tbody tableBody WAGenericTag td tableData WATableDataTag textarea textArea WATextAreaTag tfoot tableFoot WAGenericTag th tableHeading WATableHeadingTag thead tableHead WAGenericTag tr tableRow WAGenericTag tt teletype WAGenericTag ul unorderedList WAUnorderedListTag var variable WAGenericTag
Smalltalk typically encourages explicit naming and avoids abbreviations — the few seconds per day you save by typing an abbreviated method or variable name may often come back much later to haunt you or someone else reading your code as minutes or even hours spent trying to debug code with poor readability.
This book is not a complete Seaside reference. Once you’re done reading it you will want to discover new brushes and brush options yourself. Let’s take a few moments to describe how you would do that.
Suppose you know a specific XHTML tag you want to use and need to find the appropriate brush method. Some brush method names are the same as the corresponding XHTML tag name. For example you create a div
tag using the WAHtmlCanvas>>div
brush method. In other cases the brush name is the long form of the equivalent XHTML tag (WAHtmlCanvas>>paragraph
creates a p
tag, WAHtmlCanvas>>unorderedList
creates a ul
tag etc). This choice makes your methods a lot more readable than if the XHTML tags were used everywhere. Compare the following two code fragments.
"This is not working code"
html p with: 'Hello world.'.
html ol with: [
html li: 'Item 1'.
html li: 'Item 2' ].
"Working version"
html paragraph with: 'Hello world.'.
html orderedList with: [
html listItem: 'Item 1'.
html listItem: 'Item 2' ].
If you can’t guess the brush method name just open a class browser on the canvas class WARenderCanvas
. Keep in mind that the method you’re interested in may be in a superclass, see the hierarchy below.
Normally, the brush configuration methods that set tag attributes, use the same name as the attribute. So, for example, to set the altText
attribute for an IMG
(image) tag you’d send the image
brush the WAImageTag>>altText:
message. If you don’t know the tag attribute you need to open a class browser on the specific brush class. Once again, keep in mind that the method you’re interested in may be in a superclass. In addition to tag attributes, many of the Seaside brushes support convenience methods and common Javascript hacks (like setting the focus of an input field). The best way to find these is to use your Smalltalk tools.
When you first begin using Seaside your canvas and brush vocabulary will be limited and it might take you a few minutes to find what you’re looking for. After a while you’ll discover that there is a significant shared API (implemented in the abstract superclasses) and that you are already familiar with many of the brushes. Also helpful is the autocompletion mechanism in the development environment.
WABrush WACompound WADateInput WATimeInput WATagBrush WAAnchorTag WAImageMapTag WAPopupAnchorTag WAAudioTag WABasicFormTag WAFormTag WABreakTag WACanvasTag WACollectionTag WADatalistTag WAListTag WAOrderedListTag WAUnorderedListTag WASelectTag WAMultiSelectTag WACommandTag WADetailsTag WADivTag WAEventSourceTag WAFieldSetTag WAFormInputTag WAAbstractTextAreaTag WAColorInputTag WAEmailInputTag WASearchInputTag WASteppedTag WAClosedRangeTag WANumberInputTag WARangeInputTag WATimeInputTag WADateInputTag WADateTimeInputTag WADateTimeLocalInputTag WAMonthInputTag WAWeekInputTag WATelephoneInputTag WATextAreaTag WATextInputTag WAPasswordInputTag WAUrlInputTag WAButtonTag WACheckboxTag WAFileUploadTag WAHiddenInputTag WARadioButtonTag WASubmitButtonTag WACancelButtonTag WAImageButtonTag WAGenericTag WAEditTag WAHeadingTag WAHorizontalRuleTag WAIframeTag WAImageTag WAKeyGeneratorTag WALabelTag WAMenuTag WAMeterTag WAObjectTag WAOptionGroupTag WAOptionTag WAParameterTag WAProgressTag WARubyTextTag WAScriptTag WASourceTag WATableCellTag WATableColumnGroupTag WATableColumnTag WATableDataTag WATableHeadingTag WATableTag WATimeTag WAVideoTag