{"id":21352066,"url":"https://github.com/static-dev/spike-rooftop","last_synced_at":"2025-07-12T20:32:08.268Z","repository":{"id":57367486,"uuid":"58220485","full_name":"static-dev/spike-rooftop","owner":"static-dev","description":":house: Spike plugin for integrating RooftopCMS with a static site","archived":false,"fork":false,"pushed_at":"2019-02-05T12:33:32.000Z","size":748,"stargazers_count":20,"open_issues_count":12,"forks_count":3,"subscribers_count":6,"default_branch":"master","last_synced_at":"2024-04-25T13:02:08.022Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/static-dev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"contributing.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-05-06T16:30:56.000Z","updated_at":"2019-04-04T17:25:17.000Z","dependencies_parsed_at":"2022-08-23T20:10:49.428Z","dependency_job_id":null,"html_url":"https://github.com/static-dev/spike-rooftop","commit_stats":null,"previous_names":["carrot/roots-mini-rooftop"],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/static-dev%2Fspike-rooftop","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/static-dev%2Fspike-rooftop/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/static-dev%2Fspike-rooftop/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/static-dev%2Fspike-rooftop/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/static-dev","download_url":"https://codeload.github.com/static-dev/spike-rooftop/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225834367,"owners_count":17531471,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-22T03:12:27.672Z","updated_at":"2024-11-22T03:12:28.179Z","avatar_url":"https://github.com/static-dev.png","language":"JavaScript","readme":"# Spike Rooftop Plugin\n\n[![npm](http://img.shields.io/npm/v/spike-rooftop.svg?style=flat)](https://badge.fury.io/js/spike-rooftop) [![tests](http://img.shields.io/travis/static-dev/spike-rooftop/master.svg?style=flat)](https://travis-ci.org/static-dev/spike-rooftop) [![dependencies](http://img.shields.io/david/static-dev/spike-rooftop.svg?style=flat)](https://david-dm.org/static-dev/spike-rooftop)\n[![coverage](http://img.shields.io/coveralls/static-dev/spike-rooftop.svg?style=flat)](https://coveralls.io/github/static-dev/spike-rooftop)\n\n[Rooftop CMS](https://www.rooftopcms.com/) plugin for [spike](https://github.com/static-dev/spike)\n\n\u003e **Note:** This project is in early development, and versioning is a little different. [Read this](http://markup.im/#q4_cRZ1Q) for more details.\n\n### Why should you care?\n\nIf you are using the lovely [Rooftop CMS](https://www.rooftopcms.com/) and want to pull your API values in and compile them into a [spike](https://github.com/static-dev/spike) static site, this plugin will do some good work for you :grin:\n\n### Installation\n\n`npm install spike-rooftop -S`\n\n### Usage\n\nThis is a standard [webpack](https://webpack.github.io/) plugin, but is built for and intended to be used with [spike](https://github.com/static-dev/spike). You can include it in your spike project like this:\n\n```js\n// app.js\nconst Rooftop = require('spike-rooftop')\nconst htmlStandards = require('reshape-standard')\nconst locals = {}\n\nmodule.exports = {\n  plugins: [\n    new Rooftop({ addDataTo: locals, url: 'xxx', apiToken: 'xxx' })\n  ],\n  reshape: htmlStandards({ locals: () =\u003e locals })\n}\n```\n\nSince Spike uses [reshape](https://github.com/reshape/reshape), you can use a variety of different plugins to expose local variables to your html. We are using [spike html standards](https://github.com/static-dev/spike-html-standards) here because it's the plugin provided in spike's default template, and also is currently the only plugin that provides the ability to run complex loops through objects.\n\nIn order to pass the data correctly, you must pass `spike-rooftop` an object, which it will load the data onto when the compile begins under a `rooftop` key. If you also pass the same object to whatever posthtml plugin you are using in whatever manner it requires to make the data available in your html templates, the data will be present on that object before they start compiling. This is a slightly unconventional pattern for javascript libraries, but in this situation is allows for maximum flexibility and convenience.\n\nOnce included, it will expose a `rooftop` local to your jade files, which you can use to iterate through your posts. By default, it will only pull the `post` content type, which can be accessed through `rooftop.posts`, as such:\n\n```jade\n//- a template file\nul\n  for post in rooftop.posts\n    li= JSON.stringify(post)\n```\n\nIf you want to access other content types, you can easily have us grab them by customizing the `contentTypes` option, as such:\n\n```js\nconst locals = {}\n\nnew Rooftop({\n  addDataTo: locals,\n  url: 'xxx',\n  apiToken: 'xxx',\n  contentTypes: ['posts', 'case_studies']\n})\n```\n\nThis would pull any `case_studies` and add it to `rooftop.case_studies` in your jade files.\n\nNow let's say you want to get a little more granular in which posts you are pulling, what order they are in, etc. Rather than passing a string through the `contentTypes` array, you can pass an object instead with some extra options under a `params` key. For example:\n\n```js\nconst locals = {}\n\nnew Rooftop({\n  addDataTo: locals,\n  url: 'xxx',\n  apiToken: 'xxx',\n  contentTypes: [{\n    name: 'posts',\n    params: {\n      order: 'asc',\n      search: 'hello'\n    }\n  }]\n})\n```\n\nThis would pull back any posts whose content matches \"hello\" somewhere, in ascending rather than descending order. For a full list of possible parameters you can pass in here, check [the 'list posts' arguments list here](http://v2.wp-api.org/reference/posts/).\n\nNow it is true that rooftop doesn't return the cleanest and nicest-formatted json. So you can also pass a `transform` option to each content type, where you can transform the data however you'd like before it goes into your views.\n\n```js\nconst locals = {}\n\nnew Rooftop({\n  addDataTo: locals,\n  url: 'xxx',\n  apiToken: 'xxx',\n  contentTypes: [{\n    name: 'posts',\n    transform: (post) =\u003e {\n      // do your transformation here...\n      return post\n    }\n  }]\n})\n```\n\nWe run a default transform function that cleans up response objects for you, out of the box. However, if you'd like to disable this and get back the raw response directly from rooftop, if you pass `false` as the value of `transform`, it will come back untouched.\n\n```js\nconst locals = {}\n\nnew Rooftop({\n  addDataTo: locals,\n  url: 'xxx',\n  apiToken: 'xxx',\n  contentTypes: [{\n    name: 'posts',\n    transform: false // disable our standard transform function\n  }]\n})\n```\n\nUsing the template option allows you to write objects returned from Rooftop to single page templates. For example, if you are trying to render a blog as static, you might want each post returned from the API to be rendered as a single page by itself.\n\nThe template option is an object with path and output keys. path is an absolute or relative path to a template to be used to render each item, and output is a function with the currently iterated item as a parameter, which should return a string representing a path relative to the project root where the single view should be rendered. For example:\n\n```js\nconst locals = {}\n\nnew Rooftop({\n  addDataTo: locals,\n  url: 'xxx',\n  apiToken: 'xxx',\n  contentTypes: [{\n    name: 'posts',\n    template: {\n      path: 'templates/post.html',\n      output: (post) =\u003e { return `posts/${post.slug}.html` }\n    }\n  }]\n})\n```\n\nYour template must use the `item` variable as seen below. Note you also will need to prevent Spike from attempting to render your template file normally by adding your templates to Spike's `ignore` option, or adding an underscore to the file name.\n\n```html\n\u003cp\u003e{item.title}\u003c/p\u003e\n```\n\nFinally, if you'd like to have the output written locally to a JSON file so that it is effectively cached locally, you can pass the name of the file, resolved relative to your project's output, as a `json` option to the plugin. For example:\n\n```js\nconst locals = {}\n\nnew Rooftop({\n  addDataTo: locals,\n  url: 'xxx',\n  apiToken: 'xxx',\n  contentTypes: ['posts'],\n  json: 'data.json'\n})\n```\n\nIf you'd like to use our default transform outside of the library, this is also available as an export. For example, you could include it and use it with client-side js responses.\n\n```js\nconst Rooftop = require('spike-rooftop')\nconsole.log(Rooftop.transform)\n```\n\n#### Hooks\nIf you've read this far down, you're ready to unlock some true power over your\nrooftop content.\n\n##### postTransform\nThis function allows you to modify all posts \u0026 your locals AFTER you've modified your content in your `contentTypes - transform`, and BEFORE you the templates are compiled. You must return an array with the first index containing the posts object and the second index containing the locals object.\n\n**NOTE**: We have written tests to verify if nothing is passed in here, the data will not be modified in anyway. If you've added a postTransform hook and you have an error, start debugging here :smile:\n\n```js\nconst locals = {}\n\nnew Rooftop({\n  addDataTo: locals,\n  url: 'xxx',\n  apiToken: 'xxx',\n  hooks: {\n    postTransform: (posts, locals) =\u003e {\n      // posts = { posts: {} }\n      // locals = {}\n      return [posts, locals]\n    }\n  },\n  contentTypes: ['posts'],\n  json: 'data.json'\n})\n```\n\n### Testing\n\nThis project uses the `rooftop-seeds` project, which is a hosted rooftop instance with a public read-only key used specifically for testing OSS products that rely on rooftop. Please do not abuse this free service.\n\nIf any changes are needed to the test data in order to properly test a new feature, please file an issue and we will make the changes as required!\n\n### License \u0026 Contributing\n\n- Details on the license [can be found here](LICENSE.md)\n- Details on running tests and contributing [can be found here](contributing.md)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstatic-dev%2Fspike-rooftop","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstatic-dev%2Fspike-rooftop","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstatic-dev%2Fspike-rooftop/lists"}