71 |
72 |
--------------------------------------------------------------------------------
/views/layout.html:
--------------------------------------------------------------------------------
1 | {% extends data.outerLayout %}
2 |
3 | {% import 'fragments/link.html' as link %}
4 |
5 | {% block title %}
6 | {% set title = data.piece.title or data.page.title %}
7 |
8 | {{ title }}
9 |
10 | {% if not title %}
11 | {{ apos.log('Looks like you forgot to override the title block in a template that does not have access to an Apostrophe page or piece.') }}
12 | {% endif %}
13 | {% endblock %}
14 |
15 | {% block beforeMain %}
16 |
17 |
18 |
19 | {% set logo = apos.image.first(data.global.logo) %}
20 |
21 | {% if logo %}
22 |
23 | {% else %}
24 |
25 | {% endif %}
26 |
27 |
46 |
47 |
48 |
49 | {% endblock %}
50 |
51 | {% block main %}
52 | {#
53 | Usually, your page templates in the @apostrophecms/pages module will override
54 | this block. It is safe to assume this is where your page-specific content
55 | should go.
56 | #}
57 | {% endblock %}
58 |
59 | {% block afterMain %}
60 |
61 |
70 |
71 | {% endblock %}
72 |
--------------------------------------------------------------------------------
/lib/schema/link.js:
--------------------------------------------------------------------------------
1 | /**
2 | * A shared schema field configuration for Links.
3 | * You can use as is in a schema definition or destructure
4 | *destructured to only use the fields you need
5 | */
6 |
7 | export default {
8 | linkText: {
9 | label: 'Link Text',
10 | type: 'string',
11 | required: true
12 | },
13 | linkType: {
14 | label: 'Link Type',
15 | type: 'select',
16 | required: true,
17 | choices: [
18 | {
19 | label: 'Page',
20 | value: 'page'
21 | },
22 | {
23 | label: 'File',
24 | value: 'file'
25 | },
26 | {
27 | label: 'Custom URL',
28 | value: 'custom'
29 | }
30 | ]
31 | },
32 | _linkPage: {
33 | label: 'Page to link',
34 | type: 'relationship',
35 | withType: '@apostrophecms/page',
36 | max: 1,
37 | builders: {
38 | project: {
39 | title: 1,
40 | _url: 1
41 | }
42 | },
43 | if: {
44 | linkType: 'page'
45 | },
46 | required: true
47 | },
48 | _linkFile: {
49 | label: 'File to link',
50 | type: 'relationship',
51 | withType: '@apostrophecms/file',
52 | max: 1,
53 | if: {
54 | linkType: 'file'
55 | },
56 | required: true
57 | },
58 | linkUrl: {
59 | label: 'URL for custom link',
60 | type: 'url',
61 | if: {
62 | linkType: 'custom'
63 | },
64 | required: true
65 | },
66 | linkTarget: {
67 | label: 'Will the link open a new browser tab?',
68 | type: 'checkboxes',
69 | choices: [
70 | {
71 | label: 'Open in new tab',
72 | value: '_blank'
73 | }
74 | ]
75 | },
76 | linkStyle: {
77 | label: 'Link Style',
78 | type: 'select',
79 | choices: [
80 | {
81 | label: 'Button',
82 | value: 'button'
83 | },
84 | {
85 | label: 'Inline',
86 | value: 'inline'
87 | }
88 | ],
89 | def: 'button'
90 | },
91 | linkVariant: {
92 | label: 'Link Color',
93 | type: 'select',
94 | choices: [
95 | {
96 | label: 'Primary Color',
97 | value: 'primary'
98 | },
99 | {
100 | label: 'Secondary Color',
101 | value: 'secondary'
102 | },
103 | {
104 | label: 'Accent Color',
105 | value: 'accent'
106 | }
107 | ],
108 | def: 'primary'
109 | }
110 | };
111 |
--------------------------------------------------------------------------------
/modules/widgets/hero-widget/index.js:
--------------------------------------------------------------------------------
1 | import link from '../../../lib/schema/link.js';
2 |
3 | export default {
4 | extend: '@apostrophecms/widget-type',
5 | options: {
6 | label: 'Hero',
7 | icon: 'sign-text-icon'
8 | },
9 | fields: {
10 | add: {
11 | content: {
12 | type: 'area',
13 | label: 'Content',
14 | options: {
15 | widgets: {
16 | '@apostrophecms/rich-text': {}
17 | },
18 | max: 1
19 | }
20 | },
21 | actions: {
22 | type: 'array',
23 | label: 'Actions',
24 | titleField: 'linkText',
25 | fields: {
26 | add: link
27 | }
28 | },
29 | media: {
30 | type: 'select',
31 | label: 'Media',
32 | help: 'Use an image or video for the Hero\'s background',
33 | choices: [
34 | {
35 | label: 'Image',
36 | value: 'image',
37 | def: true
38 | },
39 | {
40 | label: 'Video',
41 | value: 'video'
42 | }
43 | ]
44 | },
45 | _image: {
46 | type: 'relationship',
47 | label: 'Hero Image',
48 | withType: '@apostrophecms/image',
49 | if: {
50 | media: 'image'
51 | }
52 | },
53 | videoUrl: {
54 | type: 'url',
55 | label: 'External Video URL',
56 | help: 'A URL to an externally hosted .mp4',
57 | if: {
58 | media: 'video'
59 | }
60 | },
61 | _videoPoster: {
62 | type: 'relationship',
63 | label: 'Video Poster',
64 | help: 'This image will appear as the video is loading',
65 | withType: '@apostrophecms/image',
66 | if: {
67 | background: 'video'
68 | }
69 | },
70 | size: {
71 | type: 'select',
72 | label: 'Size',
73 | choices: [
74 | {
75 | label: 'Small',
76 | value: 'small'
77 | },
78 | {
79 | label: 'Medium',
80 | value: 'medium',
81 | def: true
82 | },
83 | {
84 | label: 'Large',
85 | value: 'large'
86 | }
87 | ]
88 | },
89 | backgroundColor: {
90 | type: 'color',
91 | label: 'Background Color',
92 | help: 'This option can also be used to set a screen over an image or video by setting the color\'s opacity to a decimal',
93 | options: {
94 | format: 'rgb'
95 | }
96 | }
97 | }
98 | }
99 | };
100 |
--------------------------------------------------------------------------------
/modules/widgets/column-widget/index.js:
--------------------------------------------------------------------------------
1 | /**
2 | * Widget configuration that is shared for all columns
3 | */
4 | const widgets = {
5 | '@apostrophecms/rich-text': {},
6 | '@apostrophecms/image': { className: 'image-widget' },
7 | '@apostrophecms/video': {},
8 | link: {},
9 | card: {},
10 | accordion: {}
11 | };
12 |
13 | export default {
14 | extend: '@apostrophecms/widget-type',
15 | options: {
16 | label: 'Columns',
17 | alias: 'columnsWidget',
18 | icon: 'view-column-icon'
19 | },
20 | fields: {
21 | add: {
22 | layout: {
23 | type: 'select',
24 | label: 'Column Layout',
25 | required: true,
26 | choices: [
27 | {
28 | label: '1 column, 100%',
29 | value: '100'
30 | },
31 | {
32 | label: '2 columns, 50%',
33 | value: '50'
34 | },
35 | {
36 | label: '2 columns, 66% / 33%',
37 | value: '66-33'
38 | },
39 | {
40 | label: '2 columns, 75% / 25%',
41 | value: '75-25'
42 | },
43 | {
44 | label: '2 columns, 33% / 66%',
45 | value: '33-66'
46 | },
47 | {
48 | label: '2 columns, 25% / 75%',
49 | value: '25-75'
50 | },
51 | {
52 | label: '3 columns, 33.3%',
53 | value: '33'
54 | },
55 | {
56 | label: '4 columns, 25%',
57 | value: '25'
58 | }
59 | ],
60 | def: '100'
61 | },
62 | column1: {
63 | label: 'Column One',
64 | type: 'area',
65 | contextual: true,
66 | options: {
67 | widgets: {
68 | ...widgets,
69 | slideshow: {
70 | swiper: {
71 | /**
72 | * Override the default Swiper configuration by setting any of the
73 | * available Swiper parameters here. Pagination and Navigation are
74 | * enabled by default.
75 | * https://swiperjs.com/swiper-api#parameters
76 | */
77 | allowTouchMove: false
78 | }
79 | }
80 | }
81 | },
82 | if: {
83 | $or: [
84 | { layout: '100' },
85 | { layout: '50' },
86 | { layout: '25-75' },
87 | { layout: '33-66' },
88 | { layout: '75-25' },
89 | { layout: '66-33' },
90 | { layout: '33' },
91 | { layout: '25' }
92 | ]
93 | }
94 | },
95 | column2: {
96 | label: 'Column Two',
97 | type: 'area',
98 | contextual: true,
99 | options: { widgets },
100 | if: {
101 | $or: [
102 | { layout: '50' },
103 | { layout: '25-75' },
104 | { layout: '33-66' },
105 | { layout: '75-25' },
106 | { layout: '66-33' },
107 | { layout: '33' },
108 | { layout: '25' }
109 | ]
110 | }
111 | },
112 | column3: {
113 | label: 'Column Three',
114 | type: 'area',
115 | contextual: true,
116 | options: { widgets },
117 | if: {
118 | $or: [
119 | { layout: '33' },
120 | { layout: '25' }
121 | ]
122 | }
123 | },
124 | column4: {
125 | label: 'Column Four',
126 | type: 'area',
127 | contextual: true,
128 | options: { widgets },
129 | if: {
130 | $or: [
131 | { layout: '25' }
132 | ]
133 | }
134 | },
135 | backgroundColor: {
136 | type: 'color',
137 | label: 'Background Color'
138 | }
139 | }
140 | },
141 | helpers(self) {
142 | return {
143 | /**
144 | * A helper to get the number of columns the editor has selected
145 | * Used in the template to generate the columns and areas
146 | */
147 | getColumns(layout) {
148 |
149 | const columns = {
150 | 1: [ '100' ],
151 | 2: [ '50', '66-33', '75-25', '33-66', '25-75' ],
152 | 3: [ '33' ],
153 | 4: [ '25' ]
154 | };
155 |
156 | let number = 1;
157 | for (const key in columns) {
158 | if (columns[key].includes(layout)) {
159 | number = key;
160 | }
161 | }
162 | return parseInt(number);
163 | }
164 | };
165 | }
166 | };
167 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | # Apostrophe Starter Kit Pro Essentials
2 |
3 | >**Important Notice:**
4 | >
5 | >The code in this starter kit is freely available for use in your projects. However, to use it as a starter kit for a new project, you will need a Pro subscription to install certain dependencies.
6 | >
7 | >To obtain a license, please visit our [website](https://apostrophecms.com/pro) to learn more. You can contact our support team for assistance or purchase a license directly through your [Apostrophe Workspace](https://app.apostrophecms.com/login).
8 | >
9 | >As an alternative to this starter template, we offer several open-source starter kits that are available without any licensing restrictions. These kits, along with links to their GitHub repositories, are listed on our [website](https://apostrophecms.com/starter-kits).
10 |
11 |
13 | - [Apostrophe Starter Kit Pro Essentials](#apostrophe-starter-kit-pro-essentials)
14 | - [Purpose](#purpose)
15 | - [Before you begin](#before-you-begin)
16 | - [First Steps: required before startup](#first-steps-required-before-startup)
17 | - [Setting your shortName](#setting-your-shortname)
18 | - [Disabled File Key](#disabled-file-key)
19 | - [Session Secret](#session-secret)
20 | - [Requirements For Development On Your Computer](#requirements-for-development-on-your-computer)
21 | - [Operating System: Mac, Linux, or Virtual Linux](#operating-system-mac-linux-or-virtual-linux)
22 | - [Software Installation Requirements](#software-installation-requirements)
23 | - [Starting Up In Development](#starting-up-in-development)
24 | - [Site Development](#site-development)
25 | - [The `theme-default` module](#the-theme-default-module)
26 | - [Modern Frontend Assets Without A Custom Build Process](#modern-frontend-assets-without-a-custom-build-process)
27 | - [Frontend Assets With Your Own Build Process](#frontend-assets-with-your-own-build-process)
28 | - [Serving Static Files: Fonts and Static Images](#serving-static-files-fonts-and-static-images)
29 | - [Palette Configuration](#palette-configuration)
30 | - [Hosting and Deployment](#hosting-and-deployment)
31 | - [If we are your host](#if-we-are-your-host)
32 | - [Self-hosting](#self-hosting)
33 | - [Provided widgets](#provided-widgets)
34 | - [`accordion-widget`](#accordion-widget)
35 | - [`card-widget`](#card-widget)
36 | - [`column-widget`](#column-widget)
37 | - [`hero-widget`](#hero-widget)
38 | - [`link-widget`](#link-widget)
39 | - [`slideshow-widget`](#slideshow-widget)
40 |
41 | ## Purpose
42 |
43 | The purpose of this repository and this document is to serve as a quick start for single-site Apostrophe Pro projects.
44 |
45 | As such, it includes several pre-configured Pro modules, although it does not include all, as developer needs vary. Users with a Pro license will have access to additionally `npm install` and configure [any of the Pro modules listed on our website](https://apostrophecms.com/extensions?license=pro).
46 |
47 | It also serves as example code for creating your own custom modules and organizing your files in any ApostropheCMS project. The [section describing the widgets](#provided-widgets) outlines some code practices and features that can be used in your own custom modules.
48 |
49 | This Starter Kit includes:
50 | * Basic Apostrophe Widgets, including an Accordion, Card, Column, Hero, Link, and Slideshow Widget located in `modules/widgets`.
51 | * Basic examples of theme specific front-end code.
52 |
53 | If you have a Pro subscription it will also include:
54 | * Integration of the `@apostrophecms-pro/document-versions` module.
55 | * Example configuration for the `@apostrophecms-pro/palette` module.
56 |
57 | The Pro Essential Starter Kit is intended as a foundation for your projects and should be forked and customized to meet your needs. Once forked, your project can diverge significantly, so we do not recommend merging updates from the starter kit directly. Instead, periodically review the kit repository for ideas and improvements while managing core functionality updates through the usual `npm update` process.
58 |
59 | ## Before you begin
60 |
61 | This document assumes familiarity with Apostrophe concepts. If you are not already familiar with
62 | single-site Apostrophe development, you should pause here and familiarize yourself with the
63 | [ApostropheCMS documentation](https://docs.apostrophecms.org/) as a starting point.
64 |
65 | ## First Steps: required before startup
66 |
67 | > **📌 Note on Dependency Management**
68 | >
69 | > This starter kit ships with `package-lock.json` in `.gitignore` to avoid merge conflicts during development.
70 | >
71 | > **For production use:** Remove `package-lock.json` from `.gitignore` and commit it to lock your dependencies. This ensures stable, reproducible builds. When you're ready to update dependencies, run `npm update` and commit the updated lock file.
72 |
73 | ### Setting your shortName
74 |
75 | **Don't leave this setting in `app.js`, or anything else, set to `CHANGEME`.** The `shortName` should usually be the same
76 | as your repository name, which should usually be the same as the name of your project folder. It will also be the name of
77 | your MongoDB database by default in local development. Do not use punctuation other than hyphens. Good examples include
78 | `smithco-marketing`, to distinguish from other sites built for that company, or just `smithco`.
79 |
80 | This name should be unique among your projects.
81 |
82 | ### Disabled File Key
83 |
84 | In `app.js`, locate `disabledFileKey` and change `CHANGEME` to a random string of your choosing. This is used when disabling access to files in the local backend. Do not leave it set to `CHANGEME`.
85 |
86 | ### Session Secret
87 |
88 | In `app.js`, locate `secret` and change `CHANGEME` to a random string of your choosing. This is used for login session encryption. Do not
89 | leave it set to `CHANGEME`.
90 |
91 | ## Requirements For Development On Your Computer
92 |
93 | ### Operating System: Mac, Linux, or Virtual Linux
94 |
95 | **Your local development environment must be either MacOS or Linux.** If your development computer runs Windows, we recommend development on
96 | Windows Subsystem for Linux (WSL). Microsoft recommends WSL for Node.js development.
97 |
98 | ### Software Installation Requirements
99 |
100 | To test-drive the project in development, make sure you have Apostrophe's usual dependencies on your local machine:
101 |
102 | * MongoDB (5.x or better, we recommend 6.x or better)
103 | * NodeJS (18.x or better)
104 |
105 | For more information see the Apostrophe [Getting Started Tutorial](https://docs.apostrophecms.org/getting-started/setting-up-your-environment.html).
106 |
107 | ## Starting Up In Development
108 |
109 | First, `git clone` the Starter Kit and push it up to your own git repository under an appropriate name,
110 | matching your choice of `shortName`, for ongoing work.
111 |
112 | Then type:
113 |
114 | ``` sh
115 | npm install
116 | ```
117 |
118 | After installation, add an admin user:
119 |
120 | ``` sh
121 | node app @apostrophecms/user:add admin admin
122 | ```
123 |
124 | Enter a password when prompted.
125 |
126 | Next launch the application:
127 |
128 | ``` sh
129 | npm run dev
130 | ```
131 |
132 | When ready, visit:
133 |
134 | ``` sh
135 | http://localhost:3000/login
136 | ```
137 |
138 | And log in with the admin account you created for the site. Then make some simple edits to the homepage.
139 |
140 | ## Site Development
141 |
142 | Right now we have basic example templates in place. Let's look at where to put our code to customize the experience.
143 |
144 | > Again, if you are not already familiar with single-site Apostrophe development, you should pause here and
145 | [review the ApostropheCMS documentation](https://docs.apostrophecms.org/) as a starting point.
146 |
147 | Just like in any single-site Apostrophe project, modules are configured in `app.js`, and module code lives
148 | in subdirectories of `modules/`.
149 |
150 | Feel free to add page templates and modules as you would with an ordinary open-source Apostrophe project. You can `npm install` modules
151 | like `@apostrophecms/blog` and configure them in a normal way. With a Pro license you can also install additional Pro modules like
152 | `@apostrophecms-pro/advanced-permission` if they are necessary to your plans.
153 |
154 | ### The `theme-default` module
155 |
156 | Apostrophe allows frontend assets to be placed in any module, but as a suggested
157 | code organization, this project contains a `theme-default` module with a sample
158 | `ui/src/index.js` and `ui/src/index.scss` as described further below. This approach
159 | simplifies later migration to an Assembly multisite project especially if you anticipate
160 | implementing a choice of themes at that time.
161 |
162 | The `theme-default` module also modifies the base webpack build to incorporate SCSS variables for colors and fonts. This is included to demonstrate how to set up centralized theme management with global variables in one place. It also adds a function for converting font sizes from `px` to `rem`. While this is a useful function that is used in several of the `theme-default` stylesheets, it primarily serves to illustrate how SCSS functions can be added to your project. A similar approach would be used to add in any SCSS mixins that subsequent stylesheets utilize.
163 |
164 | The `views` folder of the `theme-default` module has two markup files that provide the HTML for the `@apostrophecms/home-page`. The main `welcome.html` file contains a conditional block for displaying different content based on whether there is a user is logged in or not. It has a second conditional block for displaying markup from the `placeholder.html` file if no content has been added to the page. You can choose to maintain this structure and modify the `welcome.html` file, or change the `modules/@apostrophecms/home-page/views/page.html` to contain your own markup.
165 |
166 | #### Modern Frontend Assets Without A Custom Build Process
167 |
168 | There is no need for a custom Webpack configuration in most cases. Specifically, you can follow our documentation and place your modern
169 | JavaScript code in the `ui/src/index.js` file of any module, or use `import` statements in that file to import it there. As noted in
170 | our documentation, it is **important for `ui/src/index.js` to export a function as its default export.** This function will be invoked
171 | to initialize your module at a safe time when `apos.http`, `apos.util`, etc. are already available.
172 |
173 | You may also place Sass SCSS code in the `ui/src/index.scss` file of any module, and use `import` statements in that file to bring in
174 | more Sass SCSS code.
175 |
176 | #### Frontend Assets With Your Own Build Process
177 |
178 | A sample webpack build is not included as standard equipment, as `ui/src` suffices for most needs, and the built-in, automatic Webpack configuration
179 | can be extended, per our public documentation and as illustrated. However, if you prefer to create your own webpack configuration, the typical pattern
180 | is to configure the output of your build process to be a `ui/public/something.js` file in any module in your Apostrophe project.
181 |
182 | #### Serving Static Files: Fonts and Static Images
183 |
184 | If you need to serve static files, you can do this much as you would in standalone Apostrophe development.
185 |
186 | The folder `public` maps to `/` in the URL space of a site. For instance, `public/fonts/myfile.ttf` maps to the URL `/fonts/myfile.ttf`.
187 | For assets like favicons and fonts, you can add `link` tags to the `standardHead` block already present in
188 | `modules/@apostrophecms/template/views/outerLayout.html`.
189 |
190 | ### Palette Configuration
191 |
192 | The `@apostrophecms-pro/palette` module requires Pro licensing and allows styles to be edited visually on the site. It is configured in `modules/@apostrophecms-pro/palette/index.js`.
193 | There you can specify the selectors, CSS properties, and field types to be used to manipulate color, font size, font family
194 | and other aspects of the site as a whole.
195 |
196 | For complete information and a sample configuration, see the [@apostrophecms-pro/palette module documentation](https://apostrophecms.com/extensions/palette-extension).
197 |
198 | > Note that like all other changes, palette changes do not take place for logged-out users until the editor clicks "Publish."
199 |
200 | ## Hosting and Deployment
201 |
202 | ### If we are your host
203 |
204 | If we are hosting Apostrophe for you, then you can deploy updates to your staging and production environments by pushing to your
205 | `staging` and `production` git branches, respectively. You will receive notifications in our shared Slack channel, including links to
206 | access the deployment progress logs.
207 |
208 | Apostrophe will complete the build steps listed in the `build` npm command provided in `package.json` and also execute any
209 | database migrations before restarting with your newest code.
210 |
211 | ### Self-hosting
212 |
213 | Self-hosting is also an option if you have not chosen to host with us. We offer several how-to guides on this, such as
214 | [Ubuntu hosting setup](https://v3.docs.apostrophecms.org/cookbook/ubuntu-hosting.html) and
215 | [deploying Apostrophe in the cloud with Heroku](https://v3.docs.apostrophecms.org/cookbook/deploying-to-heroku.html). The main new element
216 | with Apostrophe Pro is making sure that the `npm install` command has access to the `@apostrophecms-pro` modules during installation.
217 |
218 | Here is the simplest recipe to achieve that:
219 |
220 | 1. Make sure you have been granted access to install our pro modules (that is, make sure `npm install` works for you in this project). If
221 | not, reach out to our support team.
222 | 2. [Log into the npm website](https://www.npmjs.com/) using the account that has been granted access.
223 | 3. Pull down the personal menu and select "Access Tokens."
224 | 4. Select "Classic Token" from the "Generate Tokens" dropdown.
225 | 5. Give the token a name, such as "ops-deployment".
226 | 6. Select "Read-Only."
227 | 7. **Immediately** copy and paste the token that is displayed. It will not be shown again.
228 | 8. Create a `.npmrc` file in the root of your project, like this:
229 |
230 | ```
231 | //registry.npmjs.org/:_authToken=YOUR-TOKEN-HERE
232 | ```
233 |
234 | It is also possible to use an environment variable for additional security, depending on your preferred deployment and hosting
235 | solution. Please see the npm documentation for more information on that option.
236 |
237 | ## Provided widgets
238 | There are six basic widget modules located in the `modules/widgets` folder of this starter kit. This supplements the core `rich-text`, `image`, `video`, and `html` widgets. They can be altered to fit the design and functionality of your project or act as a blueprint to build your own custom widgets. Both the `hero` and `column` widgets have been added to the `main` area of the `@apostrophecms/home-page`. The remainder of the basic widgets have been added to the areas of the `column` widget as described below.
239 |
240 | If you look at the `app.js` file you won't see these widget modules in the `modules` object. Instead, they are being registered using the `nestedModuleSubdirs` property. Setting this property to `true` will cause Apostrophe to register all the modules listed in the `modules.js` file of any subfolder in the project-level `modules` folder. You can choose to organize any custom modules, such as grouping all of your piece-types, to keep your `modules` folder and the `app.js` file less cluttered. Note that if you choose to move any of the provided widgets out of the current folder you will need to add them to the `app.js` and remove them from the `modules/widgets/modules.js` file. If you choose to keep this structure, any custom widgets you add to the folder need to be listed in the `modules.js` file.
241 |
242 | All the styling for the supplied widgets, except for the partials added in the custom webpack extensions added in the `theme-default` module, is located in the `ui/src/index.scss` file of each module. You can choose to maintain this structure, move the styling to the `theme-default/ui/src/scss` folder, or organize them in a different project-specific manner. Note that for them to be included in the standard webpack build, they need to be imported into a `/ui/src/index.scss` file.
243 |
244 | ### `accordion-widget`
245 | The `accordion-widget` implements an accordion element powered by the [`accordion-js` npm package](https://www.npmjs.com/package/accordion-js). You can read about additional configuration options in the documentation of that package. The module consists of a main `index.js` file with the content schema fields, plus a `views` folder that contains a `widget.html` file with the Nunjucks markup for the accordion.
246 |
247 | Finally, there is the `ui/src` folder that contains the `index.scss` stylesheet and the `index.js` file that contains the JavaScript that is delivered to the frontend and powers the accordion using a [widget player](https://docs.apostrophecms.org/guide/custom-widgets.html#client-side-javascript-for-widgets). Any custom widgets that require client-side code should be structured in this same way. Data is passed from the schema fields to the browser for use in the player script by adding it to a data attributes in the template.
248 |
249 | ### `card-widget`
250 | The `card-widget` creates a simple card with optional image and text. The card can be made directly clickable, or can have links and buttons added. The schema fields for these elements are provided by the `lib/schema/link.js` file, which serves as a model for implementing reusable parts of widgets. These same schema fields are reused in the `hero` and `link` widgets and can be used in your custom project widgets. The markup for the links is imported into the `card-widget` template from the `views/fragments/link.html` file using the [`rendercall` helper](https://docs.apostrophecms.org/guide/fragments.html#inserting-markup-with-rendercall). This is present in a simpler form in the `links-widget`. Again, all your custom modules (not just widgets) can utilize fragments to replicate similar areas of markup in this same way.
251 |
252 | ### `column-widget`
253 | The `column-widget` implements one method of adding a user-selected number of columns to a page. It uses a select field and conditional fields that restrict the number of columns based on the value of the select. Each column has an area with widgets for the `link`, `card`, and `accordion` basic widgets, plus the core `rich-text`, `image`, and `video` widgets. These are added through a shared configuration object that defines the available widgets for each column. The first column additionally adds the basic `slideshow` widget.
254 |
255 | The widget also provides a `helper(self)` customization function that is used in the Nunjucks template. Depending on the value of the select field it returns the correct number of columns. The `helper(self)` functions can be used in your custom modules to provide computed values from data passed back from the markup.
256 |
257 | ### `hero-widget`
258 | The `hero-widget` implements a hero element with image or color background, text and links. As stated above, this module reuses the `links.js` helper file. It also demonstrates how to use `relationship` schema fields to add an image or video for the background.
259 |
260 | ### `link-widget`
261 | This simple widget adds either a button or inline-link. As described for the `card-widget`, It utilizes the `lib/schema/link.js` helper file and the `views/fragments/link.html` fragment. Within the widget template there is a `rendercall` that passes data from the widget schema fields to the fragment.
262 |
263 | ### `slideshow-widget`
264 | The `slideshow-widget`, much like the `accordion-widget`, utilizes client-side JavaScript. For this widget the `ui/src/index.js` is adding the [`swiper.js` package](https://swiperjs.com/) to the player.
265 |
--------------------------------------------------------------------------------
12 | 
25 | {% endif %}
26 |
27 |
46 |