Hjelpetekster i Episerver redaktørmodus
Livet som nettredaktør kan være vanskelig. En del større Episerver-løsninger kan ha over 100 ulike sidetyper, der alle har mange faner med et ti-talls egenskaper. Hver egenskap har riktignok en ledetekst, eller et label, som er en kort tekst som forteller redaktørene hvilken informasjon som kan fylles inn her, f.eks. «Overskrift», «Ingress» eller lignende.
Av og til er det ikke nok plass til all informasjonen som redaktørene burde få, og derfor har Episervar lagt til muligheten til å vise en tooltip, en ekstra beskrivelse som vises ved mouseover på ledeteksten. Det er et par problemer med denne tilnærmingen. Det er ingen visuell markering som informerer redaktørene om hvilke egenskaper som har en slik hjelpetekst, og hvilke som ikke har det. Og siden de færreste egenskapene har det, er sannsynligheten for at redaktørene oppdager de få hjelpetekstene som er der nokså liten.
Når ikke Episerver selv kan levere noe som fungerer, må andre gjøre sine tilpasninger! Det finnes noen grep man kan ta for å gjøre hjelpen lettere tilgjengelig!
- Alf Nilsson viser hvordan man med litt CSS kan vise hjelpeteksten under ledeteksten.
- Ted+Gustaf viser hvordan man med litt Dojo-magi kan indikere med et ikon hvilke egenskaper som har en hjelpetekst.
- Daved Artemik utretter omtrent det samme som Ted+Gustaf, men med ren CSS.
Det at alle disse løsningene finnes, tyder på at Episerver kunne ha gjort en bedre jobb selv.
Av og til kan det være hensiktsmessig å vise en hjelpetekst som ikke er direkte knyttet til, og plassert ved siden av, en bestemt egenskap. Jeg kom opp med en løsning som viser en hjelpetekst som på skjermbildet under. Jeg bruker ikke hjelpeteksten knyttet til en egenskap redaktørene kan redigere, men endrer visningen av en egenskap som ikke får noe annet formål enn å vise en hjelpetekst. En slags custom property. Egenskapens ledetekst vises her som overskrift, mens hjelpeteksten (som vanligvis vises som tooltip) vises i vanlig skrift under.
EditorDescriptor
EditorDescriptor er et konsept som Episerver introduserte i Episerver 7, og det er en klasse som definerer hvordan klienten skal vise en egenskap, eller en gruppe egenskaper. Ved å legge til en ny EditorDescriptor kan vi velge hvilken Dojo/Dijit widget (javascript-fil) som brukes til å vise egenskapen i redaktørmodus.
using System;
using System.Collections.Generic;
using EPiServer.Shell.ObjectEditing.EditorDescriptors;
using EPiServer.Shell.ObjectEditing;
namespace Alloy.Business.EditorDescriptors
{
[EditorDescriptorRegistration(TargetType = typeof(string),
UIHint = "HelpText")]
public class HelpTextEditorDescriptor : EditorDescriptor
{
public override void ModifyMetadata(ExtendedMetadata metadata,
IEnumerable attributes)
{
ClientEditingClass = "alloy/editors/HelpText";
metadata.EditorConfiguration.Add("title", metadata.DisplayName);
metadata.DisplayName = "";
base.ModifyMetadata(metadata, attributes);
}
}
}Det viktige her er TargetType som angir hvilken egenskapstype den gjelder for, UIHint som blir merkelappen vi kan sette på utvalgte egenskaper for å få den nye visningen, og ClientEditingClass som angir hvilken javascript-fil som definerer visningen av egenskapen i redaktørmodus. I tillegg oppretter vi et nytt felt title i EditorConfiguration slik at egenskapens visningsnavn blir tilgjengelig for oss fra javascriptet. Til slutt nullstiller vi visningsnavnet for å unngå at standard ledetekst med mouseover-tekst skal bli vist, vi ønsker å vise den (som title) slik at vi har full kontroll over markup.
På linjen som definererer ClientEditingClass peker alloy/ på mappen /ClientResources/Scripts, og for å se hva som er i bruk i din løsning kan du sjekke module.config etter denne definisjonen.
<dojo>
<paths>
<add name="alloy" path="Scripts" />
/paths>
</dojo>Javascript
For å definere nøyaktig hvordan egenskapen skal vises for redaktørene må vi legge til litt javascript. I dette tilfellet inneholder også javascriptet litt html. Her plasserer vi verdien title (som vi klargjorde i EditorDescriptoren) og tooltip i markup, og bruker et par CSS-klasser som vi definerer senere.
define([
"dojo/_base/array",
"dojo/_base/connect",
"dojo/_base/declare",
"dojo/_base/lang",
"dijit/_CssStateMixin",
"dijit/_Widget",
"dijit/_TemplatedMixin",
"dijit/_WidgetsInTemplateMixin",
"epi/epi"
],
function (
array,
connect,
declare,
lang,
_CssStateMixin,
_Widget,
_TemplatedMixin,
_WidgetsInTemplateMixin,
epi
) {
return declare("alloy.editors.HelpText",
[_Widget,
_TemplatedMixin,
_WidgetsInTemplateMixin,
_CssStateMixin], {
templateString:
"<div class=\"helptext shadow\">\
<strong data-dojo-attach-point=\"heading\"></strong>\
<div data-dojo-attach-point=\"description\"></div>\
</div>",
postCreate: function () {
this.inherited(arguments);
this.heading.innerHTML = this.title;
this.description.innerHTML = this.tooltip;
}
});
}); CSS
Så kan vi velge å krydre med litt CSS, og definerer de to klassene som vi brukte i javascript-filen.
.helptext {
width: 725px;
border-radius: 20px;
border: 2px solid #73AD21;
padding: 10px;
background-color: #f1f1f1;
margin-bottom: 10px;
}
.shadow {
-moz-box-shadow: 3px 3px 5px 6px #ccc;
-webkit-box-shadow: 3px 3px 5px 6px #ccc;
box-shadow: 3px 3px 5px 6px #ccc;
}CSS kan legges i en egen fil, men for å få Episerver til å laste filen i reaktørmodus må vi registrere den i module.config.
<module>
<clientResources>
<add name="epi-cms.widgets.base"
path="Styles/HelpText.css"
resourceType="Style" />
</clientResources>
</module>Legg til beskrivelsene
Nå er alt klart, og det mangler bare å legge til tekstene der vi ønsker dem. Teksten på bildet øverst i dette innlegget var lagt til slik. Overskriften som Name, den lange teksten som Description, og så må vi huske [UIHint("HelpText")].
public class ArticlePage : StandardPage
{
[Display(Name = "Redaktørene har en vanskelig jobb!",
Description = "Men jobben kan gjøres enklere hvis...")]
[UIHint("HelpText")]
public virtual string ExtraInformationAboutEditors { get; set; }
}Språkstøtte
Det kunne vært ønskelig å definere tekstene i en språkfil, både for å gjøre teksten tilgjengelig på ulike språk, og for å gjøre det mulig å oppdatere den uten å kompilere og deploye ny kode. Vi kan oppdatere språkfilen slik.
<standardpage>
<properties>
<extrainformationabouteditors>
<caption>Translated caption</caption>
<help>Translated description...</help>
</extrainformationabouteditors>
</properties>
</standardpage>Med tekstene trygt plassert i språkfilen, kan vi utelate dem fra egenskapsdefinisjonen, slik at dette er alt som blir igjen:
public class ArticlePage : StandardPage
{
[UIHint("HelpText")]
public virtual string ExtraInformationAboutEditors { get; set; }
}Litt siste finpuss
Problemet blir nå at ledeteksten får sin oversettelse fra språkfilen satt på et senere tidspunkt enn når teksten er oppgitt i egenskapsdefinisjonen, derfor blir ledeteksten vist selv om vi forsøker å nullstille den i EditorDescriptoren.
Vi kan skjule ledeteksten med CSS, uavhengig av hvordan tekstene er definert, enten om det er på egenskapsdefinisjonen eller i språkfil. Dette legges til i CSS-filen vi opprettet lenger opp.
label[for^="alloy_editors_HelpText_"] {
display: none !important;
}CSS-selectoren skjuler alle labels som er label for noe som starter med (^=) alloy_editors_HelpText_, som må matche ClientEditingClass satt i EditorDescriptor, men bytte skråstrek(/) med underscore(_).
Resultatet
Nå har vi en mulighet for å legge til en beskrivende tekst innimellom vanlige Episerver-egenskaper, og vi kan velge om overskrift og beskrivelse skal legges til i egenskapsdefinisjonen eller i språkfiler.