Neoclassical Piano Montage

    contentful-graph

    1.6.2 • Public • Published

    Build Status npm version

    contentful-graph

    Visual representation of contentful content models in form of graphs

    Can be exported with fields:

    alt

    or without:

    alt

    Requirements

    graphviz

    If you plan to render the graph as image or PDF, make sure you have graphviz installed on your system.

    node.js

    The library is using async/await functions, so you need the latest 7 or 8 versions.

    Installation

    Can be installed globally:

    npm i -g contentful-graph

    Or locally

    npm i --save-dev contentful-graph

    Running without installation

    Import script can be executed with the help of npx

    npx contentful-graph

    Running import

    There are several ways of running the import:

    1. running CLI bin/contentful-graph command
    2. import API and invoking functions programmatically

    For this purpose, you'll need to know your contentful spaceId and token

    Token may come in two flavors: Delivery token or Management token

    Management token has an advantage of showing one-to-one relationships for models (as pointed by @jelz in #1)

    Command-line version

    When running the command line version, make sure you export following variables:

    CONTENTFUL_SPACE_ID= spaceId
    CONTENTFUL_TOKEN= either deliveryToken
    CONTENTFUL_MANAGEMENT_TOKEN= or management token
    CONTENTFUL_ENVIRONMENT_ID= environment id

    or simply in command-line:

    CONTENTFUL_ENVIRONMENT_ID=master CONTENTFUL_SPACE_ID=123 CONTENTFUL_MANAGEMENT_TOKEN=token ./bin/contentful-graph

    Command-line options

    --help (-h) Displays usage information

    --dev (-d) Includes developer information (model Id's and field Id's)

    --hide-fields (-n) Do not include fields information, only entities

    Reading from local file

    It is possible to run import against local file with exported model defintions:

    ./bin/contentful-graph ./my-contentful-model.json

    Web version

    You can run it locally or host it on any server using contentful-graph-web

    docker run -it --rm -p 3000:3000 lotas/contentful-graph-web
    # or checkout project locally and
    make BUILD && make RUN
    # or if you have graphviz in your system simply
    npm run dev

    Api version

    Package exposes following functions:

    getContentTypesFromManagementApi(spaceId: string, managementToken: string, environment: string): Promise<Object>

    Will import content types from contentful using management api

    getContentTypesFromDistributionApi(spaceId: string, apiToken: string, environment: string): Promise<Object>

    Will import content types from contentful using distributions api

    contentTypesToModelMap(contentTypes: Object): Object

    Will enrich existing content types with mapping information (one-to-one, one-to-many)

    modelsMapToDot(modelsMap: Object, {hideEntityFields: Boolean, dev: Boolean}): String

    Will create dot graph definition out of the model map

    You can use them as follows:

    const convertApi = require('contentful-graph');
    
    // either with managementToken
    const contentTypes = await convertApi.getContentTypesFromManagementApi(spaceId, managementToken);
    // or with apiToken, you just need one of the calls
    const contentTypes = await convertApi.getContentTypesFromDistributionApi(spaceId, apiToken);
    
    // enrich content types with relationship definitions
    const modelsMap = convertApi.contentTypesToModelMap(contentTypes);
    
    // generate dot string that can be passed to graphviz
    const dotStr = convertApi.modelsMapToDot(modelsMap, {});

    Generating graphs

    After you would run the import, you should have something like this:

    digraph obj {
      node[shape=record];
    
      Image [label="{Image |        | <title> Title|<photo> Photo|<imageCaption> Image caption|<imageCredits> Image credits|<categoryId> CategoryId}" shape=Mrecord];
      Asset
      Author [label="{Author |        | <name> Name|<twitterHandle> Twitter handle|<profilePhoto> Profile photo|<biography> Biography|<createdEntries> Created entries}" shape=Mrecord];
      Category [label="{Category |        | <categoryId> Category Id|<categoryName> Category name}" shape=Mrecord];
      PhotoGallery [label="{Photo Gallery |        | <title> Title|<slug> Slug|<author> Author|<coverImage> Cover Image|<description> Description|<images> Images|<tags> Tags|<date> Date|<location> Location}" shape=Mrecord];
    
      Image:photo -> Asset [dir=forward];
      Image:categoryId -> Category [dir=forward];
      Author:profilePhoto -> Asset [dir=forward];
      Author:createdEntries -> Image [dir=forward,label="1..*"];
      PhotoGallery:author -> Author [dir=forward];
      PhotoGallery:coverImage -> Asset [dir=forward];
      PhotoGallery:images -> Image [dir=forward,label="1..*"];
    }

    To render this to image or PDF, pipe it to the dot command:

    ./import.js | dot -Tpng > model.png
    ./import.js | dot -Tpdf > model.pdf

    Where ./import is the script that produces dot output

    Links

    Contentful Management API

    Contentful Delivery API

    GraphViz Fiddle

    Install

    npm i contentful-graph

    DownloadsWeekly Downloads

    1,485

    Version

    1.6.2

    License

    ISC

    Unpacked Size

    19.9 kB

    Total Files

    13

    Last publish

    Collaborators

    • yaraslau.kurmyza