Sursa: W3C

Ce m-a îndemnat să scriu acest articol au fost sesizările primite de către unul dintre clienții noștri, conform cărora utilizatorii aplicațiilor web dezvoltate pentru ei nu le puteau folosi accesându-le prin intermediul conexiunilor de internet mobil (cel pentru laptop și PC). Observațiile primite nu erau legate doar de un operator anume, ci de toți trei prezenți în România – Orange, Vodafone și Cosmote.

Ce se întâmpla de fapt

Odată investigată situația, problema s-a dovedit în realitate ceva mai gravă decât era raportată de către utilizatori. Pe scurt, iată ce am descoperit:

- imaginile erau servite la o calitate inferioară celei originale, datorită compresiei agresive aplicate de către ISP, de până la 50% din dimensiunea originală;

- fișierele JavaScript erau modificate de către ISP, eliminându-se comentariile și nu numai, probabil cu scopul de a micșora traficul generat de descărcarea acestora și de a optimiza încărcarea, însă această transformare era prost implementată, funcționarea scripturilor fiind grav afectată (spre exemplu, apăreau erori la rularea acestora în browser);

- conținutul HTML al paginii era modificat de către ISP (spre exemplu comentariile și newline-urile erau eliminate, însă uneori link-urile către resursele JavaScript erau compromise din cauza unor modificări greșite);

- conținutul fișierelor CSS externe era copiat  de către ISP inline în pagina HTML, iar referințele către fișierele CSS originale erau șterse din document.

O practică destul de des întâlnită

Evident, toate aceste modificări nu puteau fi făcute decât de un proxy configurat de ISP, iar aici am găsit confirmarea acestui fapt. Se pare că, într-adevăr, instalarea și configurarea unui proxy care să cache-uiască și să transforme conținutul web în vederea optimizării traficului pe rețea (cel puțin la nivel declarativ) este o practică des întâlnită printre operatorii de internet mobil, ByteMobile fiind platforma preferată de mulți dintre aceștia (inclusiv de cei de la noi din România).

Ce alte probleme pot fi întâlnite și cum puteți voi, ca dezvoltatori să preveniți acest lucru

Transformările descrise mai sus nu sunt însă singurele pe care un astfel de proxy le poate efectua asupra conținutului unei pagini. Au mai fost raportate modificari precum:

- inserarea inline a conținutului fișierelor JavaScript externe folosite de către documentul HTML;

- inserarea inline a unor secvente de cod JavaScript proprii platformei de optimizare folosite.

Soluția la toate aceste dureri de cap produse de transformări inoportune a conținutului este trimiterea de către aplicație a unei valori speciale a header-ului Cache-Control:

Cache-Control: no-transform

Directiva no-transform este specificată și în RFC2616 și are caracter obligatoriu. Cu alte cuvinte, proxy-urile sunt obligate să transmită nemodificat conținutul paginilor ce includ în antentul lor această directivă. În ceea ce privește cazul nostru, vă pot confirma că această abordare funcționează perfect.

De ce sunt totuși inoportune aceste ”optimizări”

Primul și cel mai important argument este, evident, faptul că în majoritatea cazurilor sunt prost implementate și pot strica funcționalitatea site-ului, producând neplăceri atât utilizatorului, cât și proprietarilor aplicației, cu atât mai mult cu cât aceste modificări sunt făcute uneori fără înștiințarea utilizatorului și fără a-i acorda posibilitatea să renunțe la acest ”feature”;

Apoi, la o analiză atentă se poate observa că, de fapt, unele măsuri de optimizare au fix efectul opus. Să luam ca exemplu inserarea inline a conținutului fișierelor CSS și JavScript. În mod obișnuit, navigatorul descarcă fișierele CSS și JavaScript externe și le salvează pe disc, în cache-ul local pentru un timp oarecare. Când utilizatorul accesează succesiv pagini care fac referire către aceleasi resurse externe, navigatorul le servește pe acestea din cache, evitând astfel descărcarea lor, generând practic zero trafic pentru a le servi. Dacă în schimb conținutul resurselor este inserat inline în paginile HTML, ele vor fi transferate cu fiecare accesare a paginilor respective. Cum de obicei paginile sunt dinamice și nu sunt cache-uite rezultă că de fiecare dată când sunt accesate se transferă integral si conținutul acestor resurse, generând un trafic inutil.

UIPageViewController este de fapt un container al cărui rol principal este cel de a gestiona o colecție de view-controllere (care reprezintă paginile cărții digitale), facilitând navigarea între ele.

Opțiuni de afișare

Tranziții

O tranziție reprezintă efectul folosit pentru animarea navigării de la o pagină (adică un view-controller) la alta. Momentan nu este disponibilă decât o singură opțiune – cea care produce un efect asemănător cu cel din iBooks.

Orientarea navigării

Orientarea pe care se face trecerea între “pagini”. Aici există două opțiuni:

- pe orizontală (UIPageViewControllerNavigationOrientation.Horizontal) – trecerea se face de la stânga la dreapta, sau invers;

- pe verticală (UIPageViewControllerNavigationOrientation.Vertical) – trecerea se face de sus în jos, sau invers.

Pivotul folosit pentru animație (Spine)

Pivotul reprezintă axa în jurul căreia se animează trecerea de la o pagină la alta. Există patru opțiuni:

- UIPageViewControllerSpineLocation.None – Fără pivot – Această opțiune nu este însă validă cu tranziția standard;

- UIPageViewControllerSpineLocation.Min – Pivotul se află în partea stângă a paginii (atunci când trecerea se face pe orizontală), sau în partea de sus a paginii (atunci când trecerea se face pe verticală);

- UIPageViewControllerSpineLocation.Max – Pivotul se află în partea dreaptă a paginii (atunci când trecerea se face pe orizontal), sau în partea de jos a paginii (atunci când trecerea se face pe verticală);

- UIPageViewControllerSpineLocation.Mid – Pivotul se află la mijloc, permițând astfel afișarea a două pagini pe ecran. Acest mod se folosește de obicei atunci când device-ul este orientat landscape.

DoubleSided

Această proprietate a UIPageViewController stabiliește câte pagini sunt vizibile la un moment dat: una dacă are valoarea false, două în caz contrar. Atunci când pivotul se află la mijlocul ecranului, DoubleSided trebuie neapărat să fie true.

Dacă are valoarea true și pivotul nu se află la mijlocul ecranului, framework-ul va plasa view-controller-ele noastre și pe spatele paginilor astfel încât vizibile efectiv nu vor fi decât jumătate din ele. Ca atare, DoubleSided nu este folosită în general decât atunci când pivotul este plasat la mijloc.

Un exemplu de implementare

Pentru a exemplifica API-ul concentrat în jurul UIPageViewController am trasat următoarele cerințe:

- vor fi suportate toate orientările posibile ale interfeței dispozitivului;

- pentru orientările de tip landscape vor fi afișate câte două pagini simultan, iar pentru orientările de tip portrait va fi afișată o singură pagină.

Crearea view-controller-ului cu rol de pagină

Pentru a prezenta paginile, va fi nevoie de un view-controller care să gestioneze conținutul unei pagini. Acesta va fi responsabil pentru actualizarea conținutului în funcție de numărul paginii pe care o reprezintă. În plus, va ști să trateze cazul special al unei pagini placeholder, marcată cu numărul 0.

În exemplul nostru acest view-controller nu face decât să afișeze într-un UILabel numărul paginii curente, neavând practic nimic deosebit în construcția sa.

Constructorul clasei primește drept parametru numărul paginii pentru care va fi afișat conținutul. Acest număr poate fi consultat ulterior prin proprietatea read-only CurrentPage.

public PageContentViewController (int page) : base()
{
     mCurrentPage = page;
}

public int CurrentPage
{
	get {
		return mCurrentPage;
	}
}

În plus, trebui să instruim view-controller-ul să suporte toate orientările posibile:

