Introducing Meteor Flashnews
Tags: meteor, javascript, package, l10n
Published: 2021-12-18 18:18:18

Today I'm officially announcing the release of my newest Meteor package called [flashnews](https://github.com/Freedombase/meteor-flashnews)!

So what is this all about? Flashnews as the name suggests is for quick news that don't warrant an entire blog post or are to quickly announce something important. But it goes much further than that. You can schedule when your news is going to appear and, if you want, when it is going to stop appearing. To make things even more awesome for sites with multiple languages you can write the news in different languages to reach your audience in ways they understand. As with timing we have similar options here as well. You can select that the news will appear only in the specified languages or that they they will not appear for the user at all if they don't have the specific language set. Finally you can specify a default language that is going to appear to the user if there is no translation for the news in the language of the user.

A simple flashnews now has gained quiet a complexity to work well in apps that cater to multiple languages.

## Getting started

This is a Meteor package so you can install it in your Meteor app as follows:
```bash
meteor add freedombase:flashnews
```

This will give you the collection for flashnews, basic publications and methods that should serve most needs.

There is no free UI to this and you will have to build it yourself. My sponsors will get access to the UI I have created for Socialize-starter.

## Collection
```javascript
import { FlashNewsCollection } from 'freedombase:flashnews'
```
You can import the collection directly like this.


## Publications

### `freedombase:flashnews-getMain`
Gets current flash news for the site
* `limit` {Number} Limit for the return, defaults to 3
* `language` {String} Requested language of the news, defaults to `en`
returns {Mongo.Cursor}

### `freedombase:flashnews-getFor`
Gets current flash news for the given object
* `objectType` {String}
* `objectId` {String}
* `limit` {Number} Limit for the return, defaults to 5
* `language` {String} Requested language of the news, defaults to `en`
returns {Mongo.Cursor}

## Methods

There is one method to add a new flashnews to the DB. I highly recommend to use `beforeFlashNewsInsert` hook (described later) to limit who can add them.

### `freedombase:flashnews-create`
Create a new flash news
* `content` {Object} An object with the different locales should have format like this: { en: 'First news', cs: 'První novinka' } or instead of strings can include object with your default structure for the given language.
* `defaultLanguage` {String} Default language of the news. This language will be used when the requested language is not available.
* `startsAt` {Date} The starting date when the news should be displayed, by default it is the creation date.
* `endsAt` {Date} Add a date when the news should stop being displayed, undefined by default.
* `objectType` {String} APP_NEWS by default, but you can set here your own and in combination with objectId you can for example create custom news feed for groups.
* `objectId` {String} Use in combination with objectType to specify a specific object under which to display the news.
* `onlyDisplayIn` {String[]} Specify which languages should the news by displayed in, if the requested language is not available then defaultLanguage will be used.
* `onlyDisplayOn` {String[]} Only display content to languages specified in this array. If the language does not match any in this array it will not show the news.

## Other functions and constants

### APP_NEWS
```javascript
import { APP_NEWS } from 'freedombase:flashnews'
```
Constant for the global category of news. When put into objectType of a flashnews it will then be part of the global app news set.

### Schema
```javascript
import { FlashNewsSchema } from 'freedombase:flashnews'
```
You can import the schema for the collection and use it in your own custom functions for validation or other purposes.

### Hooks
```javascript
import { beforeFlashNewsInsert, afterFlashNewsInsert } from 'freedombase:flashnews'
```
Using `meteor/callback-hook`, you can set these hooks to be run before and after the provided insert method.

```js
beforeFlashNewsInsert.register((
  userId,
  content,
  defaultLanguage,
  startsAt,
  endsAt,
  objectType,
  objectId,
  onlyDisplayIn,
  onlyDisplayOn) => {
  // Here check the user's credentials and return true if to proceed or false if to return unauthorized error
  return !!userId
})
```

```js
afterFlashNewsInsert.register(({
    _id: newsId,
    content,
    defaultLanguage,
    userId,
    startsAt,
    endsAt,
    objectType,
    objectId,
    onlyDisplayIn,
    onlyDisplayOn
}) => {
  // Returns the details of the inserted news.
})
```

### Document methods
Once you retrieve the news, you can call the following methods on the document.
#### `getContent`
Takes in the language you want to display the news in and returns the content given all the constraints set to it.
You this method to properly retrieve the content.

```js
// subscription freedombase:flashnews-getMain
const userLanguage = 'en'
const news = FlashNewsCollection.find().fetch()
const newsList = news.map((item) => {
  return item.getContent(userLanguage)
})
```

#### `availableLanguages`
Lists all the available languages for the current news.

## UI
There is no UI in this package (though my sponsors have access to a sample React implementation), but it should be very easy to implement your own.

Subscribe to the publication you want to use, then
```javascript
const news = FlashNewsCollection.find().fetch()
```
to get all the news you have on the client, or limit it if you cache things or want to do something specific and then loop through the news constant and write the content to the UI:
```javascript
const newsContent = news.map(newsItem => newsItem.getContent('en'))
```

## What is next?

From the feature side things are done as far as I'm concerned, but maybe something will pop-up as I integrate it into more apps. What I foresee are primarily improvements on the technical and organizational side of things. I still have to figure out a proper testing as the current way is not working properly. Improving documentation is always a good thing and then anything else that comes up.
What would you like to see?

--------
If you like my work, please support me on [GitHub Sponsors ❤️](https://github.com/sponsors/StorytellerCZ).