ErstwhileComponent is the base class for each of the visual (and pseudo-visual) elements in Erstwhile. ErstwhileControl, ErstwhileForm, and ErstwhileLayout are all subclasses of ErstwhileComponent, and each of your custom components should also be a subclass of one of these.
Technically, you don’t need to override any methods in ErstwhileComponent when creating your own components; the default functionality will render the component’s component.ejs file, and if you don’t need anything more than that you’re good to go. You can pick and choose which of these methods to override as you need to change how your component works.
Containers
Some components contain other Erstwhile components (or just plain HTML) that you want to render inside your component. If your component needs this to happen, you can override the isContainer() method and insert a special element <innerContent /> in your component.ejs file to indicate where you would like the contained components/HTML placed.
Changing the component’s rendering behavior
When rendering your component, the ErML engine will, by default, create a <div> element with the component’s id attribute and all of the attributes of your component. If you specify a class attribute on your component, that same class attribute would show up on the <div> when rendered, making it a convenient pass through. The ErML engine will then render your component’s .ejs file and insert that into the <div>.
You have fine-grained control to change this, though.
Overriding getTag(), for instance, lets your component specify a tag other than <div> to use. Overriding prepareAttributes() will let you redefine the behavior for how your component’s attributes turn into HTML attributes.
Moving on to more advanced behavior, you can override the initialize() method to specify Javascript that should run post-DOM render. This will let you instantiate other libraries if needed and direct them to elements in your new DOM.
Finally, it’s sometimes necessary to do something really crazy and implement your own XML structure within your component so consumers can specify different types of data structures not available via simple attributes. If this is you, you can override the getHTML() method. This method has the inner content (as a JSONed XML document) as its argument, and you can freely iterate through that document to fine-tune component behavior.
Scoped Variables
When consuming your components in views, users can specify two different types of attributes:
- strings, such as
value="somevalue" - scoped variables, such as
value="@.page.value"
From your component’s perspective, both of these are exist in the component’s args member, and can have their present value seen by getProperty(argName). Scoped variables have some bonuses though.
First of all, if the scoped variable is a function, and the attribute it is assigned to is an on* attribute, the scoped function becomes an event handler.
Secondly, if the scoped variable is not a function, your component will receive a callback to receiveUpdate(key, value) every time the scoped variable changes. By overriding this method you will be able to tell your component how to handle that new value.