public override bool ShouldAutorotateToInterfaceOrientation
    (UIInterfaceOrientation toInterfaceOrientation)
{
	return true;
}

Crearea DataSource-ului

DataSource-ul este probabil cea mai importantă componentă care trebuie scrisă. Astfel, aceasta este creată extinzând UIPageViewControllerDataSource, care expune două metode ce pot fi suprascrise și implementate:

- GetNextViewController (UIPageViewController pageViewController, UIViewController refViewController) - trebuie să returneze view-controller-ul care-l succede pe cel curent, dat prin al doilea parametru. Primul parametru reprezintă instanța de UIPageViewController care apelează metoda atunci când utilizatorul face “swipe” pentru a naviga la pagina următoare. Dacă nu mai sunt pagini de afișat (adica dacă ne aflăm deja la ultima pagină) atunci vom returna null.

public override UIViewController GetNextViewController
	(UIPageViewController pageViewCtrl, UIViewController refViewCtrl)
{
	int page = ((PageContentViewController)refViewCtrl).CurrentPage;

	if (page == mTotalPages && pageViewCtrl.SpineLocation ==
		UIPageViewControllerSpineLocation.Mid) {
		return new PageContentViewController(0);
	}
	if (page > 0 && page + 1 <= mTotalPages) {
		return new PageContentViewController(page + 1);
	} else {
		return null;
	}
}

Implementarea prezentată aici este destul de simplă și nu voi insista decât pe liniile 6-9. Atunci când pivotul este situat la mijlocul ecranului (fiind deci afișate câte două pagini simultan), la fiecare gest de navigare făcut de utilizator UIPageViewController-ul apelează de două ori succesiv această metodă pentru a obține paginile ce vor fi afișate, iar dacă vreunul din apeluri returnează null, atunci navigarea nu va mai avea loc. Acest caz este întâlnit atunci când avem un număr impar de pagini. Ca atare, am ales ca ultima pagină să fie o pagină placeholder, marcată cu numărul 0.

- GetPreviousViewController (UIPageViewController pageViewController, UIViewController refViewController) – trebuie să returneze view-controller-ul care-l precedă pe cel curent, sau null dacă pagina curentă este prima pagină. Implementarea este asemănătoare cu cea a GetNextViewController:

public override UIViewController GetPreviousViewController
	(UIPageViewController pageViewCtrl, UIViewController refViewCtrl)
{
	int page = ((PageContentViewController)refViewCtrl).CurrentPage;

	if (page > 0 && page - 1 >= 1) {
		return new PageContentViewController(page - 1);
	} else {
		return null;
	}
}

În plus, pentru conveniență, am adăugat o nouă metodă, GetViewControllers, care primește doi parametri:

- poziționarea pivotului;

- numărul paginii de referință.

Rezultatul execuției este un vector care conține:

- două view-controllere (primul corespunde paginii de referință, iar cel de-al doilea paginii următoare, dacă aceasta există, sau unei pagini placeholder în caz contrar) , dacă pivotul este poziționat la mijlog

- un singur view-controller, corespunzător paginii de referință, în celelalte situații.

Metoda este apelată atât la selectarea view-controller-elor afișate inițial, cât și la schimbarea orientării dispozitivului, pentru a determina care sunt paginile ce trebuie afișate.

public PageContentViewController[] GetViewControllers
    (UIPageViewControllerSpineLocation spine, int fromPage)
{
	List<PageContentViewController> viewControllers =
		new List<PageContentViewController>(2);

	if (mTotalPages == 0) {
		return new PageContentViewController[] {};
	}
	if (fromPage > mTotalPages) {
		fromPage = mTotalPages;
	}

	viewControllers.Add(new PageContentViewController(fromPage));
	if (spine == UIPageViewControllerSpineLocation.Mid) {
		if (fromPage + 1 > mTotalPages) {
			fromPage = 0;
		} else {
			fromPage ++;
		}
		viewControllers.Add(new PageContentViewController(fromPage));
	}

	return viewControllers.ToArray();
}

Crearea Delegate-ului

Implementarea Delegate-ului este în principiu opțională, dar absolut necesară în cazul nostru, deoarece ne dorim să variem poziția pivotului (și implicit numărul de pagini afișate) în funcție de orientarea interfeței dispozitivului.

Pentru a obține acest lucru trebuie să suprascriem metoda GetSpineLocation care primește doi parametri:

- UIPageViewController-ul care o apelează;

- orientarea interfeței dispozitivului.

public override UIPageViewControllerSpineLocation GetSpineLocation
	(UIPageViewController pageViewCtrl, UIInterfaceOrientation o)
{
	BookDataSource ds = (BookDataSource)pageViewCtrl.DataSource;
	UIPageViewControllerSpineLocation spine;
	PageContentViewController page =
		(PageContentViewController)pageViewCtrl.ViewControllers[0];
	int startPage = page.CurrentPage;

	if (o == UIInterfaceOrientation.LandscapeLeft ||
		o == UIInterfaceOrientation.LandscapeRight) {
		spine = UIPageViewControllerSpineLocation.Mid;
		pageViewCtrl.DoubleSided = true;
		if (page.CurrentPage % 2 == 0) {
			startPage = page.CurrentPage - 1;
		}
	} else {
		spine = UIPageViewControllerSpineLocation.Min;
		pageViewCtrl.DoubleSided = false;
	}

	pageViewCtrl.SetViewControllers(
		ds.GetViewControllers(spine, startPage),
		UIPageViewControllerNavigationDirection.Forward,
		true, delegate(bool finished) {
			return;
	});
	return spine;
}

În exemplul de față sunt parcurși următorii pași:

- este determinată noua poziție a pivotului;

- instruim UIPageViewController-ul să afișeze una sau două pagini (via proprietatea DoubleSided, care trebuie să fie obligatoriu setată la valoarea true atunci când pivotul este situat la mijloc);

- setăm noile view-controllere care vor fi afișate (spre exemplu, dacă interfața este orientată portrait, afișând o singură pagină – pagina 7, și utilizatorul schimbă orientarea în landscape, vor fi afișate view-controller-ele corespunzătoare paginilor 7 și 8).

Crearea container-ului care va coordona activitatea

Pentru a folosi un UIPageViewController vom avea nevoie de un container pentru acesta. În exemplul nostru, rolurile acestui container sunt după cum urmează:

- creează o instanță de UIPageViewController, pe care o configurează cu DataSource-ul și Delegate-ul corespunzătoare;

- setează view-controller-ele afișate inițial, folosind metoda UIPageViewController.SetViewControllers;

- implementează metoda ShouldAutorotateToInterfaceOrientation, pentru a suporta toate orientările posibile ale unui dispozitiv.

public override void ViewDidLoad ()
{
	UIViewController[] viewControllers = null;
	base.ViewDidLoad ();

	mDs = new BookDataSource();
	mDlg = new BookDelegate();

	mBook = new UIPageViewController(
		UIPageViewControllerTransitionStyle.PageCurl,
		UIPageViewControllerNavigationOrientation.Horizontal,
		UIPageViewControllerSpineLocation.Min
	);
	viewControllers = mDs.GetViewControllers(mBook.SpineLocation, 1);

	mBook.DataSource = mDs;
	mBook.Delegate = mDlg;
	mBook.View.Frame = View.Bounds;

	mBook.SetViewControllers(
		viewControllers,
		UIPageViewControllerNavigationDirection.Forward,
		false, delegate(bool finished) {
			return;
	});

	View.AddSubview(mBook.View);
	AddChildViewController(mBook);
}

Metoda UIPageViewController.SetViewControllers primește următorii parametri:

- Un vector care conține view-controller-ele ce vor fi afișate. Ca regulă, acest vector conține două view-controllere atunci când pivotul este UIPageViewControllerSpineLocation.Mid și unul singur în celelalte cazuri;

- Direcția de navigare către noile view-controllere: UIPageViewControllerNavigationDirection.Forward (navigare înainte) sau UIPageViewControllerNavigationDirection.Reverse (navigare înapoi). De reținut faptul că aceast parametru nu afectează decât modul în care este animată tranziția curentă, neavând efect asupra tranzițiilor următoare;

