HtmlEditTbox .NET WebControl kuvaus ja käyttöohje

HtmlEditTbox -kontrollin on kehittänyt Juha Lähteenmäki. Kontrollin käyttö "ei kaupallisiin" tarkoituksiin on sallittu ja voit kopioida tai levittää sitä sellaisenaan (asennuspakettia ei saa muuttaa).

1. HtmlEditTbox WebControl yleiskuvaus

HtmlEditTbox on ASP.NET ympäristössä käytettäväksi suunniteltu Web-kontrolli, joka mahdollistaa Html-muotoiluja sisältävän tekstin kirjoittamisen Web-sivulla. Kontrolli tarjoaa siis käyttäjälle Web-sivulla toimivan WYSIWYG Html-editorin. Perusideana on tarjota yksinkertaiset perusmuotoilut ja toiminnot nopeasti sekä helposti Html:ää tuntemattomankin käyttäjän ulottuville mutta toisaalta tarjota edistyneelle käyttäjälle mahdollisuus Html-lähdekoodin muokkaukseen. Erilaisia tarpeita varten kontrollissa on myös kolme moodia: ReadOnly, Basic ja Advanced. Näitä moodeja voi vaihdella myös ajonaikana.

1) ReadOnly moodissa (eReadOnly) käyttäjä ei voi muokata kontrollin sisältämää tekstiä eikä työkalupalkki ole näkyvissä. Kontrolli näyttää kuitenkin sisältönsä Html-muotoiluja ja tarvittaessa vierityspalkkia käyttäen..

2) Perusmoodissa (eBasic) kontrollin sisältämää tekstiä on mahdollista muokata mutta työkalupalkissa on näkyvissä vain kaikkein tärkeimmät toiminnot.

3) Advanced moodissa (eAdvanced) muotoilutoimintoja on näkyvissä perusmoodia enemmän. Muuten itse kontrollin toiminta ei eroa perusmoodissa olevan kontrollin toiminnasta

 Moodin ja kontrollin erillisten tyyliasetusten kautta tapahtuvan mukauttamisen lisäksi kontrollin suunnittelussa on painotettu mahdollisuutta tehdä kontrollista helposti erikielisiä versioita. Tästä syystä kaikki olennaisimmat kontrollin ulospäin näkyvät tekstit ovat asetettavissa sekä suunnittelu- että ajoaikana.

2. Kontrollin käyttövaatimukset

Asiakaspäässä  kontrollin käyttö edellyttää IE5.5 tai uudempaa selainta. Laitteiston on oltava riittävän tehokas (testattu minimi P133 Win98 32 Mt muistia) ja verkkoyhteyden vähintään ISDN-nopeusluokkaa (varsinkin jos sivulla käytetään useampia kontrolleja ViewState-enabloituna) mikäli kontrollia käytetään verkon läpi.

Palvelinpuolelle edellytyksenä on Windows ympäristö ja riittävän tehokas laitteisto joka pyörittää IIS5:sta tai uudempaa sekä .NET -Framework:n versio 1.0 tai uudempi. Suunnittelutilan tuen tarjoava ohjelmointiympäristö, kuten Visual Studio.NET, helpottaa kontrollin käyttöä mutta välttämätön edellytys se ei ole. Kontrollin suunnittelutilan toimivuus on testattu Visual Studio.NET:llä .NET -framework:n 1.0 ja 1.1-versiolla sekä Asp.NET Web Matrix:n versiolla 0.6 build 812 ja sitä voi käyttää ASPX-sivulla normaalin Web-kontrollin tapaan (ks. esim luku 6).

3. Kontrollin asennus

Asennuksen esiehdoiksi ks. edellisen luvun kontrollin käyttövaatimukset.

Kun haluat käyttää kontrollia tietyllä ASPX-sivulla toimi seuraavasti:

• Pura asennuspaketti haluamaasi hakemistoon.(yleensä kontrollin dll:n tulee olla projektin (Aspx-sivun) bin alihakemistossa)
• Kopioi images -kansio Aspx-sivun kanssa samaan hakemistoon. Mikäli images kansio on olemassa ko. sijainnissa ennestään, kopioi images-kansion sisältö olemassa olevan images-kansion sisälle.

Mikäli käytät suunnittelutilan tuen tarjoavaa työkalua kuten Visual Studio.NET:ä

• Lisää kontrolli ToolBox:iin selaamalla kontrollin dll. (Valitse kolmesta valmiiksi valitusta komponentista ainoastaan HtmlEditTbox)

 4. Kontrollin tarjoamat toiminnot

