Blog

Introduction

What It Is

A blog script that generates all article previews on Blog pages with a single click.

How it Works

This script finds the site’s sitemap.xml page, locates every page with /article/ in the URL, then goes to each of those pages to grab the content on them. This content is what’s used to generate blog previews.

The current “getting articles” process is not ideal because it has to load the sitemap, and then every single article page. We’re looking into a solution where we can tap directly into the CMS content without having to load potentially hundreds of pages.

Example Sites

Design Reference

If you want to see a base-example of the blog set up, the Dev Sandbox has the blog fully installed.

Using the Blog in Our CMS

This segment of documentation was written for anyone writing, publishing, and loading blog articles.

Since the blog basically writes article preview code for you, you’ll need to place content in specific places so it can find it and use it. The following docs are related to the base blog set up. Your developer may have altered it to meet certain goals, so what’s listed as required or optional here may vary from your actual site. Notes should be provided by the developer to cover these differences.

Step 1: Create Articles

1. In Pages, click “Create A Page”
2. Enter your Page Title (This will be used for the article title) See Fig. 1
3. In Categories, choose “Articles” Important: This has to be done or the blog script will not be able to find the article. Ensure your URL has /articles/ in it See Fig. 1
4. Click “Select a layout” and choose “Article” See Fig. 1
5. Click “Create”
6. Fill out all required boxes. Usually: Published/Archived, Image, Category, Date, and Excerpt. Some set ups may require more or less information than that. Refer to the design or ask the developer. See Fig. 2
7. Click “Save” and “Publish”

Step 2: Creating/Updating the Blog

1. In Pages, click “Create A Page”
2. Enter your Page Title See Fig. 3
3. In Categories, choose “Blog” (This is not required for the blog to function, but it helps with content organization) See Fig. 3
4. Click “Select a layout” and choose “Blog” See Fig. 3
5. Click “Create”
6. Click “Load Articles” to generate all article previews See Fig. 4
7. Click “Save” and “Publish”

Step 3: Maintaining the Blog

1. For all new articles, you’ll follow the “Create Articles” steps.
2. Once the new article is saved/published, follow the “Creating/Updating the Blog” section.

If any article is edited, deleted, archived, etc, the Blog page needs to be updated by clicking “Load Articles” each time.

Setting up the Blog

This documentation was written for devs who will be setting up, editing, or otherwise troubleshooting the blog.

Current build: BS4 without reliance on jQuery. This also works on BS5 builds.

Please note: Once you’ve set this up in your project, you will not be able to fully test it until your site is on UAT and you have articles in place. The Blog script and all related CMS dialogs do not run unless you’re in the UAT environment. Also, it requires the sitemap.xml file to be in place.

Step 1. Add Blog Files Into Your Project

1. SCSS: blog.scss
2. The entire scripts/blog folder
3. Templates:
   • article.mustache
   • blog.mustache
   • partials/related-articles.mustache
4. json/templates.json - You can use these files if you want to. This contains all the content areas for both templates and three placeholder articles. Feel free to use this in your *-make.json or on Postman (for the templates) if your site has already been scaffolded.
5. templates/images - There are two images in there for the layouts. Feel free to use these.

Step 2. Edit the package.json and gulpfile.js

1. Ensure you’re using Terser instead of Uglify to prevent ES6 errors (uglify is outdated, doesn’t like template literals).
   Here’s how to do that if you need to:
   • In package.json, replace the "gulp-uglify": "latest", line with "gulp-terser": "latest",
   • In your gulpfile.js, find this line uglify = require('gulp-uglify'), and replace it with terser = require('gulp-terser'),
   • In your gulpfile.js, find every instance of this line .pipe(uglify()) with .pipe(terser({format: {comments:false}}))
2. In the js task, add the following lines before script.js to ensure Gulp will compile these files: './src/scripts/blog/templates/*.js', './src/scripts/blog/*.js',
3. Add these class prefixes to the PurgeCSS greedy list: /blog/, /article/
4. Run npm install in terminal
5. Run gulp in terminal

Step 3. Add Categories to Your *-make.json

If your site has already been scaffolded, add these via Postman.

• Articles
• Blog

Step 4. Include Blog Styles in Your Main.scss

• blog.scss - All styles for the blog, articles, and CMS-only elements are in this file, including CMS tips. Feel free to move the CMS-only elements into your cms.scss file.

Step 5. Update the Default Variables

Open script/blog-previews-template.js and edit the following:

1. Update featured image and image alt placeholders
2. Change the excerpt length and the how many articles show on preview, if desired
3. Change how many featured articles to show. If 0, the featured articles content area will not be used. You may want to delete this content area on the mustache file.

Step 6. Customize Preview HTML Templates

“Preview HTML” refers to the “cards” (or other designed element) on the Blog page that includes each article’s title, image, excerpt, and link.

All preview HTML can be found and customized in /blog/templates/blog-previews-template.js, including:

