DNM19 Sessione2 Orchard Temi e Layout (Ita)

PrimordialCodehttp://www.primordialcode.com

Orchard – Temi e Layoutconcetti di base

Ing. Giorgetti AlessandroSoftware ArtisanSID s.r.l.


About me…

Laurea in Ingegneria ElettronicaCofondatore di SID s.r.l.

Blog: http://www.primordialcode.com

Email: [email protected], [email protected]

Twitter: @A_Giorgetti

Giorgetti Alessandro

http://www.primordialcode.com/

mailto:[email protected]

mailto:[email protected]


Orchard theme – how to…Il modo più semplice per creare un nuovo tema in Orchard: utilizzare

‘Orchard command line’ + ‘Codegen’.

• Creare un tema vuoto.• Creare un tema basato su un altro tema.

La seconda opzione è particolarmente utile poiché consente di eseguire personalizzazioni solo su determinati aspetti del tema selezionato come base: si devono copiare e modificare solo quei file che si intendono cambiare.

Quando si applica un tema, l’engine di Orchard, seguendo le proprie regole di matching, cercherà prima i file specifici nella cartella del tema, in mancanza di essi proverà con quelli del tema base ed infine verifichirà il contenuto del tema di sistema ‘SafeMode’. Il risultato è un merging di tutte queste ‘strutture’.

Tutti i temi ‘vivono’ all’interno della cartella ‘Themes’.


Orchard theme – how to…

Per creare un nuovo tema vuoto:

Per creare un tema basato su un altro tema:

Se si ha in mente di utilizzare Visual Studio per editare il tema o aggiungere file di codice, vanno considerati anche questi due switch della linea di comando:

codegen theme MyTheme

codegen theme MyTheme /BasedOn:TheThemeMachine

/CreateProject:true/IncludeInSolution:true


Orchard – struttura di un tema

Ecco come si presenta la struttura del tema di default e di un tema ‘figlio’ creato basandosi sul precedente:



ManifestFile di testo denominato ‘Theme.txt’ da posizionarsi nella radice del tema.Fornisce informazioni descrittive sul tema.Fornisce informazioni su:• Tema base.• Nome delle zone in cui inserire widgets.

Name: DotNetMarcheThemeAuthor: The Orchard TeamWebsite: http://www.orchardproject.netDescription: Description for the themeVersion: 1.0BaseTheme: TheThemeMachine# todo: provide tags# Tags: Classic, Serif

Name: The Theme MachineAuthor: jowall, mibach, loudej, heskewDescription: Orchard Theme Machine is a flexible multi-zone theme that provides a solid foundation to build your site. It features 20 collapsible widget zones and is flexible enough to cover a wide range of layouts.Version: 1.1.30Tags: AwesomeWebsite: http://orchardproject.netZones: Header, Navigation, Featured, BeforeMain, AsideFirst, Messages, BeforeContent, Content, AfterContent, AsideSecond, AfterMain, TripelFirst, TripelSecond, TripelThird, FooterQuadFirst, FooterQuadSecond, FooterQuadThird, FooterQuadFourth, Footer



Immagini di PreviewTheme.png e ThemeZonePreview.png utilizzate nella

gallery e nella dashboard per fornire una preview del tema.

Risorse staticheFogli di stile, custom javascript code, immagini e tutto

quanto concerne contenuto non dinamico vanno inseriti nelle apposite sezioni.

All’interno di queste cartelle è presente un file web.config utile alla configurazione di IIS per consentirgli di servive questo tipo di risorse, è importante non eliminare questo file.



Document

Definisce la struttura di base di una pagina HTML.

Contiene gli elementi <html>, <head>, <body>.

Definisce il ‘doctype’ assumendo le specifiche di HTML5 come default.

Segue la sintassi del view engine scelto (Razor per default).

Posizionato nel tema ‘SafeMode’ nella cartella ‘Views’.



Layout

Definisce l’attuale struttura del contenuto della pagina (effettivo contenuto del tag <body>).

Segue la sintassi del view engine scelto (Razor per default).

Definisce le zone in cui iniettare widgets.

La denominazione delle zone deve corrispondere a quanto dichiarato sul file Manifest.


Orchard – shape

Shape

È un dynamic object costruito e valorizzato a runtime che descrive una porzione di contenuto e porta con se tutte le informazioni necessarie alla sua visualizzazione.

È possibile pensare ad una shape come alla coppia delle informazioni (contenuti) da rappresnetare e del template da utilizzare per la visualizzazione (metadati).

Esiste un set di regole ben definito che consente di associare uno o più template ad una shape.


Orchard – shape templateTemplateConcettualmente simile ad una partial view in asp.net, diversi tipi:

Item templateCartella ‘\Views\Items’. Definiscono come un particolare tipo di contenuto

può essere visualizzato.

Il nome del template indica come mapparlo sul contenuto: “Content-{content type name}.cshtml”“Content-{content type name}.{display type}.cshtml”.