Kontrolli tarjoaa seuraavat toiminnot (Toiminnoista kaikki eivät ole käytettävissä muussa kuin Advanced -tilassa)

Toiminto	Toiminto
Tallennus	Lähettää kontrollin sisällön (HTML) serverille. Saa aikaan Save-eventin --> Saa aikaan serverillä käynnin
Leikkaus	Siirtää valitun tekstin leikepöydälle (ja poistaa tekstin kontrollista) (pikanäppäin Ctrl x)--> Ei serverillä käyntiä
Kopiointi	Kopioi valitun tekstin leikepöydälle (pikanäppäin Ctrl c)--> Ei serverillä käyntiä
Liittäminen	Liittää tekstin valittuun kohtaan leikepöydältä (pikanäppäin Ctrl v)--> Ei serverillä käyntiä
Lihavointi	Lihavoi valitun tekstin tai mikäli teksti ennestään lihavoitu poistaa lihavoinnin. Mikäli valittua tekstiä ei ole asettaa lihavointiominaisuuden päälle tai pois --> Ei serverillä käyntiä
Kursivointi	Kursivoi valitun tekstin tai mikäli teksti ennestään kursivoitu poistaa kursivoinnin. Mikäli valittua tekstiä ei ole asettaa kursivointiominaisuuden päälle tai pois --> Ei serverillä käyntiä
Alleviivaus	Alleviivaa valitun tekstin tai mikäli teksti ennestään alleviivattu poistaa alleviivauksen. Mikäli valittua tekstiä ei ole asettaa alleviivausominaisuuden päälle tai pois --> Ei serverillä käyntiä
Numerolistanlisäys	Muuttaa valitun tekstin/aktiivisen rivin tekstin  numeroiduksi listaksi tai mikäli teksti ennestään numerolista poistaa ko. ominaisuuden. --> Ei serverillä käyntiä
Numeroimattomanlistanlisäys	Muuttaa valitun tekstin/aktiivisen rivin tekstin  numeroimattomaksi listaksi tai mikäli teksti ennestään numeroimaton lista poistaa ko. ominaisuuden. --> Ei serverillä käyntiä
Tekstin vasemmalle tasaus	Tasaa valitun/aktiivisen rivin tekstin vasemmalle --> Ei serverillä käyntiä
Tekstin keskitys	Keskittää valitun/aktiivisen rivin tekstin --> Ei serverillä käyntiä
Vaakaviivan lisäys	Lisää vaakaviivan valittuun paikkaan --> Ei serverillä käyntiä
Hyperlinkin lisäys	Lisää hyperlinkin valittuun paikkaan käyttäen tekstinä joko valittua tekstiä tai mikäli tekstiä ei valittu hyperlinkin osoitetta--> Ei serverillä käyntiä
Kuvan lisäys	Lisää kuvan tekstin loppuun--> Ei serverillä käyntiä
Tekstin muotoiluvalinta	Muuttaa aktiivisen rivin tekstin valitun tasoiseksi otsikoksi tai normaali tyyliseksi--> Ei serverillä käyntiä
Lähdekoodin näytön valinta/valinnan poisto	Näyttää tai piilottaa Html-lähdekoodin

5. Kontrollin tarjoama rajapinta

Kontrollin ulospäin näkyvä rajapinta on pyritty saamaan mahdollisimman yksinkertaiseksi jotta kontrollin käyttö olisi helppoa. Myös suunnittelutilan näkymä vastaa mahdollisimman tarkasti ajonaikaista kontrollia jotta esim. tyyliominaisuuksien muuttaminen jo suunnittelutilassa olisi helpompaa. Muotoiluun vaikuttavien ominaisuuksien asettaminen suunnittelutilassa on suositeltavaa, koska tällöin ulkoasun ja toiminnallisuuden erottaminen onnistuu helpommin ja toisaalta esim. ViewState voidaan disabloida ilman että tyyliasetukset häviävät. ViewState:n disablointi varsinkin useampia kontrolleja sisältävillä ja tehokkuuden suhteen kriittisillä ASPX-sivuilla onkin järkevää, koska itse kontrollin sisältämän Html-tekstin säilytys tehdään ViewStatesta riippumattomasti ja ViewState tahtoo useissa tapauksissa kasvaa muuhun dataan nähden melko suureksi kuormittaen tarpeettomasti verkkoyhteyttä.