• Blog Page Previews - Basic
• Blog Page Previews - Archived
• Blog Page Previews - Featured
• Related Article Previews

As you will see in these preview templates, article properties (like title, image, excerpt) are placed using bracket notation. Ternary operators can be used to conditionally show or hide any content in those templates. There are examples in that file on the Author and the Read Time lines.

Tip Build the previews on the actual blog page, inside the dev environment conditionals with dummy content. Once you’re done, copy your HTML and place it into the blog-previews-template.js file and replace all dummy content with the variables.

Step 7. CMS Dialogs (Optional)

If you need to update anything CMS dialogs, such as words or hiding things, you can find these in the /blog/templates/blog-cms-dialogs.js.

This includes dialogs like:

• CMS Blog Dialog
• CMS Article Dialog
• CMS Related Article Dialog
• Related Articles

Step 8. Add Related Articles (Optional)

This is already set up for the Article page layout.

But, if your design has a section for other pages/templates to show related articles, follow these steps to implement it:

• Add “related-articles” to the <body> class.
• Add the template partial “related-articles.mustace” or its contents to your template
• Add the following content areas to your JSON for each template that has related articles:
  • relatedArticles
  • relatedArticleDetails

Side note: Shared content areas can be used in conjunction with related articles. Only one related articles section per page is supported at this time.

Step 9. Testing!

Push the site up to CMS.

If you used the templates.json content when scaffolding, you should be able to just go to the Blog page in the CMS and click “Load Articles”. If not, you’ll need to add fake articles.

Try loading Related Articles, too!

Customization Options

These areas of the blog all are available for design customization:

• Blog page
  • Featured Articles area
  • Blog previews
  • Archived articles
• Article page

Generally, these are easily edited and could be redesigned to a point. However, if any designer has a question about how much customization is possible for their specific design, it’s best to check with a developer.

The following content that’s available (and their script variables for devs) are shown below:

These are what are automatically included on the Blog Previews but can be removed or edited by a developer:

• Image
• Image alt tag
• Article category
• Article date
• Article author
• Article read time
• Article excerpt
• Article URL

FAQs

Troubleshooting

Articles Don’t Load When Clicking Load Articles Button

1. Ensure you have article pages categorized as Articles (in page settings) and ALSO has a url structure of /articles/ (this may also be “article”—go with whatever is automatically populated in the URL after clicking the category).
   • The blog script cannot find articles that are not categorized this way in the Page Settings (not the article’s categories edited within the content area).
   • See this section for an example.
2. Ensure your article pages have the Article template.
   • See this section for an example.
3. Ensure there are no special characters (& or ‘ ) in your article URL (like if you scaffolded articles).
   • Found this out the hard way.

Articles Load and Can Be Saved, but Invisible on the Front End

• Check the CSS. This could be a problem with the “load more” show/hide thing. The “initial” class may be the cause.

Rebecca ran into this with animations on Academy, so this might be a unique case. She forgot to add the animation classes to the article previews template js. Basically, animations weren’t working, so the previews were not visible and it made it look like the blog wasn’t working (but it was).

Problem: When client clicks the Load Articles button, no articles ever load. But it works for everyone else.

Possible Cause: Network settings on the client’s end.

The Blog script goes to the sitemap.xml and finds every single URL that’s on the site and categorized as /article/, then it loads each and every single one, nearly simultaneously. That’s potentially hundreds of requests all at once, and their firewall or network settings may be preventing this action.

Rebecca ran into this issue with AFBank.com and AcademyBank.com. If there were less than 100 articles, it would load with no issues. This is how we were able to determine it’s the number of requests.

Solution: Limit the amount of requests happening at once. We also are working on a future fix to use the pages API instead of loading each page individually.

Additional Solution: Add error catching to see if the page has connection issues and try it again later (after some delay).

Problem: Script does not seem to work at all.

As in, the dialogs in the CMS side are not showing up, nothing is working.

Cause: This could be a gulpfile issue, where the sript is not getting compiled with everything else.

Solution: Double-check that the blog script files are added in the scripts task. If it is, check your deploy folder and see if the blog scripts are adding in the script.min.js file. If it’s not in there, try removing the done(); callback function.

Found an Issue

• If you’re a CMS user, send a message in the #org-content-dev Slack channel.
• If you’re a dev, please submit an issue on the GitHub repo. If you’ve already figured out the solution, please include that. If you want to go ahead and update the code, please do so in a branch with a Pull Request. Test it by pushing it up to the demo site

Improving the Blog Script

How to update the blog script:
I mean, you know how to edit code on a branch. The main thing is you’ll want to edit it in 2 places:

1. On the blog repo
2. On the devsandbox-blog site

And the reason is: devsandbox-blog is really easy to test on. But, feel free to create your own testing site!

Once you’ve done your magic, be sure to do a Pull Request and ask us to review. :)