concepts > documents

Using Blocks

Last updated Invalid Date

Contents

Generating the Document API

After you've added Blocks to a Document and saved, go to the API tab where you can click the Run REST or Run GraphQL button to see the API for the Document. In the following example, we've run GraphQL.

Doc API Example

On the left, notice your KEY information followed by a fetch() method. The above example shows the code for an empty Document. As you add Blocks and come back to the API tab, you'll see that the code changes to reflect what you've done.

After you've added Blocks, there's a new query object that will change every time you add a Block. Each Block is represented by an object with properties you can call in your app. The following example is from our Vue Starter where you can see an article with properties such as the title and body. On the right, you see the actual shape of the data you can query in JSON format.

API Example

The generated code on the left shows how you can shape your GraphQL query in your app. You can copy and paste the relevant pieces of code from the left pane into your .graphql file. The right pane shows you the values associated with the properties for any block you've added.

If the value for a Block is null, that Block won't show up in your app. For example, a Toggle must be set to on, which generates a true Boolean value, in order for it to be available to your app.

High level view

To use a Block, do the following:

  1. Create the Block and Save your Document.
  2. Make sure your Document is Published.
  3. Go to the API tab and generate your desired code by clicking the Run REST or Run GraphQL button.
  4. Copy the Code Example and put it in your app.
  5. Make the appropriate references to the Block in your app.

Step-by-step instructions

Simple Text (GraphQL)

In the Tipe Dashboard

  1. Add a Simple Text Block to your Document. Make sure it's set to true, or turned on. If it's off, it won't show in your app.
  2. Go to the API tab.
  3. Click the Run GraphQL button.
  4. On the left, you'll see how to write your GraphQL query. On the right, you'll see JSON representing your Document, as in the picture above from our Vue Starter.

In your app

  1. Add the GraphQL for the Toggle to your .graphql file. For example, we've added a myText Block to an article in our Vue Starter:

    graphql
     query Articles {
       articles: allArticleExamples {
         title
         urlSlug
         body
         myText # we added a block called myText
         # ...
      }
     }
  2. Make the approriate call in your template. Here we're adding it to pages/blog/_article.vue in the Vue Starter:

    html
     <div>{{ article.myText }}</div>

Yes/No Toggle (GraphQL)

In the Tipe Dashboard

  1. Add a Yes/No Toggle Block to your Document. Make sure it's set to true, or turned on. If it's off, it won't show in your app.
  2. Go to the API tab.
  3. Click the Run GraphQL button.
  4. On the left, you'll see how to write your GraphQL query. On the right, you'll see JSON representing your Document, as in the picture above from our Vue Starter.

In your app

  1. Add the GraphQL for the Toggle to your .graphql file. For example, we've added a myToggle Block to an article in our Vue Starter:

    graphql
     query Articles {
       articles: allArticleExamples {
         title
         urlSlug
         body
         myToggle # we added a block called myToggle
         # ...
      }
     }
  2. Make the approriate call in your template. Here we're adding it to pages/blog/_article.vue in the Vue Starter:

    html
     <div>{{ article.myToggle }}</div>

Markdown (GraphQL)

In the Tipe Dashboard

  1. Create a Markdown Block and Save your Document. For this example, we've named it MyMarkdown.
  2. Make sure your Document is Published.
  3. Go to the API tab and generate your desired code by clicking the Run GraphQL button.
  4. On the left, you'll see how to write your GraphQL query. On the right, you'll see JSON representing your Document, as in the picture above from our Vue Starter.

In your app

  1. Add the GraphQL for the Markdown to your .graphql file. For example, we've added a myMarkdown Block to an article in our Vue Starter:

    graphql
     query Articles {
       articles: allArticleExamples {
         title
         urlSlug
         body
         myMarkdown # we added a block called myMarkdown
         # ...
      }
     }
  2. Make the approriate call in your template. Here we're adding it to pages/blog/_article.vue in the Vue Starter:

    html
     <Markdown :markdown="article.myMarkdown"/>

If you're running your app locally and you're using one of our starters, it should auto refresh and you should see your content. If you're running your own, be sure to refresh.

Media (GraphQL)

In the Tipe Dashboard

  1. Create a Media Block and Save your Document. For this example, we've named it MyPicture.
  2. Make sure your Document is Published.
  3. Go to the API tab and generate your desired code by clicking the Run GraphQL button.
  4. On the left, you'll see how to write your GraphQL query. On the right, you'll see JSON representing your Document, as in the picture above from our Vue Starter.

In your app

  1. Add the GraphQL for the Markdown to your .graphql file. For example, we've added a myPicture Block to an article in our Vue Starter:

    graphql
     query Articles {
       articles: allArticleExamples {
         title
         urlSlug
         body
         myPicture { # we added a block called myPicture
          id
          name
          size    
          url
          mime
         }
        # ...
      }
     }

    Notice that a Media block offers additional properties.

  2. Make the appropriate call in your template. Here we're adding it to pages/blog/_article.vue in the Vue Starter:

    html
         <!-- my media -->
         <div><img :src="article.myPicture.url"></div>