Kontrollin tarjoama rajapinta on jakautunut periaatteessa kolmeen osaan. Koko kontrollia koskevat metodit ja propertyt on kasattu suoraan pääkontrolliluokan alle, pelkästään ToolBar:iin vaikuttavat ToolBar propertyn sekä pelkkään editoriosaan vaikuttavat taas EditTbox propertyn alle. Propertyjen nimeämisessä on pyritty noudattamaan selkeää logiikkaa, joten rajapinnan käytön pitäisi olla suhteellisen helppoa. Suuri osa koko kontrollia koskevista propertyistä ja metodeista on lisäksi WebControl-kantaluokasta periytettyjä joten niiden dokumentaatio löytyy jo .NET:n mukana tulevasta dokumentaatiosta.

Kontrollista ulospäin näkyvät luokat nimiavaruuksineen ovat:

• Web.UI.WebControls.HtmlEditTbox --> Varsinainen kontrolliluokka
• Web.UI.WebControls.HtmlEditTboxToolBar --> Työkaluriviin liittyvät ominaisuudet
• Web.UI.WebControls.HtmlEditTboxTextbox --> Editoriin (tekstiosaan) liittyvät ominaisuudet
• Web.UI.WebControls.HtmlEditTboxDesigner --> Suunnittelutilan aikaisesta näyttämisestä vastaava luokka
• Web.UI.WebControls.HtmlEditTbox.HtmlEditTboxSaveEventArgs --> Save-eventin Eventtiargumentti luokka

Seuraavissa rajapintakuvauksissa on kuvattu kaikki kontrollista ulospäin näkyvät ominaisuudet. Mikäli ominaisuus on periytynyt kantaluokasta eikä sen toteutusta/toimintaa ole millään tavalla kantaluokan vastaavasta muutettu on rajapintakuvauksen kohdalla pelkästään linkki kantaluokan rajapintakuvaukseen.

5.1 Rajapintakuvauksissa käytetyt symbolit

Rajapintasymbolien selitykset

	Public Interface
	Internal Interface
	Public Class
	Internal Class
	Public Property
	Protected Property
	Internal Property
	Private Property
	Public Event
	Internal Event
	Public Const/Enum
	Protected Const/Enum
	Internal Const/Enum
	Private Const/Enum
	Public method
	Protected method
	Internal method
	Private method

5.2 HtmlEditTbox

Periytyy:

Luokka/rajapinta	Kuvaus (erityisesti kantaluokkanäkökulmasta)
System.Web.UI.WebControls.WebControl	.NET:n WebControllien kantaluokka. Kantaluokan valmiiksi tarjoamat ominaisuudet ja yhtenäinen rajapinta muiden WebControllien kanssa tekevät periyttämisestä ehdottomasti järkevimmän ratkaisun.

Ominaisuus	Kuvaus
EHtmlEditTboxState	Enumi joka kuvaa HtmEditTbox-kontrollin mahdollisia tiloja. Tilat ovat eBasic (käyttöliittymä basic-moodissa) ,  eAdvanced (käyttöliittymä advanced moodissa) sekä eReadOnly (Toolbar-piilossa ja käyttöliittymä ReadOnly moodissa) (ks. moodispesifiset kuvat)   Virhekäsittely:-
Mode:EHtmlEditTboxState	HtmEditTbox-kontrollin tila. Mahdolliset tilat ovat eBasic (käyttöliittymä basic-moodissa) , eAdvanced (käyttöliittymä advanced moodissa), sekä eReadOnly (ks. moodispesifiset kuvat) Oletus: eBasic Esim: HtmlEditTbox1.Mode = HtmlEditTbox.EHtmlEditTboxState.eBasic;   Virhekäsittely:-
ToolBar:HtmlEditTboxToolBar	HtmEditTbox-kontrollin ToolBar:iin liittyvät ominaisuudet. ToolBar:n tarjoamat julkiset propertyt löytyvät HtmlEditTboxToolBar:n kohdalta.  Property on readonly eli ToolBar:ia ei voi kerralla asettaa mutta sen yksittäiset ominaisuudet ovat muutettavissa Oletus: ToolBar ko. moodia vastaavassa oletustilassa Esim. HtmlEditTbox1.ToolBar.BtnSaveToolTip = "Tässäpä tallennus nappula";   Virhekäsittely: Jos lapsikontrollien alustus jostakin syystä epäonnistuu viittaus aiheuttaa NullReferenceException:in
EditTextBox:HtmlEditTboxTextbox	HtmEditTbox-kontrollin TextBox:iin liittyvät ominaisuudet. TextBox:n tarjoamat julkiset propertyt löytyvät HtmlEditTboxTextbox:n, kohdalta.  Property on readonly eli TextBox:ia ei voi kerralla asettaa mutta sen yksittäiset ominaisuudet ovat muutettavissa Oletus: TextBox: ko. moodia ja sourcevalintatilaa vastaavassa oletustilassa Esim. HtmlEditTbox1.EditTextBox.BackColor = System.Drawing.Color.Red;   Virhekäsittely: Jos lapsikontrollien alustus jostakin syystä epäonnistuu viittaus aiheuttaa NullReferenceException:in
TboxHTMLSaved	Eventti joka nousee kun HtmlEditTbox:n teksti tallennetaan (kun painetaan Save-nappulaa). Parametrina välitetään src = HtmlEditTbox ja eventtiargumenttiluokkan HtmlEditTboxEventArgs ilmentymä. Esim. override protected void OnInit(EventArgs e) //sivun alustus { this.HtmlEditTbox1.TboxHTMLSave += new Web.UI.WebControls.HtmlEditTbox.TboxHTMLSavedHandler(this.HtmlEditTbox1_TboxHTMLSave); base.OnInit(e); } private void HtmlEditTbox1_TboxHTMLSave(object sender, Web.UI.WebControls.HtmlEditTbox.HtmlEditTboxSaveEventArgs e) { HtmlEditTbox1.ToolTip = e.HtmlEditTboxHTMLValue; }   Virhekäsittely:-

