Controls

Controls are fractions of HTML code. They can be used to encapsulate a part of a page that appears in many actions in the application, but it cannot be called directly as a stand alone action. Each control extends the Control and must override the Render method, just like in the actions.

class HelloWorldControl extends Control { public function Render(){ echo 'Hello world!'; } } HelloWorldControl::Make()->Render();

Each control has a unique name that can be used as a namespace for the ids of the HTML elements inside the rendering.

class MyControl extends Control { public function Render(){ echo '<div id="'.$this->name.'-first-div">Div 1</div>'; echo '<div id="'.$this->name.'-second-div">Div 2</div>'; } } $c1 = MyContol::Make(); $c2 = MyContol::Make(); $c1->Render(); $c2->Render(); // no id conflict because each control has a different name

The Make function is equivalent to the constructor, but it can be used for method chaining. It can accept an argument, which is the name of the control. If no argument is passed, then a random name is assigned.

MyContol::Make('my_control_1')->Render();

Value controls

Value controls are those controls that also have one value to be transferred through HTTP. These are controls that render an HTML form element. The value of the control is passed to the constructor along with the name. This time, the name of the control is important because this will be the name of the HTTP variable passed through the POST or GET request.

There are several premade value controls, such as the TextBox, the CheckBox, the SelectBox and others.

// This will create an HTML form text input with name "title", filled with the book's title. Several // attributes can be defined in a chained fashion. TextBox::Make( 'title' , $book->Title ) ->WithWidth( '100px' ) // width ->WithOnChange( 'CheckBookTitle();' ) // a Javascript event ->Render();

The value of a control passed through HTTP, can be retrieved by the name:

$book->Title = Http::$POST[ 'title' ]->AsString();

The conversion of the value to HTML is done according to the rules of the Oxygen's type system (the the chapter on The type system).

TextBox::Make( 'NumberOfPages' , $book->NumberOfPages )->Render(); ... $book->NumberOfPages = Http::$POST['NumberOfPages']->AsIntegerOrNull();

Common value controls

The HiddenBox renders a hidden HTML form element.

HiddenBox::Make( 'title' , $book->Title )->Render();

The TextBox renders a text or a textarea input.

TextBox::Make( 'description' , $book->Description )->WithRows(10)->Render();

The TextBox is also for passwords.

TextBox::Make( 'password' , '' )->WithIsPassword(true)->Render(); // pre-fill does not make sense here...

The SelectBox renders a select input.

SelectBox::Make( 'author' , $book->Author ) ->Add( 'Lewis Carol') ->Add( 'J.R.Tolkien') ->Render();

This is a more complex, but more sane use of the select control:

// Select the id of the author in a list of XItems. Each option in the list will have // the the author's id as value and the author's GetTitle() as caption. SelectBox::Make( 'idAuthor' , $book->idAuthor ) ->AddMany( Author::Seek() ) ->Render();

The DateBox, the DateTimeBox, TimeBox and the TimeSpanBox work on time related values.

DateBox::Make( 'DatePublished' , $book->DatePublished )->Render();

The ButtonBox makes buttons.

ButtonBox::Make()->WithValue('OK')->WithIsSubmit(true)->Render(); ButtonBox::Make()->WithValue('Cancel')->WithIsReset(true)->Render(); ButtonBox::Make()->WithValue('Click me!')->WithOnClick('Clicked();')->Render();

The CheckBox is for boolean values.

// This will render a check box along with a label. CheckBox::Make( 'IsMagazine' , $book->IsMagazine ) ->WithLabel('This is a magasine') ->WithShowLabel(true) ->Render();