Overview

Factor blog makes it easy to add a blog to your app.

Add images, tags, and manage your content dynamically through the Factor dashboard without having to rebuild your app. It can be easily customized via factor-settings.

Installation

Just add to your application dependencies:

npm add  @factor/plugin-blog

Once you've installed it in your project, next time you run Factor it will be automatically loaded. The loading will handle endpoints and data, all you need to do now is add some routes, import components and customize.

Adding Routes

Auto Routes

By default this plugin adds routes for you (which can be customized). However, in many cases this is not desireable since it can be harder to customize. You can disable this by adding blog.disableAutoRoutes to true in your factor settings. If instead you'd just like to customize the default routes, you can use blog.indexRoute and blog.postRoute.

// factor-settings
export default {
  blog: {
    indexRoute: "/blog",
    postRoute: "/entry",
    disableAutoRoutes: false,
    // other settings
  },
}

Note that when using auto routes, you'll often need to override the blogSingle or blogIndex

Manually Adding Routes

If you'd like to customize the blog, we recommend you disable automatic routes and manually add them, then import the blog components. This allows you complete control of the views on these pages.

Make sure to set blog.indexRoute and blog.postRoute so the blog knows how to handle links and other functionality.

// factor-settings
export default {
  blog: {
    indexRoute: "/journal",
    postRoute: "/journal-post",
    disableAutoRoutes: true,
    // other settings
  },
}

Then in your main file you can add your routes using the addRoutes function:

// index
import { addRoutes } from "@factor/api"

addRoutes({
  key: "myRoutes",
  routes: [
    {
      path: "/journal",
      component: (): Promise<any> => import("./my-index.vue"),
    },
    {
      path: "/journal-post/:permalink",
      component: (): Promise<any> => import("./my-single.vue"),
    },
  ],
})

Now inside each of your custom components (my-index and my-single above) you can import the blog index and single post components respectively.

<!-- my-index.vue -->
<template>
  <div class="blog-index">
    <h1>My Custom Layout</h1>
    <standard-blog-index />
  </div>
</template>
<script lang="ts">
  import { standardBlogIndex } from "@factor/plugin-blog"
  export default {
    components: {
      standardBlogIndex,
    },
  }
</script>

<!-- my-single.vue -->
<template>
  <div class="blog-index">
    <h1>My Custom Layout</h1>
    <standard-blog-single />
  </div>
</template>
<script lang="ts">
  import { standardBlogSingle } from "@factor/plugin-blog"
  export default {
    components: {
      standardBlogSingle,
    },
  }
</script>

Now you should be up and running with a working blog. The plugin takes care of all the data handling from here. Let's discuss further customization.

Taxonomy - Categories, Tags and Search

The standard post index functions in Factor allow category, tag and search filtering and this plugin supports this.

To filter by category, for example, all you need to do is add category=theCategory to your url and the plugin will take care of the rest. Same goes for search and tag:

- https://www.example.com/blog?category=rome
- https://www.example.com/blog?tag=aristotle
- https://www.example.com/blog?search=plato

Now with this, you can add custom navigation schemes or links to your layout.

To create a set list of categories that can be selected in the dashboard, you can use the blog.categories setting.

// factor-settings
export default {
  blog: {
    categories: ["cicero", "aristotle", "plato"],
    // other settings
  },
}

Post Limit / Pagination

If you'd like to change the amount of posts that are shown on the index before pagination, use the blog.limit option.

// factor-settings
export default {
  blog: {
    limit: 40,
    // other settings
  },
}

Localization / i18n

Factor supports localization and this plugin can easily be localized by adding the translations to a factor-lang-[locale-code].ts file in your app.

If you'd like to contribute a translation to the plugin that would be much appreciated. Please create a pull request to add it.

Advanced Customization

Layout and Overriding

The layout of components and the components in this plugin can easily be overwritten from your app.

The settings available look like this:

// factor-settings
export default {
  blog: {
    // other settings
    layout: {
      index: ["featuredImage", "title", "subtitle", "meta"],
      single: ["returnLink", "title", "meta", "entry", "social", "authorBio"],
      meta: ["authorDate", "tags"],
    },
    components: {
      blogWrap: (): Promise<any> => import("./blog-wrap.vue"),
      blogIndex: (): Promise<any> => import("./blog-index.vue"),
      blogSingle: (): Promise<any> => import("./blog-single.vue"),
      returnLink: (): Promise<any> => import("./widget-return-link.vue"),
      featuredImage: (): Promise<any> => import("./widget-featured-image.vue"),
      title: (): Promise<any> => import("./widget-title.vue"),
      meta: (): Promise<any> => import("./widget-meta.vue"),
      subtitle: (): Promise<any> => import("./widget-subtitle.vue"),
      pagination: (): Promise<any> => import("./widget-pagination.vue"),
      authorDate: (): Promise<any> => import("./widget-author-date.vue"),
      authorBio: (): Promise<any> => import("./widget-author-bio.vue"),
      entry: (): Promise<any> => import("./widget-entry.vue"),
      excerpt: (): Promise<any> => import("./widget-excerpt.vue"),
      social: (): Promise<any> => import("./widget-social.vue"),
      tags: (): Promise<any> => import("./widget-tags.vue"),
      notFound: (): Promise<any> => import("./widget-not-found.vue"),
      loading: (): Promise<any> => import("./widget-loading.vue"),
    },
  },
}

In your app's settings file you can choose to change the layout of components in the index single or post meta area.

You can also override the components in this plugin with your own if you'd like detailed component customization.