5.3 HtmlEditTboxToolbar

Periytyy:

Luokka/rajapinta	Kuvaus (erityisesti kantaluokkanäkökulmasta)
Web.UI.WebControls.ICtrlPart	Internal rajapintaluokka jolla ei ole merkitystä ulkoisen käytön kannalta

Ominaisuus	Kuvaus
BtnBoldToolTip	Lihavointinappulan ToolTip Oletus ""
BtnItalicToolTip	Kursivointinappulan ToolTip Oletus ""
BtnUnderlineToolTip	Alleviivausnappulan ToolTip Oletus ""
BtnSaveToolTip	Tallennusnappulan ToolTip Oletus ""
BtnCutToolTip	Leikkausnappulan ToolTip Oletus ""
BtnCopyToolTip	Kopiointinappulan ToolTip Oletus ""
BtnPasteToolTip	Liittämisnappulan ToolTip Oletus ""
BtnNbrListToolTip	Numerolistanappulan ToolTip Oletus ""
BtnBulletListToolTip	Listanappulan Tooltip Oletus ""
BtnAlignLeftToolTip	Vasemmalletasausnappulan Tooltip Oletus ""
BtnAlignCenterToolTip	Keskelletasausnappulan Tooltip Oletus ""
BtnHrToolTip	Vaakaviivanappulan Tooltip Oletus ""
BtnHrefToolTip	Hyperlinkkinappulan Tooltip Oletus ""
BtnImageToolTip	Kuvan lisäysnappulan Tooltip Oletus ""
CheckBoxSourceToolTip	Lähdekoodinäytön valintanappulan Tooltip Oletus ""
CheckBoxSourceText	Lähdekoodi-valintanappulan  teksti Oletus: source
CheckBoxSourceEnabled	True jos source-näytön valintanappula enabloitu. Oletus: true
BtnDlistHeadingText	Tyylivalinta (otsikkovalinta) dropdown-listan valinta-ohjeen teksti (otsikkovalinta)
SourceSelected	True jos source-näkyvissä. Tällöin nappulat Savea ja Source-valintaa lukuunottamatta disabloitu. Oletus: False
BtnCssClass	ToolBar:n nappuloihin liitettävä CssClassId Oletus: "HtmlEditTbox_ToolbarImageBtn"
BtnMouseOverColor	Toolbar:n nappuliden taustaväri kun hiiren kursori viedään nappulan päälle Oletus:System.Drawing.SystemColors.Highlight

HtmlEditTboxToolBar-oliosta ei voi luoda olioita komponentin ulkopuolella vaan sen ominaisuuksien kutsuminen käy kontrollin ToolBar ominaisuuden kautta esim. HtmlEditTbox1.ToolBar.BtnSaveToolTip = "Tässäpä tallennus nappula";

5.4 HtmlEditTboxTextbox

Periytyy:

Luokka/rajapinta	Kuvaus (erityisesti kantaluokkanäkökulmasta)
Web.UI.WebControls.ICtrlPart	Internal rajapintaluokka jolla ei ole merkitystä ulkoisen käytön kannalta

