File structure
90% of your focus either making new component blocks or editing existing blocks will be focused on these files under resources/js:
├── Utils
│ └── blocks.js
├── components
│ ├── Blocks
│ │ ├── BlockGroup.vue
│ │ ├── BlockPreviewer.vue
│ │ ├── BlockWrapper.vue
│ │ ├── FAQ
│ │ │ ├── FAQCollapse.vue
│ │ │ ├── FAQCollapseOptions.vue
│ │ │ ├── FAQCollapseRendered.vue
│ │ │ ├── FAQCondensed.vue
│ │ │ ├── FAQCondensedOptions.vue
│ │ │ ├── FAQCondensedRendered.vue
│ │ │ ├── FAQList.vue
│ │ │ ├── FAQListOptions.vue
│ │ │ └── FAQListRendered.vue
│ │ ├── Heroes
│ │ │ ├── HeroLogoText.vue
│ │ │ ├── HeroLogoTextOptions.vue
│ │ │ └── HeroLogoTextRendered.vue
│ │ ├── Statics
│ │ │ ├── FrontPageEventsList.vue
│ │ │ ├── FrontPageEventsListOptions.vue
│ │ │ ├── FrontPageEventsListRendered.vue
│ │ │ ├── FrontPageMembershipInfo.vue
│ │ │ ├── FrontPageMembershipInfoOptions.vue
│ │ │ ├── FrontPageMembershipInfoRendered.vue
│ │ │ ├── FrontPageMenuHeader.vue
│ │ │ ├── FrontPageMenuHeaderOptions.vue
│ │ │ ├── FrontPageMenuHeaderRendered.vue
│ │ │ ├── FrontPageNewsList.vue
│ │ │ ├── FrontPageNewsListOptions.vue
│ │ │ ├── FrontPageNewsListRendered.vue
│ │ │ ├── FrontPageSponsors.vue
│ │ │ ├── FrontPageSponsorsOptions.vue
│ │ │ ├── FrontPageSponsorsRendered.vue
│ │ │ ├── PageFooter.vue
│ │ │ └── PageFooterRendered.vue
│ │ └── Text
│ │ ├── TwoColumnText.vue
│ │ ├── TwoColumnTextOptions.vue
│ │ └── TwoColumnTextRendered.vue
Component files
All vue files under resources/js/components/Blocks/<block_category>/ are the actual components. Each component will have:
- A vue file for rendering the look of the component on the page builder (<ComponentName>.vue)
- A vue file for rendering the look of the component on the actual page (<ComponentName>Rendered.vue)
- A vue file for rendering the form fields the author of the page uses to fill out and manipulate component block data (for instance, title, text, button text, button type, size, etc. Everything you can think off) that will pop up in the left drawer, when the user clicks the cogwheel button (<ComponentName>Options.vue)
block.js - definition file
block.js (in resources/js/Utils) contains all the component block categories, component blocks, and field definitions for each component block in json format. Some field definitions are hardcoded with the system, and dictates their behaviour, other field definitions you are free to define yourself (as long as they don't conflict with the other built in field definitions). Let's go over one of the components defined in block.js and describe their field definitions:
{
uuid: uuidv4(),
componentName: 'FrontPageNewsList',
optionsComponentName: 'FrontPageNewsListOptions',
renderComponentName: 'FrontPageNewsListRendered',
description: 'Nyhetsartikler',
thumbUrl: '/img/blocks/frontpagenews_oms_preview.jpg',
static: false,
title: 'Nyheter',
showtitle: true,
label: 'Hold deg oppdatert med hva som skjer i ØMS',
anchorName: 'intro',
showlabel: true,
image: '/img/pexels-andrew-neel-2859169.jpg',
buttontext: 'Vis flere nyheter',
needs: ['articles']
}
- uuid required The uuid field is required for all block components, it contains an unique identifier for that block instance when it is dragged to the canvas
- componentName required The componentName field is required for all block components. It tells the pagebuilder what vue file to look for when rendering the block on the page builder canvas, after it is dragged from the block selection.
- optionsComponentName optional (if static is true) The optionsComponentName field is optional for block components that has a static value of true, required if the value is false. It tells the pagebuilder what vue file to look for when rendering the input fields and forms when the user clicks the cogwheel to customize the block
- renderComponentName required The renderComponentName field is required for all block components. It tells the pagebuilder what vue file to look for when rendering the component on a page when it is finished.
- description required The description is the title of the block that appears in the block selector on the pagebuilder
- thumbUrl required The thumbUrl field is the relative path of the visual preview image in the block selector, giving the user a visual preview of the block
- static required The static value tells the pagebuilder if the block component has any option form fields (coghwheel disabled or enabled)
- title optional This is just a data field that holds a string for the title value for the component
- showtitle optional This is another data field that the user can turn off or on using a checkmark in optionsComponentName, that will show or hide the title text
- label optional A string representation that shows a label text (typically right before or after the title)
- showlabel optional another boolean value the user interacts with through a checkmark
- image optional A string file path to the default image. In this case, the image is used as a background image covering the whole component block. It is a good idea to have a default image outside of the main storage that is always accessible.
- buttontext optional A string value that shows a button text value. In this case a link that directs the user to an overview of all the news articles on the site
needs field
This is a somewhat exceptional field that deserves its own section to describe properly. While all the field names so far is encapsulated and operates just within their respective components, the needs field is a special field. It lets the component "hook" into the overall lifecycle of the app to retrieve data. It is an optional field and takes an array of strings. Those strings (in this case, one string 'articles' represents the name(s) of the static function(s) that is going to be called from App/Helpers/PageBlocksHelper. Any data returned from that/those function(s) (typically via Eloquent) is included in the blockData object.
In the case of this object 'articles' function, it fetches the appropriate amount of newsarticles to display in the block. The code specifically for these helper functions have been omitted, since it's part of the larger CMS codebase and it's not needed for the pagebuilder to run on it's own. But you can still use the helper functions to retrieve this data if your component is ported into the CMS and if you want to make another component like it (or other components that retrieve other data).
BlockWrapper
This vue component is responsible for rendering all the component blocks on the pagebuilder canvas and it's options drawer if the user click the associated cogwheel for that component. It's important that you import and include the component in const components for it to be detected and rendered.
Root and Preview
├── pages
│ ├── Backend
│ │ └── PageBuilder
│ │ └── Preview.vue
│ ├── Root.vue
These two vue files renders a preview page accessible directly from within the pagebuilder ui, and the pages themselves. It's also important that you import all the components into these files, and define them in their const components object holding the component definitions, for the system to detect and render the components.