Notice that to get the actual picture, you need the path to the url, article.myPicture.url.

If you're running your app locally and you're using one of our starters, it should auto refresh and you should see your content. If you're running your own, be sure to refresh.

Document (GraphQL)

By including a Document Block within another Document, you can pull in another Document in its entirety. This allows you to query a Document along with all its child Blocks and would be handy if you had a repeated view throughout your website, for example, an author's bio that would appear along with multiple articles.

In the Tipe Dashboard

  1. Create a Document Block and Save your Document. For this example, we've named it MyLinkDocument.
  2. Make sure your Document is Published.
  3. Go to the API tab and generate your desired code by clicking the Run GraphQL button.
  4. On the left, you'll see how to write your GraphQL query. On the right, you'll see JSON representing your Document, as in the picture above from our Vue Starter.

In your app

  1. Add the GraphQL for the Document to your .graphql file. For example, we've added a myLinkDocument Block to an article in our Vue Starter:

    graphql
     query Articles {
       articles: allArticleExamples {
         title
         urlSlug
         body
         myLinkDocument { # we added a block called myLinkDocument
           ... on Link {
           text
           link
           }
         }
         #...
      }
     }
  2. Make the approriate call in your template. Here we're adding it to pages/blog/_article.vue in the Vue Starter:

    html
     <div><a :href="article.myLinkDocument.link">{{ article.myLinkDocument.text }}</a></div>

If you're running your app locally and you're using one of our starters, it should auto refresh and you should see your content. If you're running your own, be sure to refresh.

Number (GraphQL)

In the Tipe Dashboard

  1. Add a Number Block to your Document. In this example, we've named it myNumber.
  2. Go to the API tab.
  3. Click the Run GraphQL button.
  4. On the left, you'll see how to write your GraphQL query. On the right, you'll see JSON representing your Document, as in the picture above from our Vue Starter.

In your app

  1. Add the GraphQL for the Number to your .graphql file. For example, we've added a myNumber Block to an article in our Vue Starter:

    graphql
     query Articles {
       articles: allArticleExamples {
         title
         urlSlug
         body
         myNumber # we added a block called myNumber
         # ...
     }
    }
  2. Make the approriate call in your template. Here we're adding it to pages/blog/_article.vue in the Vue Starter:

    html
     <div>{{ article.myNumber }}</div>

If you're running your app locally and you're using one of our starters, it should auto refresh and you should see your content. If you're running your own, be sure to refresh.

Date (GraphQL)

In the Tipe Dashboard

  1. Add a Date Block to your Document. In this example, we've named it myDate.
  2. Go to the API tab.
  3. Click the Run GraphQL button.
  4. On the left, you'll see how to write your GraphQL query. On the right, you'll see JSON representing your Document, as in the picture above from our Vue Starter.

In your app

  1. Add the GraphQL for the Date to your .graphql file. For example, we've added a myDate Block to an article in our Vue Starter:

    graphql
     query Articles {
       articles: allArticleExamples {
         title
         urlSlug
         body
         myDate # we added a block called myDate
         #...
      }
    }
  2. JavaScript dates require a little extra attention to make them human-readable. We need a little code in the component to make the date appear the way we want it:

    javascript
       humanDate() {
         const date = new Date(this.article.myDate);
         return date.toLocaleString();
       }
  3. Make the approriate call in your template and pass in humanDate. Here we're adding it to pages/blog/_article.vue in the Vue Starter:

    html
     <div>{{ humanDate }}</div>

If you're running your app locally and you're using one of our starters, it should auto refresh and you should see your content. If you're running your own, be sure to refresh.

Color

In the Tipe Dashboard

  1. Add a Color Block to your Document. In this example, we've named it myColor.
  2. Go to the API tab.
  3. Click the Run GraphQL button.
  4. On the left, you'll see how to write your GraphQL query. On the right, you'll see JSON representing your Document, as in the picture above from our Vue Starter.

In your app

  1. Add the GraphQL for the Color to your .graphql file. For example, we've added a myColor Block to an article in our Vue Starter:

    graphql
     query Articles {
       articles: allArticleExamples {
         title
         urlSlug
         body
         myColor # we added a block called myColor
         # ...
      }
     }
  2. Add the following to your component to change the background color:

    javascript
      dynamicColor() {
        return 'background-color: ' + this.article.myColor;
     }
  3. Make the approriate call in your template and pass in dynamicColor. Here we're adding it to pages/blog/_article.vue in the Vue Starter to a block called myNewText. The Block you apply the color to can be any other Block:

    html
     <div :style="dynamicColor">{{ article.myNewText }} </div>

