Smalltalk/X Webserver

Documentation of class 'HTML::AbstractElement':

Class: AbstractElement (in HTML)

Inheritance
Description
Class protocol
Instance protocol

Inheritance:

   Object
   |
   +--HTML::AbstractElement
      |
      +--HTML::AbstractHTMLElement
      |
      +--HTML::AbstractProcessingElement
      |
      +--HTML::Embed
      |
      +--HTML::SVGAbstractElement

Package:: stx:goodies/webServer/htmlTree

Category:: Net-Documents-HTML-ModelTree

Version:: rev: 1.129 date: 2024/03/18 12:53:53; user: cg; file: HTML__AbstractElement.st directory: goodies/webServer/htmlTree; module: stx stc-classLibrary: htmlTree

Description:

common superclass for both HTML and SVG elements

copyrightCOPYRIGHT (c) 2003 by eXept Software AG
             All Rights Reserved

This software is furnished under a license and may be used
only in accordance with the terms of that license and with the
inclusion of the above copyright notice.   This software may not
be provided or otherwise made available to, or used by, any
other person.  No title to or ownership of the software is
hereby transferred.

Class protocol:

accessing

allConcreteSubclasses

Return all concrete subclasses.

Usage example(s):

     self allConcreteSubclasses.

allElementImplementingClasses

Return all classes that implement a concrete tag

Usage example(s):

     AbstractHTMLElement allElementImplementingClasses

auloadAllClassesInPackage

instance creation

newTag: aString

Build a tag for a tag name. If the tag name is fitting to an
existing tag use this tag. If not build a generic tag holding
this new tag name.

Usage example(s):

     Element newTag:'a'
     Element newTag:'span'

tagToClassMapping

return a mapping for all existing tag names.
The key is the tag name, the value is a
concrete element class.

** This method must be redefined in concrete classes (subclassResponsibility) **

with: aRawObject

Every HTML element can be created upon a collection of children or
simply on a single element to be the child(ren) of this html-element.

It is allowed to create empty html-objects with '#new' too.

with: anObject class: aHTMLClass

Create an element with the information from an object(See '#with:').
Set a html stylesheet class to use for this element and automatically
all included elements.

withNew: aOneArgBlock

queries

isAbstract

Return if this class is an abstract class.
Return true for this class but false for all subclasses.
To have an abstract subclass implement this method there again.

Usage example(s):

     AbstractElement isAbstract.
     Table isAbstract.

required protocol

tagName: Return a tag name for the html object.
Each html object needs to define a tag name.

Instance protocol:

accessing

add: aChildOrClass: Add a new element to the children.
Use this method as interface to add children.
Do not add children directly into the children collection.
addElement: aChildOrClass: Add a new element to the children.
Use this method as interface to add children.
Do not add children directly into the children collection.
addElement: aChildOrClass at: anIndex: Add an element of type a class or a child directly.
Fill up the indices upd to an index with empty elements
of the same type.
addElement: aChildOrClass before: anIndex: Add an element of type a class or a child directly before anIndex. If
index greater then children size, the element will be added at the end
addElements: aCollection: Add new elements to the children.
Use this method as interface to add children.
Do not add children directly into the children collection.
addFirst: aChildOrClass: Add a new element to the children.
Use this method as interface to add children.
Do not add children directly into the children collection.
attributes: Return a dictionary with html-attributes
or nil if there are no attributes set.

The attributes are included in the opening tag.
An attribute is a key value pair.
extractedText: extract the raw text from this (and all sub-elements)
parent: Return the parent of this element.
Can be nil for top level elements.
On correct html a page will be the
top level item.
removeAllElements
removeElement: anElement
removeFirst
tagName: Return the tag name of this element.
Each element must define its own tag
name in class method.
tagName: aStringOrSymbol: Here, assert that the given tag conforms to my
class-given default tagName - i.e. fail, if there is a mismatch.

accessing - xpath like

/ anElementName

XPath like processing - answer all the elements named anElementName
which are direct children of the receiver