- Dacă tranziția este animată sau nu;

- Un callback ce va fi apelat atunci când tranziția este finalizată. Acest callback trebuie să primească un parametru de tip boolean care este true dacă animația a fost finalizată, respectiv false dacă animația nu a fost executată.

În plus, trebuie menționat că fără a adăuga explicită UIPageViewController-ul drept copil al container-ului nostru, metoda GetSpineLocation a Delegate-ului nu va fi apelată, de unde utilitatea liniei 28.

Folosirea acestor clase

Odată create aceste clase, utilizarea lor este simplă și se reduce la a adăuga container-ul nostru în ierarhia de view-uri a aplicației:

[Register ("AppDelegate")]
public partial class AppDelegate : UIApplicationDelegate
{
	private UIWindow window;

	private BookViewController mBook = null;

	public override bool FinishedLaunching
            (UIApplication app, NSDictionary opts)
	{
		mBook = new BookViewController();

		window = new UIWindow (UIScreen.MainScreen.Bounds);
		window.RootViewController = mBook;
		window.MakeKeyAndVisible ();

		return true;
	}
}

Click aici pentru a descărca proiectul care exemplifică toate aceste concepte.

Datele problemei

Avem următoarea sarcină de lucru: trebuie să prezentăm o pagină al cărei conținut nu se schimbă foarte des și este același, indiferent de utilizatorul autentificat, fiind astfel un candidat foarte bun pentru output caching. Totuși, există o mică zonă din pagină care poate varia: link-ul de log-in (care apare dacă utilizatorul nu e autentificat), sau de log-out (care apare dacă utilizatorul este autentificat). Problema este că, odată salvat răspunsul în cache, acel link va rămâne același din momentul primei accesări a paginii, indiferent utilizatorul se autentifică sau nu ulterior.

Prima soluție

Prima soluție, cea mai simplă, implică folosirea controlului asp:Substitution cu o metodă callback care produce întreg HTML-ul necesar afișării link-ului. Adică ceva de genul:

<asp:Substitution ID="LinkSubstitution" runat="server" MethodName="GenerateLink" />

unde GenerateLink este definită în code-behind astfel:

public static string GenerateLink(HttpContext context)
{
    bool auth = false;
    if (context.Request["IsAuthenticated"] == "true")
        auth = true;
   if (auth)
       return "<a href=\"Logout.aspx\">Log-out</a>";
   else
       return "<a href=\"Login.aspx\">Log-in</a>";
}

Observație: De reținut e faptul că metoda callback nu poate aparține unui instanțe de obiect de tip Page sau Control. Trebuie să fie ori statică, ori să aparțină unei instanțe de obiect de tip diferit.

O rezolvare mai bună

Soluția de  mai sus, deși ușor de implementat, nu este deloc elegantă, pretându-se mai degrabă ca artificiu temporar și nu ca o soluție de durată.

Ideal ar fi să avem o componentă care să ne ofere posibilitatea de varia codul HTML generat în funcție de rezultatul callback-ului dat de noi. În cazul nostru, acest rezultat ar fi format din: text-ul link-ului, adresa lui (atributul href) și, opțional, atributul title al acestuia. Aceste informații le vom grupa într-o mică clasă, după cum urmează:

public class HtmlDynamicAnchorData
{
     public string Href;
     public string Text;
     public string Title;

     public HtmlDynamicAnchorData(string href, string txt)
     {
         Href = href;
         Text = txt;
     }

     public HtmlDynamicAnchorData(string href, string txt, string t)
         : this(href, txt)
     {
         Title = t;
     }
}

Pentru a crea o componentă reutilizabilă și ușor de folosit, am ales varianta dezvoltării ei ca un server control, pe care l-am denumit HtmlDynamicAnchor. Clasa de bază pentru acesta este System.Web.UI.Control, întrucât nu avem nevoie decât de funcționalități minime, cum ar fi folosirea view-state-ului și renderizarea.

Controlul expune două proprietăți:

- CssClass – folosită pentru a stabili clasa CSS a link-ului – opțional;

- MethodName – folosită pentru a stabili numele metodei ce va returna datele necesare: titlu, url și text – obligatoriu. Această metodă trebuie să primească drept parametru un obiect de tip HttpContext și să returneze un obiect de tip HtmlDynamicAnchorData.

În plus, am suprascris metoda Control.RenderControl, astfel încât, în loc de a scrie output-ul propriu-zis, scrie un placeholder pentru a marca faptul că va fi actualizat dinamic chiar și atunci când pagina sau control-ul din care face parte va fi cache-uit:

public override void RenderControl(HtmlTextWriter output)
{
    TemplateControl tc = TemplateControl;
    Type dlgType = typeof(HtmlDynamicAnchorDataDelegate);
    HtmlDynamicAnchorDataDelegate dataDlg = null;
    Dictionary<string, string> attribs = null;
    HtmlDynamicAnchorSubstitution subst = null;
    string attrib = null;

    try
    {
        dataDlg = (HtmlDynamicAnchorDataDelegate)
           Delegate.CreateDelegate(dlgType, tc.GetType(), MethodName);
    }
    catch (Exception)
    {
        dataDlg = null;
    }

    if (dataDlg == null)
        ThrowBadMethodName(MethodName);

    attribs = new Dictionary<string, string>();
    attrib = CssClass;
    if (!string.IsNullOrEmpty(attrib))
        attribs.Add("class", attrib);

    subst = new HtmlDynamicAnchorSubstitution(dataDlg, attribs);
    subst.RegisterCallback(HttpContext.Current);
}

unde HtmlDynamicAnchorDataDelegate este definită astfel:

public delegate HtmlDynamicAnchorData
        HtmlDynamicAnchorDataDelegate(HttpContext context);

Majoritatea operațiilor efectuate de această metodă ar trebui sa fie clare, punctul de interes constituindu-l ultimele două linii. Astfel, HtmlDynamicAnchorSubstitution reprezintă o clasă ajutătoare care:

- prin intermediul metodei RegisterCallback apelează HttpResponse.WriteSubstitution având ca parametru metoda privată Render(context);

public void RegisterCallback(HttpContext context)
{
    HttpResponseSubstitutionCallback callback = null;
    HttpResponse response = context.Response;

    callback = new HttpResponseSubstitutionCallback(Render);
    response.WriteSubstitution(callback);
}

- ține o referință către delegate-ul al cărui nume l-am transmis controlului nostru, astfel încât, atunci cand metoda privată Render este apelată, delegate-ul respectiv va fi folosit pentru a obține datele necesare redării link-ului propriu-zis.

private string Render(HttpContext context)
{
    StringBuilder sb = null;
    HtmlDynamicAnchorData data = null;

    if (mDataDlg != null)
        data = mDataDlg(context);
    data = mDataDlg(context);
    if (data == null)
        return string.Empty;

    sb = new StringBuilder();
    sb.Append("<a");

    foreach (string attribute in mAttributes.Keys)
    {
        if (attribute == "href" || attribute == "title")
            continue;
        AppendAttribute(sb, attribute, mAttributes[attribute]);
    }

    if (!string.IsNullOrEmpty(data.Href))
        AppendAttribute(sb, "href", data.Href);
    if (!string.IsNullOrEmpty(data.Title))
        AppendAttribute(sb, "title", data.Title);

    sb.Append(">");
    if (mDataDlg != null)
        sb.Append(HttpUtility.HtmlEncode(data.InnerText));
    sb.Append("</a>");

    return sb.ToString();
}

Pentru motivul care ne impune folosirea unei clase ajutătoare, vezi obsevația de mai sus.

Folosirea controlului astfel creat

În primul rând, trebuie definită (spre exemplu, în code-behind) metoda care va genera datele pentru redarea controlului:

