npm package: @ff0000-ad-tech/tmpl-build-sources
Description: [![npm (tag)](https://img.shields.io/npm/v/@ff0000-ad-tech%2Ftmpl-build-sources.svg?style=flat-square)](https://www.npmjs.com/package/@ff0000-ad-tech%2Ftmpl-build-sources) [![GitHub issues](https://img.shields.io/github/issues/ff0000-ad-tech/tmpl-build-so
Author: RED Interactive Agency
Latest version: 1.0.1

##### RED Interactive Agency - FF0000 Ad Tech

[![npm (tag)](https://img.shields.io/npm/v/@ff0000-ad-tech%2Ftmpl-build-sources.svg?style=flat-square)](https://www.npmjs.com/package/@ff0000-ad-tech%2Ftmpl-build-sources)
[![GitHub issues](https://img.shields.io/github/issues/ff0000-ad-tech/tmpl-build-sources.svg?style=flat-square)](https://github.com/ff0000-ad-tech/tmpl-build-sources)
[![npm downloads](https://img.shields.io/npm/dm/@ff0000-ad-tech%2Ftmpl-build-sources.svg?style=flat-square)](https://www.npmjs.com/package/@ff0000-ad-tech%2Ftmpl-build-sources)

[![GitHub contributors](https://img.shields.io/github/contributors/ff0000-ad-tech/tmpl-build-sources.svg?style=flat-square)](https://github.com/ff0000-ad-tech/tmpl-build-sources/graphs/contributors/)
[![npm license](https://img.shields.io/npm/l/@ff0000-ad-tech%2Ftmpl-build-sources.svg?style=flat-square)](https://github.com/ff0000-ad-tech/tmpl-build-sources/blob/master/LICENSE)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](http://makeapullrequest.com)

# tmpl-build-sources

[Getting Started](#getting-started)

[REST API + Postman](#api-postman)

[Build Source Management](#bs-management)

### Overview

This project generates [FF0000 Ad Tech](https://github.com/ff0000-ad-tech) Ad Templates, per requested:

- **Platform** (DCM, DC Studio, Velvet, Flashtalking, Sizmek, Atlas, Monet, etc)
- **Type** (Standard Polite, Intro/Endframe, Expandable, etc)
- **Options** (Date Management, Video Players, Tracking Pixels, etc)

Build Sources are the code-snippets that are assembled together to create the requested Ad Templates. The relationships are modeled using `json`-based files, called `stub.json`. The insertions are denoted by a "[template hook](https://github.com/ff0000-ad-tech/hooks-regex)" system. For more information about about how Build Sources work, see [Build Source Management](#bs-management).

## Getting Started

<a name="getting-started"></a>

1.  [NPM Install](#install) this project
2.  Run [Build Source Server](#build-source-server)
3.  [Preview](#preview): Platforms, Types, and Options
4.  [Download](#download): Sizes for Development

#### System Dependencies

Make sure your machine has at least these versions installed:

- Node `^9.0.0`
- NPM `^6.0.0`
- Python `^2.7.0`

You can check your versions in Terminal (or shell of preference): Execute commands `node -v`, `npm -v`, and `python` to see which versions you're running. If you need to update or install, check online for instructions for your operating system.

### Install Project

<a name="install"></a>

Clone or Download this repo and unzip it. In Terminal, `cd` into the result directory, then:

```sh
npm install
```

### Build Source Server

<a name="build-source-server"></a>

Build Source Server will give you an interface to generate browser-runnable ads from the Build Source stubs.

Run it with this command:

```sh
npm start
```

### Preview

<a name="preview"></a>

Preview provides a way to quickly verify edits to Build Source stubs. They are organized accordian-style by

- Platform
- Type
- Options

Select what you wish to preview, and click <img title="Reload" width="16" height="16" src="views/app/src/components/Content/components/BsPanel/components/BsPlatform/components/BsType/components/PreviewButton/images/reload.svg" />.

The following processes will happen:

1. Render Build Source
2. NPM Install top / build packages
3. Launch [Creative Server](https://github.com/ff0000-ad-tech/wp-creative-server)
4. Run Traffic-compile

Once complete, the <img title="Preview" width="20" height="20" src="views/app/src/components/Content/components/BsPanel/components/BsPlatform/components/BsType/components/PreviewButton/images/view-icon.svg" /> will become clickable. That means a Creative Server is running and has a `3-traffic/` folder to serve as a preview.

### Download

<a name="download"></a>

Download generates clean, uninstalled templates. Use these for ad development!

Select what you wish to download, and click the "Download" button. You will be prompted for a size.

## REST API + Postman

<a name="api-postman"></a>

Build Source Server exposes a REST API for executing functionality. [Postman](https://www.getpostman.com/) is a tool that lets you craft & save HTTP requests. Once the server is running, you can use the API + Postman together to save & execute commands.

Making requests in this manner is useful for:

- modifying & testing the actual Build Source layer
- keeping ecosystem templates up-to-date by mapping renders to any location in your ecosystem

For all routes, refer to [./routes/api.js](routes/api.js).

### Build Source Requests

Requests to Assemble (http://localhost:4200/api/assemble) or Preview (http://localhost:4200/api/preview) require a POST body of valid JSON. Consider the following format:

```js
{
	"units": [
		{
			"name": "standard-base",
			"build_size": "300x250",
			"build_source": {
				"build_source_path": "./standard-base/"
			},
			"build_source_options": {
				"stub_paths": [
					"./AD-BASE/options/sample-uicomponents/stub.json"
				]
			}
		}
	]
}
```

Additional URL parameters are:

- &reinstall Optional, @string: "top", "build" - forces the reinstall of requested package.json
- &hooks Optional, @boolean: if truthy, hooks will not be removed from the build-source. Helpful for debugging
- &verbose Optional, @boolean: if truthy, processes log more output to stdout

## Build Source Management

<a name="bs-management"></a>

Build Sources are a hierarchy of code snippets & assets that are mapped with a collection of `stub.json` and are rendered with an internal python engine. These sources can be found in the `./build_sources` folder.

If you want to make edits to the Build Sources, you must learn the "Stub Map" system. These docs are currently internal only: https://confluence.ff0000.com/display/AT/Technical+Overview

### Build Source Map

In order to keep the UI snappy, available build sources (http://localhost:4200/api/list) are pre-mapped to `./build_sources/_build_source_maps.json`.

This map needs to be updated when you change the top level folder-naming or -structure in `./build_sources`.

The following route updates the map:

http://localhost:4200/api/refresh