Een ander uiterlijk verlengen | Handleiding voor Adobe Commerce-ontwikkelaars
Standaard biedt Page Builder een verscheidenheid aan interactieve CSS-stijlopties voor uw inhoudstypen. Bijvoorbeeld Page Builder’s Heading inhoudstype biedt opties voor het instellen van koptypen (h1 door h6), tekstuitlijningen, randeigenschappen, marges en opvullingen. Het laat gebruikers ook een of meer statische CSS-klassen toepassen door ze in een tekstinvoerveld in te voeren.
Maar wat als u gebruikers nog meer stylingopties wilt geven? Misschien wilt u bijvoorbeeld kleuropties voor kopteksten toevoegen. Of Koptekststijlopties. In dit onderwerp wordt uitgelegd hoe u de attribute, styleen css configuratie-opties om de elementen in uw inhoudstypen op te maken.
Het grote geheel begrijpen
Voordat we ingaan op de details van het gebruik van verschillende configuratie-opties, nemen we even de tijd om de rol van de configuraties binnen een Page Builder-inhoudstype te begrijpen. Het volgende diagram laat zien hoe de configuratie-opties voor de Heading inhoudstype verbind of wijs de invoer van het kopformulier toe aan de bindingen in de kopsjablonen en tenslotte aan de gerenderde uitvoer in de DOM:
:mag_right: Tik of klik om uit te vouwen
-
Kopformulier (
pagebuilder_heading_form.xml). Dit formulier erft van depagebuilder_base_form.xml, dat de meeste invoervelden voor de kop biedt. Het Heading-formulier zelf biedt invoervelden voor het selecteren van eenappearancebinnenkomen in deheading_texten het selecteren van aheading_type(h1toth6). De tekst links van elk veld geeft aan uit welke vorm het veld komt, deheading_formof debase_form. -
Kopconfiguratie (
heading.xml). Het belangrijkste doel van alle configuratiebestanden van het inhoudstype is om de gegevenstoewijzing tussen de formuliervelden en de HTML-sjablonen te bieden. Configuraties worden toegewezen aan velden met overeenkomende namen. -
Kopsjabloon (
master.html,preview.html). Sjabloon Knockout-bindingen worden toegewezen aan configuraties met behulp van hun elementnaamgevingshiërarchieën. -
Kop weergegeven in DOM. Page Builder maakt de sjabloonbindingen naar de DOM. De
<attribute>configuraties worden weergegeven als aangepaste kenmerken voor het element. De<style>configuraties worden weergegeven als inline-stijlen op het element. De<css>configuratie wordt weergegeven als aclassattribuut voor het element. En de<html>configuratie geeft de tekst voor het element weer.
Je begrijpt misschien niet meteen alle details, maar we hopen dat door het hele verhaal vooraf te geven, het je zal helpen om de stukjes in elkaar te zetten terwijl je je een weg baant door dit onderwerp en speelt met de begeleidende voorbeeldmodule.
Installeer de voorbeeldmodule
Om u op weg te helpen en te volgen, hebben we een voorbeeldmodule gemaakt die u kunt klonen en installeren vanuit magento-devdocs/PageBuilderStylingOptions. De instructies voor het installeren van de module vindt u in de README bestand op de repo.
Voor deze voorbeeldmodule hebben we ervoor gekozen om de Heading inhoudstype door drie nieuwe Heading-velden toe te voegen: Heading Colors, Heading Stylesen Heading Opacityzoals hier getoond:
:pijl omhoog: Verlengd Heading formulier met opties voor kleur, tekststijl en dekking
De voorbeeldmodule biedt alle code die hier wordt gebruikt om te beschrijven hoe u elementen kunt stylen met <attribute> en <style> knooppunten. Het toont ook het gebruik van een aangepaste converter voor onze opacity stijl om ervoor te zorgen dat gebruikers de dekking als een percentage kunnen invoeren.
Stappenoverzicht
Een overzicht van de stappen voor het stylen van inhoudstype-elementen wordt hier getoond, gevolgd door de gedetailleerde instructies voor elke stap:
Stap 1: Formuliervelden toevoegen voor gebruikersinvoer
Eerst moet u velden toevoegen aan het formulier van uw inhoudstype, zodat gebruikers stijlopties kunnen selecteren of invoeren. In onze Heading-extensie voegen we drie nieuwe velden toe:
heading_colorvoor het selecteren van een kleur voor de koptekstheading_stylevoor het selecteren van tekststijlenheading_opacityvoor het invoeren van een dekking voor de koptekst
Het UI-componentformulier voor deze velden ziet er als volgt uit:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
<?xml version="1.0" encoding="UTF-8"?>
<form xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Ui:etc/ui_configuration.xsd">
<fieldset name="general">
<field name="heading_color" sortOrder="25" formElement="select" component="Magento_PageBuilder/js/form/element/visual-select">
<argument name="data" xsi:type="array">
<item name="config" xsi:type="array">
<item name="default" xsi:type="string">brand-black</item>
</item>
</argument>
<settings>
<dataType>text</dataType>
<label translate="true">Heading Colors</label>
<elementTmpl>Magento_PageBuilder/form/element/visual-select</elementTmpl>
<notice translate="true">Select from one of the approved Acme brand colors.</notice>
</settings>
<formElements>
<select>
<settings>
<options class="BrandColorSource"/>
</settings>
</select>
</formElements>
</field>
<field name="heading_style" sortOrder="26" formElement="select" component="Magento_PageBuilder/js/form/element/visual-select">
<argument name="data" xsi:type="array">
<item name="config" xsi:type="array">
<item name="default" xsi:type="string">style-default</item>
</item>
</argument>
<settings>
<dataType>text</dataType>
<label translate="true">Heading Styles</label>
<elementTmpl>Magento_PageBuilder/form/element/visual-select</elementTmpl>
</settings>
<formElements>
<select>
<settings>
<options class="TextStyleSource"/>
</settings>
</select>
</formElements>
</field>
<field name="heading_opacity" sortOrder="27" formElement="input">
<argument name="data" xsi:type="array">
<item name="config" xsi:type="array">
<item name="default" xsi:type="string">100</item>
</item>
</argument>
<settings>
<label translate="true">Heading Opacity</label>
<additionalClasses>
<class name="admin__field-small">true</class>
</additionalClasses>
<addAfter translate="true">%</addAfter>
<validation>
<rule name="validate-number" xsi:type="boolean">true</rule>
<rule name="greater-than-equals-to" xsi:type="number">0</rule>
<rule name="less-than-equals-to" xsi:type="number">100</rule>
</validation>
</settings>
</field>
</fieldset>
</form>
:pijl omhoog: Nieuwe velden om de . uit te breiden Heading formulier
De namen van deze velden, heading_color, heading_styleen heading_opacity zijn bijzonder belangrijk. Het zijn dezelfde namen die u moet toewijzen aan hun corresponderende <attribute> en <style> knooppunten voor de <element> in uw configuratiebestand. Dat doen we hierna.
Stap 2: Elementconfiguratie-opties toevoegen
Toevoegen <attribute> en <style> knooppunten naar een <element> configuratie is hoe u respectievelijk aangepaste kenmerken en inline-stijlen aan de DOM toevoegt. Beide <attributes> en <style> knooppunten hebben een name eigendom en een source eigendom.
De name eigenschappen van deze knooppunten moeten overeenkomen met de naam van het overeenkomstige veld in het formulier. Door dezelfde namen te gebruiken (tussen configuratie en veld) kan Page Builder de invoerwaarden van het veld toewijzen aan de uitvoerwaarden van de sjabloon.
De source eigendom voor <attribute> nodes definieert de naam van het aangepaste attribuut dat is toegevoegd aan de DOM van het element, zodat u het kunt gebruiken om het element te targeten met uw op attributen gebaseerde CSS-klassen (stap 4).
De source eigendom voor <style> nodes specificeert de CSS-eigenschap (in snake_case) toegevoegd aan het element style attribuut in de DOM.
In onze uitgebreide Heading-configuratie hebben we twee <attribute> knooppunten en een <style> knooppunt, met namen die overeenkomen met de eerder gedefinieerde Heading formulier velden: heading_color, heading_styleen heading_opacity:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
<!-- heading.xml config extension -->
<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_PageBuilder:etc/content_type.xsd">
<type name="heading">
<appearances>
<appearance name="default">
<elements>
<element name="main">
<attribute name="heading_color" source="data-heading-color"/>
<attribute name="heading_style" source="data-heading-style"/>
<style name="heading_opacity" source="opacity"/>
</element>
</elements>
</appearance>
</appearances>
</type>
</config>
:pijl omhoog: NewConfiguration attributen voor de Heading element
In dit voorbeeld is de source waarden voor de knooppunten (data-heading-color, data-heading-styleen opacity) wordt weergegeven in de DOM voor de Heading’s main element (dat is h2 standaard), zoals hier weergegeven:
1
2
3
4
5
6
7
8
<h2 data-content-type="heading"
data-appearance="default"
data-heading-color="brand-green"
data-heading-style="style-italic"
data-element="main"
style="...; opacity: 1;">
My Heading Text
</h2>
De waarden die voor deze attributen en inline-stijleigenschappen worden getoond, worden door de gebruiker ingesteld vanuit de formuliervelden. In dit voorbeeld heeft de gebruiker geselecteerd brand-green van de heading_color veld, style-italic van de heading_style veld, en ingevoerd 100 (in procenten) in de heading_opacity veld (geconverteerd naar de decimale vorm die u hier ziet met behulp van een aangepaste converter die u in het voorbeeld vindt).
Maar voordat Page Builder de kan renderen attributes en styles aan de DOM zoals weergegeven, moeten we de benodigde Knockout-bindingen toevoegen aan onze HTML-sjablonen.
Stap 3: Sjabloon Knockout-bindingen toevoegen
In onze voorbeeldmodule gebruiken we de native . van de Heading master.html en preview.html sjablonen, die al alle Knockout-bindingen hebben die nodig zijn om onze nieuwe <attribute> en <style> configuraties naar de DOM. Maar het is van cruciaal belang dat u begrijpt wat deze bindingen zijn en wat ze doen. Want zonder hen geeft Page Builder niets weer op het scherm.
Om onze configuratie-opties in de DOM weer te geven (zoals beschreven in stap 2), moeten we ervoor zorgen dat Knockout-bindingen in onze HTML-sjablonen staan. De drie Knockout bindingen voor de <attribute>, <style>en <css> configuratieknooppunten zijn attr, ko-styleen cssrespectievelijk:
1
<h2 attr="data.main.attributes" ko-style="data.main.style" css="data.main.css"...></h2>
Voor alle drie de Knockout bindingen, data.main verwijst naar de main element in het configuratiebestand (heading.xml). De overige bindende referenties zijn als volgt:
-
Voor de
attrbindend, deattributeseigenschap verwijst naar de verzameling van<attribute>knooppunten gedefinieerd voor demainelement. -
Voor de
ko-stylebindend, destyleeigenschap verwijst naar de verzameling van<style>knooppunten gedefinieerd voor demainelement. -
Voor de
cssbindend, decsseigendomsverwijzingen de<css>knooppunt gedefinieerd voor demainelement.
Je moet deze Knockout bindingen toevoegen aan de Heading’s master.html sjabloon (evenals de preview.html sjabloon), zoals hier weergegeven:
1
2
3
4
5
6
7
8
<!-- Heading master.html -->
<h1 if="data.main.heading_type() == 'h1'" attr="data.main.attributes" ko-style="data.main.style" css="data.main.css" html="data.main.html"></h1>
<h2 if="data.main.heading_type() == 'h2'" attr="data.main.attributes" ko-style="data.main.style" css="data.main.css" html="data.main.html"></h2>
<h3 if="data.main.heading_type() == 'h3'" attr="data.main.attributes" ko-style="data.main.style" css="data.main.css" html="data.main.html"></h3>
<h4 if="data.main.heading_type() == 'h4'" attr="data.main.attributes" ko-style="data.main.style" css="data.main.css" html="data.main.html"></h4>
<h5 if="data.main.heading_type() == 'h5'" attr="data.main.attributes" ko-style="data.main.style" css="data.main.css" html="data.main.html"></h5>
<h6 if="data.main.heading_type() == 'h6'" attr="data.main.attributes" ko-style="data.main.style" css="data.main.css" html="data.main.html"></h6>
:pijl omhoog: Knock-out bindingen voor de Heading’s data.main configuratie-elementen
Met deze bindingen op hun plaats, zal Page Builder ze naar de DOM renderen, met behulp van de waarden uit de formuliervelden (zoals vermeld in stap 2), om er ongeveer zo uit te zien:
1
2
3
4
5
6
7
8
<h2 data-content-type="heading"
data-appearance="default"
data-heading-color="brand-green"
data-heading-style="style-italic"
data-element="main"
style="...; opacity: 1;">
My Heading Text
</h2>
Nadat u begrijpt hoe Page Builder kenmerken en hun door de gebruiker geselecteerde waarden naar de DOM schrijft, kunt u de inhoudstypes targeten main element (<h2> in dit voorbeeld) gebruikmakend van op attributen gebaseerde CSS-klassen uit onze _default.less bestanden. We zullen dit hierna doen.
Stap 4: CSS-klassen toevoegen
Om onze DOM-uitvoer te targeten, willen we op attributen gebaseerde CSS-klassen gebruiken in onze _default.less bestanden voor zowel de adminhtml en frontendzoals hier getoond (uit het adminhtml-gebied van onze module):
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
/*-- adminhtml _default.less attribute-based classes */
/*-- the frontend _default.less is the same, but without the .pagebuilder-stage wrapper */
& when (@media-common = true) {
// Heading Colors
.pagebuilder-stage {
[data-heading-color='brand-black'] {
color: #333333;
}
[data-heading-color='brand-blue'] {
color: #007ab9;
}
[data-heading-color='brand-green'] {
color: #009900;
}
[data-heading-color='brand-red'] {
color: #990000;
}
[data-heading-color='brand-purple'] {
color: #990099;
}
}
// Heading Styles
[data-heading-style='style-default'] {
font-weight: normal;
font-style: normal;
}
[data-heading-style='style-bold'] {
font-weight: bold;
}
[data-heading-style='style-italic'] {
font-style: italic;
}
[data-heading-style='style-quotes'] {
&:before {
content: '\201C';
}
&:after {
content: '\201D';
}
}
}
:pijl omhoog: Op attributen gebaseerde CSS-klassen
Om eindgebruikers stijlopties te bieden in de formuliervelden van de beheerdersinterface, kunnen we verschillende CSS-eigenschappen toevoegen voor elke beschikbare waarde. Dit maakt het gemakkelijk om uw inhoudstype-elementen op zowel kleine als grote manieren te targeten en op te maken, afhankelijk van uw gebruiksscenario’s.
Discussie
Page Builder biedt drie configuratie-opties voor het opmaken van de elementen in uw inhoudstypen. Jij kan:
- Gebruik
<attribute>knooppunten om content-type-elementen op te maken met op attributen gebaseerde CSS-klassen. - Gebruik
<style>nodes om content-type-elementen te stylen met specifieke CSS-eigenschappen. - Gebruik
<css>knooppunten om content-type-elementen te stylen met een of meer statische CSS-klassen gekozen door de eindgebruiker.
U kunt de . toevoegen <attribute> en <style> knooppunten vaak naar een inhoudstype element. Maar je kunt de . toevoegen <css> knooppunt slechts één keer per element. Raadpleeg Inzicht in de <css> knooppunt voor meer informatie.
Om te helpen bij onze bespreking van deze configuratieknooppunten en hoe ze te gebruiken, verwijzen we naar de element configuratie van heading.xml (PageBuilder/view/adminhtml/pagebuilder/content_type/heading.xml):
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
<!-- snippet from heading.xml -->
<element name="main">
<style name="text_align" source="text_align"/>
<style name="border" source="border_style" converter="Magento_PageBuilder/js/converter/style/border-style"/>
<style name="border_color" source="border_color"/>
<style name="border_width" source="border_width" converter="Magento_PageBuilder/js/converter/style/border-width"/>
<style name="border_radius" source="border_radius" converter="Magento_PageBuilder/js/converter/style/remove-px"/>
<style name="display" source="display" converter="Magento_PageBuilder/js/converter/style/display" preview_converter="Magento_PageBuilder/js/converter/style/preview/display"/>
<style name="margins" storage_key="margins_and_padding" reader="Magento_PageBuilder/js/property/margins" converter="Magento_PageBuilder/js/converter/style/margins"/>
<style name="padding" storage_key="margins_and_padding" reader="Magento_PageBuilder/js/property/paddings" converter="Magento_PageBuilder/js/converter/style/paddings"/>
<attribute name="name" source="data-content-type"/>
<attribute name="appearance" source="data-appearance"/>
<tag name="heading_type"/>
<html name="heading_text" converter="Magento_PageBuilder/js/converter/html/tag-escaper"/>
<css name="css_classes"/>
</element>
De <tag> en <html> knooppunten vallen buiten het bestek van dit onderwerp, maar net als de andere knooppunten verwijzen ze ook naar velden in een formulier. In dit geval is de <tag> knooppunten naar de Heading’s heading_type veld en de <html> knooppunt wijst naar de heading_text veld van de pagebuilder_heading_form.xml.
Begrijpen en gebruiken style knooppunten
Door te configureren <elements> met <style> nodes, kunt u eindgebruikers een formulierveld geven dat verandert specifiek CSS-eigenschap, zoals we deden met opacity.
In de heading.xml config voorbeeld, de <style> knooppunten worden toegewezen aan de velden met dezelfde naam die zijn gedefinieerd in de pagebuilder_base_form.xml. Dit formulier geeft gebruikers de velden die nodig zijn om elk van de opgegeven CSS-eigenschappen te wijzigen. Wanneer weergegeven in de DOM, voegt Page Builder deze toe: <style>-gedefinieerde eigenschappen (en hun door de gebruiker ingevoerde waarden) naar de inline style attribuut van de main DOM-element, <h1> tot <h6> afhankelijk van het koptype dat is geselecteerd in het kopformulier.
Als een gebruiker bijvoorbeeld een waarde heeft geselecteerd voor elk van de stijlen die zijn gedefinieerd in de heading.xml config, de inline style attribuut in de storefront DOM zou de property:values voor alle <style> knooppunten gedefinieerd, zoals hier weergegeven:
1
2
3
4
5
6
7
8
9
10
11
<h2 data-content-type="heading"
data-element="main"
style="text-align: left;
border-style: solid;
border-color: rgb(240, 240, 240);
border-width: 1px;
border-radius: 3px;
margin: 5px;
padding: 2px;">
My Heading Text
</h2>
Elk <style> node gedefinieerd voor de configuratie van het element wordt toegevoegd aan de DOM als een andere CSS-eigenschap in de element’s style attribuut. In de voorbeeldmodule voor dit onderwerp hebben we toegevoegd: <style name="heading_opacity" source="opacity"/> naar de heading.xml configuratie Dus wanneer Page Builder het uitgebreide inhoudstype Kop in de DOM rendert, voegt het toe: opacity naar de bestaande lijst met CSS-eigenschappen in de style attribuut:
1
2
3
4
5
6
7
8
9
10
11
12
<h2 data-content-type="heading"
data-element="main"
style="text-align: left;
border-style: solid;
border-color: rgb(240, 240, 240);
border-width: 1px;
border-radius: 3px;
margin: 5px;
padding: 2px;
opacity: 1;">
My Heading Text
</h2>
Beslissen om te gebruiken attribute of style configuraties
Zoals gezegd, het toevoegen van een <attribute> knoop naar an element configuratie geeft u een manier om eindgebruikers te voorzien van een formulierveld dat kan gebruiken CSS-klassenwaardoor u kunt veranderen meerdere CSS-eigenschappen tegelijk. Dit kan krachtiger zijn dan het gebruik van <style> configuraties die alleen enkele CSS-eigenschappen kunnen wijzigen. Maar afhankelijk van uw gebruikssituatie, hoeft u misschien niet te gebruiken <attribute> configuraties.
Gebruik makend van <attribute> of <style> configuraties is transparant voor eindgebruikers. Maar voor jou, de ontwikkelaar, hangt de keuze echt af van hoeveel je het element moet veranderen. Als de gebruikersoptie het element aanzienlijk moet wijzigen, kunt u een <attribute> zodat u CSS-klassen op het element kunt toepassen. En als de gebruikersoptie is gericht op het maken van een eenvoudige eigenschapswijziging in het element, kunt u a . gebruiken <style> configuratie.
Het begrijpen css knooppunt
De <css> config node is een beetje anders dan de <attribute> en <style> knooppunten. De <css> knooppunt is niet ontworpen om meer dan één keer aan een element te worden toegevoegd, zoals de andere twee knooppunten. In plaats daarvan is het ontworpen om meerdere CSS-klassen uit een enkel formulierveld vast te leggen en die klassen weer te geven in de DOM binnen de class attribuut. Om deze reden is het momenteel niet mogelijk om CSS-klassen toe te voegen aan een element class attribuut uit andere formuliervelden.
Out of the box, Page Builder brengt de <css> config node (voor elk inhoudstype) naar de css_classes invoerveld van de pagebuilder_base_form.xml. Als u bijvoorbeeld twee CSS-klassen in dit veld zou invoeren in het formulier Kop, zou Page Builder de . toevoegen class toeschrijven aan de Heading’s main element (<h2>) en vul het met de ingevoerde CSS-klassen, zoals weergegeven op de eerste regel hier:
1
2
3
4
5
6
7
8
9
<h2 class="fall-heading-style halloween-heading-style"
data-content-type="heading"
data-appearance="default"
data-heading-color="brand-blue"
data-heading-style="style-default"
data-element="main"
style="text-align: left; border-style: solid; border-color: rgb(240, 240, 240); border-width: 1px; border-radius: 3px; margin: 5px; padding: 2px; opacity: 1;">
My Heading Text
</h2>
Zoals vermeld, kunt u de <css> node om het toe te wijzen aan een andere veldnaam en/of -type. Je kunt het gewoon niet meer dan één keer per element gebruiken.
Ongeacht de beperking kunt u nog steeds de <css> node om creatieve stijlopties voor een inhoudstype te bieden. Als een handelaar bijvoorbeeld een set standaard CSS-klassen heeft die ze gedurende het jaar gebruiken voor vakanties, kunt u de <css> knoop naar a select veld waarmee eindgebruikers kunnen kiezen uit sets van door verkopers goedgekeurde klassen met beschrijvende namen, zoals Halloween-styling, Christmas-styling, enzovoort.
Laatste gedachten
Weten hoe u nieuwe opties voor inhoudstyling kunt maken door formulierinvoer te verbinden met sjabloonuitvoer, is een van de belangrijkste vaardigheden die u als Page Builder-ontwikkelaar moet hebben. En weten hoe je die verbindingen kunt maken met behulp van <attribute>, <style>en <css> configuraties bieden u een verscheidenheid aan krachtige en flexibele opties voor het stylen van inhoud die u uw eindgebruikers kunt bieden. Dus wees creatief en veel plezier!