public static HtmlDynamicAnchorData GetLinkData(HttpContext context)
{
    bool auth = false;
    if (context.Request["IsAuthenticated"] == "true")
        auth = true;
   if (!auth)
       return new HtmlDynamicAnchorData("Login.aspx", "Log-in");
   else
       return new HtmlDynamicAnchorData("Logout.aspx", "Log-out");
}

Folosirea este apoi cât se poate de simplă:

- mai întâi înregistrăm controlul:

<%@ Register Assembly="AssemblyName"
    Namespace="ContorlNamespace" TagPrefix="ui" %>

- apoi îl plasăm unde dorim în pagină:

<ui:HtmlDynamicAnchor ID="DynamicAnchor"
    runat="server" MethodName="GetLinkData" />

În sfârșit, atașez acestui articol un mic proiect demonstrativ, care include întreg codul sursă pentru acest control plus un exemplu de utilizare. Click aici pentru descărcare.

Și în caz că vă întrebați, ce legătură există între articol și imagine, aflați că procedeul descris aici se mai numeste și ”donut caching” .

- XDebug – o extensie PHP care oferă facilități precum profiling, code coverage, remote debugging, afișarea stack trace-urilor, afișarea îmbunătățită a rezultatelor produse de var_dump etc.;

- APD – Advanced PHP Debugger – este tot o extensie de PHP care oferă un API pentru debugging;

- DBG – software disponibil atât gratuit, cât și cu plată;

- FirePHP – permite tipărirea mesajelor în consola Firebug, folosind apeluri de funcții executate în scripturile PHP;

- Zend IDE, care vine cu propriul său debugger etc.

Primii pași

Atunci când începem un proiect este bine să avem un mediu de dezvoltare configurat corespunzător, astfel încât să putem fi notificați din timp de eventualele probleme apărute, oricât de nesemnificative ar putea fi. Astfel, când dezvoltăm o aplicație în PHP trebuie să ne asigurăm ca nivelul de raportare a erorilor este cel mai ridicat posibil și că, evident, PHP-ul este configurat să afișeze erorile. Setările necesare ar putea fi făcute dinamic la începutul unui script, după cum urmează:

ini_set('display_errors', 'On');
error_reporting(E_ALL);

Merită menționat faptul că, începând cu PHP5, este disponibilă constanta E_STRICT, care, printre altele, activează emiterea avertizărilor referitoare la metodele deprecated folosite în programul vostru. Astfel, linia 2 ar deveni:

error_reporting(E_ALL | E_STRICT)

Suportul standard existent în PHP – limitat

După cum am spus și mai devreme, suportul standard pentru debugging în PHP este insuficient, fiindu-ne puse la dispoziție doar câteva funcții, cum ar fi: var_dump, print_r, sau debug_backtrace. Dintre ele, probabil cea mai utilă (probabil după var_dump ) ar fi debug_backtrace care, după cum afirmă și numele ei, generează o listă detaliată cu toate apelurile ce au condus la execuția funcției sau liniei unde a fost utilizată, returnând această listă ca un array. Iată și un exemplu:

function error_handler($errNo, $errStr) {
    print '<pre>';
    var_dump(debug_backtrace());
    print '</pre>';
}

set_error_handler('error_handler');
trigger_error('An error occured', E_USER_ERROR);

Am ilustrat aici un posibil scenariu de utilizare: obținerea backtrace-ului într-un handler global de erori, pentru a investiga condițiile producerii erorii respective. O puteți folosi însă în orice funcție în care doriți să aflați care este contextul în care aceasta este executată.

Componente externe pe care le putem folosi

Pe lângă capabilitățile standard, avem la dispoziție o suită întreagă de extensii și de tool-uri externe de debugging, o parte din ele amintite ceva mai sus. În continuare voi vorbi însă numai de una dintre ele: XDebug.

XDebug

XDebug este o extensie de PHP care facilitează depanarea scripturilor oferind funcționalități precum:

- stacktrace-uri cu un nivel configurabil de detaliere, furnizate automat la apariția unei erori;

- afișarea îmbunătățită a conținutului variabilelor;

- code coverage – evidențierea liniilor și secvențelor de cod ce au fost efectiv rulate într-un script;

- profiling – măsurarea performanțelor înregistrate de script ca ajutor în determinarea punctelor lente conținute de acesta;

- remote debugging – XDebug furnizează o interfață prin care programele externe de debugging pot interacționa cu scripturile PHP.

Stacktrace-urile și configurarea detaliilor oferite de acestea

Atunci când în script va fi declanșată o eroare, fie ea de către interpretor, fie de către programator (folosind trigger_error), XDebug este configurat să afișeze implicit un stacktrace asociat acelei erori.

function trigger_user_error() {
    trigger_error('An error occured', E_USER_ERROR);
}
trigger_user_error();

Această secvență de cod va produce următorul stacktrace:

Implicit, sunt prezentate următoarele informații:

- Momentul de timp la care a început execuția funcției;

- Câtă memorie era folosită în momentul respectiv;

- Numele funcției executate;

- Locul (fișierul și linia) în care a fost executată funcția.

Dar, uneori avem nevoie de ceva mai multe informații decât atât, cum ar fi informații despre variabilele transmise ca parametru funcțiilor afișate în stacktrace. Pentru a obține aceste informații, trebuie să activăm colectarea parametrilor în XDebug, atribuind valoarea dorită directivei de configurare xdebug.collect_params. Spre exemplu, atribuirea valorii 4 are drept rezultat afișarea numelui variabilei și a conținutului acesteia:

ini_set('xdebug.collect_params', '4');

Pe lângă această facilitate, XDebug mai permite și afișarea conținutului variabilelor superglobale, sau a celor locale. Pentru mai multe detalii, accesați pagina de documentație referitoare la stacktrace-uri.

Totuși, dacă dintr-un oarecare motiv doriți să dezactivați temporar afișarea stacktrace-urilor, puteți folosi funcția xdebug_disable() și, pentru a reactiva această funcționalitate, xdebug_enable().

Afișarea îmbunătățită a conținutului variabilelor

XDebug înlocuiește funcția var_dump existentă în PHP, varianta oferită în schimb producând un output preformatat (nu mai este deci nevoie să folosim tag-ul <pre> pentru a putea citi rezultatul funcției), în care tipurile diferite de date sunt colorate diferit, permițând totodată configurarea nivelului maxim de imbricare, precum și a porțiunii afișabile dintr-un șir de caractere.

ini_set('xdebug.var_display_max_children', 5);
ini_set('xdebug.var_display_max_data', 5);
ini_set('xdebug.var_display_max_depth', 1);

$object = new stdClass;
$object->self = $object;

$array = array(
	'first' => 1,
	'second' => 2,
	'third' => 3,
	'fourth' => 'Lorem ipsum dolor sit amet (...)',
	'fifth' => $object,
	'sixth' => 'Not shown'
);
var_dump($array);

Secvența de cod de mai sus produce următorul rezultat:

Astfel:

- numărul de elemente afișate dintr-un array poate fi configurat cu ajutorul directivei xdebug.var_display_max_children;

- numărul de caractere afișate dintr-un string poate fi configurat cu ajutorul directivei xdebug.var_display_max_data;

- nivelul maxim de niveluri imbricate afișate (în cazul array-urilor și al obiectelor) poate fi configurat cu ajutorul directivei xdebug.var_display_max_depth.

Code coverage

Activarea code coverage-ului permite detectarea liniilor dintr-un script, precum și fișierele corespunzătoare, care sunt efectiv executate la rularea unui program. Acest lucru este util atunci când doriți să aflați cât de eficiente sunt testele pe care le-ați scris, întrucât vă arată practic ce zone de cod au rămas neacoperite de test case-uri.

ini_set('xdebug.coverage_enable', '1');

xdebug_start_code_coverage();

function execute($value) {
	if ($value % 2 == 0) {
		return $value + 3;
	} else {
		return $value + 2;
	}
}

$values = array( 2, 4, 6, 8, 10 );
foreach ($values as $value) {
	$value = execute($value);
}