If you're running your app locally and you're using one of our starters, it should auto refresh and you should see your content. If you're running your own, be sure to refresh.

In the Tipe Dashboard

  1. Add a Link Block to your Document. In this example, we've named it myLink.
  2. Go to the API tab.
  3. Click the Run GraphQL button.
  4. On the left, you'll see how to write your GraphQL query. On the right, you'll see JSON representing your Document, as in the picture above from our Vue Starter.

In your app

  1. Add the GraphQL for the Link to your .graphql file. For example, we've added a myLink Block to an article in our Vue Starter:

    graphql
     query Articles {
       articles: allArticleExamples {
         title
         urlSlug
         body
         myLink # we added a block called myLink
         #...
      }
     }
  2. Make the approriate call in your template. Here we're adding it to pages/blog/_article.vue in the Vue Starter:

    html
     <div>{{ article.myLink }}</div>

If you're running your app locally and you're using one of our starters, it should auto refresh and you should see your content. If you're running your own, be sure to refresh.

Location

You can use the Location Block to pull map coordinates into your app.

In the Tipe Dashboard

  1. Add a Location Block to your Document. In this example, we've named it myLocation.
  2. Go to the API tab.
  3. Click the Run GraphQL button.
  4. On the left, you'll see how to write your GraphQL query. On the right, you'll see JSON representing your Document, as in the picture above from our Vue Starter.

In your app

  1. Add the GraphQL for the Location to your .graphql file. For example, we've added a myLocation Block to an article in our Vue Starter:

    graphql
     query Articles {
       articles: allArticleExamples {
         title
         urlSlug
         body
         myLocation { # we added a block called myLocation
           address
           coordinates
         }
         #...
      }
     }
  2. Make the approriate call in your template. Here we're adding it to pages/blog/_article.vue in the Vue Starter:

    html
     <div>{{ article.myLocation }}</div>

If you're running your app locally and you're using one of our starters, it should auto refresh and you should see your content. If you're running your own, be sure to refresh.

Group

Use the Group Block to organize other Blocks.

In the Tipe Dashboard

  1. Add a Group Block to your Document. In this example, we've named it myGroup.
  2. Go to the API tab.
  3. Click the Run GraphQL button.
  4. On the left, you'll see how to write your GraphQL query. On the right, you'll see JSON representing your Document, as in the picture above from our Vue Starter.

In your app

  1. Add the GraphQL for the Group to your .graphql file. For example, we've added a myGroup Block to an article in our Vue Starter:

    graphql
     query Articles {
       articles: allArticleExamples {
         title
         urlSlug
         body
         myMap 
         myGroup { # we added a block called myGroup
          myHeader
          myParagraph
        }
      }
     }
  2. Make the approriate call in your template. Here we're adding it to pages/blog/_article.vue in the Vue Starter:

    html
     <div>{{ article.myGroup.myHeader }}</div>

Group Blocks hold other Blocks. For example, after you've added a Group Block, click onthe blue plus in the Group Block: block plus icon

Next, you can choose another kind of block to be within the Group. These include Simple Text, Toggle, Markdown, Link, Color, Date, Media, Document, Number, and Map.

add blocks to a group

Notice that you can't add another Group Block or List Block to an existing Group.

List

Use the List Block to organize other Blocks.

In the Tipe Dashboard

  1. Add a List Block to your Document. In this example, we've named it myList.
  2. Go to the API tab.
  3. Click the Run GraphQL button.
  4. On the left, you'll see how to write your GraphQL query. On the right, you'll see JSON representing your Document, as in the picture above from our Vue Starter.

In your app

  1. Add the GraphQL for the Group to your .graphql file. For example, we've added a myList Block to an article in our Vue Starter:

    graphql
     query Articles {
       articles: allArticleExamples {
         title
         urlSlug
         body
         myMap 
         myList { # we added a block called myList
          _meta {
           id
           name
           updatedAt
           createdAt
           published
         }
        }
      }
     }
  2. Make the approriate call in your template. Here we're adding it to pages/blog/_article.vue in the Vue Starter:

    html
     <div>{{ article.myList }}</div>

Block validations

You can easily add Block level validations. On a Block, hover the green check mark to the right of the Block title:

Block Validation Location

Click the green check mark to edit validations.

Edit Block Validations

Here, you can make a Block required, meaning that it has to contain something — it can't be null. You can also set a max length.

Make your edits and then click Save in the upper right of the Dashboard.

Save Button

Next, make sure you've Published your Document so that the validations go into effect. If your Document isn't Published, any validations you create won't be applied.

If the Document is already Published, any Blocks that aren't passing validation won't be saved. Likewise, if a Document isn't valid, Tipe won't let you Publish it.


Go further

Publishing

If you haven't already learned about Publishing check this page out to learn how Publishing your Document can speed up your content delivery.


Organizing your Documents

See how to organize Documents in the Tipe dashboard with a blog example.