Part TemplateCartella ‘\views\parts’. Definisce l’aspetto di una singola Part (un set di

attributi per un oggetto che definiscono un comportamento comune).Ex: “\Views\Parts\Comments.cshtml” definisce l’override del rendering

HTML dei commenti associati ad un oggetto


Orchard – shape template

Field templateCartella ‘\Views\Fields’. Definisce l’aspetto generale

dei singoli elementi di pagina(es: campi di testo “\Views\Fields\Common.Text.cshtml”).

AlternatesIntrodotto in Orchard 1.1.È possibile definire delle rappresentazioni alternative

per uno stesso elemento del tema da utilizzare in diversi contesti. Esistono diversi modi per indicare quale visualizzazione alternativa utilizzare.


Orchard – shape template

Widgets

Cartella ‘\Views’. È possibile eseguire l’override della visualizzazione di un qualsiasi widget utilizzando un file denominato: “widget-{widget type}.cshtml.

Placement file

Introdotto con Orchard 1.1.File ‘placement.info’ posizionato nella radice del sito.Consente di modificare dove le shape sono posizionate

relativamente all’interno della pagina.Regole di composizione avanzate.


Orchard – template namingEsistono complesse regole di composizione per determinare quale template viene

utilizziato durante la fase di renderizzazione delle shape:• Vengono analizzati i metadati della shape (proprietà shape.metadata).• Lo ‘shape type name’ effettua il binding della shape allo specifico template che sarà

utilizzato per il rendering secondo una specifica convenzione basata sul nome.

Regole per il posizionamento dei template file:• Content item cartella views/items• Parts cartella views/parts• Fields cartella views/fields• EditorTemplate shapes cartella views/EditorTemplate/(template name)• Tutto il resto cartella views/

Regole per la conversione Shape Name File Name:• Punto (.) e backslash (\) vengono cambiati in underscore (_)• Hypen (-) viene convertito in un doppio underscore (__)

Regole addizionali che riguardano i prefissi da utilizzare in base al tipo di contenuto (content items, parts, widgets o altro).


Orchard – template namingApplied To Shape Naming Convention Shape Type Example Template Example

Content shapes Content__[ContentType] Content__BlogPost Content-BlogPost

Content shapes Content__[Id] Content__42 Content-42

Content shapes Content__[DisplayType] Content__Summary Content.Summary

Content shapes Content_[DisplayType]__[ContentType] Content_Summary__BlogPost Content-BlogPost.Summary

Content shapes Content_[DisplayType]__[Id] Content_Summary__42 Content-42.Summary

Content.Edit shapes Content_Edit__[DisplayType] Content_Edit__Page Content-Page.Edit

Content Part templates [ShapeType]__[Id] Parts_Common_Metadata__42 Parts/Common.Metadata-42

Content Part templates [ShapeType]__[ContentType] Parts_Common_Metadata__BlogPost Parts/Common.Metadata-BlogPost

Field templates [ShapeType]__[FieldName] Fields_Common_Text__Teaser Fields/Common.Text-Teaser

Field templates [ShapeType]__{PartName] Fields_Common_Text__TeaserPart Fileds/Common.Text-TeaserPart

Field templates [ShapeType]__[ContentType]__[PartName] Fields_Common_Text__Blog__TeaserPart Fields/Common.Text-Blog-TeaserPart


Orchard – template namingApplied To Shape Naming Convention Shape Type Example Template Example

Field templates [ShapeType]__[PartName]__[FieldName] Fields_Common_Text__TeaserPart__Teaser Fields/Common.Text-TeaserPart-Teaser

Field templates [ShapeType]__[ContentType]__[FieldName] Fields_Common_Text__Blog__Teaser Fields/Common.Text-Blog-Teaser

Field templates [ShapeType]__[ContentType]__[PartName]__[FieldName]

Fields_Common_Text__Blog__TeaserPart__Teaser Fields/Common.Text-Blog-TeaserPart-Teaser

LocalMenu LocalMenu__[MenuName] LocalMenu__main LocalMenu-main

LocalMenuItem LocalMenuItem__[MenuName] LocalMenuItem__main LocalMenuItem-main

Menu Menu__[MenuName] Menu__main Menu-main

MenuItem MenuItem__[MenuName] MenuItem__main MenuItem-main

Resource Resource__[FileName] Resource__flower.gif Resource-flower.gif

Style Style__[FileName] Style__site.css Style-site.css

Widget Widget__[ContentType] Widget__HtmlWidget Widget-HtmlWidget

Widget Widget__[ZoneName] Widget__AsideSecond Widget-AsideSecond

Zone Zone__[ZoneName] Zone__AsideSecond Zone-AsideSecond


Orchard - Designer Helper Tools

La struttura è obiettivamente complessa.

Visualizzare l’albero delle shapes nella nostra testa non è semplice.

Il Team di Orchard pensa a noi e ci offre un tool – Shape Tracing - che ci consente di navigare all’interno della struttura del sito e di avere informazioni sulle shape, i model ed i template coinvolti nel rendering.

Shape Tracing è disponibile nel modulo ‘Designer Tools’.