$coverage = xdebug_get_code_coverage();

print '<pre>';
foreach ($coverage as $file => $execLines) {
	$fileContents = file($file);
	$lines = array_keys($execLines);
	print '<b>' . $file . '</b>' . PHP_EOL;
	foreach ($fileContents as $idx => $line) {
		if (in_array($idx + 1, $lines)) {
			print '<span style="background-color:red; color:white;">'
				. htmlentities($line) .
					'</span>';
		} else {
			print htmlentities($line);
		}
	}
}
print '</pre>';

Exemplul de față ilustrează următoarele operații:

- activarea code coverage-ului (acesta este dezactivat implicit, din motive ce țin de performanță);

- începerea colectării informațiilor legate de code-coverage, apelând xdebug_start_code_coverage();

- citirea acestor informații într-un array, folosind xdebug_get_code_coverage();

- folosirea datelor obținute pentru a evidenția liniile executate (liniile 20 – 35).

Remote debugging

XDebug oferă o interfață prin intermediul căreia clienții de debugging pot interacționa cu scripturile PHP. Pentru a realiza acest lucru, XDebug pune la dispoziție două protocoale:

- vechiul protocol GDB, folosit din linia de comandă;

- DBGp, suportat începând cu XDebug 2, folosit și în exemplele de mai jos.

În ceea ce privește clienții de debugging, oferta este foarte variată, din care am ales plug-in-ul de Notepad++, ce poate fi descărcat gratuit de aici. Pentru a-l instala, pur și simplu copiați fișierul dbgpPlugin.dll în folderul plugins din locul unde ați instalat Notepad++, după care reporniți editorul.

Pentru a putea iniția o sesiune de debugging trebuie mai întâi să configurați XDebug:

- activarea suportului pentru remote debugging se face atribuind valoarea 1 directivei xdebug.remote_enable;

- adresa unde rulează clientul de debugging și portul pe care ascultă acesta sunt specificate ca valori ale directivelor xdebug.remote_host, respectiv xdebug.remote_port;

- modul de debugging este stabilit folosind directiva xdebug.remote_mode; valorile posibile sunt ”req” (implicit, sesiunea de debugging este inițiată odată cu pornirea scriptului) sau ”jit” (sesiunea de debugging este inițiată la apariția unei erori).

Aceste configurări vor fi salvate în php.ini, sub grupul XDebug:

[XDebug]
xdebug.remote_enable = 1
xdebug.remote_host = 127.0.0.1
xdebug.remote_port = 9000
xdebug.remote_mode = req

Pentru ca aceste modificări să aibă efect, trebuie ca server-ul web să fie repornit. Odată configurat XDebug, puteți porni consola de debugging din Notepad++:

Interfața de debugging oferă aproape toate controalele obișnuite pentru o astfel de consolă: stabilirea breakpoint-urilor, step-in, step-out, step-over, watch etc. După ce ați stabilit breakpoint-urile nu vă ramâne decât să accesați din browser script-ul pe care doriți să îl depanați adăugand la URL parametrul XDEBUG_SESSION_START=nume_sesiune, pentru a activa debugger-ul.

Pentru a putea vedea contextele local (variabilele aflate în scriptul / metoda / funcția curentă) și global (variabilele superglobale$_SERVER, $_ENV etc.) actualizate la fiecare step, trebuie să accesați interfața de configurare a plugin-ului: Plugins / DBGp / Config. Aici va trebui să bifați următoarele opțiuni:

- Refresh local context on every step – pentru actualizarea contextului local;

- Refresh global context on every step – pentru actualizarea contextului global.

SSH.NET este un proiect complet nou, foarte bine scris care, din câte observ, primește din ce în ce mai multă atenție (paradoxal însă, am dat destul de greu de el). Fiind însă destul de slab documentat (pe undeva e și normal să fie așa, focusul fiind momentan pe dezvoltare) m-am gândit că ar fi bine sa ilustrez într-o serie de două articole modalitatea de utilizare a acestei librării pentru a lucra cu SFTP, respectiv SSH în C#/.NET.

Conectarea

Întâi de toate, trebuie să aflați ce modalități de conectare suportă server-ul la care vă conectați. Odată ce aflați aceste detalii, veți configura o instanță a uneia dintre clasele:

- PrivateKeyConnectionInfo – pentru autentificarea folosind o pereche de chei;

- PasswordConnectionInfo – pentru autentificarea folosind un nume de utilizator și o parolă;

- KeyboardInteractiveConnectionInfo – pentru a folosi modalitatea de autentificare interactivă (care, în particular, poate funcționa asemănător modalității de autentificare cu parolă).

pentru a vă putea autentifica.

În exemplul de mai jos am folosit modalitatea de autentificare interactivă:

private void ConnectToServer()
{
    _kbConnectionInfo = new KeyboardInteractiveConnectionInfo("127.0.0.1", 22, "root");
    _kbConnectionInfo.AuthenticationBanner += new EventHandler(OnAuthenticationBanner);
    _kbConnectionInfo.AuthenticationPrompt += new EventHandler(OnAuthenticationPrompt);
    _sftpClient = new SftpClient(_kbConnectionInfo);
    _sftpClient.Connect();
}

private void OnAuthenticationPrompt(object sender, AuthenticationPromptEventArgs e)
{
    foreach (AuthenticationPrompt p in e.Prompts)
        p.Response = "root";
}

private void OnAuthenticationBanner(object sender, AuthenticationBannerEventArgs e)
{
    Console.WriteLine(e.BannerMessage);
}

Se observă că, pe lângă simpla furnizare a adresei server-ului, a portului si a numelui de utilizator, atașăm handlere pentru două evenimente:

- AuthenticationBanner – care este declanșat atunci când (și dacă) banner-ul de autentificare este trimis dinspre server. Acest eveniment este disponibil indiferent de ce modalitate de autentificare veți folosi și nu este neapărat necesar să înregistrați un handler pentru el;

- AuthenticationPrompt – este declanșat atunci când server-ul trimite prompt-urile de autentificare. Acest eveniment este specific modalității de autentificare interactivă și este obligatoriu să înregistrați un handler pentru el, în vederea finalizării cu succes a autentificării. În cazul de față, este vorba de un server care pur și simplu se așteptă să îi trimitem o parolă validă, așă că nu avem altceva de făcut decât să scriem parola în răspunsul prompt-ului conținut în colecția e.Prompts. Pentru scenarii mai avansate însă, puteți inspecta și proprietatea AuthenticationPrompt.Request pentru a lua deciziile potrivite.

Odată creat și configurat obiectul ce reprezintă modalitatea de autentificare, acesta va fi dat ca parametru la crearea unei noi instanțe de SftpClient, clasa care oferă metodele de lucru cu fișierele si directoarele server-ului prin intermediul SFTP.

Lucrul cu fișierele și directoarele

Cum scopul principal al unui client SFTP îl reprezintă manipularea fișierelor și directoarelor, să vedem ce ne oferă SSH.NET în acest sens.

Cea mai simplă operație posibilă este aflarea directorului curent:

Console.WriteLine(_sftpClient.WorkingDirectory);

Pentru a lista conținutul unui director vom folosi metoda SftpClient.ListDirectory, ce returnează o colecție de obiecte de tip SftpFile:

_entries = _sftpClient.ListDirectory("/path/or/dir");
foreach (SftpFile _entry in _entries)
    Console.WriteLine(_entry.Name);

Schimbarea directorului curent se realizează foarte simplu, folosind metoda SftpClient.ChangeDirectory:

_sftpClient.ChangeDirectory("/path/to/dir");

Pentru a copia un fișier de pe server se folosește metoda SftpClient.DownloadFile, care ia ca parametri calea fișierului ce va fi descărcat de pe server și un System.IO.Stream în care va fi scris fișierul:

_fs = new FileStream("/to", FileMode.OpenOrCreate, FileAccess.Write);
_sftpClient.DownloadFile("/from", _fs);

