How Entities Work

At the core of TypeTote are entities. Entities are the menus, blocks, and content you see throughout the site. Any data created by the user is an entity and is managed via the entity class located in the app/Entity.php.

When a user creates a post, on save, the saveEntity method is invoked (found on around line 80 in the app/Entity.php). The method itself is called via the /post route function found around line 43.

The saveEntity method takes the raw POST and sanitizes the data to remove any script tags as the input comes from a WYSWYG (see _modules/admin/_templates/entity-form.tpl.php). 

After the data is sanitized, we run a quick check to see if the entity type is a block as we exclude those from the manifest (will go into more detail later on what that means). 

Before we move forward, the core entity structure is rather simple, it includes:

  • Title: the name of the entity and the initial pathname 
  • Body: the core entity data where the user inputs via the WYSIWYG 
  • Summary: The short excerpt used in content lists and page description.

The real unique part of the entity is the meta section, which includes self-identifying information about the entity that is later used in our manifests. The entities meta section includes the following items:

  • entity_type: page, post, or block
  • entity_status: published or unpublished
  • tags: a way to tag content
  • path: URL path of the entity
  • data published & date edited
  • entity_id: the unique identifier of the entity

As this is the second time we mention manifests, let's talk about what those are and how they work.

A manifest is an index of content on the site. TypeTote uses manifests as a means to quickly identify if a piece of content exists. Manifests are used for the /blog listing page, the admin dashboard, tags, site search, and just about everywhere else we need to call or check if content exists or return a list of content. 

Manifests themselves are JSON files stored in _data/manifests and are an aggregation of the site's entities' meta values. At the end of the saveEntity method, we call the createManifest method (around line 40 in app/Entity.php), which scans the _data/content directory, builds the manifest. 

Going back to our current post creation, blocks have their own manifest since they are not bound to a path. After the block check, if no content has been created yet, TypeTote will create the data directory that saves the entity JSON files. At that point the following items occur in sequence:

  • Using the entity id, we use that to create the file name.
  • We then check the summary section, if no summary was created TypeTote extracts the first 125 characters from the body
  • Depending on the entity type, we then build out the path if its a post we insert the category and generate the path based on the title
  • At this point, the entity is ready to be saved as a file, and we then run the createManifest method

When all is done, you can view the newly created entity file found in _data/content and the updated manifest in _data/manifest/content_manifests.json

We are always looking for ways to improve TypeTote, so please take some time to explore the codebase and let us know if you have any questions or suggestions for future guides.