Usage example(s):

     |doc|
     
     doc :=(HTML::HTMLParser parseFile:'../../doc/online/english/top.html').
     doc // 'a'.
     (doc // 'a') select:[:d | (d @ 'HREF') startsWith:'misc']

Usage example(s):

Modified (comment): / 12-07-2022 / 12:15:40 / cg

// anElementName

XPath like processing - traverse the tree and answer all the elements named anElementName
(i.e. anywhere below)

/@ anAttributeName

XPath like processing - answer a nodeSet with attributes named anAttributeName

@ anAttributeName

XPath like processing - answer the attribute named anAttributeName

enumeration

allParents: Evaluate a block recursively for all parents
allParentsDo: aOneArgumentBlock: Evaluate a block recursively for all parents
allSubElementsDo: aOneArgumentBlock: Evaluate a block recursively for all children
subElementsDo: aOneArgumentBlock: Evaluate a block for my direct children.
Wrapper for the bad naming...
subelementsDo: aOneArgumentBlock: Evaluate a block for all components wrapped by this element.
Default is to evaluate this block for all children.
Subclasses may add special components to be evaluated here.
Bad name; should be named subElementsDo:

interface-attributes

automationId: anID: Set the automationId of the element.
classAttribute: Return the class attribute of the element.
Notice: an element can have multiple classes, being space-separated in the class attribute
classList: Return the list of classes defined in the class attribute of the element.
Notice: an element can have multiple classes, being space-separated in the class attribute
hasClass: className: true if className is includes in my class attribute.
Notice: an element can have multiple classes, being space-separated in the class attribute
id: Return the id of the element.
id: anID: Set the id of the element.
on: what script: aScript: common helper for onXXX: messages;
looks if there is already a script defined for the what-message, and concatenates the scripts,
if required
onChange: aScript: Set the on-change-attribute of this element.
onClick
onClick: aScript
onDoubleClick: aScript
onKeyDown: aScript
onKeyPress: aScript
onKeyUp: aScript
onMouseDown
onMouseDown: aScript
onMouseMove: aScript
onMouseOut: aScript
onMouseOver
onMouseOver: aScript
onMouseUp
onMouseUp: aScript

private-accessing

addChild: aChild: Add a new child to the children.

Use this method as interface to add children.
Do not add children directly into the children collection.
addElementOfClass: anElementOrStringOrCollection with: aClass: Add an elment. this can be a ready build elment
or a string or a collection of elements.
addFirstChild: aChild: Add a new child to the children.

Use this method as interface to add children.
Do not add children directly into the children collection.
Be careful: returns the added child
childAt: anIndex ifAbsent: anExceptionBlock: Return the child at an index or nil if it does not exist.
childAt: anIndex put: aNewChildOrClass: Set a child to be at an index.
children: Return the children of this element.
getElement: aClass: Return the first element of a class that can
be found, or build a new element if none is
present.
Self children can build a children collection,
this collection will be needed anyhow to hold
the searched element if not present and build.
parent: anItem: Set an item to be the parent of this item.
Private - Use only to set child elements.
Do not call from other classes.
replaceChild: anUnlovedChild with: adoptedChild
setChildren: aCollectionOfElementsOrStrings: Set a collection of elements or strings
to be the children of this element.
Private - Use only for instance creation.
style: ** This method must be redefined in concrete classes (subclassResponsibility) **
style: aStyle: ** This method must be redefined in concrete classes (subclassResponsibility) **

private-accessing-attributes

addAttribute: aSymbol: Add an attribute without value
addStyle: aStyleElement: Add a css-style-element to the attributes.
Private interface used for accessing style methods.
attributeAt: aSymbol: Return the attribute at a symbol
or nil if the attribute is not set.
attributeAt: aSymbol add: more: Set or add an attribute value to the attribute.
attributeAt: aSymbol put: aValue: Set an attribute's value.
If aValue is nil the attribute is removed.
elementAtId: anId: Return the element at an ID
or nil if the attribute is not set.
getAttributes: Return a dictionary to put in attributes.
Despite normal access method: '#attributes'
this method garanties to deliver a
dictionary for the attributes.

Call only if you want to set attributes.
Do not call for checking for attributes.
Use method: '#attributes' for this instead.
removeAttribute: aSymbol: Remove a symbol from the attribute list
and check if we need the attributes dictionary any longer after removing.

private-building

buildElement: aNewChildOrClass: Take the item or instantiate the class.
buildElement: aRawData ofType: aClass: Build a new element created from raw data.
Raw data can be either a ready built subelement of the
fitting class, or it can be a simple string that will be
wrapped by a new element of the given class. Or it can be nil
to construct an empty element of the given class.
buildElement: rawData ofType: aClass onCollectionDo: aTwoArgumentBLock: Build a new element created from raw data.
Raw data can be either a ready built subelement of the
fitting class, or it can be a simple string that will be
wrapped by a new element of the given class. Or it can be nil
to construct an empty element of the given class. It is
also possible to give a collection of subelements the
added element shall consist of, then a block is executed
for each of these subelements to construct it properly
into the element.

See method: '#addRow' in class Table for usage.

queries

canHaveChild: anotherElement: return true, if anotherElement is allowed as my child

** This method must be redefined in concrete classes (subclassResponsibility) **
canHaveChild: anotherElement in: aParser: return true, if anotherElement is allowed as my child
canHaveText: return true, if I allow text as child (i.f. PCDATA)
hasChildren: summary:
This may look to you like a terrible idea. You may be also be right.
However, there is a reason for it. There are cases in the HTML tree where
children are not in the children instance variable. For example, In <Head>
there is a child that is not in the collecion children called title.

This makes:

children size ~= 0

not work. So you may rightly argue that we should define hasChildren in each subclass
that has children that are not in the instance variable children. Then we have two methods
that define what an element's children are (a possible reciepe for disaster). So
with this in mind, the following implementation was born.
isVoidElement: A void element is an element whose content model
never allows it to have contents under any circumstances.
Void elements can have attributes.
mustBeClosed: return true, if I need a closing tag
(as opposed to eg <br>, <li> or <img>, which do not)

required-visiting

acceptHTMLVisitor: aVisitor: Visit this element.
To be implemented by each element(subclass).

** This method must be redefined in concrete classes (subclassResponsibility) **

testing

isAnchor
isArea
isBlockElement
isBody
isBold
isButton
isCaption
isCenter
isCode
isColgroup
isComment
isDefinitionDescription
isDefinitionList
isDefinitionTerm
isDiv
isDummyContainer
isForm
isFormWidgetElement
isFrame
isHTMLDocument
isHead
isHeading
isHeading1
isHorizontalRule
isImg
isInput
isLabel
isLink
isListItem
isMeta
isNoBr
isOption
isOrderedList
isParagraph
isPre
isProcessingInstruction
isScript
isSelect
isSpan
isStrong
isStyle
isTable
isTableBody
isTableCell
isTableDataCell
isTableFoot
isTableHead
isTableHeaderCell
isTableRow
isTextArea
isTitle
isUnorderedList

xml dom protocol compatibility

addAllAttributesNamed: attributeName to: aCollection: Recursively (depth-first) traverse the element tree and add any
sub-elements atributes named attributeName to aCollection.
Sigh: stupid code duplication (see XML)
addAllElementsNamed: elementName to: aCollection: Recursively (depth-first) traverse the element tree and add any
sub-element named elementName to aCollection.
Sigh: stupid code duplication (see XML)
addAttributesNamed: anAttributeName to: aCollection: XPath like processing - add attributes named anAttributeName to aCollection.
Sigh: stupid code duplication (see XML)
addElementsNamed: elementName to: aCollection: Traverse the tree and add the direct child elements named elementName to aCollection
Sigh: stupid code duplication (see XML)
allAttributesNamed: attributeName do: aBlock: Recursively (depth-first) traverse the element tree and evaluate aBlock for each.
Sigh: stupid code duplication (see XML)
allElementsNamed: elementName do: aBlock: Recursively (depth-first) traverse the element tree and evaluates aBlock for each.
Sigh: stupid code duplication (see XML)
attributeNamed: anAttributeName: for compatibility with VW DOM nodes (so XML inspector can use both).
Sigh: stupid code duplication (see XML)
attributesNamed: anAttributeName do: aBlock: XPath like processing - evaluate aBlock for all attributes named anAttributeName.
Sigh: stupid code duplication (see XML)
elements: for XML dom compatibility
elementsDo: aBlock: recursively (depth-first) descend into my child-elements and
evaluate aBlock for each sub-element.
Bad naming: should be called allElementsDo:
tag: Return the tag name of this element.
Each element must define its own tag
name in class method.

ST/X 7.7.0.0; WebServer 1.702 at 20f6060372b9.unknown:8081; Mon, 18 Nov 2024 04:21:30 GMT