Pentru a încărca un fișier pe server vom proceda asemănător, folsind metoda SftpClient.UploadFile, care ia ca parametri un System.IO.Stream din care va fi citit conținutul fișierului și calea de pe server unde va fi stocat:

_fs = new FileStream("/from", FileMode.Open, FileAccess.Read);
_sftpClient.UploadFile(_fs, "/to");

De remarcat că aceste două metode, UploadFile și DownloadFile nu limitează scenariile de utilizare la încărcarea dintr-un fișier, respectiv descărcarea într-un fișier, programatorul putând opta pentru folosirea și altor tipuri de stream-uri, cum ar fi un System.IO.MemoryStream.

Dar dacă dorim să ștergem un fișier sau un director? În acest caz vom folosi metodele SftpClient.DeleteFile, respectiv SftpClient.DeleteDirectory:

_sftpClient.DeleteFile("/path/to/delete");

O metodă la fel de utilă este și SftpClient.Exists care returnează true în cazul existenței căii către fișierul sau directorul dat ca parametru.

Tratarea erorilor

Cum lucrurile mai merg și prost uneori, aceste metode pot genera excepții, în funcție de cazurile limită întâlnite. Astfel:

- o excepție de tip SftpPermissionDeniedException este generată atunci când operația nu este permisă pentru utilizatorul curent;

- o excepție de tip SftpPathNotFoundException este generată atunci când calea asupra căreia se efectuează operația nu a fost găsită pe server;

- o excepție de tip SshException când orice altceva merge prost în comunicația dintre server și client.

Astfel, o operație efectuată pe server nu se reduce la un simplu apel al metodei corespunzătoare, fiind necesară și o tratare a erorilor. Spre exemplu, operația de ștergere a unui fișier ar putea arăta așa:

try
{
    _sftpClient.DeleteFile("/at/path");
}
catch (SftpPathNotFoundException)
{
    Console.WriteLine("Path not found");
}
catch (SftpPermissionDeniedException)
{
    Console.WriteLine("Permission denied");
}
catch (Exception)
{
    Console.WriteLine("File could not be deleted");
}

Operații asincrone

Toate operațiile descrise până acum au fost sincrone, fapt ce ne poate pune în dificultate dacă avem de-a face cu operații care necesită mult timp pentru a fi terminate (ex: transferul unui fișier mare, latența mare a rețelei etc.). Soluțiile la această problemă sunt fie desfășurarea operațiilor explicit într-un thread separat de thread-ul în care rulează interfața, fie utilizarea facilităților de operații asincrone oferite de clasa SftpClient. Pentru exemplificare am ales operația de încărcare a unui fișier:

_fs = new FileStream("/from", FileMode.Open, FileAccess.Read);
_sftpClient.BeginUploadFile(_fs, "/to", AsyncCopyCallback, _fs);

unde AsyncCopyCallback este definită astfel:

private void AsyncCopyCallback(IAsyncResult result)
{
    FileStream _uploadedStream = null;

    try
    {
        _sftpClient.EndUploadFile(result);
    }
    catch (SftpPathNotFoundException)
    {
        Console.WriteLine("Path not found");
    }
    catch (SftpPermissionDeniedException)
    {
        Console.WriteLine("Permission denied");
    }
    catch (Exception)
    {
        Console.WriteLine("Could not copy file");
    }
    finally
    {
        _uploadedStream = result.AsyncState as FileStream;
        if (_uploadedStream != null)
            _uploadedStream.Dispose();
    }
}

Vă sunt dator cu câteva explicații:

- orice excepție apărută în timp ce fișierul este încărcat, va fi generată odată cu apelul metodei EndUploadFile (acest lucru este de fapt general valabil pentru orice metodă invocată asincron în .NET, nu numai în cazul particular al librăriei SSH.NET care reproduce acest comportament);

- toate operațiile primesc drept parametri suplimentari un callback ce va fi executat când se finalizează operația (putem seta acest parametru la valoarea null daca nu suntem interesați de a primi această notificare) și un obiect ce poate conține informații suplimentare și care se regăsește în IAsyncResult.AsyncState (și acesta poate fi, și de cele mai multe ori chiar este, setat la valoarea null). În cazul de față, cel din urmă parametru este folosit pentru a transmit stream-ul din care se citește, pentru a-l putea închide la finalul operației (evident, puteam să ținem o referință către stream într-o variabilă privată, însă poate nu ne dorim întotdeauna acest lucru).

La final, atașez un mic proiect care exemplifică utilizarea clasei SftpClient. Proiectul conține o aplicație ce rulează în consolă și oferă câteva funcționalități de bază pentru interacționarea cu un server SFTP, a cărui adresă o puteți configura în app.config. Numele de utilizator și parola folosite la autentificare pot fi deasemenea configurate în app.config.

Tehnologii folosite

- ActionScript și Adobe Air pentru dezvoltarea aplicației desktop;

- C# și ASP.NET pentru serviciile web ce rulează pe serverele NORC și furnizează date pentru aplicație.

Responsabilitățile avute în cadrul proiectului

- dezvoltarea integrală a aplicației desktop;

- am contribuit la dezvoltarea serviciului web ce furnizează date pentru aplicație.

Scurtă descriere a aplicației

Aplicația NorcImoDesktop propune o modalitate simplă pentru gestionarea anunțurilor existente pe NORC Imobiliare, precum și pentru adăugarea de noi anunțuri.

Facilitățile oferite includ:

- o interfata simpla si bine structurata pentru introducerea de anunturi noi pe site;

- modificarea textului anuntului, asistata de sugestii de descriere precum si de generarea automata a unui text ce include punctele de interes din jur;

- modificarea/stabilirea amplasamentului proprietatii folosind harta digitala;

- promovarea anunțurilor;

- vizualizarea performanțelor contului.

Pentru a nu da acestei expuneri un aer plictisitor de manual școlar, am ales să exemplific conceptele folosind un site aflat în producție, alegând în acest scop www.realitatea.net. Voi extrage din pagina principală a acestui site următoarele elemente:

- titlul paginii HTML;

- toate foile de still incluse;

- toate scripturile externe incluse;

- articolul principal: titlu, fotografie și conținut;

- cele mai noi știri: titlu si link.

Pregătirile

Pentru început, va trebui să descărcați SimpleHtmlDom de aici. Pachetul include mai multe fișiere și directoare, dar veți avea nevoie doar de simple_html_dom.php, pe care îl veți include ca de obicei:

require_once 'simple_html_dom.php';

Analiza paginii

Pasul următor presupune puțină muncă de documentare: dacă modalitatea de obținere a script-urilor, foilor de stil și a titlului este identică pentru orice pagină html, pentru a citi celelalte elemente va trebui să analizăm structura paginii în cauză. Acest lucru poate fi făcut vizualizând direct sursa sau, mai ușor, folosind Firebug. Iată ce obținem:

Codul HTML pentru articolul principal

Codul HTML pentru lista de cele mai noi articole

Să trecem la treabă

Înarmați cu aceste informații, putem  începe lucrul efectiv. Mai întâi, încărcăm pagina și construim arborele DOM:

$html = file_get_html('http://www.realitatea.net/');

Pentru obținerea titlului paginii, nu avem decât să  căutam primul element și să îi citim conținutul:

$title = $html->find('title', 0);
if ($title) {
    $title = $title->plaintext;
}

Metoda find este metoda pe care o veți folosi cel mai mult. Exemplul de față este probabil cel mai simplu caz de utilizare: găsește elementele având tag-ul dat ca prim parametru (title) și returnează numai elementul cu indexul dat ca al doilea parametru (0, adică primul element). În plus, mai merită menționat că putem obține conținutul text al unui element (din care au fost scoase tag-urile HTML) folosind proprietatea plaintext (ex: $title->plaintext).

Să citim acum lista de script-uri și lista de foi de stil:

$styles = array();
$domStyles = $html->find('link[rel=stylesheet]');
foreach ($domStyles as $ds) {
    $styles[] = $ds->href;
}

