blogit v1.0.1 Blogit View Source

The Blogit Application module for the application :blogit.

The application is started using this module and can be used using the public interface it provides.

What is Blogit? Blogit is a blog engine. It uses a repository (by default a git repository) containing markdown files to build posts and configuration for a blog. It can be used by, for example, Phoenix application as a back-end. An example of such Phoenix application is Blogit Web.

An example of a running blog which uses Blogit and Blogit Web is the blog of the Elixir Course of the Sofia University : blog.elixir-lang.bg. Its repository, used by Blogit can be found here https://github.com/ElixirCourse/blog.

Yes, Blogit is the Elixir version of Octopress. That said, Blogit is very extensible - the repository it uses can be something other than a Git one. For example it could be FTP, local file system, Mnesia, Postgres, etc… The only thing needed is to implement the Blogit.RepositoryProvider behaviour and to configure Blogit to use it:

Example (config/prod.exs):

  config :blogit,
    repository_url: "some_protocol://some_location.net",
    repository_provider: Blogit.RepositoryProviders.MyProvider

For now the post files have to be in markdown, but this will be configurable too. The meta-data of a post is in YAML for the moment.

As Blogit is simple OTP Application with very simple public interface, presented by this module, it can have custom front-end too. It can be Phoenix+HTLM, Phoenix+React.js, Phoenix+ELM, it can be just some Plug application, it can use :gen_tcp or be some blog-in-the-terminal.

So Blogit is blog engine by a programmer for programmers.

Link to this section Summary

Types

filters()

Functions

configuration()

Retrieves the blog configuration. The configuration is in the form of a Blogit.Models.Configuration structure

filter_posts(params, from \\ 0, size \\ 5)

Returns a list of Blogit.Models.Post structures, filtered by given criteria

list_pinned()

Returns a list of Blogit.Models.Post structures representing pinned posts in the blog. These posts are sorted by their last updated date

list_posts(from \\ 0, size \\ 5)

Returns a list of Blogit.Models.Post structures representing posts in the blog. The posts are sorted by their creation date, newest first

post_by_name(name)

Returns a single post by its unique identifiers - its name field. The name should be an atom

posts_by_dates()

Returns lists of posts grouped by years and then months for every year

start(type, args)

Called when an application is started

Link to this section Types

filters()

filters() :: %{optional(String.t) => Blogit.Logic.Search.search_value}

Link to this section Functions

configuration()

configuration() :: Blogit.Models.Configuration.t

Retrieves the blog configuration. The configuration is in the form of a Blogit.Models.Configuration structure.

filter_posts(params, from \\ 0, size \\ 5)

filter_posts(filters, non_neg_integer, non_neg_integer) :: [Blogit.Models.Post.t]

Returns a list of Blogit.Models.Post structures, filtered by given criteria.

The first argument of the function is a map of filters. This map supports zero or more of the following keys:

“author” - Used to filter posts by their .meta.author field.
“category” - Used to filter posts by their .meta.category field.
“tags” - Used to filter posts by their .meta.tags field. The value for this key should a string of comma separated tags.
“year” - Used to filter posts by their .meta.year field.
“month” - Used to filter posts by their .meta.month field.
“q” - A query to filter posts by their content or title. Supports text in double quotes in order to search for phrases.

For more information on the filtering see Blogit.Logic.Search.filter_by_params/2.

The other two arguments of the function can be used for paging. Filtered posts can be skipped using the from argument, which is 0 by default. The size of the returned list is 5 by default, but it can be changed with the third argument of the function - size.

list_pinned()

list_pinned() :: [Blogit.Models.Post.t]

Returns a list of Blogit.Models.Post structures representing pinned posts in the blog. These posts are sorted by their last updated date.

All the markdown files in the configured posts folder will be transformed into Blogit.Models.Post structures and their updated_at meta field will be read using the configured Blogit.RepositoryProvider.

Pinned posts are posts which have specified pinned: true in their meta data.

These are special posts which should be easy to find in the front-end implementation.

list_posts(from \\ 0, size \\ 5)

list_posts(non_neg_integer, non_neg_integer) :: [Blogit.Models.Post.t]

Returns a list of Blogit.Models.Post structures representing posts in the blog. The posts are sorted by their creation date, newest first.

All the markdown files in the configured posts folder will be transformed into Blogit.Models.Post structures and their created_at meta field will be read using the configured Blogit.RepositoryProvider.

Example configuration (config/prod.exs):

  config :blogit,
    repository_url: "some_protocol://some_location.net",
    repository_provider: Blogit.RepositoryProviders.MyProvider,
    posts_folder: "path-to-the-posts-folder-relative-to-the-repository-root"

By default this folder is set to “.” - the root of the repository.

Posts can be skipped using the from argument, passed to the function, which is 0 by default. The size of the returned list is 5 by default, but it can be changed with the second argument of the function - size. By using these two arguments simple paging functionality can be implemented.

post_by_name(name)

post_by_name(atom) :: Blogit.Models.Post.t | :error

Returns a single post by its unique identifiers - its name field. The name should be an atom.

Posts have unique names, usually constructed using the file path of their source markdown file in the repository.

If there is no post with the given name, the atom :error is returned.

posts_by_dates()

posts_by_dates() :: Blogit.Models.Post.year_month_count_result

Returns lists of posts grouped by years and then months for every year.

Can be used for implementing an easy-to-browse view component by years/months.

For more information see Blogit.Models.Post.collect_by_year_and_month/1.

start(type, args)

Called when an application is started.

This function is called when an the application is started using Application.start/2 (and functions on top of that, such as Application.ensure_started/2). This function should start the top-level process of the application (which should be the top supervisor of the application’s supervision tree if the application follows the OTP design principles around supervision).

start_type defines how the application is started:

:normal - used if the startup is a normal startup or if the application is distributed and is started on the current node because of a failover from another mode and the application specification key :start_phases is :undefined.
{:takeover, node} - used if the application is distributed and is started on the current node because of a failover on the node node.
{:failover, node} - used if the application is distributed and is started on the current node because of a failover on node node, and the application specification key :start_phases is not :undefined.

start_args are the arguments passed to the application in the :mod specification key (e.g., mod: {MyApp, [:my_args]}).

This function should either return {:ok, pid} or {:ok, pid, state} if startup is successful. pid should be the PID of the top supervisor. state can be an arbitrary term, and if omitted will default to []; if the application is later stopped, state is passed to the stop/1 callback (see the documentation for the c:stop/1 callback for more information).

use Application provides no default implementation for the start/2 callback.

Callback implementation for Application.start/2.