talk/docs/faq.md

title, sidebar, permalink, summary

title	sidebar	permalink	summary
Frequently Asked Questions	talk_sidebar	faq.html

How are new stories/assets added to Talk? Is there an API?

There are three ways that new assets can make their way into Talk: just in time, active and manual.

Just in Time asset creation

Talk ships with a just in time mechanism that works out of the box without integration with any CMS or manual work needed.

The just in time flow looks like this:

• Request comes in for a stream on an asset that doesn't yet exist.
• Talk screens the domain against the domain whitelist, fails if doesn't pass.
• Then, concurrently
  • Talk creates a new asset record and returns the stream data (which will be empty)
  • Schedules a job to scrape the new page and fill in asset information.

The scraping mechanism utilizes metascraper and is queued using the Que. If your Talk deployments is configured to run separate job worker cluster, scraping will be performed by them.

Active (or push based) asset creation

If tighter CMS integration is required to push custom data into assets and/or keep data in sync as changes are made in a CMS an active push based workflow must be implemented.

This is an ideal candidate for a plugin. If you are interested in working on it, please contact us!

Manual asset creation

Sometimes you want to load a lot of assets into the database. The most common use case for this is populating the database during an initial installation. We recommend writing a script that transforms the data from it's source and inserts it into the assets collection.

For current schema information, please see the asset model.

Where are your http API docs?

Coral relies on GraphQL for the vast majority of it's client <-> server communication. All core queries, mutations and subscriptions are defined along with types and comments in our central TypeDef. For plugin graph api typedefs, see each plugin's /server/ directory.

In addition, Talk Server ships with GraphiQL. GraphiQL provides a full data layer IDE including interactive documentation. The autocompletes and documentation are populated from introspection meaning that Core and plugin apis will be fully explorable.

To access GraphiQL:

• Install Talk.
• Open http://localhost:3000/api/v1/graph/iql in your browser. (Note, your server an port may differ.)

Where is documentation for a specific component?

We strive for clear inline documentation across our codebase, but have gaps. Contributions to documentation would be greatly appreciated and is a great way to start contributing to the project!

If you are considering changing a core component (aka, one that is not in a plugin), you are entering the realm of a core developer. We strongly ask that you reach out the coral team before forking and changing core code. We are glad to help talk through your product need and come up with a strategy for implementing as a plugin, or working with you to extend the plugin API for your use case.

How do I contribute to these docs?

Contributions to the docs are much appreciated and a great way to get involved in the project.

Fork the Talk repo, clone it locally (no need to go through the install from source process), then:

cd docs
docker build --no-cache -t mydocs .
docker run -v "$PWD:/src" -p 4000:4000 mydocs serve -H 0.0.0.0

You can edit the files in docs with any editor and view the live updates in a browser by hitting http://localhost:4000.

Once you've made the changes, file a PR back to the coralproject/talk repo.