$scripts = array();
$domJs = $html->find('script[type=text/javascript]');
foreach ($domJs as $dj) {
    if (!$dj->src) {
        continue;
    }
    $scripts[] = $dj->src;
}

Aceste două exemple ilustrează o altă modalitate de selecție a elementelor: toate elementele HTML cu numele de tag dat,  filtrând după valoarea unui anumit atribut (ex: style[rel=stylesheet]), precum și faptul că putem accesa atributele html ca proprietăți ale obiectului ce reprezintă tag-ul respectiv ($ds->href).

Urmează extragerea articolului principal:

$mainNews = array();
$mainNewsDom = $html->getElementById('mainNews');
if ($mainNewsDom) {
	//title
	$mainNewsTitleDom = $mainNewsDom->find('div.title h2', 0);
	if ($mainNewsTitleDom) {
		$mainNews['title'] = $mainNewsTitleDom->plaintext;
	}

	//content
	$mainNewsContentDom = $mainNewsDom->find('div.leadIn p');
	if ($mainNewsContentDom) {
		foreach ($mainNewsContentDom as $content) {
			$content = trim($content->plaintext);
			if (empty($content)) {
				continue;
			}
			$mainNews['content'] = $content;
		}
	}

	//picture
	$mainPicDom = $html->getElementById('main_gallery');
	if ($mainPicDom && ($mainPicDom = $mainPicDom->find('img', 0))) {
		$mainNews['pic'] = $mainPicDom->src;
	}
}

Ce putem observa în această secvență de cod:

- că putem identifica un element direct dupa identificatorul său (valoarea atributului id): $html->getElementById('mainNews');

- că fiecare nod suportă metoda find;

- că putem interoga arborele după o anumită ierarhie, în exemplul de față cerând toate elementele h2 care sunt descendente ai tag-urilor div cu clasa leadIn: $mainNewsDom->find('div.title h2', 0).

În sfârșit, să citim cele mai noi articole:

$latestNewsDom = $html->find('div.newsList ul div');
if ($latestNewsDom) {
	foreach ($latestNewsDom as $lnd) {
		$lnd = $lnd->first_child()->first_child();
		$latestNews[] = array(
			'url' => $lnd->getAttribute('href'),
			'title' => $lnd->plaintext
		);
	}
}

În acest fel aflăm și cum putem accesa primul copil al unui nod: $nod->first_child(). Pe lângă first_child() mai există următoarele metode care permit aflarea nodurilor învecinate:

- $nod->parent() – accesarea nodului părinte;

- $nod->last_child() – accesarea ultimului copil al unui nod;

- $nod->next_sibling() – accesarea următorului nod aflat pe același nivel al ierarhiei cu nodul $nod;

- $nod->prev_sibling() – accesarea precendentului nod aflat pe același nivel al ierarhiei cu nodul $nod.

Evident, API-ul oferit de către SimpleHtmlDom suportă mai multe modalități de procesare a conținutului unui document HTML, modalități pe care le puteți afla citind documentația ce înșoțește pachetul oferit de autor. În final, atașez codul sursă ce reunește toate aceste exemple într-un script demonstrativ.

Click aici pentru a descărca exemplul.

- pan de hartă (drag & drop, prin intermediul controlului de pan, sau programatic cu ajutorul metodei GMap2.setCenter);

- zoom de hartă (folosind rotița de la mouse, prin dublu clic, folosind controlul de zoom, sau programatic cu ajutorul metodei GMap2.setZoom).

Nu are rost să menționez cât de util poate fi , și chiar este, un astfel de eveniment. Problema este că acesta a dispărut în versiunea 3, apărând în schimb o serie de alte evenimente:

- center_changed – declanșat de fiecare dată când centrul hărții se schimbă;

- bounds_changed – declanșat atunci când box-ul hărții se schimbă;

- idle – atunci când harta nu mai primește evenimente, după o secvență de pan sau zoom.

Evenimentele bounds_changed și center_changed nu pot fi folosite ca surogat din cauză că în cazul unui pan prin drag & drop sunt declanșate pentru fiecare poziție intermediară între punctul final și inițial.

Evenimentul idle, totuși, seamănă cel mai mult în funcționare cu ceea ce vrem să obținem. Diferența este că atunci când utilizatorul începe să facă drag și se oprește temporar, fără a ridica însă degetul de pe mouse, harta declanșează evenimentul idle, iar după ce utilizatorul ridică degetul de pe mouse fără a mai mișca harta, evenimentul idle nu mai este semnalat. Ori eu îmi doream ca acest eveniment să fie declanșat doar după ce utilizatorul a ridicat degetul de pe mouse. Pentru a simula acest comportament a trebuit să folosesc două evenimente suplimentare: dragstart și dragend, astfel:

1. Atunci când este declanșat evenimentul dragstart, setează indicatorul bIsDragging = true;

2. Atunci când este declanșat evenimentul dragend, setează indicatorul bIsDragging = false. Verifica daca indicatorul bTriggeredIdle este false. Dacă da, atunci declanșează manual evenimentul idle.

3. Atunci când este declanșat evenimentul idle, verifică dacă indicatorul bIsDragging are valoarea true. Dacă da, atunci oprește execuția, setand indicatorul bTriggeredIdle = false. Altfel, continuă procesarea evenimentului si seteaza indicatorul bTriggeredIdle = true.

Iată și o secvență de cod care exemplifică cele prezentate mai sus:

var bDragging = false;
var bTriggeredIdle = false;
var opts = { /*...map options...*/ }
var canvas = document.getElementById('map_canvas');
var map = new google.maps.Map(canvas, opts);
google.maps.event.addListener(map, 'idle', function() {
    if (bDragging) {
        bTriggeredIdle = false;
        return;
    }
    bTriggeredIdle = true;
    /*...do processing here...*/
 });
google.maps.event.addListener(map, 'dragstart', function() {
    bDragging = true;
});
google.maps.event.addListener(map, 'dragend', function() {
    bDragging = false;  
    if (bTriggeredIdle == false) {
        google.maps.event.trigger(map, 'idle');
    }
});

Foarte important de reținut este faptul că putem folosi aceste mecanisme pentru a consuma orice librărie scrisă în Objective-C, care nu este încă expusă prin intermediul framework-ului MonoTouch. Acesta este și cazul librăriei AdMob, pe care Google o livrează compilată doar ca binar pentru Objective-C, impunându-se deci nevoia creării unui binding.

Nu voi prezenta toți pașii necesari scrierii unui astfel de binding, aceștia fiind descriși aici cu lux de amănunte. Voi atașa în schimb sursele necesare, prezentând, evident, instrucțiunile și exemplele de rigoare.

Pasul 1. În primul rând, având sursele binding-urilor, veți folosi executabilul btouch pentru a general DLL-ul ce realizează intermedierea cu librăria AdMob:

/Developer/MonoTouch/usr/bin/btouch AdMob.cs -s:Enums.cs 

Trebuie notat că, deși pachetul oferit spre descărcare conține deja acest DLL, el nu este compatibil cu toate versiunile de MonoTouch datorită faptului ca de la o versiune la alta mecanismele interne necesare realizării interoperabilității pot diferi. Este, deci, recomandat să generați DLL-ul folosind utilitarul corespunzând versiunii pe care o aveți instalată.

Pasul 2. Adăugați librăria AdMob în proiect, referențiați DLL-ul proaspăt generat și configurați compilatorul pentru folosi această librărie. Pentru a configura compilatorul va trebui să accesați Project -> [NumeProiect] Options -> iPhone Build în MonoDevelop. În fereastra deschisă, completați câmpul "Additional mtouch arguments" astfel:

-gcc_flags "-L${ProjectDir} -lGoogleAdMobAds -force_load ${ProjectDir}/libGoogleAdMobAds.a"

Acest câmp trebuie completat pentru fiecare configurație definită în proiectul vostru.