Può essere abilitato/disabilitato all’occorrenza.


Orchard - demo

How it works…

Designer Tools


Orchard – Razor View Engine

Ricapitoliamo alcuni concetti sui template:

• Simili ad una Partial View.

• Contengono HTML, stili CSS, Javascript o codice.

• Il ‘View Engine’ è responsabile del parsing del template e del rendering effettivo dell’HTML che verrà poi spedito al browser.

• Possono contenere server side code (C# o VB) per accedere e renderizzare o dati delle shape (View Engine Razor).

• File con estensione .cshtml o .vbhtml


Orchard – Razor syntaxCommenti

Client markup comments

Sono presenti anche nell’HTML che viene renderizzato per il client: visibili analizzando il sorgente delle pagine lato client.

Server markup comments

Vengono eliminati dal markup finale: l’utente non è in grado di vedere questo tipo di commenti (rendono la pagina più leggera)

@* single line comment *@

@* multiline comment*@

<!– your comments goes here -->


Orchard – Razor syntaxCode BlockCarattere ‘@’ seguito dalle parentesi ‘{‘ e ‘}’:

Inline CodeCarattere ‘@’ seguito dal riferimento all’oggetto:

Single ExpressionSe il blocco di codice consiste di una singola espressione (come ad esempio un ‘for’, ‘if-

then’, ‘while’, etc…), il carattere ‘@’ può precedere direttamente la keyword senza bisogno di specificare le parentesi:

@{ … var homeUrl = Href("~/");… }

<h1 id="branding“><a href="@homeUrl">@WorkContext.CurrentSite.SiteName</a></h1>

…class="group"> @if (Model.AsideFirst != null) { <aside id="aside-first" class="aside-first group"> @Zone(Model.AsideFirst) </aside> } <div…


Orchard – accedere alle proprietà

Accesso semplificato agli oggetti del dominio (shape): è possibile accedere direttamente alle content part senza dover utilizzare casting.

Prima: var contentItem = (ContentItem)Model.ContentItem; var picture = (ImageField)contentItem.As<ProfilePart>().Fields.First(f => f.Name == "Picture");@picture.Width

Dopo: @Model.ContentItem.ProfilePart.Picture.Width


Orchard - demo

Razor


Orchard – advanced topicPlacement


Orchard - placement• I contenuti (Content) sono composti da sottoelementi (Parts).

• Ogni elemento ha la propria rappresentazione grafica (template).

• I contenuti sono dinamici, possono variare nel tempo (è possibile aggiungere field o parts, anche questi con i loro template).

• La rappresentazione grafica deve variare di conseguenza:

- intervenire direttamente sui template per ‘incorporare’ il rendering dei nuovi elementi.

- sfruttare i placement.info file (new in Orchard 1.1)


Orchard - placement

Orchard, durante la generazione del layout, separa le operazioni di:

• Rendering – eseguito dai template

• Placement – eseguito ricorrendo ai file placement.info

Ogni modulo o tema può definire il posizionamento dei propri elementi utilizzando un placement.info file posizionato nella propria root folder .

Placement.info agisce a livello di Content-item (è possibile riordinare solo gli elementi all’interno della specifica sezione in cui si trovano).


Orchard – placement.infoSintassi XML specifica:

<placement> - elemento contenitore esterno

<place> - definisce il posizionamento di uno o più oggetti in base agli attributi specifici:“name” – il nome di una specifica shape (designer tool)

“value” – definisce il posizionamento, composta da nome di una zona (header, content, meta, footer), il carattare “:” se guito da una posizione numerica o dai qualificatori ‘before’ o ‘after’.

Sempre sulla porzione “value”è possibile specificare eventuali alternates da utilizzare per la visualizzazione se forniti assieme al tema.


Orchard – placement.info<Match> - consente di definire lo scope di un determinato set di

<place> utilizzando degli attributi:

• DisplayType. Scopes the contained Place tags to a specific display type (such as Detailor Summary).

• ContentType. Scopes the contained Place tags to a specific content type (such asBlogPost or Page) or stereotype (such as Widget; this feature is new to Orchard 1.1).

• Path. Scopes the contained Place tags to a specific path or to a path and its children. For example, Path="/About" enables changes that only affect the About page (assuming you have one), and Path="/MyBlog/*" affects everything that is under the path MyBlog, such as Myblog or MyBlog/FirstPost. The Path attribute is new to Orchard 1.1.


Orchard – placement.info<Placement>    <Place Parts_Blogs_Blog_Fields="Content:2"/> <Place Parts_Blogs_BlogArchives_Edit="Content:5"/> <Place Parts_Blogs_RecentBlogPosts_Edit="Content:5"/>  <Place Parts_Blogs_BlogArchives="Content"/> <Place Parts_Blogs_RecentBlogPosts="Content"/>  <Match ContentType="Blog"> <Match DisplayType="Detail">….


Orchard - demo

Placement


Thanks for attending!

Technology

DNM19 Sessione2 Orchard Temi e Layout (Ita)