{"type":"doc","content":[{"type":"heading","attrs":{"level":2},"content":[{"text":"Introduction","type":"text"}]},{"type":"paragraph","content":[{"text":"With custom modules it is possible for an","type":"text"},{"text":" agency ","type":"text","marks":[{"type":"strong"}]},{"text":"or ","type":"text"},{"text":"develope","type":"text","marks":[{"type":"strong"}]},{"text":"r to create a personalized module intended to extend the functionality of our Editor. This custom module will be fully integrated into the Editor Page Builder and will be available as another core module. It will thus be possible to create a complete custom DOM structure with custom styling and even custom JavaScript.","type":"text"}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"paragraph","content":[{"text":"Custom modules are defined on a front level and not at organization level. This is important to consider when planning the roll out of a custom module for a customer/organization with multiple fronts.","type":"text"}]}]},{"type":"rule"},{"type":"heading","attrs":{"level":2},"content":[{"text":"Setting up a custom module","type":"text"}]},{"type":"paragraph","content":[{"text":"Custom modules are set in the front configuration tab of a front, in the ","type":"text"},{"text":"Organization Manager","type":"text","marks":[{"type":"strong"},{"type":"link","attrs":{"href":"https://admin.styla.eu"}}]},{"text":" and by users with an admin or agency role.","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"center"},"content":[{"type":"media","attrs":{"width":982,"id":"85f7ac20-bb2a-4291-9ca7-550cc18f2f0a","collection":"contentId-1400242186","type":"file","height":775}}]},{"type":"paragraph"},{"type":"paragraph","content":[{"text":"A single front can contain an unlimited number of Custom Modules. In the picture above you can see that each definition is a row in the ","type":"text"},{"text":"customModules","type":"text","marks":[{"type":"code"}]},{"text":" array.","type":"text"}]},{"type":"paragraph","content":[{"text":"Each Custom Module requires the following information:","type":"text"}]},{"type":"table","attrs":{"layout":"default","localId":"b2add75b-fd43-48fa-853e-fe4b18bfe489"},"content":[{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[340.0]},"content":[{"type":"paragraph","content":[{"text":"type","type":"text","marks":[{"type":"code"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[340.0]},"content":[{"type":"paragraph","content":[{"text":"This is the so-called “slug” of the module. It will be used as a reference when a module is stored in the Styla DB. Therefore, it needs to be a unique identifier (cannot be the same as another module for the same front) and cannot contain spaces or special characters. The slug is case-insensitive, and will anyway be converted to all uppercase by our system. We will also automatically prepend your front name followed by a dot.","type":"text"},{"type":"hardBreak"},{"text":"E.g. ","type":"text"},{"text":"my-front.PRODUCT","type":"text","marks":[{"type":"strong"}]},{"text":".","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[340.0]},"content":[{"type":"paragraph","content":[{"text":"title","type":"text","marks":[{"type":"code"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[340.0]},"content":[{"type":"paragraph","content":[{"text":"This is what will be shown in the Editor UI, e.g. when dragging and dropping a new module. This can be a descriptive name and can contain spaces.","type":"text"}]},{"type":"paragraph","content":[{"text":"E.g. ","type":"text"},{"text":"Countdown Module","type":"text","marks":[{"type":"strong"}]}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[340.0]},"content":[{"type":"paragraph","content":[{"text":"schema","type":"text","marks":[{"type":"code"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[340.0]},"content":[{"type":"paragraph","content":[{"text":"A URL pointing to a JSON file containing the custom module’s data structure definition (*).","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[340.0]},"content":[{"type":"paragraph","content":[{"text":"template","type":"text","marks":[{"type":"code"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[340.0]},"content":[{"type":"paragraph","content":[{"text":"A URL to a handlebars template file that will be used for rendering the DOM structure of the module (*).","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[340.0]},"content":[{"type":"paragraph","content":[{"text":"js","type":"text","marks":[{"type":"code"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[340.0]},"content":[{"type":"paragraph","content":[{"type":"status","attrs":{"color":"yellow","style":"bold","text":"OPTIONAL","localId":"14c27121-5d41-467a-9b59-39e493cca835"}},{"text":" A URL pointing to a javascript file that would be executed in order to extend the functionality of the module or enrich it with a dynamic behaviour.","type":"text"},{"type":"hardBreak"},{"type":"hardBreak"},{"text":"The files provided can be hosted anywhere, for example on an S3 bucket or on a customer’s server. ","type":"text"},{"text":"It is important to make sure that the files remain accessible by the Styla Editor and your publishing front","type":"text","marks":[{"type":"strong"}]},{"text":" by setting the appropriate CORS response headers in the chosen hosting. In addition, If you expect a high traffic on your site, we recommend using a CDN for distributing these assets.","type":"text"}]}]}]}]},{"type":"rule"},{"type":"paragraph","content":[{"text":"Let’s look in more detail at the ","type":"text"},{"text":"schema","type":"text","marks":[{"type":"code"}]},{"text":", ","type":"text"},{"text":"template","type":"text","marks":[{"type":"code"}]},{"text":" and ","type":"text"},{"text":"js","type":"text","marks":[{"type":"code"}]},{"text":".","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Schema (Data structure)","type":"text"}]},{"type":"paragraph","content":[{"text":"The edit schema file contains the definition of the dynamic data of the module and the corresponding UI for editing it in the module edit panel.","type":"text"},{"type":"hardBreak"},{"text":"In order to define which fields will be available (with a related fields definition) we use the ","type":"text"},{"text":"React JSON Schema Form","type":"text","marks":[{"type":"strong"}]},{"text":" specification (","type":"text"},{"type":"inlineCard","attrs":{"url":"https://github.com/rjsf-team/react-jsonschema-form"}},{"text":" ).","type":"text"}]},{"type":"paragraph","content":[{"text":"Since the Editor UI provides different tabs for managing content, we support 2 main blocks as children of editSchema:","type":"text"}]},{"type":"table","attrs":{"layout":"default","localId":"58d9629d-1726-4701-a504-d5e7fb2a4fff"},"content":[{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"background":"transparent","rowspan":1,"colwidth":[226.67]},"content":[{"type":"paragraph","content":[{"text":"content","type":"text","marks":[{"type":"code"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"background":"transparent","rowspan":1,"colwidth":[226.67]},"content":[{"type":"paragraph","content":[{"text":"This is what will be rendered in the content tab. Here is where you define the fields that will be used by the content manager to create content (e.g. headlines or paragraph text)","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"background":"transparent","rowspan":1,"colwidth":[226.67]},"content":[{"type":"paragraph","content":[{"type":"status","attrs":{"color":"red","style":"bold","text":"required","localId":"ca88d85b-2da1-4bc4-9f75-b2e136f08bd6"}},{"text":" ","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"background":"transparent","rowspan":1,"colwidth":[226.67]},"content":[{"type":"paragraph","content":[{"text":"settings","type":"text","marks":[{"type":"code"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"background":"transparent","rowspan":1,"colwidth":[226.67]},"content":[{"type":"paragraph","content":[{"text":"This is what will be rendered in the settings tab. Fields like “number of products per view” or “module padding” usually belong in this tab","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[226.67]},"content":[{"type":"paragraph","content":[{"type":"status","attrs":{"color":"yellow","style":"bold","text":"OPTIONAL","localId":"c4ee3bcd-d426-4170-8117-a8b1c88c84a0"}},{"type":"hardBreak"},{"text":"If missing, the default UI element for field type will be used.","type":"text"}]}]}]}]},{"type":"paragraph","content":[{"text":"Each of these blocks (","type":"text"},{"text":"content","type":"text","marks":[{"type":"code"}]},{"text":" and ","type":"text"},{"text":"settings","type":"text","marks":[{"type":"code"}]},{"text":") support the following fields as children:","type":"text"}]},{"type":"table","attrs":{"layout":"default","localId":"7b11696c-886c-4fb9-8b82-dc719849db8e"},"content":[{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[226.67]},"content":[{"type":"paragraph","content":[{"text":"data","type":"text","marks":[{"type":"code"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[226.67]},"content":[{"type":"paragraph","content":[{"text":"This is the data definition. Here you will define what the fields are called, what type of field they are, what their default values are, etc.","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[226.67]},"content":[{"type":"paragraph","content":[{"type":"status","attrs":{"color":"red","style":"bold","text":"required","localId":"de3767c0-047d-4adf-8c94-c69e2f81fa51"}}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[226.67]},"content":[{"type":"paragraph","content":[{"text":"ui","type":"text","marks":[{"type":"code"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[226.67]},"content":[{"type":"paragraph","content":[{"text":"This is the UI definition. For each data element defined in the data block you will be able to specify which UI element should be used for rendering.","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[226.67]},"content":[{"type":"paragraph","content":[{"type":"status","attrs":{"color":"yellow","style":"bold","text":"OPTIONAL","localId":"0a1f4889-e217-4fd5-9f7a-b1849c188841"}},{"type":"hardBreak"},{"text":"If missing, the default UI element for field type will be used.","type":"text"}]}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Example","type":"text"}]},{"type":"paragraph","content":[{"text":"If we want to create a very simple module where we can add a headline and then have a slider control to set the font-size, we can write it like this:","type":"text"}]},{"type":"paragraph"},{"type":"codeBlock","attrs":{"language":"javascript"},"content":[{"text":"{\n \"content\": {\n \"data\": {\n \"properties\": {\n \"headerTitle\": {\n \"title\": \"Title\",\n \"placeholder\": \"Enter title here\",\n \"type\": \"string\"\n }\n },\n \"type\": \"object\"\n }\n },\n \"settings\": {\n \"data\": {\n \"properties\": {\n \"fontSize\": {\n \"title\": \"Font size\",\n \"type\": \"number\",\n \"default\": 12,\n \"minimum\": 9,\n \"maximum\": 24\n }\n }\n },\n \"ui\": {\n \"fontSize\": {\n \"ui:field\": \"SliderField\",\n \"ui:options\": {\n \"marks\": {\n \"9\": \"9\",\n \"12\": \"12\",\n \"14\": \"14\",\n \"20\": \"20\",\n \"24\": \"24\"\n },\n \"step\": 1\n }\n }\n }\n }\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"As you can see we don’t have a UI block for ","type":"text"},{"text":"headerTitle","type":"text","marks":[{"type":"code"}]},{"text":", inside the content object. This is because we just want to render a standard text input, so there’s no need to declare a specific UI element for it. We do that with ","type":"text"},{"text":"fontSize","type":"text","marks":[{"type":"code"}]},{"text":", however, since we want to use ","type":"text"},{"text":"SliderField","type":"text","marks":[{"type":"code"}]},{"text":" and also specify which steps are allowed. ","type":"text"},{"text":"default","type":"text","marks":[{"type":"code"}]},{"text":", ","type":"text"},{"text":"maximum","type":"text","marks":[{"type":"code"}]},{"text":" and ","type":"text"},{"text":"minimum","type":"text","marks":[{"type":"code"}]},{"text":", on the other hand, are defined in the data part.","type":"text"}]},{"type":"paragraph","content":[{"text":"SliderField","type":"text","marks":[{"type":"code"}]},{"text":" is one of the UI widgets provided by Styla. Here is the full list:","type":"text"}]},{"type":"table","attrs":{"layout":"default","localId":"6425901b-0632-41ac-9e4e-721e6e38e5b0"},"content":[{"type":"tableRow","content":[{"type":"tableHeader","attrs":{"colspan":1,"background":"#f4f5f7","rowspan":1,"colwidth":[226.67]},"content":[{"type":"paragraph","content":[{"text":"UI field name","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"tableHeader","attrs":{"colspan":1,"background":"#f4f5f7","rowspan":1,"colwidth":[226.67]},"content":[{"type":"paragraph","content":[{"text":"Description","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"tableHeader","attrs":{"colspan":1,"background":"#f4f5f7","rowspan":1,"colwidth":[226.67]},"content":[{"type":"paragraph","content":[{"text":"Data Type","type":"text","marks":[{"type":"strong"}]}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"background":"transparent","rowspan":1,"colwidth":[226.67]},"content":[{"type":"paragraph","content":[{"text":"sliderField","type":"text","marks":[{"type":"code"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"background":"transparent","rowspan":1,"colwidth":[226.67]},"content":[{"type":"paragraph","content":[{"text":"Shows a draggable slider for selecting a number value inside a given range. Supports a “step” parameter and only allowing a specific set of values as well.","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"background":"transparent","rowspan":1,"colwidth":[226.67]},"content":[{"type":"paragraph","content":[{"text":"number","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"background":"transparent","rowspan":1,"colwidth":[226.67]},"content":[{"type":"paragraph","content":[{"text":"LinkField","type":"text","marks":[{"type":"code"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"background":"transparent","rowspan":1,"colwidth":[226.67]},"content":[{"type":"paragraph","content":[{"text":"Shows the enriched link field, with support for selection of internal vs. external and the style selection dropdown","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"background":"transparent","rowspan":1,"colwidth":[226.67]},"content":[{"type":"paragraph","content":[{"text":"Object","type":"text"}]},{"type":"codeBlock","content":[{"text":"{\n link: string,\n text: string,\n stylePreset: string\n}\n\t\t\t\t","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"background":"transparent","rowspan":1,"colwidth":[226.67]},"content":[{"type":"paragraph","content":[{"text":"RichTextField","type":"text","marks":[{"type":"code"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"background":"transparent","rowspan":1,"colwidth":[226.67]},"content":[{"type":"paragraph","content":[{"text":"Shows the Rich Text Editor field.","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"background":"transparent","rowspan":1,"colwidth":[226.67]},"content":[{"type":"paragraph","content":[{"text":"Object, using the Quill delta specifications: ","type":"text"},{"text":"https://quilljs.com/docs/delta/","type":"text","marks":[{"type":"underline"},{"type":"link","attrs":{"href":"https://quilljs.com/docs/delta/"}}]}]},{"type":"paragraph"},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"paragraph","content":[{"text":"This also requires a UI config for specifying which elements are going to be shown in the Toolbar. More details on this in RichTextField Options","type":"text"}]}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"background":"transparent","rowspan":1,"colwidth":[226.67]},"content":[{"type":"paragraph","content":[{"text":"ImageField","type":"text","marks":[{"type":"code"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"background":"transparent","rowspan":1,"colwidth":[226.67]},"content":[{"type":"paragraph","content":[{"text":"Image Uploader","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"background":"transparent","rowspan":1,"colwidth":[226.67]},"content":[{"type":"paragraph","content":[{"text":"Object","type":"text"}]},{"type":"codeBlock","content":[{"text":"{\n url: string,\n width: number,\n height: number \n}\n\t\t\t\t","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"background":"transparent","rowspan":1,"colwidth":[226.67]},"content":[{"type":"paragraph","content":[{"text":"InputField","type":"text","marks":[{"type":"code"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"background":"transparent","rowspan":1,"colwidth":[226.67]},"content":[{"type":"paragraph","content":[{"text":"A regular input field. As mentioned before, will be used as default for strings so it’s not necessary to explicitly set it","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"background":"transparent","rowspan":1,"colwidth":[226.67]},"content":[{"type":"paragraph","content":[{"text":"string","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"background":"transparent","rowspan":1,"colwidth":[226.67]},"content":[{"type":"paragraph","content":[{"text":"CustomMenuItemsWidget","type":"text","marks":[{"type":"code"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"background":"transparent","rowspan":1,"colwidth":[226.67]},"content":[{"type":"paragraph","content":[{"text":"A multi-item widget built for menu entries. It allows adding, deleting and sorting. It also supports nested items, by dragging items on top of the others. For each entry it stores a title and a link.","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"background":"transparent","rowspan":1,"colwidth":[226.67]},"content":[{"type":"paragraph","content":[{"text":"string","type":"text"}]},{"type":"paragraph"},{"type":"paragraph","content":[{"text":"NOTE: this is a UI widget, so it needs to be used with the following syntax:","type":"text"}]},{"type":"codeBlock","content":[{"text":"\"ui:widget\": \"CustomMenuItemsWidget\"","type":"text"}]}]}]}]},{"type":"paragraph"},{"type":"heading","attrs":{"level":3},"content":[{"text":"RichTextField Options","type":"text"}]},{"type":"paragraph","content":[{"text":"The toolbar of RichTextField widget can be customized based on the specific needs. It’s important that a UI config is provided, otherwise no options are going to be shown.","type":"text"}]},{"type":"paragraph","content":[{"text":"This is a recap of the allowed toolbar elements:","type":"text"}]},{"type":"table","attrs":{"layout":"default","localId":"01c68fdc-d925-446b-9cb0-89095db0aba3"},"content":[{"type":"tableRow","content":[{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":[144.0]},"content":[{"type":"paragraph","content":[{"text":"Name","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":[476.0]},"content":[{"type":"paragraph","content":[{"text":"Description","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":[140.0]},"content":[{"type":"paragraph","content":[{"text":"Field Type","type":"text","marks":[{"type":"strong"}]}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[144.0]},"content":[{"type":"paragraph","content":[{"text":"textMarkup","type":"text","marks":[{"type":"code"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[476.0]},"content":[{"type":"paragraph","content":[{"text":"Enables markup options (bold, italic and underline)","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[140.0]},"content":[{"type":"paragraph","content":[{"type":"status","attrs":{"color":"neutral","style":"bold","text":"boolean","localId":"4c3c142e-b6b4-4e9b-aa09-0910dae1ea12"}},{"text":" ","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[144.0]},"content":[{"type":"paragraph","content":[{"text":"headlines","type":"text","marks":[{"type":"code"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[476.0]},"content":[{"type":"paragraph","content":[{"text":"Specifies the allowed headline types","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[140.0]},"content":[{"type":"paragraph","content":[{"type":"status","attrs":{"color":"blue","style":"bold","text":"array","localId":"d93f11d0-bd1e-4386-88a5-bd651b07c2b6"}},{"text":" ","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[144.0]},"content":[{"type":"paragraph","content":[{"text":"quote","type":"text","marks":[{"type":"code"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[476.0]},"content":[{"type":"paragraph","content":[{"text":"Enables the creation of quoted text","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[140.0]},"content":[{"type":"paragraph","content":[{"type":"status","attrs":{"color":"neutral","style":"bold","text":"boolean","localId":"eef00022-c4b2-426a-8b3f-8324ed339a6b"}},{"text":" ","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[144.0]},"content":[{"type":"paragraph","content":[{"text":"textAlign","type":"text","marks":[{"type":"code"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[476.0]},"content":[{"type":"paragraph","content":[{"text":"Enables text alignment (left, center, right, justified)","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[140.0]},"content":[{"type":"paragraph","content":[{"type":"status","attrs":{"color":"neutral","style":"bold","text":"boolean","localId":"9cd01d20-4e14-4bd2-bea7-7151120bf34f"}},{"text":" ","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[144.0]},"content":[{"type":"paragraph","content":[{"text":"link","type":"text","marks":[{"type":"code"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[476.0]},"content":[{"type":"paragraph","content":[{"text":"Enables hyperlinks support","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[140.0]},"content":[{"type":"paragraph","content":[{"type":"status","attrs":{"color":"neutral","style":"bold","text":"boolean","localId":"cc452077-4b3d-469c-9e84-3b169b83ae86"}},{"text":" ","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[144.0]},"content":[{"type":"paragraph","content":[{"text":"textColor","type":"text","marks":[{"type":"code"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[476.0]},"content":[{"type":"paragraph","content":[{"text":"Enables the text color overrides","type":"text"}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"paragraph","content":[{"text":"NOTE: using this feature results in inline styles being rendered in the HTML. It will therefore have more specificity than CSS definitions made in the module itself","type":"text"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[140.0]},"content":[{"type":"paragraph","content":[{"type":"status","attrs":{"color":"neutral","style":"bold","text":"boolean","localId":"ba661e3b-50fc-4b2d-b394-a9a1ecfcd4ff"}},{"text":" ","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[144.0]},"content":[{"type":"paragraph","content":[{"text":"list","type":"text","marks":[{"type":"code"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[476.0]},"content":[{"type":"paragraph","content":[{"text":"Allows the creation of lists (numbered or bulleted)","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[140.0]},"content":[{"type":"paragraph","content":[{"type":"status","attrs":{"color":"neutral","style":"bold","text":"boolean","localId":"945a8072-ed2a-46bc-b365-9906d91e8ddc"}},{"text":" ","type":"text"}]}]}]}]},{"type":"paragraph","content":[{"text":"This is a sample UI configuration, for a field called ","type":"text"},{"text":"description","type":"text","marks":[{"type":"code"}]},{"text":":","type":"text"}]},{"type":"codeBlock","content":[{"text":"\"description\": {\n \"ui:field\": \"RichTextField\",\n \"ui:options\": {\n \"textMarkup\": true,\n \"headlines\": [\n 1,\n 2,\n 3\n ],\n \"quote\": true,\n \"textAlign\": true,\n \"link\": true,\n \"textColor\": true,\n \"list\": true\n }\n },","type":"text"}]},{"type":"paragraph"},{"type":"heading","attrs":{"level":4},"content":[{"type":"hardBreak"},{"text":"Arrays","type":"text"}]},{"type":"paragraph","content":[{"text":"We support arrays as well, which is very useful when we need a repeater field (e.g. an image gallery module). ","type":"text"}]},{"type":"paragraph","content":[{"text":"To define an array use this structure:","type":"text"}]},{"type":"expand","attrs":{"title":"Arrays"},"content":[{"type":"paragraph","content":[{"type":"status","attrs":{"color":"neutral","style":"bold","text":"IN DATA:","localId":"bd728eb2-d047-49a3-8960-3821f45aec06"}},{"text":" ","type":"text"}]},{"type":"codeBlock","content":[{"text":"{\n \"images\": {\n \"title\": \"Gallery Images\",\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"isShown\": {\n \"title\": \"Is image shown\",\n \"type\": \"boolean\",\n \"default\": true\n },\n \"image\": {\n \"title\": \"Image\",\n \"type\": \"object\"\n }\n }\n }\n }\n}","type":"text"}]},{"type":"paragraph"},{"type":"paragraph","content":[{"type":"status","attrs":{"color":"neutral","style":"bold","text":"IN CONTENT:","localId":"c1903660-321c-4fbc-8d05-0c2be00a93cd"}}]},{"type":"codeBlock","content":[{"text":"{\n \"ui\": {\n \"images\": {\n \"items\": {\n \"image\": {\n \"ui:field\": \"ImageField\"\n }\n }\n }\n }\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"This will render a repeater field where the user can upload an unlimited number of images, order them and they will also be able to toggle visibility, using the ","type":"text"},{"text":"isShown","type":"text","marks":[{"type":"underline"}]},{"text":" field. Please note that we didn’t explicitly set a UI type for this switch. This is not necessary, as by default all boolean fields will be rendered as UI toggle buttons. We did, however, specify ","type":"text"},{"text":"ImageField","type":"text","marks":[{"type":"underline"}]},{"text":" as a field for the image, in order to use the image uploader.","type":"text"}]}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Dropdowns","type":"text"}]},{"type":"paragraph","content":[{"text":"We support dropdowns as well. ","type":"text"},{"type":"hardBreak"}]},{"type":"expand","attrs":{"title":"Dropdowns"},"content":[{"type":"paragraph","content":[{"text":"In this case it is enough to just define the field as an ","type":"text"},{"text":"enum","type":"text","marks":[{"type":"code"}]},{"text":".","type":"text"}]},{"type":"codeBlock","content":[{"text":"\"imageSize\": {\n \"title\": \"Image Size\",\n \"placeholder\": \"Select Image Size\",\n \"enum\": [\n \"small\",\n \"medium\",\n \"large\"\n ]\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"This will automatically be rendered as a dropdown selection with the 3 options.","type":"text"}]}]},{"type":"rule"},{"type":"heading","attrs":{"level":2},"content":[{"text":"Template (Handlebars Template)","type":"text","marks":[{"type":"annotation","attrs":{"annotationType":"inlineComment","id":"ea4cb536-9a0e-4fe2-9a35-29a5bf80f531"}},{"type":"annotation","attrs":{"annotationType":"inlineComment","id":"36a39536-ae24-426c-9f95-2c11d372cc3d"}}]}]},{"type":"paragraph","content":[{"text":"This is where the HTML structure of the module is defined. To allow dynamic capabilities, we support Handlebars syntax ( ","type":"text"},{"text":"https://handlebarsjs.com/","type":"text","marks":[{"type":"underline"},{"type":"link","attrs":{"href":"https://handlebarsjs.com/"}}]},{"text":" ).","type":"text"},{"type":"hardBreak"},{"text":"By using the Handlebars variables you will be able to access every piece of information that was created through the editor UI.","type":"text"}]},{"type":"paragraph","content":[{"text":"For example, to access the variable called “headerTitle”:","type":"text"}]},{"type":"codeBlock","content":[{"text":"

","type":"text"}]},{"type":"paragraph","content":[{"text":"In a similar way you can access something that was defined inside settings:","type":"text"}]},{"type":"codeBlock","content":[{"text":"

hello

","type":"text"}]},{"type":"paragraph","content":[{"text":"This is of course a very simple example, but even complex layouts can be achieved by using the Handlebars capabilities, such as iterations, conditional rendering, etc.","type":"text"},{"type":"hardBreak"},{"text":"For this we suggest taking a look at their official documentation:","type":"text"},{"type":"hardBreak"},{"text":"https://handlebarsjs.com/guide/builtin-helpers.html","type":"text","marks":[{"type":"underline"},{"type":"link","attrs":{"href":"https://handlebarsjs.com/guide/builtin-helpers.html"}}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Documentation for Handlebar Helpers ","type":"text"}]},{"type":"paragraph","content":[{"text":"We currently provide all the Handlebar helpers","type":"text","marks":[{"type":"annotation","attrs":{"annotationType":"inlineComment","id":"75715369-e8a0-466e-aebe-23d57ed76f81"}},{"type":"annotation","attrs":{"annotationType":"inlineComment","id":"13bd5ba4-1752-4586-8aac-73dd38575415"}}]},{"text":" listed on this documentation website: ","type":"text"},{"type":"inlineCard","attrs":{"url":"https://documentation.styla.eu/custom-modules/handlebars-helpers/helpers-index"}},{"text":". One thing you can build using these helpers is product details page as custom module. More helpers will be added in the future, for instance, some facilitating building product listing (category grids) pages as custom modules. ","type":"text"}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"paragraph","content":[{"text":"The Handlebars Template will be fully prerendered and the static html will be outputted in the page source. It is important to include as much content as possible in the template and as little as possible in the javascript file. This way the user’s browser will need less time to render the content with less layout shifts in the process.","type":"text"}]}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"paragraph","content":[{"text":"Since updating this file will automatically affect the associated module in all the active pages where the module is used. Always keep this in mind when modifying the template.","type":"text"}]}]},{"type":"rule"},{"type":"heading","attrs":{"level":2},"content":[{"text":"JS (Javascript)","type":"text","marks":[{"type":"annotation","attrs":{"annotationType":"inlineComment","id":"98313c4a-39cc-4436-8da0-f5bce9b9a3e0"}}]}]},{"type":"paragraph","content":[{"text":"If your module requires some dynamic functionality that can only be achieved with Javascript, you can develop a script that will be executed right after your custom module is mounted.","type":"text"}]},{"type":"paragraph","content":[{"text":"The JS snippet needs to be a function that will accept one parameter, which will be the custom module main wrapping DOM element. This will be useful in order to be able to target the correct element without having to rely on id or class names. This will additionally allow the safe use of multiple instances of the module on the same page without causing conflicts.","type":"text"}]},{"type":"paragraph","content":[{"text":"In addition to that we can as well return a cleanup function, which will be called when the element is unmounted. This can be useful e.g. for removing click listeners etc.","type":"text"}]},{"type":"paragraph","content":[{"text":"This is a very ","type":"text"},{"text":"basic example","type":"text","marks":[{"type":"annotation","attrs":{"annotationType":"inlineComment","id":"4d9de4dc-e5be-41fb-8dd4-3a4932276cb7"}}]},{"text":":","type":"text"}]},{"type":"codeBlock","content":[{"text":"window.styla.registerCustomModule(\"CUSTOM_MODULE_NAME\", \n (\n wrapperElem, // DOM container for this custom module\n content, // Module content from schema input\n context, // Page context contains title, path, entity data etc.\n settings, // Module settings from schema input\n helpers, // Additional helpers provided by styla\n ) => {\n\n console.log( 'hello', wrapperElem );\n\n return () => {\n console.log( 'this is a cleanup function' );\n }\n\n});","type":"text"}]},{"type":"paragraph","content":[{"text":"The ","type":"text"},{"text":"\"CUSTOM_MODULE_NAME\"","type":"text","marks":[{"type":"code"}]},{"text":" needs to match your module name defined in the front configuration. The function can take up to 5 parameters. They might change from time to time on the Styla end. ","type":"text"}]},{"type":"paragraph","content":[{"text":"The cleanup function is optional and can be omitted.","type":"text"}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"paragraph","content":[{"text":"The JavaScript file is only executed in the browser of the website user. It is not executed in the prerender pipeline. The script will update the static html content only once executed, and some search engine bots have problems executing JS. Therefore any SEO-relevant data should be added directly to the handlebar template (above) and not modified by the JS.","type":"text"}]}]},{"type":"panel","attrs":{"panelType":"warning"},"content":[{"type":"paragraph","content":[{"text":"Make sure to include an ","type":"text"},{"text":"access origin header ","type":"text","marks":[{"type":"strong"}]},{"text":"for all the files (schema, template, JS) you configure for a custom module. The files will be requested in the browser and if you don't include these headers, your custom module won't load in the Editor and display the follow error message in the console:","type":"text"},{"type":"hardBreak"}]},{"type":"paragraph","content":[{"text":"Access to XMLHttpRequest at '(url)' from origin '","type":"text","marks":[{"type":"em"}]},{"text":"https://editor.styla.eu","type":"text","marks":[{"type":"em"},{"type":"link","attrs":{"href":"https://editor.styla.eu"}}]},{"text":"' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource.","type":"text","marks":[{"type":"em"}]}]}]},{"type":"rule"},{"type":"heading","attrs":{"level":2},"content":[{"text":"Full Example","type":"text"}]},{"type":"paragraph","content":[{"text":"In this example, we are going to create a “Social Sharing” module:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The final result is a Social Sharing element, where the final user can click on a specific service and share the current page on the selected Social Media platform","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Content creators need to be able to upload images with the Social Media logos. In addition they need to be able to rearrange the items, type a title which will be shown on mouseover, disable an element without deleting it.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Content creators need to be able to set a title for the whole module","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Content creators need to be able to adjust the spacing between the icons and the icon size via a simple UI","type":"text"}]}]}]},{"type":"mediaSingle","attrs":{"layout":"center"},"content":[{"type":"media","attrs":{"width":2560,"id":"0c7516de-1a8c-4542-ad2a-07901282749e","collection":"contentId-1400242186","type":"file","height":1401},"marks":[{"type":"link","attrs":{"href":"https://monosnap.com/file/J7466WoiTDSEYyQy6Z2whFcXM0lvDD"}}]}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"paragraph","content":[{"text":"Watch the full Demo video (","type":"text"},{"text":"https://monosnap.com/file/J7466WoiTDSEYyQy6Z2whFcXM0lvDD","type":"text","marks":[{"type":"underline"},{"type":"link","attrs":{"href":"https://monosnap.com/file/J7466WoiTDSEYyQy6Z2whFcXM0lvDD"}}]},{"text":")","type":"text"}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Schema (Data structure)","type":"text"}]},{"type":"paragraph","content":[{"text":"We will first define a standard text field which we will use as a call to action phrase naming it ","type":"text"},{"text":"headerTitle","type":"text","marks":[{"type":"code"}]},{"text":". In addition to this we will have a repeater field which we will call icons. Each of these elements will contain the following data:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"isShown","type":"text","marks":[{"type":"code"}]},{"text":": a boolean to hide/show the icon","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"image","type":"text","marks":[{"type":"code"}]},{"text":": the icon image. We will use the Styla image uploader for this.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"title","type":"text","marks":[{"type":"code"}]},{"text":": the title that will be shown on mouseover on the icon","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"identifier","type":"text","marks":[{"type":"code"}]},{"text":": an identifier of the type of Social Network. This will be used by the JS file in order to determine how the destination URL will be constructed.","type":"text"}]}]}]},{"type":"paragraph","content":[{"type":"hardBreak"},{"text":"We also want to support a couple of settings:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"iconsSize","type":"text","marks":[{"type":"code"}]},{"text":": the size of the icons in pixels","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"iconsPadding","type":"text","marks":[{"type":"code"}]},{"text":": the spacing between icons in pixels","type":"text"}]}]}]},{"type":"paragraph","content":[{"type":"hardBreak"},{"text":"For these 2 settings we want to use the ","type":"text"},{"text":"SliderField","type":"text","marks":[{"type":"code"}]},{"text":" widget and also set some predefined values on the slider. ","type":"text"}]},{"type":"paragraph","content":[{"text":"The final content of ","type":"text"},{"text":"schema.json","type":"text","marks":[{"type":"code"}]},{"text":" will therefore look like this:","type":"text"}]},{"type":"expand","attrs":{"title":"Schema"},"content":[{"type":"codeBlock","content":[{"text":"{\n \"data\": {\n \"properties\": {\n \"headerTitle\": {\n \"title\": \"Action description\",\n \"placeholder\": \"Example: Share now\",\n \"type\": \"string\"\n },\n \"icons\": {\n \"title\": \"Social icons\",\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"isShown\": {\n \"title\": \"Is shown\",\n \"type\": \"boolean\",\n \"default\": true\n },\n \"image\": {\n \"title\": \"Image\",\n \"placeholder\": \"enter the image URL here...\",\n \"type\": \"object\"\n },\n \"title\": {\n \"title\": \"Title\",\n \"placeholder\": \"enter a Title here...\",\n \"type\": \"string\"\n },\n \"identifier\": {\n \"title\": \"Service Name\",\n \"placeholder\": \"select a service from the list\",\n \"enum\": [\n \"facebook\",\n \"linkedin\",\n \"pinterest\",\n \"twitter\",\n \"whatsapp\"\n ]\n }\n }\n }\n }\n },\n \"type\": \"object\"\n },\n \"ui\": {\n \"icons\": {\n \"items\": {\n \"image\": {\n \"ui:field\": \"ImageField\"\n }\n }\n }\n }\n},\n\"settings\": {\n \"data\": {\n \"properties\": {\n \"iconsSize\": {\n \"title\": \"Icons size\",\n \"type\": \"number\",\n \"default\": 50,\n \"minimum\": 25,\n \"maximum\": 100\n },\n \"iconsPadding\": {\n \"title\": \"Space between icons\",\n \"type\": \"number\",\n \"default\": 16,\n \"minimum\": 1,\n \"maximum\": 32\n }\n }\n },\n \"ui\": {\n \"iconsSize\": {\n \"ui:field\": \"SliderField\",\n \"ui:options\": {\n \"marks\": {\n \"25\": \"25\",\n \"50\": \"50\",\n \"75\": \"75\",\n \"100\": \"100\"\n },\n \"step\": 5\n }\n },\n \"iconsPadding\": {\n \"ui:field\": \"SliderField\",\n \"ui:options\": {\n \"marks\": {\n \"1\": \"1\",\n \"4\": \"4\",\n \"8\": \"8\",\n \"12\": \"12\",\n \"16\": \"16\",\n \"20\": \"20\",\n \"24\": \"24\",\n \"32\": \"32\"\n },\n \"step\": 1\n }\n }\n }\n}","type":"text"}]},{"type":"paragraph"}]},{"type":"paragraph","content":[{"text":"Once we have this we can already store it in a file, upload it in a web host (or S3 bucket) and then create the Custom Module configuration in the Styla ","type":"text"},{"text":"Organization Manager","type":"text","marks":[{"type":"link","attrs":{"href":"https://admin.styla.eu"}}]},{"text":" (admin.styla.eu):","type":"text"}]},{"type":"expand","attrs":{"title":"CustomModule in Domain Configuration (Organization Manager)"},"content":[{"type":"codeBlock","content":[{"text":"{\n \"customModules\": [\n {\n \"type\": \"SOCIAL_SHARING\",\n \"title\": \"Social Sharing Module\",\n \"schema\": \"https://custom-url.com/schema.json\"\n }\n ]\n}","type":"text"}]}]},{"type":"paragraph","content":[{"text":"After this, the module will already be available for use within the Editor. ","type":"text"},{"text":"Of course there will not be any preview","type":"text","marks":[{"type":"strong"}]},{"text":" (since the ","type":"text"},{"text":"template","type":"text","marks":[{"type":"code"}]},{"text":" part is still missing) but we can already test the Editor part and make sure that it looks as we intended.","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"center","width":30.0},"content":[{"type":"media","attrs":{"width":2560,"id":"1fde8dca-6eec-44cb-9d55-ce2bd6f3c431","collection":"contentId-1400242186","type":"file","height":4606}}]},{"type":"paragraph","content":[{"text":"After populating the module with dummy data we can even check the generated JSON (by clicking on ","type":"text"},{"text":"Edit JSON","type":"text","marks":[{"type":"strong"}]},{"text":" on the bottom left of the module) to double-check the data structure. This can be particularly useful when creating the Handlebars template.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Template (Handlebars Template)","type":"text"}]},{"type":"paragraph","content":[{"text":"As mentioned above, the single icon is a repeater field, since the user can add an unlimited number of these items. Therefore, we need to rely on the iteration functionality provided by Handlebars. In addition to that, we also want to access the settings from each element of this iteration. For this, we will use the shortcut ","type":"text"},{"text":"@root","type":"text","marks":[{"type":"strong"}]},{"text":".","type":"text"}]},{"type":"paragraph","content":[{"text":"The final template will look like this","type":"text","marks":[{"type":"annotation","attrs":{"annotationType":"inlineComment","id":"662391d4-7ed1-4b95-a60b-ab3f0cf73ede"}}]},{"text":":","type":"text"},{"type":"hardBreak"}]},{"type":"expand","attrs":{"title":"Template"},"content":[{"type":"codeBlock","content":[{"text":"\n

\n {{ content.headerTitle }}\n {{#each content.icons}}\n {{#if isShown}}\n \n \n \n {{/if}}\n {{/each}}\n

Browser not supported