Pasul 3. Folosirea efectivă a librăriei. Cel mai frecvent model de utilizare este reprezentat de servirea unei reclame standard, folosind una din dimensiunile suportate de AdMob:

mBanner = new GADBannerView();
mBanner.AdUnitId = "[your-ad-unit-id]";
mBanner.Delegate = new TestBannerDelegate();
mBanner.RootViewController = this;
mBanner.Frame = new RectangleF(0, 0, 320, 50);
mBanner.LoadRequest(GADRequest.Request);

Un alt exemplu este reprezentat de servirea reclamelor interstițiale, afișate pe tot ecranul. Servirea acestor reclame se face, de obicei în două etape: lansarea cererii pentru reclama și, odată cu finalizarea acesteia cu succes, afișarea reclamei. Vom avea, deci, nevoie de un delegate:

public class TestInterstitialDelegate : GADInterstitialDelegate
{
    private SomeViewController mCtrl = null;

    public TestInterstitialDelegate (SomeViewController ctrl)
    {
         mCtrl = ctrl;
    }

    public override void DidReceiveAd (GADInterstitial ad)
    {
         ad.PresentFromViewController(mCtrl);
    }
}

Lansarea cererii se face asemănător:

mInterstitial = new GADInterstitial();
mInterstitial.AdUnitId = "[your-ad-unit-id]";
mInterstitial.Delegate = new TestInterstitialDelegate(this);
mInterstitial.LoadRequest(GADRequest.Request);

Când rulați aplicația de pe simulator este bine să efectuați cererile de reclamă în modul test, astfel:

request = GADRequest();
if (Runtime.Arch == Arch.Simulator) {
    request.TestDevices = new string[] {
        "Simulator"
    };
}
mBanner.LoadRequest(request);

Iata, în sfârșit, și pachetul promis la începutul articolului. Acesta conține atât sursele pentru binding-uri, cât și un proiect demonstrativ.

Click aici pentru a decărca pachetul.

Ce este NLog

NLog este o platformă gratuită de jurnalizare pentru .NET și Mono care oferă facilităţi avansate precum:

- procesarea mesajelor primite, îmbunătățirea lor cu diverse informații contextuale (precum momentul de timp al înregistrării, informații despre firul de execuție, informații despre proces etc.) și formatarea acestora conform regulilor dorite;

- suportă diverse modalități de jurnalizare: în fișiere pe disc, într-o bază de date, în EventLog-ul sistemului de operare, pe rețea, pe e-mail etc.

- opțiuni de rutare a mesajelor, incluzând: buffering, jurnalizare asincronă, load balancing, failover etc.

- ușor de configurat, incluzând și o extensie de Visual Studio ce face mai comodă crearea fişierelor de configurare.

Este disponibil sub licență BSD, iar sursa poate fi descărcata de pe GitHub.

Ce este un target pentru NLog și cum scriem un astfel de target

Pe scurt, un target pentru NLog reprezintă o destinaţie a mesajelor trimise de aplicaţie, un target putând fie să stocheze mesajele, fie să le afişeze, sau să le trimită mai departe. Puteti găsi aici o listă de target-uri suportate de NLog în momentul de față.

Totuși, necesitățile unui proiect nu pot fi acoperite mereu de componentele standard, tocmai acesta fiind motivul pentru care NLog ne oferă posibilitatea de a ne crea propriile target-uri. În continuare voi descrie, deci, pașii necesari în crearea unui astfel de target, alegând pentru exemplificare dezvoltarea unui target care salvează în baza de date mesaje personalizate ce descriu operațiunile efectuate într-un sistem.

Întâi de toate, să creăm tabela care va ține înregistrările noastre:

CREATE TABLE samplenlog_target_t
(
  log_id serial NOT NULL,
  log_time bigint,
  log_operation character varying(250),
  log_username character varying(250),
  log_accesslevel character varying(250),
  log_description character varying(250)
)

Pasul 1 - Extidenți clasa de baza NLog.Targets.Target si implementați metoda Write(LogEventInfo logEvent):

using System;
using NLog;
using NLog.Targets;

namespace Ro.LiveDesign.Samples.SampleNLogTargets
{
    /// <summary>
    /// Step 1 - Extend the base class Nlog.Targets.Target
    /// </summary>
    [Target("CustomDbNLog")]
    public class CustomDbNLogTarget : Target
    {
        protected override void Write(LogEventInfo logEvent)
        {
            base.Write(logEvent);
        }
    }
}

Pasul 2 – Definiți structura mesajului personalizat extinzând clasa NLog.LogEventInfo și definind proprietățile ce compun mesajul personalizat. În exemplul nostru avem patru astfel de proprietăți:

- momentul de timp al înregistrării mesajului;

- tipul operațiunii efectuate;

- numele de utilizator al celui care a efectuat operațiunea;

- nivelul de acces al utilizatorului;

- o descriere suplimentară (opțională).

using System;
using NLog;

namespace Ro.LiveDesign.Samples.SampleNLogTargets
{
    /// <summary>
    /// Step 2 - Define custom event info
    /// </summary>
    public class CustomDbNLogEventInfo : LogEventInfo
    {
        public long Time { get; set;}

        public string Operation { get; set; }

        public string UserName { get; set; }

        public string AccessLevel { get; set; }

        public string Description { get; set; }
    }
}

Pasul 3 - Pentru a putea folosi noul target trebuie sa configurați framework-ul NLog, dându-i informațiile necesare despre target-ul dumneavoastră. Puteți face acest lucru în două moduri: programatic sau folosind fișierul de configurare.

Configurarea programatică se realizează în felul următor:

CustomDbNLogTarget target = null;
LoggingConfiguration config = null;
LoggingRule rule = null;

//create and configure target
target = new CustomDbNLogTarget();
target.ConnectionStringName = "MyConnection";
target.Name = "CustomDbNLog";

//create logging rule
rule = new LoggingRule(LOGGER_NAME, LogLevel.Info, target);

//create logging configuration
config = LogManager.Configuration;
if (config == null)
    config = new LoggingConfiguration();
config.AddTarget("CustomDbNLog", target);
config.LoggingRules.Add(rule);

//load the new logging configuration
LogManager.Configuration = config;

Alternativ, puteți folosi fișierul de configurare pentru a specifica informațiile necesare:

<?xml version="1.0" encoding="utf-8" ?>
<nlog xmlns="http://www.nlog-project.org/schemas/NLog.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <extensions>
        <add assembly="Ro.LiveDesign.Samples.SampleNLogTargets" />
    </extensions>
    <targets>
        <target xsi:type="CustomDbNLog" name="CustomDbNLog" connectionStringName="MyConnection" />
    </targets>
    <rules>
        <logger name="Ro.LiveDesign.Samples.CustomDbNLog" minlevel="Info" writeTo="CustomDbNLog"></logger>
    </rules>
</nlog>

Pasul 4 – Odată ajunși aici nu trebuie decât să trimitem mesajele noastre logger-ului corespunzător:

Logger logger = null;
CustomDbNLogEventInfo eventInfo = null;

//register the target
//RegisterTarget();

//create a sample event info
eventInfo = new CustomDbNLogEventInfo();
eventInfo.Time = DateTime.Now.Ticks;
eventInfo.Operation = "op.login";
eventInfo.AccessLevel = "administrator";
eventInfo.UserName = "admin";
eventInfo.Description = "User admin logged in";
eventInfo.Level = LogLevel.Info;

//fetch logger and log event
logger = LogManager.GetLogger(LOGGER_NAME);
logger.Log(eventInfo);

Și pentru că orice explicație teoretică trebuie însoțită de exemple, la sfârșitul articolului atașez și proiectul VS 2010 care conține implementarea acestui tutorial.

Pentru a-l rula aveți nevoie de:

- Visual Studio 2010;

- .NET Framework 3.5 (minim);

- PostgreSQL.

Puteți, evident, adapta exemplul pentru a salva informațiile folosind alt SGBD, cum ar fi MySQL sau SQL Server.

Click aici pentru a descărca proiectul demonstrativ.