Ominaisuus	Kuvaus
BackColor	Tekstiosan (EditTextBox) taustaväri Oletus: System.Drawing.SystemColors.Window
BorderColor	Tekstiosan (EditTextBox) reunuksen väri Oletus: System.Drawing.SystemColors.ControlDark
CssClass	Tekstiosan (EditTextBox) css-luokka Id Oletus: ""
HtmlText	Tekstiosan (EditTextBox) sisältämä Html-muotoinen teksti Oletus: ""
ToolTip	Tekstiosan (EditTextBox) ToolTip Oletus: ""

HtmlEditTboxTextbox-oliosta ei voi luoda olioita komponentin ulkopuolella vaan sen ominaisuuksien kutsuminen käy kontrollin EditTextBox ominaisuuden kautta esim. HtmlEditTbox1.EditTextBox.CssClass = "CssClassId";

5.5 HtmlEditTboxSaveEventArgs

Periytyy:

Luokka/rajapinta	Kuvaus (erityisesti kantaluokkanäkökulmasta)
System.EventArgs	.NET:n eventtiargumenttien kantaluokka. Periyttämisen ansiosta HtmlEditTboxEventArgs -tyypin olio voidaan välittää myös yleisen eventtiargumenttiparametrin (EventArgs) kautta.

Rajapinta

Rajapintametodi/property/eventti	Kuvaus
HtmlEditTboxHTMLValue	Editorin sisältö eventin tapahtumahetkellä (esim. Save) Oletus: ""   Virhekäsittely: -

5.6 HtmlEditTboxDesigner

Periytyy:

Luokka/rajapinta	Kuvaus (erityisesti kantaluokkanäkökulmasta)
System.Web.UI.Desing.ControlDesigner	.NET:n kontrolli Designerien kantaluokka.

Rajapinta

Rajapintametodi/property/eventti	Kuvaus
GetDesignTimeHtml():string	Palauttaa HtmlEditTbox:ia vastaavan suunnittelunaikaisen Html:n  (inherited from ControlDesigner)

6. Esimerkki käytöstä

Tässä esitetään yksinkertainen esimerkki kontrollin lisäämisestä aspx-sivulle Vs.NET -editorilla ja Save-eventin käsittelystä. Sinänsä HtmlEdtiTbox-kontrollin käsittely hoituu Aspx-sivulla kuten minkä tahansa muunkin WebControllin joten mitään erityistä uutta esimerkeissä ei .NET:n Web-kontrolleja aiemmin käsitelleelle ole.

Mikäli kontrollia ei ole vielä lisättynä ToolBox:n valitse Customize ToolBox ja valitse kontrollin dll. ToolBar:iin pitäisi nyt ilmestyä kontrollin kuvake:  . Kopioi vielä kontrollin mukana tullut image-kansio projektisi alihakemistoksi kaikkine kuvineen. Tämän jälkeen kontrolli on normaaliin tapaan lisättävissä aspx-sivulle esim. vedä pudota taktiikalla.

Kun kontrolli on lisätty sivulle pitäisi  sivun näyttää suunnilleen tältä:

ja aspx:n html:n tältä:

Huomaa kontrolin lisäyksen yhteydessä aspx-sivun alkuosaan ilmestynyt seuraavan näköinen rekisteröinti koodi:

Muokataan seuraavaksi muutamaa komponentin ominaisuutta. Muutokset päivittyvät samalla automaattisesti myös suunnittelutilassa joten tätä kautta näkee heti miltä kontrolli oikeasti näyttää:

Ensin säädetään leveys vetämällä hiirellä kontrollia leveämmäksi.

Sama voitaisiin tehdä myös properties-ikkunan kautta josta muutetaan nyt kontrollin taustaväri:

Tämän jälkeen kontrollin ulkoasu suunnittelutilassa muuttuu valintojen mukaisesti. Vastaavasti muutokset näkyvät myös aspx-sivun html-koodissa jonka kautta muutokset olisi tietysti voitu tehdä suoraankin.

Lisätään kontrolliin vielä TboxHtmlSaved-eventin käsittely normaalisti seuraavaan tapaan:

...ja kirjoitetaan eventille käsittelijä:

Tämän jälkeen voidaan kääntää ja ajaa projekti ja tutkia tuloksia  testitekstin kirjoittamisen ja tallennuksen jälkeen:

7. Mistä löydän kontrollin päivitykset ja muuta apua?

• Kontrollin päivityksiä ja uusinta asennuspakettia voi etsiä Web:stä sivulta http://koti.mbnet.fi/lahteenj/Projects/HtmlEditCtrl/
• Tarkempaa informaatiota kontrolliin liittyen voi kysellä sähköpostitse: osoite löytyy kotisivuiltani.