diff --git a/docs/components/ALThemeTemplate/althemetemplate_overview.md b/docs/components/ALThemeTemplate/althemetemplate_overview.md index 03abb16ea..34b310964 100644 --- a/docs/components/ALThemeTemplate/althemetemplate_overview.md +++ b/docs/components/ALThemeTemplate/althemetemplate_overview.md @@ -1,8 +1,8 @@ --- id: althemetemplate_overview title: | - ALThemeTemplate: Applying a Custom Theme or Brand -sidebar_label: ALThemeTemplate + Customizing look and feel +sidebar_label: Customizing look and feel slug: overview --- @@ -11,6 +11,9 @@ slug: overview The [ALThemeTemplate](https://github.com/SuffolkLITLab/docassemble-ALThemeTemplate) repository is a template for a "brand" package that you can use for your own organization. +You can use this as the starting point for your own customizations, or decide which of the customizations +below you want to implement for your organization. + ## Visual customization You can customize Docassemble, and Assembly Line interviews, with a Bootstrap 5 theme. @@ -18,20 +21,57 @@ You can customize Docassemble, and Assembly Line interviews, with a Bootstrap 5 ### Customizing the logo and title for Assembly Line interviews You should also customize the: + * [Title](../AssemblyLine/magic_variables.md#al_organization_title) * [Home page](../AssemblyLine/magic_variables.md#al_organization_homepage) * and [logo](../AssemblyLine/magic_variables.md#al_logo) -### Creating a custom CSS theme with Bootstrap.build +### Creating a custom theme If you want to build a custom theme, encompassing colors, fonts, button styles and other -options that are configurable with css, you can: +options that are configurable with css, you can create a custom Bootstrap theme. + +To use a custom theme with Docassemble, you: + +1. Create a .scss file with your customized variables. + +* If you only want to customize colors, use [Huemint](https://huemint.com/bootstrap-basic/). +* For more complex customization, including fonts and button shape, use [bootstrap.build](https://bootstrap.build/). + +2. Compile the theme using a tool like the ALDashboard. + +#### Use Huemint to make a .scss file that customizes colors only + +Visit [Huemint](https://huemint.com/bootstrap-basic/). Create a color pallette that you like. + +Scroll to the bottom of the page and copy the SCSS code that looks like this: + +```scss +$white: #ffffff; + +$theme-colors: ( + "light": #cfd6d1, + "dark": #090807, + "primary": #760076, + "secondary": #f92e42, + "info": #9e8412, + "success": #00a167, + "warning": #d9cd00, + "danger": #e63300, +); +``` + +#### Or use Bootstrap.build to customize fonts, buttons, and more + +To customize other elements of the theme, including fonts and button shapes, +you need a more full-featured build tool. [bootstrap.build](https://bootstrap.build/) can customize +every Bootstrap option. -1. build one from Bootstrap 5 source -1. start with a theme generator tool like [bootstrap.build](https://bootstrap.build/) - and in some cases, add some custom CSS to make it work with Docassemble. +:::warning Bootstrap.build cannot compile a working theme for you -Using bootstrap.build is the simplest option for most authors. +It is important that you only use Bootstrap.build to make a _SCSS_ file. Do not download +a bootstrap.css file from this site. +::: 1. Visit the [bootstrap.build](https://bootstrap.build/) website. 1. Click the button to open the Builder @@ -42,94 +82,50 @@ Using bootstrap.build is the simplest option for most authors. * Under Typography, customize any fonts that you wish to use * Under forms, you may want to customize button size and rounded edges 1. Click the "export theme" button (it may be hidden behind a banner at the top of the page) and choose the - "bootstrap.min.css" option. Rename this theme to be more specific. Optionally, download the `_variables.scss` file - so that you can easily load and adjust your settings in future. + "`_variables.scss`" option. -Next, you will need to make a small adjustment to the theme generated by bootstrap.build. -Copy and paste the code below into the `bootstrap.min.css` file (or your new file name). +#### Compile your theme using the ALDashboard tool -```css -.visually-hidden { - clip: rect(0 0 0 0); - clip-path: inset(50%); - height: 1px; - overflow: hidden; - position: absolute; - white-space: nowrap; - width: 1px; -} - -.bg-dark { - background-color: #1a73e8!important; /* replace with your desired nav bar color */ -} -``` - -Add this theme to your Docassemble playground using the Folders | Static menu. +Inside the AssemblyLine's [ALDashboard](https://github.com/SuffolkLITLab/docassemble-ALDashboard) tool, +visit the Compile Bootstrap Theme widget. -You can then reference your new file by adding a bootstrap theme feature to your interview: - -```yaml -features: - bootstrap theme: bootstrap.min.css -``` +The link should be /start/ALDashboard/compile_bootstrap on your server. If you are associated with the Suffolk LIT Lab and have an account on +the Suffolk Development server, you can visit a [live version of the tool](https://apps-dev.suffolklitlab.org/start/ALDashboard/compile_bootstrap) +to try it out. -### Creating a custom theme from source instead of with a theme generator +Click continue to acknowledge the minimum system version of your Docassemble server. -While the above instructions to use bootstrap.build can work well in most -circumstances, you may run into small interface bugs introduced by the theme -generator. If you prefer more control over building the theme, you can create -a custom theme from the bootstrap source code. The Bootstrap documentation -[covers the details of theming](https://getbootstrap.com/docs/5.1/customize/overview) -if you want to take this approach. +Either copy and paste the snippet you copied from Huemint.com, or open the `_variables.scss` file you exported +from Bootstrap.build and copy and paste its contents. The `_variables.scss` file is a simple text file +that can be opened in any editor. -Create a new `custom.scss` file anywhere on your computer to contain the SASS/CSS styles for your branding. -Detailed instructions on what this file can contain are in the [Bootstrap -documentation](https://getbootstrap.com/docs/5.1/customize/sass/#importing). +**Add the `@import "bootstrap";` line to the end of the Dashboard text entry field.** This is required +for your theme to compile. -You can use a [color theme generator](https://huemint.com/bootstrap-basic/) like -[Huemint.com](https://huemint.com/bootstrap-basic/) to make sure that you have a -consistent set of all 9 Bootstrap variables. When you use the color theme -generator, at the bottom of the page, you will see a small snippet of code that -you can copy into the `customs.scss` file. +If you changed the `$primary` color (from the default blue), it usually also makes sense to directly set the +value of `$blue` to the same value you chose for `$primary`. (Docassemble uses `$blue` for the section navigation, +and it usually looks better if it is the same color as the next/continue button). -For example, your new `custom.scss` might look like this: +Here is an example of working contents for a custom theme in the Dashboard window: ```scss -// Custom.scss -// Option A: Include all of Bootstrap - -// Include any default variable overrides here (though functions won't be available) - $white: #ffffff; +$blue: #760076; $theme-colors: ( - "light": #d8e2a5, - "dark": #1b1b1b, - "primary": #25dec6, - "secondary": #375b5a, - "info": #d74d72, - "success": #0cb545, - "warning": #f4ca0b, - "danger": #fa043c, + "light": #cfd6d1, + "dark": #090807, + "primary": #760076, + "secondary": #f92e42, + "info": #9e8412, + "success": #00a167, + "warning": #d9cd00, + "danger": #e63300, ); - -// Note: we placed our custom.scss file in the bootstrap path for simplicity, -// so we use a different path than in the bootstrap documentation -// @import "../node_modules/bootstrap/scss/bootstrap"; @import "bootstrap"; - -// Then add additional custom code here ``` -Once you have written your `custom.scss` file, you can use the -[ALDashboard](https://github.com/SuffolkLITLab/docassemble-ALDashboard) (which you can [install on -your docassemble server](../../get_started/installation.md#install-aldashboard)) -to compile a custom Bootstrap theme. If you are associated with the Suffolk LIT Lab and have an account on -the Suffolk Development server, you can visit a [live version of the tool](https://apps-dev.suffolklitlab.org/start/ALDashboard/compile_bootstrap) -to try it out. - -At the end of the tool, you can view what all of the different bootstrap components will look like with your theme. -If you want to change any of the colors, you can go back and edit your "custom.scss" file and regenerate the bootstrap theme. +The ALDashboard widget will let you see a preview of your theme so you can see what it will look like in Docassemble. ![A screenshot that says "Your file is compiled! You can view and copy your file, or download it directly by right clicking the link to save it as a CSS file". Below are examples of Bootstrap components like buttons and nav bars.](../../assets/dashboard-bootstrap-example.png) @@ -211,7 +207,6 @@ features: The favicon will be updated whenever a new page loads in your interview, overriding the server's default favicon for that specific interview only. - ### Using dark mode Docassemble by default will show an alternate "dark mode" version of your interview to @@ -219,7 +214,6 @@ users who request it, usually with a browser or OS setting. You can set your bro or OS to use dark mode by following [these instructions](https://support.google.com/chrome/answer/9275525?hl=en&co=GENIE.Platform%3DDesktop#zippy=) to see what your interview looks like. - ### Using custom fonts in the frontend You can use custom webfonts with Docassemble, just like you can with any other web @@ -267,7 +261,6 @@ Make sure that you have a license for each font you want to install. The first step is to locate the .otf or .ttf file representing the font that you want to use inside your Word template (note that these are often in c:\windows\fonts\) - #### Use the ALDashboard to install the font The [ALDashboard](https://github.com/suffolklitlab/docassemble-ALDashboard) tool has a