DEV Community: Apostrophe

Creation of the ApostropheCMS Documentation Chatbot

The Apostrophe Team — Thu, 29 Aug 2024 15:17:08 +0000

Introduction

Chatbots have evolved significantly since their inception in the 1960s with simple programs like ELIZA, which could mimic human conversation through predefined scripts. Initially limited to basic interactions, typically in customer service roles, advancements in artificial intelligence have transformed chatbots into essential tools for businesses, enhancing user engagement and providing 24/7 customer support. Recently, the shift from rule-based systems to the utilization of large language models (LLMs) has enabled chatbots to understand and respond with greater comprehension and context awareness.

AI-powered assistants are now revolutionizing the developer tools landscape, offering more efficient ways to interact with documentation. When they are at their best, these intelligent search assistants provide accurate, contextual, and efficient navigation through complex information, significantly boosting productivity and saving valuable time.

Our decision to build an AI-powered documentation assistant was driven by the desire to provide rapid and customized responses to engineers developing with ApostropheCMS. While we remain committed to providing guidance and fostering community in Discord, support via this channel is limited by personnel availability. Implementing an AI-driven chatbot enables developers to receive instant, customized answers anytime, even outside of regular support hours, and expands accessibility by providing support in multiple languages. Our assistant aims to transform the documentation experience by moving beyond simple scripts, offering a seamless and intelligent solution tailored to developers' needs.

Technical Design Highlights

Asking a question of the new ApostropheCMS Documentation chatbot is easy!

Building an AI-powered chatbot is more than just connecting a user’s query to an LLM. While commercial options often bundle everything—natural language processing, conversational memory, knowledge retrieval—into a neat package, they tend to be a black box, leaving us with little control over the finer details. When we set out to create our documentation chatbot, we knew we wanted more than just an out-of-the-box solution. We leveraged the power of an LLM, but also took steps to refine the process, enhancing accuracy and overall user experience by making thoughtful design choices along the way. In this section, we will highlight some of those key design decisions.

Retrieval-Augmented Generation (RAG) with Vector Database

When designing our documentation chatbot, we knew from using commercial offerings that there were significant issues with hallucination, where AI generates confident but incorrect or irrelevant information, and references to outdated information about older versions of Apostrophe in answers. Hallucination occurs because large language models (LLMs) are designed to generate the most likely response based on their training data, even if the data doesn't contain relevant or up-to-date information.

We toyed with “prompt engineering”, essentially adding extra information to guide the AI’s response to enhance the accuracy of answers. For example, for each query we added language like, “Using only information about the latest version of Apostrophe, answer the following query: `{{ user_query }}.`” But as many of you have probably found in your own experiments, this approach on its own has its limits. The AI would still go off track, lacking the real-time knowledge to separate fact from fiction.

Simplified Retrieval-Augmented Generation (RAG) workflow.

So rather than relying solely on prompt engineering, we chose a Retrieval-Augmented Generation (RAG) approach for our chatbot. Without diving too deep into the technicalities (there is a great article here for a more comprehensive explanation), RAG is fundamentally about enhancing an LLM's responses by providing it with additional, real-time info. At its simplest, RAG involves three main steps:

Retrieval: Using the user's query to find relevant information from a knowledge base.
Augmentation: Adding this retrieved information to context provided along with the query to the LLM.
Generation: Having the LLM generate a response based on both the original query and the augmented context.

This approach lets us feed the LLM current knowledge that wasn't part of its original training, leading to more accurate and up-to-date answers. The retrieval part can be done in various ways, from simple keyword matching to fancier semantic search techniques. For us, it was a game-changer in helping to reduce hallucination and outdated info problems.

Steps in the creation of a RAG vector database.

Vector Embedding

We settled on using a vector database mechanism for our RAG implementation. This approach allows us to efficiently store and retrieve relevant information based on the semantic meaning of queries. Here's how we built our vector database:

First, we gathered all of our documentation and extension README files into a collection of about 150 documents. We then split these documents into smaller chunks of 1000 characters each, with an overlap of 200 characters between chunks. This chunking process helps maintain context while allowing for more precise retrieval of relevant information.

Next, we created embeddings for each of these chunks. Embeddings are numerical representations that capture the semantic meaning of the text, allowing for similarity comparisons. We used the OpenAI text-embedding-3-small model to convert each text chunk into a high-dimensional vector. This is a decision that we may re-think moving forward, based on a number of factors such as whether more context is worth the cost. We'll touch on this briefly in the last section of this article.

Finally, we stored these vectors in our chosen database: the activeloop DeepLake database. This database is open source, something near and dear to our own open-source hearts. We will cover some additional details in a further section, but it is specifically designed to handle vector data and perform efficient similarity searches, which is crucial for quick and accurate retrieval during the RAG process.

One of the key advantages of this approach is its flexibility and cost-effectiveness. Updating our RAG database is a straightforward process that costs only about five cents per update. This allows us to continuously expand and refine our knowledge base as our documentation evolves, ensuring that our chatbot always has access to the most up-to-date information.

Compared to alternatives like fine-tuning an entire LLM, which can be time-consuming and expensive, especially with frequently changing content, our vector database approach for RAG is more accurate and cost-effective for maintaining current and constantly changing knowledge in our chatbot.

Steps in responding to a user-submitted query.

Document Retrieval with Nearest Neighbor

When a user submits a query to our docbot, we employ a process known as nearest neighbor search to find the most relevant information:

Vector Conversion: The query is first converted into a vector, representing its semantic meaning in a multi-dimensional space. This is done with the same embedding model as was used to create the database.
Nearest Neighbor Search: We use a nearest neighbor algorithm to find the most similar document chunks in our knowledge base. This technique efficiently identifies the 'closest' vectors to our query vector in the high-dimensional space.
Initial Retrieval: Our system retrieves the top 75 nearest neighbors (fetch_k = 75). In essence, we're finding the 75 document chunks that are most semantically similar to the query.
Refinement: From these 75 chunks, we further refine our selection to the 12 most relevant (k = 12). This two-step process helps balance between broad coverage and focused relevance.
Prompt Creation: The selected chunks, along with the original query, are formatted into a prompt for the LLM.

Nearest neighbor search is a fundamental concept in information retrieval and machine learning. It's particularly useful in our context because it allows us to quickly find the most similar documents without having to compare the query to every single document in our database. We use cosine similarity as our distance metric to determine how 'close' or similar two vectors are.

This approach ensures that the model's answers are grounded in the most relevant and up-to-date information available in our documentation. Our initial parameter choices to fetch 75 document chunks and narrow it to 12 can likely be further optimized to balance between response accuracy and processing speed.

LangChain Framework

Any commercial or open-source LLM model is going to have some type of API that allows you to interact with the model, but using these APIs directly can lead to model-specific implementations and require significant custom development for advanced features. To enhance flexibility and streamline development, we chose to use the LangChain framework. LangChain offers a layer of abstraction that allows us to create model-agnostic chains of processes, easily switch between different LLMs, and leverage pre-built components for common tasks like memory management and prompt engineering.

Detailed steps in the processing of a user query in our LLM-powered docbot.

As the name suggests, the LangChain framework allows for queries and retrieved documents to be passed down a chain of processes. Here's how we've implemented it:

Query Reformulation: We first combine the user's query with the current user’s chat history from that same session to create a new, stand-alone query. This process, using LangChain's ConversationBufferMemory, improves clarity by providing context from previous interactions. For example, if a user asks, "How do I modify it?" the reformulated query might be, "How do I modify the page template in ApostropheCMS?" based on the context of the previous conversation.
Document Retrieval and Prompt Engineering: The reformulated query is used to retrieve relevant documents from our RAG database. We then apply prompt engineering using LangChain's PromptTemplate before querying the LLM.

Other Useful Features:

Model Flexibility: LangChain's model-agnostic design allows for easy A/B testing between different LLMs. This means that you can easily switch between different LLMs or even fine-tuned versions of the same model to compare performance and outcomes. We've been comparing OpenAI's GPT-4 and Anthropic's Claude Sonnet. This flexibility allows for continuous optimization of the chatbot's responses and ensures that you can choose the best model for your specific needs without significant re-engineering.

LangSmith provides a (highly) detailed dashboard that lets you monitor all of the aspects of your query chain.

Performance Monitoring: LangChain integrates with LangSmith, offering advanced tools for debugging and monitoring. Using LangSmith, we identified that the amount of chat history we were passing with our queries is likely creating excessive and unnecessary token usage. This is an area we can actively investigate to see if we can reduce costs without impacting response quality.

This integrated suite of tools makes LangChain a powerful choice for building and optimizing AI-powered chatbots. It allows us to continually refine our implementation, ensuring we deliver the best possible user experience while managing resources efficiently.

DeepLake Database

While we've already discussed the basics of our vector database implementation, it's worth diving deeper into why we chose activeloop DeepLake and how it enhances our chatbot's performance.

Memory-Resident Capability: DeepLake offers the ability to create a memory-resident database. This feature significantly reduces latency by keeping the data in RAM, close to where it's processed. For our current dataset of about 150 documents, this in-memory approach provides very rapid retrieval times.

Versioning System: DeepLake's built-in versioning system is a powerful tool for managing our knowledge base. It allows us to track changes over time, making it easy to update our documentation or roll back to previous versions if needed. This is particularly valuable as our product evolves and documentation is frequently updated.

Efficient Querying and Compression: The database supports efficient data querying, allowing us to quickly retrieve relevant information. Additionally, its data compression features help optimize memory usage, which is crucial for maintaining high performance as our dataset grows.

Scalability: While we currently use DeepLake in-memory due to our relatively small dataset, we have a clear path for scaling. If we expand our dataset to include a large codebase, for example, we can easily transition to DeepLake's cloud offering. However, this would come at the cost of increased latency in document retrieval and hosting costs.

Future Optimizations: As our dataset grows and we potentially move to cloud storage, we're already considering optimizations. For instance, we may need to implement increased caching of the first document retrieval in our chain of processes to mitigate latency issues. Our current setup, with document retrieval occurring twice in our process flow, may need adjustment to maintain optimal performance.

By leveraging DeepLake's features, we've created a flexible, efficient foundation for our RAG system. This allows us to focus on improving the chatbot's responses and user experience, knowing that our data retrieval system can scale and adapt as our needs evolve.

Reflection from Early Adoption

Our experience with the chatbot in production is still in the early stages, but we’ve already seen some promising results. For instance, there have been strong examples where the chatbot has effectively guided users through building features like custom widgets from scratch. This includes the main index.js file, Nunjucks template, and player code. As user adoption increases, we hope these positive outcomes will continue. While we've only touched on the key design highlights, there are several other noteworthy takeaways from our early experiences.

One observation is that users often ask a series of highly similar questions sequentially. This behavior can increase hallucinations, as the LLM may attempt to modify its responses each time. Fortunately, since we control the chain of processes, we were able to introduce a step that evaluates new queries against previous ones in the chat history to mitigate this issue. Unless the two queries have a low similarity (<0.85), they are rejected as being the same questions. Although this change has occasionally led to user frustration when they perceive their queries as different, it has generally reduced hallucinations.

Similarly, we noticed that users sometimes ask questions using terminology that is absent in our documentation but appears in our codebase. Because the LLM is primarily limited to our documentation, it tends to hallucinate answers for these unfamiliar terms. By adjusting the process chain to examine the vector scores of the retrieved documents and ensuring that the returned documents have significant (0.85) semantic similarity with the query, we've also been able to reduce this type of hallucination.

Another unexpected benefit of monitoring user interactions is that it has highlighted areas for improving our documentation. When the LLM struggles to find information, it's often a sign that the content is either not in the right context or not prominently featured. In one case, this led us to discover an incorrectly documented feature, allowing us to rectify the error and enhance our overall documentation quality.

These early reflections have not only helped us refine our chatbot but have also provided valuable insights into our documentation strategy and user behavior. As we continue to learn and adapt, we're excited about the potential for further improvements and the positive impact on our users' experience.

Looking Ahead

When originally designing the chatbot, we opted to build it in Python, despite being a heavily JavaScript-oriented shop. This decision was driven by the availability of more mature analytic tools for objectively testing chatbot hallucination and accuracy in Python. So far, we've been evaluating answers qualitatively, but we plan to incorporate a tool like Giskard to bring a more quantitative approach to our evaluations. This step is crucial and one that, anecdotally, is often overlooked in many production chatbots.

Another goal on the horizon is optimizing how we manage passed history to reduce token usage. However, with the decreasing cost of most LLM models and the increasing token limits, this concern has become less pressing. These advancements allow us to pass more context for less money without the worry of truncated answers due to token constraints.

We’re also exploring the idea of supplementing our RAG database with several codebases, including the core Apostrophe repository and potentially some of our starter kits. However, this would complicate the embedding process and might challenge the LLM’s primary goal of guiding users to the most relevant documentation for further reading. However, along with this, we have also thought about changing to the text-embedding-3-large model. This would provide more context for our documentation and might also be better suited for large amounts of code. We’re carefully weighing the best way forward, aiming to balance the richness of our database with the clarity and utility of the chatbot’s responses.

As we continue refining our chatbot, our primary focus remains on providing developers with precise, actionable information. Every enhancement is a step toward that goal, and we're excited to see how these improvements will further elevate the user experience. One key item under discussion is how to best collect user feedback and ensure that when answers have a degree of hallucination and are not effective solutions for the end developer, we can help remedy this.

We invite you to experience our AI-powered documentation assistant firsthand and explore how it can enhance your development workflow. Try it out here, and let us know your thoughts! Join our Discord community to share feedback, ask questions, and collaborate with other developers. Together, we can continue to refine and improve this tool to better serve the ApostropheCMS community.

Expand Content Reach Using AI for SEO and Translation in Your CMS

Antonello Zanini — Thu, 22 Aug 2024 15:38:48 +0000

In recent months, the way we approach our work has changed significantly. AI has become central to many workflows, driving productivity, enhancing efficiency, and providing valuable insights. The CMS industry is no exception to this trend. That is why why Apostrophe recently released two new extensions that leverage AI for SEO and translation.

In this article, you will discover the latest developments from Apostrophe in the AI space. You will learn what the new SEO Assistant and Automatic Translation extensions are, and see how they can streamline your SEO metadata definition and content translation processes with just a few clicks.

AI Applications in the CMS Industry: From Ideas to Reality

In our article published in mid-2023, we examined how AI could transform the CMS industry. During that discussion, we introduced the AI Helper extension to generate images and rich text directly from a prompt within ApostropheCMS.

In the months that followed, those insights were validated and evolved into concrete developments. These ideas were incorporated into Apostrophe's roadmap and have now materialized into two new AI-powered extensions for Apostrophe Pro.

Let’s dive into these exciting new features!

Introducing New Apostrophe AI-Powered Plugins: SEO Assistant and Automatic Translation

These are two new extensions in the Apostrophe AI offerings:

SEO Assistant: Automatically generates SEO page metadata through AI.
Automatic Translation: Provides AI-driven translation of documents (pages and pieces) for content localization.

Note: Both extensions are exclusive to Apostrophe Pro and Apostrophe Assembly users. These premium versions of Apostrophe offers advanced features tailored for both developers and editors.

As you are about to learn, both extensions work together to optimize your site’s reach. To better showcase SEO Assistant and Automatic Translation, they will be integrated into the site showcased in our tutorial on how to create an e-commerce platform with Apostrophe. If you are not familiar with that article, you can see an example of in the following video.

Using AI for SEO Optimization in Your CMS

One of the most tedious, yet essential, tasks when handling the SEO of a website is defining the meta title and SEO description of a webpage. This information is key because search engines like Google use it to generate the SERP (Search Engine Results Page) entry associated with your page, as in the following image:

This is even more important when considering that over 50% of traffic to business websites comes from organic search (i.e., SEO).

When specifying the SEO meta title and description of a page, there are a few best practices to keep in mind:

Both the title and description should be concise, actionable, and to the point. They should also include relevant keywords to help search engines rank your page higher.
The meta title should be between 50 to 60 characters long to ensure that search engines do not truncate it in the SERP snippet.
The meta description should ideally be between 50 to 160 characters, with an optimal length of around 150/160 characters. For more information, check out Google's best practices of meta descriptions.

The problem is that writing effective SEO titles and descriptions is often seen as a boring task. Ask your editors, and they will likely tell you that they prefer to craft great content rather than focusing on SEO details.

Additionally, SEO optimization is typically the final step in the publication process. As a result, some editors might overlook it or not give it the attention it deserves to push the page online.

The good news is that SEO title and description values are directly related to the page's content, which opens the door to leveraging AI for SEO. Specifically, the AI-powered SEO Assistant extension can analyze the page content to generate effective meta titles and descriptions for you.

Let’s explore how this Apostrophe Pro extension works in the section below!

SEO Assistant in Action

Follow the official integration guide to install and configure the SEO Assistant extension in your Apostrophe application. As of this writing, the prerequisites for using the SEO Assistant are:

An Apostrophe 4 application with the SEO Tools and other required extensions installed, as described in the documentation.
An OpenAI API key or a custom integration.

In this example, we will use OpenAI as the AI provider, but keep in mind that SEO Assistant also supports custom AI providers.

Now, assume you just created a special web page called “Summer Collection 2024" to promote your clothing line for the summer season. The final step before publishing it is to define the meta title and description.

To reach the page edit modal, click on “Pages” in the top left menu, locate the “Summer Collection 2024” draft page, and select the “Edit” option:

Navigate to the “SEO” tab, where you will see that both the “Title” and “Description” fields are empty:

Normally, you would have to manually fill in those fields, but no worries—your AI-powered SEO Assistant is here to help!

Click on the button to access the SEO Assistant options. Select “Make a suggestion based on page content” to instruct AI to generate the selected meta field using the content found on the page:

Now you have three options:

1. Use this suggestion: Populate the field with the AI-generated text.

2. Try again: Request an alternative suggestion on the fly.

3. Edit prompt: Manually configure the prompt used to query the AI for SEO meta field generation.

Similarly, you can generate an SEO meta description with a couple of clicks:

Note: The above example focused on a page, but SEO Assistant also works for individual content pieces. Plus, it can be configured to produce results of a given minimum length.

Amazing! SEO Assistant generated a captivating meta title and description for you in just a fraction of a second. It only remains to click “Publish.”

As shown here, using AI for SEO simplifies metadata optimization and removes the tediousness associated with the task.

Integrating AI for Translation in your CMS

Localizing a website into several languages is critical to reaching a global audience. As of 2023, approximately 1.46 billion people are estimated to speak English worldwide. That represents about 18.07% of the global population—less than 1 in 5 people.

As you can imagine, localization becomes essential when targeting local markets in regions such as Asia, Europe, or Latin America. Thankfully, Apostrophe comes with comprehensive support for localization.

When translating a website, a common practice is to start with layout elements like menus, footers, and headers. Although this initial step can be time-consuming, it only needs to be done once as those elements are shared across all pages. That might create the misconception that translating a website into a new language is a quick task. Well, that is not true!

The real challenge arises when realizing that you have to translate all pages, content, and media files. This process can take up to months, especially on large sites. Luckily, you can now automate the task by using AI for translation.

Let’s see how the Apostrophe Pro Automatic Translation extension can help you translate pages and pieces with just a few clicks!

Automatic Translation in Action

Follow the integration guide to install and set up the Automatic Translation extension in your Apostrophe application.

Automatic Translation comes with built-in support for Google Cloud Translation and DeepL as AI translation providers (with support for Azure AI Translator coming soon). To integrate them, you just need a valid API key. Keep in mind that the extension also supports custom providers.

In this example, we will use DeepL, but any other AI translation provider will do.

Suppose you already configured the es locale in your Apostrophe e-commerce project and translated all layout elements. The next step is to translate all content from English to Spanish, which will make your site more accessible to the 500 million native Spanish speakers worldwide. ¡Empezamos!

This is what the English version of the e-commerce site currently looks like:

The goal is to have the entire site translated into Spanish.

The first document to translate is undoubtedly the home page. To do that, click on "Pages" in the top left menu, locate the "Home" page, and select the "Localize…" option:

This will open the Automatic Translation modal below:

A wizard will guide you through the process of configuring how Apostrophe will use AI for translation. Specifically, you will be asked to:

Select the content to localize. The available options are the current document, the current document and its related documents (such as images and any other referenced documents), or only the related documents.
Choose the locales to translate the content into.
Specify the related document types to localize, if you chose to translate them in step 1. You can also decide whether to translate only new related documents or to overwrite existing translated documents. Select the “Translate text content option“ for automatic AI translation.

The home page depends on some related documents. Therefore, the recommended option is "This document and related documents":

In the last step of the wizard, you can select which types of related documents you want to localize. Apostrophe will automatically translate them together with the current document.

The following notifications will inform you that the current document and the selected related documents were translated successfully:

Visit the home page of the Spanish version of your e-commerce site, and you will now see:

Wow, a good start! However, notice that there are no products or categories on the page. This is because they need to be translated as well.

Before translating them, you may find that you are not satisfied with the translation results provided by the AI. No problem, you can always edit the localized documents using Apostrophe's editing capabilities:

The translated pages will be saved as drafts in the selected locale(s). This way, a content manager will have to manually review and approve them for publication. Also, Apostrophe will automatically mark the AI-translated fields, as they require additional attention from your editors.

Also, keep in mind that Automatic Translation also translates the SEO meta title and description into the target language. To verify that, explore the “SEO” tab of the “Summer Collection 2024” page mentioned in the previous chapter:

Observe how both the meta title and the SEO description were translated into Spanish.

Awesome, you are ready to translate products and categories!

Click on "Content" in the top left menu, select a content category, and follow the same procedure as above to translate each piece:

Considering that pieces often involve or are connected to other documents, you can choose the “this document and related documents” option to speed up the translation process.

Use AI to translate all pages and pieces in your project, and this is the end result you will get in just a few minutes:

While it may not be perfect, this is definitely impressive!

Similarly, this is what an AI-translated page product looks like:

Note: Automatic Translation offers a wide range of options and customizations to tailor the AI content translation experience to your needs. For more details, see the developer documentation.

As proven here, leveraging AI for translation significantly accelerates the content localization process. That creates a tremendous opportunity to make your site accessible to millions of users worldwide.

Benefits of SEO Assistant and Automatic Translation Extensions

A few months ago, it was merely a guess, but now there is little doubt that integrating AI directly into a CMS introduces substantial benefits. Specifically, using AI for SEO and translation provides these advantages:

Expanding content reach: AI-driven SEO and translation help to reach a broader audience. Enhanced SEO rankings increase your site's visibility, while localized content resonates with diverse audiences in different regions, significantly boosting the chances of attracting new users to your pages.
Improving productivity: Tasks that once required hours of meticulous work can now be completed in seconds. AI handles the heavy lifting, leaving you to refine and personalize the generated content. This shift reduces time spent on manual tasks and helps you concentrate on what truly matters, such as creating outstanding user experiences.
Saving money: By delegating specialized tasks like SEO optimization and translation to AI, you may no longer need to hire a team of dedicated experts in those fields. Such a cost-effective strategy enables you to allocate resources more efficiently while still achieving high-quality results, ultimately saving your business money.

The above improvements are made possible by SEO Assistant and Automatic Translation, the new AI-powered Apostrophe Pro extensions.

These are just a few of the several powerful features available in the Pro and Assembly tiers of Apostrophe, which also include advanced permissions, document version history, and more.

Conclusion

In this article, we looked at what the new AI-powered SEO Assistant and Automatic Translation extensions have to offer. With AI integrated directly into Apostrophe, you can now generate SEO metadata and translate content into any language within seconds and a handful of clicks.

While the current results are already spectacular, this is just the beginning. The Apostrophe team is continually working to discover new and effective AI integrations, and you should be excited about what the future holds.

To get a preview of what's next for Apostrophe, keep an eye on our product roadmap!

How To Set Up the Advanced Permission Pro Extension

Antonello Zanini — Tue, 07 May 2024 20:01:12 +0000

The Advanced Permission module is a Pro extension that adds more granular control over content permissions. It provides the ability to create custom groups and assign them to users directly in the admin UI.

A group is a set of rules that specify how users can create, edit, delete, and publish content, including creating new users and groups. The module provides granular control, allowing admins to give a group Create, Edit, Delete, and Publish permissions for each piece type on the site. Those four core permissions can be extended with new custom permissions.

The Advanced Permission extension also enables admins to give groups and individual users granular per-document permissions on specific pages and pieces.

NOTE: The name of the npm package of the Advanced Permission module is @apostrophecms-pro/advanced-permission.

Prerequisites

The requirements for setting up the Advanced Permission module are:

An Apostrophe 3+ application: If you don’t already have one, make sure you meet the requirements and then follow the instructions in the development setup guide.
An Apostrophe Pro or Apostrophe Assembly subscription: To gain access to the Advanced Permission module, you first need to join Apostrophe Pro or Apostrophe Assembly.

Installing the Advanced Permission Module

After joining Apostrophe Pro or Apostrophe Assembly, you'll be added to the @apostrophecms-pro npm organization. This gives you the ability to install the Advanced Permission module in your Apostrophe project.

WARNING: If you try to add @apostrophecms-pro/advanced-permission to your project's dependency before being added to @apostrophecms-pro, you’ll get the following error:

@apostrophecms-pro/advanced-permission' is not in this registry.

@apostrophecms-pro/advanced-permission is a private npm package. You must authenticate in npm before installing it. The recommended authentication method changes depending on whether you’re in a development or production environment.

Development Setup
In a development environment, run the following command to start the npm authentication procedure:

npm login

This will produce an output as below:

Login at:
https://www.npmjs.com/login?next=/login/cli/<NPM_HASH>
Press ENTER to open in the browser...

Press ENTER to open the npm login page in your default browser. Type in your credentials, sign in, and return to the CLI.

After logging in successfully, you’ll receive the following message:

Logged in on https://registry.npmjs.org/

NOTE: To keep the session alive, npm will create a global .npmrc configuration file containing your access token in the following line:

//registry.npmjs.org/:_authToken=<YOUR_NPM_ACCESS_TOKEN>

cd to your project folder and then install the Advanced Permission Pro extension with the command below:

npm install @apostrophecms-pro/advanced-permission

npm will use the authenticated URL in .npmrc to download the private @apostrophecms-pro/advanced-permission package. It will then install it as per usual.

Production Setup
In a production environment, authenticate npm commands by setting up a granular token related to the @apostrophecms-pro organization. Follow the official guide for guidance.

After setting up an npm granular token, add a .npmrc file to the root folder of your Apostrophe project. Initialize it with the following line:

//registry.npmjs.org/:_authToken=${NPM_TOKEN}

When launching an npm command, ${NPM_TOKEN} will be replaced with the value read from the NPM_TOKEN environment variable. That URL will be used to retrieve packages from the npm registry as an authenticated user.

WARNING: Adding a local .npmrc file will override your global .npmrc file npm created on npm login. To avoid authorization issues while installing private packages from the @apostrophecms-pro npm organization, set the NPM_TOKEN environment variable on your local machine when working with a project that has a .npmrc defined as above. You can do that in your .bashrc file using EXPORT NPM_TOKEN="<YOUR_PERSONAL_NPM_TOKEN>"

In the production server, set the NPM_TOKEN env to the value of your npm granular token:

export NPM_TOKEN="<YOUR_NPM_GRANULAR_TOKEN>"

When launching npm install, the production environment will now be able to install the "@apostrophecms-pro/doc-template-library" dependency in package.json.

Enable the Module in Apostrophe

Enable the Advanced Permission extension by adding the following two modules to the app.js file:

// app.js

require('apostrophe')({
  shortName: 'my-project',
  modules: {
    // other modules...

    // enable the Advanced Permission extension
    '@apostrophecms-pro/advanced-permission-group': {},
    '@apostrophecms-pro/advanced-permission': {}
  },
  // remaining configs...
});

NOTE: To use Advanced Permission in a multisite project, you can add the two modules outlined above to both the site/index.js and dashboard/index.js files. Adding the modules to the two files will enable the Pro extension for both the dashboard and all individual sites. It’s also possible to enable the extension only for the dashboard on individual sites. Before starting to use the Advanced Permission module in the dashboard, make sure the privateDashboards feature is set to false. This setting won’t affect individual sites.

On the first run of your project after enabling the Advanced Permission module, some database migrations will automatically occur. These create a group for each role found in existing users and link them to the group corresponding to their role field.

After adding the Advanced Permission extension, a “Groups” item will appear in the top left menu in the admin bar.

Adding Custom Permissions

In addition to the Create, Edit, Delete, and Publish core permissions, new custom permissions can be defined through the permissions object in a piece-type index.js file for an individual piece or in @apostrophecms/page-type/index.js for all pages. You can’t define custom permissions in individual page types.

Much like the fields object, the permissions object takes an add property. This accepts permission properties with objects having the following three properties:

label: A string that describes the new permission to the user. It determines what is shown in the group and per-document permission grids.
requires: An optional string with the name of an existing permission or an object with multiple permissions (e.g., requires: { $or: [ 'edit', 'create' ] }). It determines whether the new permission is dependent on any other permission in the grid. For example, requires: 'publish' would require the admin to select the "Publish" permission for the document or document type before they could select the new permission.
perDoc: An optional boolean to define whether the new permission should appear in the user and group per-document permission matrices. The default value is false.

For example, you can define a custom decriptionField permission with:

module.exports = {
  // ...
  fields: {
    // ...
  },
  // ...
  permissions: {
    add: {
      decriptionField: {
        label: 'Description',
        requires: 'publish',
        perDoc: false
      }
    }
  }
};

TIP: By using permissions in an Apostrophe core module at the project level, you can add a new custom permission to multiple document types. For example, extending the @apostrophecms/piece-type module with the permissions object would add the custom permissions to all pieces.

editPermission: Limiting Access to a Single Field
After defining a custom permission, you can assign it to a specific field of a piece type by using editPermission. This schema field property takes an object with the following two properties:

action: A string with the name of one of the built-in permissions (e.g., 'create') or a custom permission.
type: A string with the name of the module that permission is associated with. For core modules, make sure to prefix the module name with @apostrophecms/ or @apostrophecms-pro/.

For example, you can assign the custom decriptionField permission to the description field of a product as below:

module.exports = {
  // ...
  fields: {
    add: {
      description: {
        type: 'string',
        label: 'Description',
        textarea: true,
        editPermission: {
          action: 'descriptionField', // custom permission
          type: 'product'
        }
      },
      // other fields...
    },
  },
  // ...
};

Only users who have been granted the Create and/or Modify permissions as well as the descriptionField permission will now be able to edit the description of product pieces.

NOTE: perDoc: true isn’t compatible with the editPermission feature. To grant a user per-document custom permission on a given field of a piece, follow this procedure instead:

Define a custom permission with perDoc: false.
Use editPermission to assign the custom permission to the desired field of the given piece.
Define a group with the selected custom permission for the given piece.
Assign the group to the user.
Grant the user per-document permission to Modify the documents of the given piece.

A complete example: defining the custom “Pricing” permission
Suppose your project has a service piece. You want to add a custom “Pricing” permission so that only users with this permission can edit the price of services on your site. That can be achieved with the permissions and editPermission objects in modules/service/index.js as below:

module.exports = {
  extend: '@apostrophecms/piece-type',
  options: {
    label: 'Service'
  },
  fields: {
    add: {
      title: {
        type: 'string',
        label: 'Title'
      },
      description: {
        type: 'string',
        label: 'Description',
        textarea: true
      },
      price: {
        type: 'float',
        label: 'Price',
        editPermission: {
          action: 'pricingField',
          type: 'service'
        }
      }
    },
    group: {
      basics: {
        label: 'Basics',
        fields: [
          'title',
          'description',
          'price'
        ]
      }
    }
  },
  permissions: {
    add: {
      pricingField: {
        label: 'Pricing'
      }
    }
  }
};

Customized permission checks
editPermission is not the only way to take advantage of custom permissions. You can also verify if a particular user has a custom permission (including per-document permissions) when coding your own routes and methods server-side with the following line:

self.apos.permission.can(req, '<custom_permission_name>', doc)

The function returns true if the user has the custom permission, false otherwise. This approach opens the door to custom use cases involving permission verification.

How to Integrate Astro with ApostropheCMS pt. 2

Antonello Zanini — Thu, 21 Mar 2024 16:45:38 +0000

This is the second and conclusive part of the ApostropheCMS / Astro integration tutorial. In Part 1, you learned how to set up an Astro frontend that communicates with an ApostropheCMS backend through the ApostropheCMS Astro Integration Starter Kit.

In this tutorial, you will complete the Astro blog application by integrating React into it and using React components to improve its user interface and interactivity.

Let’s look at the remaining aspects of the ApostropheCMS integration into Astro!

What We Achieved So Far

In Part 1, you used the ApostropheCMS Astro Integration Starter Kit to integrate an ApostropheCMS backend with an Astro frontend application. In this setup, ApostropheCMS handles content management, URL routing, and content retrieval, while Astro renders the HTML documents and delivers them to the user's browser.

The Astro-ready ApostropheCMS application we started from uses the @apostrophecms/blog module. This includes a blog index page with a list of all posts on the site and a page for each individual blog post.

This is what the blog index page currently looks like in the Astro frontend:

And this is the dedicated blog post page:

As you can see, there is still a lot to do when it comes to UI and UX to transform this web application into a more usable and interesting site. To accomplish that, you will see how to take advantage of the features offered by Astro, such as the support of multiple UI frameworks.

By adding custom styling and using interactive React components, you will learn how to take the ApostropheCMS-powered Astro blog application to the next level!

Add React to Astro

Astro comes with a CLI command to automate the setup of React. In the Astro project folder, launch the command below to install @astrojs/react and configure it to use React components in Astro:

npx astro add react

This will launch a CLI wizard where you will be asked a few questions. Answer “yes” to each of them to:

Install the libraries required for integrating React.
Add the react() integration to the astro.config.mjs configuration file.
Update the tsconfig.json file for JSX support.

This process will take a while, so be patient. If something goes wrong, refer to the official documentation for more information.

Excellent! You can now use React components in Astro.

Prepare your astro-frontend project to host React components by adding a components folder to ./src.

Customize the UI of Your ApostropheCMS-Powered Astro Blog

Follow the steps below and learn how to improve the UI and interactivity of the ApostropheCMS Astro blog application!

If you are eager to take a look at the code of the final Astro codebase or want to use it as a reference while you follow the tutorial, clone the GitHub repository supporting the article:

git clone https://github.com/Tonel/astro-frontend.git

Note that we will use the apostrophecms/astro-frontend project as a starting point.

General UI Improvements
If you inspect the Astro template components under the ./src/templates folder, you will see that they all share this structure:

---
// JS imports
---

<section class='bp-content'>
  <!-- HTML structure -->
</section>

This means you can target the bp-content class to add a responsive layout to your site. To define a global CSS rule that applies to those Astro components, you need to define a local stylesheet file.

In this tutorial, we are going to use SCSS. Thus, add the sass npm package to your project’s dependency:

npm install sass

Next, create a styles folder inside ./src and add the following blog.scss file to it:

// .src/styles/blog.scss

.blog {
  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol";

  .bp-content {
    padding-right: 15px;
    padding-left: 15px;
    margin-right: auto;
    margin-left: auto;

    @media (min-width: 576px) {
      width: 540px;
    }

    @media (min-width: 768px) {
      width: 720px;
    }

    @media (min-width: 992px) {
      width: 960px;
    }

    @media (min-width: 1200px) {
      width: 1140px;
    }
  }

  .h1 {
    text-align: center;
    margin: 0 0 20px;
    font-size: 4em;
    font-weight: 200;
  }

  a {
    color: #6236ff;
    text-decoration: none;
    background-color: transparent;

    &:hover {
      text-decoration: underline;
    }
  }
}

This defines global styles for the page structure, links, and blog fonts. Also, it contains useful global classes that we will use later on. As you can see, the top wrapping class of this SCSS file is blog.

Import .src/styles/blog.scss and set the <body> class to blog in [...slug].astro as follows:

---
// ./src/[...slug].astro

import aposPageFetch from '@apostrophecms/apostrophe-astro/lib/aposPageFetch.js'
import AposLayout from '@apostrophecms/apostrophe-astro/components/layouts/AposLayout.astro'
import AposTemplate from '@apostrophecms/apostrophe-astro/components/AposTemplate.astro'
import '../styles/blog.scss' // <-- import the custom SCSS file  

const aposData = await aposPageFetch(Astro.request)
const bodyClass = `blog` // <-- update the <body> class

if (aposData.redirect) {
  return Astro.redirect(aposData.url, aposData.status)
}
if (aposData.notFound) {
  Astro.response.status = 404
}
---
<AposLayout title={aposData.page?.title} {aposData} {bodyClass}>
    <Fragment slot='standardHead'>
      <meta name='description' content={aposData.page?.seoDescription} />
      <meta name='viewport' content='width=device-width, initial-scale=1' />
      <meta charset='UTF-8' />
    </Fragment>
    <AposTemplate {aposData} slot='main'/>
</AposLayout>

Open http://localhost:4321/blog in the browser and you will now see:

Similarly, this is what a blog post page will look like:

Awesome! The appearance of the blog has already improved a bit, but there is still much to be done.

Create a Blog Card Component
The current index page of the blog is nothing more than a list of links. As such, the user experience is very limited. Improve it with a custom React UI component representing a blog post card to use in that list!

In the ./src/components folder, add a BlogCard.jsx file that contains these lines:

// ./src/components/BlogCard.jsx

import './BlogCard.scss'
import dayjs from 'dayjs'

export default function BlogPost({ blog }) {
  return (
    <div className='blog-card'>
      <div className='date'>
        Released On {dayjs(blog.publishedAt).format('MMMM D, YYYY')}
      </div>
      <div className='title'>
        <a href={blog._url}>{blog.title}</a>
      </div>
    </div>
  )
}

This JSX React component wraps and extends the following blog post representation logic in ./src/templates/BlogIndexPage.astro:

<h4>
  Released On { dayjs(piece.publishedAt).format('MMMM D, YYYY') }
</h4>
<h3>
  <a href={ piece._url }>{ piece.title }</a>
</h3>

As you are about to learn, the main advantage of using React components is that they make it easier to implement advanced user interactions without any impact on SEO.

Notice that the first line of the component is an import to a SCSS file. So, define the BlogCard.scss file this way:

// ./src/components/BlogCard.scss

.blog-card {
  border-radius: 5px;
  border: solid #111111 1px;
  padding: 20px;
  margin-bottom: 10px;

  .date {
    font-style: italic;
    color: #505050;
    font-size: 14px;
    margin-bottom: 15px;
  }

  .title {
    font-size: 20px;
  }
}

Keep in mind that Astro supports CSS imports via ESM inside any JavaScript file, including JSX components. This is useful for writing granular, per-component styles for your React components.

Import the Blog Card Component in the Blog Index Page
Open over the BlogIndexPage.astro template component and add the BlogCard import in the JavaScript section:

import BlogCard from '../components/BlogCard'

You do not need to import BlogCard.scss as well, since the React component already imports it.

In the template section of the Astro component, replace the blog post HTML representation logic with <BlogCard />:

{
  pieces.map((piece) => {
    return <BlogCard blog={piece} />
  })
}

Note that Astro will manage the keys for each DOM element under the hood. So, you do not need to manually provide a key prop as you would normally do in React.

This is where the Astro magic happens. Your BlogIndexPage.astro Astro template component now contains HTML mixed with a React component. In the same way, you could use other components written in Vue.js, Preact, or other frameworks.

Your BlogIndexPage.astro file will now contain:

---
// ./src/templates/BlogIndexPage.astro

import setParameter from '@apostrophecms/apostrophe-astro/lib/aposSetQueryParameter.js'
import BlogCard from '../components/BlogCard'

const {
  page,
  user,
  query,
  piecesFilters,
  pieces,
  currentPage,
  totalPages
} = Astro.props.aposData

const pages = []
for (let i = 1; i <= totalPages; i++) {
  console.log(page, currentPage)
  pages.push({
    number: i,
    current: i === currentPage,
    url: setParameter(Astro.url, 'page', i),
  })
}
---
<section class='bp-content'>
  <h1>{page.title}</h1>

  <h2>Blog Posts</h2>

  {
    pieces.map((piece) => {
      return <BlogCard blog={piece} />
    })
  }

  {pages.map(page => (
    <a
      class={(page === currentPage) ? 'current' : ''} 
      href={page.url}>{page.number}
    </a>
  ))}
</section>

For more information on how aposSetQueryParameter() works, check out the official documentation.

This is what the http://localhost:4321/blog index page will look like:

The biggest concern you might have is that those React components are rendered client-side. This would not be good for SEO, especially in a blog. To check whether the React components are rendered on the client or the server, you need to inspect the HTML pages returned by Astro to the client.

To do so, stop the local development server and build your application with:

npm run build

The /dist folder in your project will now contain the Astro bundle. Serve it with:

npm run serve

Visit http://localhost:4321/blog again, right-click, and select the “View page source” option. Take a look at the source code of the page, and you will see HTML code like:

<div class="blog-card">
  <div class="date">
    Released On February 1, 2023
   </div>
   <div class="title">
     <a href="/blog/lorem-ipsum-1">Lorem Ipsum 1</a>
   </div>
</div>

Fantastic! This is proof that Astro automatically renders React components on the server, as their HTML is embedded in the document sent to the client. Bear in mind that this is just the default behavior, and you can customize that with the Astro template directives. Learn more in the next section.

Add Client-Side Interaction to the Blog Card Component
Currently, the only way to interact with the blog card component is to click on the title link inside it. Suppose you want to make the entire card interactive. Specifically, you want users to be redirected to the blog post page even when they click on the card element.

You could easily achieve that by passing an onClick handler to the <div> card in the React component, as shown below:

// ./src/components/BlogCard.scss

// ...

export default function BlogPost({ blog }) {
  return (
    <div
      className='blog-card'
      onClick={(e) => {
        e.preventDefault()
        // redirect to the blog post page
        window.location.href = blog._url
      }}
    >
      {/* ... */}
    </div>
  )
}

To help users understand this interaction, you should also add a hover effect to the card:

// ./src/components/BlogCard.scss

.blog-card {
  // ...

  &:hover {
    border: solid #6236ff 1px;
    background-color: #f2f0f9;
    cursor: pointer;
  }

  // ...
}

Note that this is just a simple example but you could implement more complex interactions using React state management and hooks.

Visit the http://localhost:4321/blog page and move the mouse on a card to see that the background of the card will change as expected. At the same time, if you click on it, nothing will happen. Why? Because Astro does not hydrate UI framework components in the client by default.

If you are not familiar with this process, hydration refers to the process of attaching event listeners and state to UI components in the browser, making them interactive. In the scenario described above, the visual changes triggered by mouse movement and handled via CSS are possible, but interactive functionality such as clicking is not enabled.

To instruct Astro to hydrate the blog card component in the client, pass the client:load directive to <BlogCard /> in BlogIndexPage.astro:

{
  pieces.map((piece) => {
    return <BlogCard blog={piece} client:load />
  })
}

Interact with the blog index page again, and the click interaction will now work as desired:

To make this possible, Astro will send the minimum amount of JavaScript possible to the client. This way, the web pages served by your site will remain quick to be retrieved and rendered by the browser.

Add a Pagination Component
You must have noticed that little "1" at the bottom of the index blog page:

This is a pagination element that allows you to explore the list of all articles in your blog. Use ApostropheCMS to populate your application with more than 10 posts, and more pagination numbers will appear:

Currently, the pagination logic is handled by the following lines in ./src/templates/BlogIndexPage.astro:

{pages.map(page => (
  <a
    class={(page === currentPage) ? 'current' : ''} 
    href={page.url}>{page.number}
  </a>
))}

This is definitely not an optimal interaction, and you should replace it with a dedicated React interactive component. Inside ./src/components, add a BlogPagination.jsx file with this code:

// ./src/components/BlogPagination.jsx

import './BlogPagination.scss'

export default function BlogPagination({ pages = [] }) {
  return (
    <div className='blog-pagination'>
      {pages.map((page) => {
        return (
          <span
            key={page.number}
            className={`pagination-element ${page.current ? 'current' : ''}`}
            onClick={(e) => {
              e.preventDefault()
              // redirect to the blog index pagination page
              window.location.href = page.url
            }}
          >
            <a href={page.url}>{page.number}</a>
          </span>
        )
      })}
    </div>
  )
}

As before, this component contains both a crawlable link for SEO and a more intuitive click interaction for users.

The style and interactivity of each pagination element should change whether the number matches the current page or not. You can define this logic in a dedicated BlogPagination.scss style file:

// ./src/components/BlogPagination.scss

.blog-pagination {
  display: flex;
  align-items: center;
  justify-content: center;
  margin-top: 40px;
  margin-bottom: 40px;

  .pagination-element {
    border: solid #111111 1px;
    text-align: center;
    padding: 10px 20px;
    margin-right: 10px;
    border-radius: 5px;

    a {
      text-decoration: none;
      color: inherit;
      &:hover {
        text-decoration: none;
      }
    }

    &.current {
      pointer-events: none;
      background-color: #111111;
      color: white;
    }

    &:hover {
      color: white;
      background-color: #111111;
      cursor: pointer;
    }
  }
}

Import the component in BlogIndexPage.astro and use it to replace the aforementioned pagination lines:

---
// ./src/templates/BlogIndexPage.astro

import setParameter from '@apostrophecms/apostrophe-astro/lib/aposSetQueryParameter.js'
import BlogCard from '../components/BlogCard'
import BlogPagination from '../components/BlogPagination'

const {
  page,
  user,
  query,
  piecesFilters,
  pieces,
  currentPage,
  totalPages
} = Astro.props.aposData

const pages = []
for (let i = 1; i <= totalPages; i++) {
  pages.push({
    number: i,
    current: i === currentPage,
    url: setParameter(Astro.url, 'page', i),
  })
}
---
<section class='bp-content'>
  <h1>{page.title}</h1>

  <h2>Blog Posts</h2>

  {
    pieces.map((piece) => {
      return <BlogCard blog={piece} client:load />
    })
  }

  <BlogPagination pages={pages} client:load />
</section>

Again, notice the client:load directive required to load the click interactivity in the client. This is what the new pagination component will look like:

If you click on one of the active number elements, you will be redirected to the selected pagination page:

Complete the Blog Index Page
The blog index page has improved a lot in terms of both UI and UX. It is just a matter of adding the finishing touches. For example, you could assign the h1 class from the global blog.scss style file to the <h1> element in BlogIndexPage.astro:

Also, assume you want to center the <h2> element in this Astro component. Instead of defining a global CSS rule, you can use the Astro special <style> tag to write scoped CSS:

<style>
  h2 {
    text-align: center
  }
</style>

CSS rules defined here always come last in the order of appearance. Therefore, if you import a style sheet that conflicts with a scoped style, the scoped style’s value will apply.

The final BlogIndexPage.astro template component will contain:

---
// ./src/templates/BlogIndexPage.astro

import setParameter from '@apostrophecms/apostrophe-astro/lib/aposSetQueryParameter.js'
import BlogCard from '../components/BlogCard'
import BlogPagination from '../components/BlogPagination'

const {
  page,
  user,
  query,
  piecesFilters,
  pieces,
  currentPage,
  totalPages
} = Astro.props.aposData

const pages = []
for (let i = 1; i <= totalPages; i++) {
  pages.push({
    number: i,
    current: i === currentPage,
    url: setParameter(Astro.url, 'page', i),
  })
}
---
<style>
  h2 {
    text-align: center
  }
</style>

<section class='bp-content'>
  <h1 class='h1'>{page.title}</h1>

  <h2>Blog Posts</h2>

  {
    pieces.map((piece) => {
      return <BlogCard blog={piece} client:load />
    })
  }

  <BlogPagination pages={pages} client:load />
</section>

This is how the definitive blog page index will appear:

Wonderful! You just learned how to customize the UI and UX of the index page of your blog. Time to focus on the blog post page!

Style the Blog Show Page
The current page for individual blog posts is rather ugly and does not provide a good reading experience. As a first step to improve it, modify BlogShowPage.astro as below:

---
// ./src/templates/BlogShowPage.astro

import AposArea from '@apostrophecms/apostrophe-astro/components/AposArea.astro'
import dayjs from 'dayjs'

const { page, piece, user, query } = Astro.props.aposData
const { main } = piece
---
<style>
  .publication-date {
    text-align: center;
    font-style: italic;
    color: #505050;
    font-size: 16px;
    margin-bottom: 25px;
  }
</style>

<section class='bp-content'>
  <h1 class='h1'>{ piece.title }</h1>
  <div class='publication-date'>
    { dayjs(piece.publishedAt).format('MMMM D, YYYY') }
  </h4>
  <AposArea area={main} />
</section>

This Astro component has a custom style for the date element and relies on the global h1 class seen earlier.

The new blog show page definitely looks better:

If you inspect the blog post content rendered in the AposArea component, you will notice that it is nothing more than a list of <p>, each of which represents a paragraph:

As a first approach to style that section of the page, you might consider adding a CSS rule for p tags in <style>:

<style>
  // ...

  p {
    margin-bottom: 35px;
    line-height: 35px;
    font-size: 18px;
  }
</style>

This will not work because that CSS snippet is scoped and the <p> elements are not directly in the template component but within AposArea. In detail, it is ApostropheCMS that takes care of handling and returning that content.

To define CSS rules for HTML documents whose content lives outside Astro—as in this case—Astro provides a special global() CSS function:

<style>
  // ...

  :global(p) {
    margin-bottom: 35px;
    line-height: 35px;
    font-size: 18px;
  }
</style>

That function allows you to write global, unscoped CSS in the <style> tag.

Equivalently, you can add another <style> tag marked with the is:global attribute:

<style is:global>
  p {
    margin-bottom: 35px;
    line-height: 35px;
    font-size: 18px;
  }
</style>

The CSS rules marked as “global” will apply to all the HTML elements in the DOM subtree of the Astro component.

Put it all together, and you will get the following BlogShowPage.astro file:

---
// ./src/templates/BlogShowPage.astro

import AposArea from '@apostrophecms/apostrophe-astro/components/AposArea.astro'
import dayjs from 'dayjs'

const { page, piece, user, query } = Astro.props.aposData
const { main } = piece
---
<style>
  .publication-date {
    text-align: center;
    font-style: italic;
    color: #505050;
    font-size: 16px;
    margin-bottom: 25px;
  }

  :global(p) {
    margin-bottom: 35px;
    line-height: 35px;
    font-size: 18px;
  }
</style>

<section class='bp-content'>
  <h1 class='h1'>{ piece.title }</h1>
  <div class='publication-date'>
    { dayjs(piece.publishedAt).format('MMMM D, YYYY') }
  </h4>
  <AposArea area={main} />
</section>

This is what the blog show page will now look like:

Congratulations! You now know how to build a site that relies on Astro on the frontend and uses ApostropheCMS for content management.

Conclusion

Part 2 of this two-article series ends up here. But, suggested next steps for you are revamping the home page, improving the 404 page, designing a proper 500 page, and adding new features such as a top menu, a footer, sharing buttons, the ability to comment, and more. Thanks to what you have learned here, you have all the building blocks you need to achieve those goals and get the most out of the Astro/ApostropheCMS integration!

Once again, ApostropheCMS has proven to be a modern, robust, future-oriented technology that can support new approaches to web development due to its unopinionated approach on the frontend. Try Apostrophe today!

FAQ

How does Astro communicate with ApostropheCMS?
The @apostrophecms/apostrophe-astro npm library automatically proxies certain ApostropheCMS endpoints in Astro. In particular, these are the routes proxied by the package:

/apos-frontend/[...slug]: For serving ApostropheCMS assets.
/uploads/[...slug]: For serving ApostropheCMS uploaded assets.
/api/v1/[...slug] and /[locale]/api/v1/[...slug]: For contacting the ApostropheCMS API endpoints.
/login and /[locale]/login: For accessing the ApostropheCMS login page.

So, for example, when you visit the /login page in Astro, the aposPageFetch() function from @apostrophecms/apostrophe-astro takes care of forwarding the request to the /login endpoint of your ApostropheCMS backend and retrieving the returned HTML.

Note that this proxy mechanism forwards all the headers of the original request, including cookies. This also explains how Apostrophe login works in Astro.

Do ApostropheCMS widget players still work in Astro?
In ApostropheCMS, widget players are a frontend feature that allows developers to provide special behavior to widgets, calling each widget's player exactly once at page load and when new widgets are inserted or replaced with new values. This interactive widget feature should still work without a page refresh, even if the widget was just added to the page. To achieve the same result, you can use Astro web components.

Defining and using an HTMLElement inside an Astro widget component has much the same effect as defining a widget player in a standalone ApostropheCMS project. For a complete example, check out the source code of VideoWidget.astro in the apostrophecms/astro-frontend project.

How are error messages presented in Astro?
Astro comes with a default error page that contains the error message, the snippet that caused the error, and the stack trace as below:

If you receive the following error after integrating the @apostrophecms/apostrophe-astro library:

Only URLs with a scheme in: file and data are supported by the default ESM
loader. Received protocol 'virtual:'

Then, you most likely left out this part from the astro.config.mjs file:

export default defineConfig({
  // other settings here ...
  vite: {
    ssr: {
      noExternal: [ '@apostrophecms/apostrophe-astro' ],
    }
  }
})

Without this logic, the virtual: URLs used to access configuration information will cause the build to fail.

How to Integrate Astro With ApostropheCMS pt. 1

Antonello Zanini — Thu, 21 Mar 2024 16:12:02 +0000

Apostrophe recently announced the integration for the Astro web framework, one of the hottest technologies in the IT community. Astro has become so popular because it offers developers the ability to create efficient and SEO-oriented web applications using multiple UI frameworks like React and Vue.js, even on the same project.

In the first part of this two-article series, you will learn what Astro is, what the ApostropheCMS Astro Integration Starter Kit is, and how to use it to manage the pages and content of an Astro frontend via ApostropheCMS.

What Is Astro?

Astro is an open-source JavaScript framework known for its versatility, performance, and new approach to web development. It enables developers to create fast, modern, content-rich web applications and sites using the "Bring Your Own Framework" (BYOF) model.

What makes Astro special is its ability to work with multiple JavaScript frameworks at the same time, including React, Preact, Svelte, Vue.js, and others. This gives developers the flexibility to choose the tools they prefer for any specific goal. For example, one UI component might be in Vue and another in React. In Astro, that is entirely possible.

Astro relies on an innovative "Island Architecture" that separates static content from interactive parts of a web page. This architecture allows you to mix static content, server-rendered components, and client-rendered components on the same page without conflict. Astro will take care of sending the minimum amount of JavaScript required for interactivity on the page.

The framework also offers several other features, such as top-level waiting, support for Markdown and MDX, and themes, making it a complete solution for modern web development needs.

Integrate ApostropheCMS With Astro With the Starter Kit

Integrating ApostropheCMS into an Astro application means:

Let ApostropheCMS manage the content, handle URL routing, and content retrieval.
Let Astro take responsibility for page rendering and implementing the UI logic using a frontend framework of your choice, such as React, Vue.js, or Svelte.

Note that this integration is possible because ApostropheCMS is unopinionated on the frontend. For example, you can also integrate it with new technologies such as HTMX. Learn more in our HTMX integration guide.

The easiest way to achieve the Astro integration is through the ApostropheCMS Astro Integration Starter Kit. This module uses the @apostrophecms/apostrophe-astro npm library to bring the ApostropheCMS Admin UI to your Astro application. That way, you can manage your Astro site exactly as if you were in a regular ApostropheCMS application.

Given the dual nature of this setup, you need two projects to get the most out of the starter kit module. These are:

An ApostropheCMS project: This is where you define your page types, widget types, and other content types with their schemas and other customizations.
An Astro project: This is where you write your templates and frontend code.

Let’s now see how to set up these two projects and integrate ApostropheCMS into Astro.

Set Up an ApostropheCMS Project for Astro

The recommended way to set up an ApostropheCMS project for Astro integration is to clone the apostrophecms/starter-kit-astro project:

git clone apostrophecms/starter-kit-astro.git

Or, equivalently, create a new Apostrophe project using the Astro starter kit:

apos create my-apos-project-name --starter=astro

The main benefit of starting with the provided project is that it contains an ApostropheCMS blog application that has already been configured for integration with an Astro frontend. This will save you a lot of time.
If you want to use your ApostropheCMS project, make sure to:

Be using Apostrophe >= 3.x.
Run npm update to bring your project to the latest version of apostrophe.
Update any page templates in your Apostrophe project to provide a link to your Astro frontend site and remove all other output. Everyone who accesses the backend, editors included, should go straight to the Astro frontend.

Well done! You now have an ApostropheCMS project for Astro. From now on, we will assume that your ApostropheCMS project is in the starter-kit-astro folder.

Set Up an Astro Project for ApostropheCMS

Follow the steps below and learn how to set up an Astro frontend project that integrates with an ApostropheCMS backend.

Initialize an Astro Project

The recommended way to create an Astro-based site that relies on ApostropheCMS for content editing is to clone the apostrophecms/astro-frontend repository:

git clone https://github.com/apostrophecms/astro-frontend.git

This project will already contain all the configurations, components, and templates to connect Astro to the ApostropheCMS Astro starter kit. Again, the main advantage of using the provided project is that almost everything needed to run Astro with AspotropheCMS is done there. So, you can get a huge head start.

If you instead prefer to start from scratch, run the command below and follow the wizard to initialize a new Astro project:

npm create astro@latest

Then, add @apostrophecms/apostrophe-astro to your project dependencies with:

npm install @apostrophecms/apostrophe-astro

As mentioned before, this module allows you to integrate ApostropheCMS into your Astro application.

Great! You now have an Astro project for ApostropheCMS. From now on, we will assume that your Astro project is in the astro-frontend folder.

Add an Astro Configuration File

To make Astro communicate with the Apostrophe backend, you need to customize how Astro works. To do so, add an astro.config.mjs file to the project's root folder. Note that most Astro template projects—including apostrophecms/astro-frontend—come with a working configuration file. But if you are not starting from our astro-frontend project, then you will need to add Apostrophe-related configuration yourself.

This is what your astro.config.mjs configuration file should look like:

// ./astro.config.mjs

import { defineConfig } from 'astro/config';
import node from '@astrojs/node';
import apostrophe from '@apostrophecms/apostrophe-astro';

export default defineConfig({
  output: 'server',
  adapter: node({
    mode: 'standalone'
  }),
  integrations: [
    apostrophe({
      aposHost: 'http://localhost:3000',
      widgetsMapping: './src/widgets',
      templatesMapping: './src/templates',
      forwardHeaders: [
        'content-security-policy', 
        'strict-transport-security', 
        'x-frame-options',
        'referrer-policy',
        'cache-control',
        'host'
      ]
    })
  ],
  vite: {
    ssr: {
      // Do not externalize the @apostrophecms/apostrophe-astro plugin, we need
      // to be able to use virtual: URLs there
      noExternal: [ '@apostrophecms/apostrophe-astro' ],
    }
  }
});

To give editors the ability to edit the content directly on the page, the @apostrophecms/apostrophe-astro module requires Astro to be configured in SSR (Server-Side Rendering) mode. In detail, the output: 'server' setting enables on-demand rendering on the ApostropheCMS server at request time. As of this writing, support for SSG (Static Site Generation) is under consideration for the future.

What you should focus your attention on is the object passed to the apostrophe() integration function. That specifies the following options:

aposHost: The base URL of your ApostropheCMS instance. When developing locally or contacting an ApostropheCMS instance on the same server, the URL must contain the port number. During development, its value should be http://localhost:3000. You can override this option through the APOS_HOST environment variable.
widgetsMapping: The optional path to the JavaScript file in your Astro project that contains the mapping between Apostrophe widget types and your Astro components.
templatesMapping: The optional path to the JavaScript file in your Astro project that contains the mapping between Apostrophe templates and your Astro templates.
forwardHeaders: An optional array of HTTP headers that you want to forward from the ApostropheCMS backend to the final response sent to the browser. This is useful if your backend is using a module like @apostrophecms/security-headers and wants to keep the headers you configured in ApostropheCMS.

For more information on all supported options, see the documentation.

Now, you may be wondering what the widget mapping file and the template mapping file are. Find that out in the next sections.

Mapping Apostrophe Widgets to Astro Components

The core element of the in-context editing experience offered by ApostropheCMS revolves around areas. These are special sections of the page where editors can add one or more content widgets. A widget is a section of structured content, such as a block of rich text, an image, or a video. You can configure which widgets are allowed in a specific area in the ApostropheCMS field schema of a page or piece type.

For example, these are the widgets supported by the area field of the blog page type in the apostrophecms/starter-kit-astro project:

widgets: {
  '@apostrophecms/rich-text': {
   // extra configurations...
  },
  '@apostrophecms/image': {},
  '@apostrophecms/video': {},
  'two-column': {}
}

When an editor clicks on the “+ Add Content” button of that area, these will be the corresponding options that they will see:

To enable Astro to render the areas received from ApostropheCMS, you must define an Astro component for each ApostropheCMS widget in use. This is true even for basic widget types like @apostrophecms/image.

As a best practice, you should place all Astro widget components in the ./src/widgets folder of your project.

An Astro component is nothing more than a .astro file that contains some reusable UI elements. For example, this is how you could define the Astro component for the @apostrophecms/image widget:

---
// ./src/widgets/ImageWidget.astro

const { widget } = Astro.props;
const placeholder = widget?.aposPlaceholder;
const src = placeholder ?
  '/images/image-widget-placeholder.jpg' :
  widget?._image[0]?.attachment?._urls['full'];
---
<style>
  .img-widget {
    width: 100%;
  }
</style>
<img class="img-widget" {src} />

This will take care of rendering in an HTML <img> tag the image contained in the widget or a placeholder. For more information on how this component works, check out the documentation.

The apostrophecms/astro-frontend project currently ships only with the following Astro widget components:

RichTextWidget
ImageWidget
VideoWidget
TwoColumnWidget

If you use other widgets, you will have to manually add a component.

Once you have defined all the required Astro widget components, you need to list them in the mapping file specified in the aforementioned widgetsMapping option. In this case, this is what the ./src/widgets/index.js mapping file should contain:

// ./src/widgets/index.js

import RichTextWidget from './RichTextWidget.astro';
import ImageWidget from './ImageWidget.astro';
import VideoWidget from './VideoWidget.astro';
import TwoColumnWidget from './TwoColumnWidget.astro';

const widgetComponents = {
  '@apostrophecms/rich-text': RichTextWidget,
  '@apostrophecms/image': ImageWidget,
  '@apostrophecms/video': VideoWidget,
  'two-column': TwoColumnWidget
};

export default widgetComponents;

As you can see, this file imports all the Astro widget component files, associates them with the equivalent ApostropheCMS widget types in a mapping object, and exports it.

Mapping Apostrophe Templates to Astro Components

In ApostropheCMS, templates are where code and content become web pages. Specifically, templates are written in normal HTML markup with special tags and are based on the Nunjucks template language. Thus, they are .html files placed in the /views subfolder of an ApostropheCMS module.

Do not forget that the frontend of this application is handled entirely by Astro. So, just like what happened with widgets, you need to create an Astro component corresponding to each template that ApostropheCMS would normally render with Nunjucks.

Keep in mind that a template represents only a part of an entire web page. In other words, you do not want Astro to treat those components as routes. To prevent them from becoming Astro pages, avoid placing them in the ./src/pages folder. Instead, you should place your Astro template components in the ./src/templates directory.

Now, let’s look at how to write Astro template components. This is what a simple component for the template of the “default” page might look like:

---
// ./src/templates/DefaultPage.astro

import AposArea from '@apostrophecms/apostrophe-astro/components/AposArea.astro';
const { page, user, query } = Astro.props.aposData;
const { main } = page;
---

<section class="bp-content">
  <h1>{ page.title }</h1>
  <AposArea area={main} />
</section>

Notice that the Astro.props.aposData object received from ApostropheCMS gives you access to page, user, query, and other useful data. In particular, page represents the Nunjucks template and contains the area field of the page called main.

AposArea is a special component from the @apostrophecms/apostrophe-astro package that gives Astro the ability to render ApostropheCMS areas. That means it provides the standard ApostropheCMS in-context editing experience to the Astro frontend application. Behind the scenes, Astro will automatically render the widgets used in the area through the widget components mapped previously.

To see more Astro template component implementations, explore the ./src/templates folder of the apostrophecms/astro-frontend repository.

After defining all the necessary Astro template components, you have to list them in the mapping file specified in the aforementioned templatesMapping option. In this sample application, the ./src/templates/index.js mapping file will contain:

// ./src/templates/index.js

import HomePage from './HomePage.astro';
import DefaultPage from './DefaultPage.astro';
import BlogIndexPage from './BlogIndexPage.astro';
import BlogShowPage from './BlogShowPage.astro';
import NotFoundPage from './NotFoundPage.astro';

const templateComponents = {
  '@apostrophecms/home-page': HomePage,
  'default-page': DefaultPage,
  '@apostrophecms/blog-page:index': BlogIndexPage,
  '@apostrophecms/blog-page:show': BlogShowPage,
  '@apostrophecms/page:notFound': NotFoundPage
};

export default templateComponents;

This file imports all the Astro template component files, associates them with the equivalent ApostropheCMS template in a mapping object, and exports it.

For ordinary page templates, such as the home page or the “default” page type, just specify the name of the Apostrophe module. For special templates like notFound and for modules that serve more than one template, you have to specify the full name.

For instance, the page type @apostrophecms/blog-page has an index template to display the main blog page and a show template to display a single blog post. If you omit the specific template name, :page is assumed.

To map the 404 page to a component, use @apostrophecms/page:notFound. Also, bear in mind that the @apostrophecms/apostrophe-astro library involves two additional template names that can be mapped to custom components:

apos-fetch-error: Served when Apostrophe generates an HTTP 5XX error. In this case, Astro will respond with the 500 status code.
apos-no-template: Served when there is no mapping corresponding to the ApostropheCMS template.

Handle Routing in Astro via ApostropheCMS

In this setup, ApostropheCMS is responsible for managing URLs to content, including creating new content and pages on the fly. So, you will only need one top-level Astro page component matching all routes.

To define it, add a [...slug].astro dynamic route file in the ./src/pages folder of your project as follows:

---
// ./src/pages/[...slug].astro

import aposPageFetch from '@apostrophecms/apostrophe-astro/lib/aposPageFetch.js';
import AposLayout from '@apostrophecms/apostrophe-astro/components/layouts/AposLayout.astro';
import AposTemplate from '@apostrophecms/apostrophe-astro/components/AposTemplate.astro';

const aposData = await aposPageFetch(Astro.request);
const bodyClass = `myclass`;

if (aposData.redirect) {
  return Astro.redirect(aposData.url, aposData.status);
}
if (aposData.notFound) {
  Astro.response.status = 404;
}
---
<AposLayout title={aposData.page?.title} {aposData} {bodyClass}>
    <Fragment slot="standardHead">
      <meta name="description" content={aposData.page?.seoDescription} />
      <meta name="viewport" content="width=device-width, initial-scale=1" />
      <meta charset="UTF-8" />
    </Fragment>
    <AposTemplate {aposData} slot="main" />
</AposLayout>

The aposPageFetch() function from the @apostrophecms/apostrophe-astro library fetches the data for the current URL from ApostropheCMS. In detail, the aposData object will contain all of the information normally provided by data in an ApostropheCMS Nunjucks template. This includes:

page: The HTML template document associated with the current URL.
piece: The piece document, when visiting a "show page" of a particular piece page type.
pieces: An array of pieces, when visiting an "index page" of a given piece page type.
user: General information about the currently logged-in user.
global: The ApostropheCMS global settings.
query: The query parameters of the URL.

Any other custom data set by ApostropheCMS is also available here.

The AposLayout component finds the right Astro template component to render based on the template mapping defined earlier. It also automatically handles the switch between the editing UI when a user is logged in and the normal layout for visitors. AposLayout accepts four props:

aposData: The data fetched from ApostropheCMS.
title: The page title to set in the the <title> HTML tag.
lang: The language code to set in the <html> lang attribute.
bodyClass: The custom class attribute to add to the <body> element.

To override any aspect of the global layout, take advantage of the named Astro slots matching what template blocks ApostropheCMS offers in Nunjucks. In the example below, the standardHead <Fragment /> component is used to add a slot at the very beginning of the <head> element of the page.

Wonderful! Your Astro frontend project for an ApostropheCMS backend is ready!

Get Started With the ApostropheCMS Astro Application

Now that you know how to set up an Astro project and an ApostorpheCMS project that can communicate with each other, it is time to see the resulting application in action!

Here, we will assume that you cloned the two projects presented at the beginning of the article.

Start the Projects

To prevent other users from retrieving a lot of data from your ApostropheCMS backend without your permission, you must use the APOS_EXTERNAL_FRONT_KEY environment variable. Set that env to a secret value when running the Astro project and set the same variable to the same value when running the Apostrophe application.

Use the commands below to start your ApostropheCMS backend locally:

cd starter-kit-astro
npm install
export APOS_EXTERNAL_FRONT_KEY=<YOUR_SECRET>
npm run dev

By default, ApostropheCMS will start on port 3000. Visit http://localhost:3000 and you should see:

Similarly, run your Astro frontend with:

cd astro-frontend
npm install
export APOS_EXTERNAL_FRONT_KEY=<YOUR_SECRET>
npm run dev

By default, Astro will start on port 4321. Open http://localhost:4321 in your browser and you will see:

If you forget to set the APOS_EXTERNAL_FRONT_KEY environment variable, you will receive the following error message:

[ERROR] APOS_EXTERNAL_FRONT_KEY environment variable must be set, here and in the Apostrophe app

And the error page below:

Add an ApostropheCMS Admin User and Log In

As mentioned on the Astro frontend home page, the next step is to log in as an administrator. If you have already set up an admin user in the ApsotropheCMS project, you can skip to the next step.

Otherwise, run the following command inside the ApostropheCMS project folder to add an administrator user:

node app @apostrophecms/user:add myAdmin admin

Replace myAdmin with the name you want to give the user. During the process, you will be prompted for a password. Type it in and press ENTER.

Access the ApostorpheCMS Editing UI in Astro

Now, click on the login link or visit http://localhost:4321/login. Fill out the login form with your ApostropheCMS admin credentials:

Press the “Login” button, and you will get access to the editing UI:

Click on the "Edit" button in the upper right corner to enter the ApostropheCMS in-context editing mode:

Keep in mind that this is all happening in Astro, not in the ApostropheCMS application.

Create a Blog Page

The starter-kit-astro project is based on the ApostropheCMS @apostrophecms/blog module. This helps you create a blog in ApostropheCMS in just a few minutes. To understand how this module works and what it offers, read our dedicated guide.

To get started with the blog module, create a new page of type "Blog Page.” Click on the "Pages" option in the top left menu, then hit the "New Page” button:

Fill out the ApostropheCMS page creation modal by selecting the “Blog Page” type, and click “Publish:”

Visit the http://localhost:4321/blog and you will now see:

This corresponds to the ./src/templates/BlogIndexPage.astro template component in your Astro project. The page is currently empty as you still have to populate your blog with some posts. Learn how to do that in the next step!

Populate Your Blog

To create a new blog post, select “Blog post” in the top left menu and then click the "New Blog post” button. You will reach the following form:

Give your blog a title, a publication date, a slug, and write some content. Then, press "Publish.”

Add a few posts to your application and visit http://localhost:4321/blog again. This time, you will see:

Click on a blog post link and you will be redirected to the blog piece's show page:

Et voilà! You just used the ApostropheCMS content editing features to build your Astro site!

Next Steps

Part 1 of this two-article series ends here. Although the results achieved are pretty amazing, there is still a lot to be done. At the end of the day, the blog application is pretty ugly right now. In the next part, you will learn how to make your application more interactive and visually appealing using React components in Astro.

Continue with the article “How to Integrate Astro With ApostropheCMS pt. 2” to complete the ApostropheCMS / Astro integration.

How to Build an Ecommerce Website with ApostropheCMS

Antonello Zanini — Fri, 16 Feb 2024 21:15:29 +0000

Ecommerce sites are among the most popular and visited platforms on the Internet. There are many technologies available to create ecommerce platforms, and knowing how to build one is a critical skill to have in the IT world. While starting a new ecommerce project from scratch is good for learning purposes, isn't there a ready-made, more reliable solution for developers and their businesses? This is where the ApostropheCMS Ecommerce Starter Kit comes into play!

In this article, you will find out why building an ecommerce site from the ground up may not be the best approach. You will then explore an alternative and more effective method of kicking off an ecommerce site project thanks to the ApostropheCMS Ecommerce Starter Kit.

Why You Should Not Build an Ecommerce Platform From Scratch

Suppose you want to create an ecommerce site with popular technologies like Next.js, Vue.js, Laravel, or Angular. To have more control over the project, you may prefer to start from the ground up. Well, there are three major challenges if you want to go that route:

Development time and costs: Creating a robust ecommerce solution requires product, tag, and category management, content filtering, offers handling, and more. To implement those features, be prepared to invest dozens, if not hundreds, of hours in coding. That implies a significant financial investment in the project, without a guarantee of success.
Maintainability concerns: Completing the project and deploying it online is just the beginning. Maintaining a custom solution can be complex, requiring meticulous attention to updates, security patches, and industry standards.
Content management complexity: Most JavaScript framework allows you to present data nicely and crafting interactive pages, but what tools will you use for content management? Developing a user-friendly content management system (CMS) is a daunting challenge in itself. You could opt for a headless CMS, but integrating and configuring it properly takes time.

These non-negligible issues lead raise some doubts. Does it make sense to develop an ecommerce site from scratch? Isn’t out there a better solution? Of course, there is!

ApostropheCMS Ecommerce Starter Kit: The Solution You Were Looking For!

The ApostropheCMS Ecommerce Starter Kit serves as an open-source template for initializing a new JavaScript ecommerce project. In detail, the starter kit generates an ApostropheCMS project that provides all the features developers and content managers need to build an ecommerce platform.

If you are not familiar with that technology, ApostropheCMS is an open-source website builder and CMS developed with modern technologies such as Vue.js and Node.js. It enables editors to effortlessly create and manage content through an intuitive UI, while developers have the ability to customize the admin UI by overriding existing Vue.js components and extending it with new menus and field types. At the same time, you keep the ability to use your technologies of choice on the front end. Learn more in the documentation.

Thanks to the ApostropheCMS core, the ecommerce starter kit speeds up the creation of a fully functional ecommerce JavaScript project with advanced content management capabilities, a focus on user experience, and a clear path for further development. Thus, it gives content managers the ability to define tags, products, and categories and use them to design engaging ecommerce pages through a useful set of built-in widgets.

In other words, the Ecommerce Starter Kit for ApostropheCMS equips editors, marketers, and developers with everything they need to create an efficient, effective, eye-catching ecommerce platform that delivers a high-quality user experience to customers.

This starter Kit has been created by Corllete in partnership with Apostrophe. From a technical point of view, the ecommerce project is based on several UI components. Each of them relies entirely on Tailwind CSS for styling, with no additional CSS files. These components are organized in macros and fragments coming from the default server-side template engine Nunjucks.

The advantages of this approach to creating an ecommerce store are:

Quick development.
Built-in content management functionality.
Excellent UX and highly customizable UI.

Now, learn how to use it in the guided section below!

Create an Ecommerce Site With ApostropheCMS

Follow this step-by-step tutorial to learn how to use the Apostrophe CMS Ecommerce Starter Kit to create a full-featured ecommerce site in minutes.

You can find the complete documentation on how to get the most out of this starter kit below:

Let’s dive in!

Set Up an Ecommerce Starter Project
Keep in mind that the Ecommerce Starter Kit for ApostropheCMS is not designed to be installed into an existing project. So, you will have to create a new project from scratch. Before getting started, make sure to meet the requirements for Apostrophe 3+.

Next, launch the command below to initialize an ApostropheCMS project using the ecommerce starter:

apos create my-apostrophe-ecommerce-site --starter=ecommerce

Here, my-apostrophe-ecommerce-site is the name of the project, while ecommerce is the starter used to create the new boilerplate project. Follow the procedure to add an admin user. For finishing touches or more information, take a look at the official setup guide.

Run the local development server with:

npm run dev

Visit the login page at http://localhost:3000/login and use the credentials you set up earlier to log in as an admin. This is what you should be seeing:

Awesome! You now have everything you need to start working on your ApostropheCMS ecommerce platform.

Add Some Products and Categories
The first thing to do is to populate your ecommerce with some data. The ApostropheCMS ecommerce starter comes with the following types of pieces:

Content Tag: A label to describe products and product categories.
Product Category: A set of tags.
Product: An item for sale in the ecommerce platform.

Since the project's content taxonomy is based on tags, start by adding some Content Tag pieces. To do so, click “Content” in the upper left corner, select the “Content Tags” options, and click the “New Content Tag” button on the right:

You will reach the following form:

Populate the “Title” field and press “Save” to add a new Content Tag record. Repeat the procedure to create all the tags you need.

Examples of tags are “Shoes,” “T-Shirts,” “Bracelets,” “Necklaces,” “Kids,” “Adults,“ “Women,” “Men,” “Unisex,” “Summer Collection,” “Winter Collection”, “September Sale,” “Black Friday Sale,” etc.

Next, add some “Product Category” records. If you do not plan to use categories, you can skip this part. Otherwise, click “Content,” “Product Categories”, and then the “New Product Category” button. You will reach the following form:

Note that a product category can either correspond to a single tag or cover multiple tags. Thus, you could define the category “Shoes” that corresponds to the tag “Shoes” as well as the category “Accessories” for the tags “Bracelets” and “Necklaces.” By default, the category page associated will automatically show only products that have at least one tag in common among the selected ones.

In the “Page” tab, you can add UI elements that will appear at the top or the bottom of the specific product page (e.g., a call to action or a promo). Instead, the “SEO” and “Open Graph” tabs allow you to specify information for internal search and search engine indexing.

Once you are done, click “Publish” to create a new category for your product. Repeat the procedure to add as many product categories as you need.

You are finally ready to add some products! Open the “Content” menu, select “Products,” and then click on “New Product.” As you can see from the GIF below, the product form allows you to enter a lot of useful information:

Here, you can upload multiple images, define the price and the discounted price, describe the product's details, add up to 4 meta fields, and more. In particular, there is also a “Buy Now URL” for integration with any online service that provides buy Now URL functionality. Through this, users will have the ability not only to explore products but also to buy them.

In the “Page” tab, you can also customize the elements that will appear at the end of the page (i.e., add a promo or a specific call to action). Do not forget to explore the “SEO” and “Open Graph” tabs to define how search engines will index the page and how the link to the product page will be rendered on social platforms. To find out more, read the SEO and Open Graph section of the starter documentation.

When you are satisfied with the data you have entered, press “Publish” to make the product public. To add new products, perform this procedure again.

Great! You now know how to handle content on your ecommerce site.

Create the Essential Pages
The first step to making your ecommerce site work properly is to add a product page. That is nothing more than a landing page to show all the products in your online store. To create it, click “Pages” in the upper left corner, then press the “New Page” button on the right, and add a new page of the type “Product:”

At this point, you will have the form below in front of you:

Give your product page a title and a unique slug and click the “Publish” button. By default, the product page will show a list of all your products. If you want to add extra elements at the bottom of the page, you can do it through the rich-text field “Content,” but that is optional. In detail, the ApostropheCMS ecommerce starter pack comes with a set of widgets specifically designed for an online store:

Check out the docs to learn how these widgets work and what they offer.

After publishing the product page, you are ready to explore it and see how it presents the list of all your products. Suppose the product page you just created has products as its slug page. To open it, visit http://localhost/3000/products in your browser. This is what you will see:

As anticipated earlier, it contains a list with all the products available on your site. If you click on one of the product cards, you will be redirected to the detail page with all the information about the selected product. For example, here is what the product detail page for the “Air Pro 47” sports shoes looks like:

Note that it automatically presents all the information you provided for the product in a visually appealing way.

Amazing, the ecommerce store is starting to come alive!

If your ecommerce site uses categories, you will also need to define a category page. To do so, create a new page of type “Product Category." This will automatically show a list of the available product categories:

To learn more about products and categories, see the dedicated page on the ecommerce starter documentation.

Populating the Home Page
Your ecommerce site is starting to take shape, but the home page is still completely blank. Time to fix that!

Visit http://localhost:3000 and click the “Edit” button on the right to enter the ApostropheCMS in-context live editing mode:

Here, you can customize the content of your home page:

For example, you could add a hero section, followed by a list of the latest products added to the site, followed by a promo and the list of categories as below:

Fantastic! You are almost there!

Add Some Custom Pages
To promote your products and raise brand awareness, your ecommerce site is likely to need some additional pages. This is why the ApostropheCMS Ecommerce Starter Kit enables content creators and marketers to define custom pages.

To add a custom page, click on “Pages” in the top left menu, press “New Page,” and create a new page of type “Default:”

You might use this feature to add an “About Us” page or some landing pages. For example, you could create the following landing page to promote your summer collection:

Explore the documentation to learn more about custom pages.

Customize Your Ecommerce Site
Your ecommerce platform only requires the finishing touches. Get ready to make your ApostropheCMS ecommerce site unique!

Click on the gear icon at the top right to open the global site settings:

Here you can customize your company logo, site favicon, colors, navigation links, and more:

You can also enable the search feature by choosing the “Page” type and selecting the “Search” page as explained in the documentation:

That allows users to find pages based on the content of the “SEO — Description” field or “Tagline” field:

Notice that not all customizations supported by the starter kit are available through that configuration modal. For example, if you want to change the brand palette, you must overwrite the APP_BRAND env before running the npm build command. Find all available color palettes in the /colors folder of your project.

Suppose you want to test the purple palette locally. Then, launch the local development server with:

APP_BRAND="purple" npm run dev

If you like that and want to use it in production, you will have to build your ecommerce project with:

APP_BRAND="purple" npm run build

This is what your new site will look like:

Note the new logo, navigation menu, and how the palette has changed from aquamarine to purple.

Do not forget that all ecommerce components are styled via Tailwind. You can find the Tailwind configuration in tailwind.config.js file in the root folder of the project. Refer to the official Tailwind CSS documentation for more information about the options you can set. For example, you could modify some Tailwind classes used in the application to fit your project needs.

You can also define a custom brand palette for your site, again using Taliwind. Find out more on how to customize the style of your ecommerce site in the Tailwind CSS section in the developer documentation.

For more branding and UI customizations, follow the instructions in the developer documentation.

Et voilà! Your ecommerce platform is finally ready. It is time to see it in action!

Put It All Together
This is what your ecommerce webshop may look like:

Congratulations! Thanks to the ApostropheCMS ecommerce starter kit, you were able to set up a full-featured ecommerce site in minutes and with a handful of lines of code!

Next Steps

The tutorial is over, but there are still some features you can add to improve this project! In this guide, you learned how easy and quick it is to set up a JavaScript ecommerce project with the ApostropheCMS Ecommerce Starter Kit. The next steps include:

Add a shopping cart: Offer complete cart functionality through a shopping cart provider such as Snipcart. Learn more about ApostropheCMS and Snipcart integration.
Integrate a payment system platform: Add a secure payment system platform that supports several payment methods such as Stripe or Braintree.

ApostropheCMS has proven to be a modern and efficient solution to help businesses build ecommerce sites. This is just a taste of what that technology can do. Explore Apostrophe today!

Introducing the Apostrophe / Astro Integration

The Apostrophe Team — Fri, 16 Feb 2024 18:57:25 +0000

What’s the big news?

In another step towards making Apostrophe the most dynamic, feature-rich website ecosystem for building and maintaining your website, our team is pleased to announce the integration for the Astro web framework.

What is Astro?

Astro is a free, open-source software that enables users to build fast, content-driven websites with an emphasis on ease-of-use. It operates using a BYOF or “Bring Your Own Framework” model that makes it compatible with popular JS frameworks such as React, Svelt, or Vue. Some other key features of Astro’s technology include static site generation, component-based architecture, and built in automations. You can read more on Astro’s website.

What does the integration mean for Apostrophe users?

With the new integration comes the ability to let Apostrophe manage your content, handle routing of URLs and fetch content, and let Astro take the responsibility for the rendering of pages and any associated logic using your framework(s) of choice. Additionally, you can now bring the ApostropheCMS Admin UI into your Astro application, meaning can manage your site exactly as if you were in a "normal" Apostrophe instance.

Why is this such a big deal? Apostrophe has always been great for providing a rich live editing experience for marketing teams. When we originally introduced our native REST APIs in A3, we made it easier than ever to use Apostrophe as a headless CMS. However, it’s always been harder than it should be to deliver our standard fully WYSIWYG editing experience when running Apostrophe in headless mode. This new integration is an incredible solution to that puzzle, and we’re thrilled that we can now support such an elegant option for delivering a rich, in-context editing experience within a headless architecture.

How to get started…

There’s more information about these exciting new capabilities and instructions on how to use the integration at the Astro docs and on our Extensions page. Head over there now to get setup and install the module.

What’s next?

If you have questions about Astro or how to leverage some of the new features, feel free to reach out to us directly or, better yet, bring your feedback to Apostrophe’s Discord Community so others can benefit as well.

Lastly, we’d love to see you at our next live Show & Tell event on January 25th! We’ll be hosting an open discussion around some of the more commonly used JS frameworks, including some of the ones mentioned earlier in this announcement, and how to use them with Astro. It’s all going down in the Discord, see you there!

Digging Into HTMX: Examples and How to Use It

Antonello Zanini — Fri, 08 Dec 2023 17:15:21 +0000

HTMX aims to provide access to modern browser functionality directly in HTML code, without a single line of JavaScript. Even though version 1.0 of the library was launched just a few years ago, in late 2020, the project has already become incredibly popular. As of this writing, it has more than 20k stars on GitHub and has been accepted into the GitHub Open Source Accelerator!

Why is the web developer community so excited about it? Embark on this journey and find out! You will learn how to build modern user interfaces with simple hypertext.

What Is HTMX?

HTMX is a small, dependency-free, extendable library that allows you to access modern browser features directly from HTML, instead of using JavaScript. Specifically, it gives you access to AJAX (i.e., fetching content without reloading the whole page), CSS Transitions, WebSockets, and Server Sent Events directly via HTML attributes. The motivation behind the project is to overcome the limitations imposed by HTML to make it a true hypertext.

The easiest way to understand what we are talking about? An example! Take a look at this snippet:

<button hx-get="/api/v1/hello-world" hx-swap="outerHTML">Click Me</button>

The special hx-get and hx-swap attributes tell HTMX:

“When a user clicks on this button, instruct the browser to perform an AJAX request to the ‘/api/v1/hello-world’ endpoint, and replace the entire button with the HTML content returned by the server”

In JavaScript, achieving the same result would take dozens of lines of code. That is the power of HTMX!

How We Got to HTMX: From HTML to HTMX

Web development has evolved a lot since its early days. It started with static web pages, where manual updates to HTML files were the norm. The introduction of JavaScript added interactivity, opening the door to a new era. AJAX then completed the revolution, enabling seamless content updates and new interactions.

Over time, frameworks like React, Vue, and Angular took the stage and became the standard. These technologies are great for structured applications. However, they also involve a lot of complexity, and sometimes you want to keep things simple. That is why HTMX!

HTMX aims to achieve efficient interactivity without the complexity of traditional JavaScript setups. In particular, it extends HTML with custom attributes, allowing the execution of AJAX requests without JavaScript. It also integrates seamlessly with existing technology stacks to provide an improved user experience without a complete overhaul.

Let’s now explore the features and syntax of HTMX!

HTMX Overview: Syntax, Features, and Capabilities

The core idea behind HTMX is the ability to send AJAX requests directly from HTML, with no JavaScript involved. This is possible thanks to the following attributes:

hx-get: To perform a GET request to the given URL.
hx-post: To perform a POST request to the given URL.
hx-put: To perform a PUT request to the given URL.
hx-patch: To perform a PATCH request to the given URL.
hx-delete: To perform a DELETE request to the given URL.

When a specific event is triggered, the HTML element involving one of these HTMX attributes will make an AJAX request of the specified type to the given URL. Consider the example below:

<button hx-post="/api/v1/products/buy">Buy</button>

This tells the browser:

“When a user clicks on the <button>, make a POST request to the URL ‘/api/v1/products/buy’ and load the response into the inner HTML of the <button>”

How can a single line of HTML result in that behavior? Well, the aspects to consider when making an AJAX request are three:

When to perform the request
The query parameters and/or body to send
What to do with the response

Time to dig into how HTMX handles them!

Request Triggers
By default, AJAX requests made by HTMX are triggered by the “natural” event associated with the HTML element:

change: For <input>, <textarea> and <select> elements.
submit: For the <form> element.
click: For every other element.

Going back to the snippet seen earlier, it should now be clear why the action that triggers the request is a click, even if not specified.

To modify the default trigger behavior, you can use the hx-trigger attribute to set which HTML event will cause the request. Check out the list of events supported by HTML.

Take a look at the example below:

<span hx-get="/api/v1/products" hx-trigger="mouseenter">Hover Me!</span>

This tells the browser:

"When a user moves the mouse over the <span>, perform a GET request to the URL ‘/api/v1/products’ and render the response in the inner HTML of the <span>”

Keep in mind that hx-trigger also supports modifiers and filters to tailor the triggering logic to your needs. Plus, HTMX provides the following special events:

load: Fires when the element is loaded for the first time.
revealed: Fires once when the element is scrolled into the viewport.
intersect: Fires once when the element intersects with the viewport. As opposed to revealed, it accepts an optional CSS selector of the root element for intersection and a float number between 0.0 and 1.0 to indicate the amount of intersection to trigger the event on.

Query Parameters and Body Data
The way HTMX handles parameters and body data changes depending on the type of the request:

GET requests: The query parameters should be specified in the URL passed to hx-get. By default, hx-get does not automatically include any parameters to the request. Anyway, you can control that with the hx-params attribute as explained in the documentation.
Non-GET requests: If an element is a <form>, the body will include the values of all inputs within it, using their name attribute as the parameter name. If it is not a <form>, the body will include the values of all the inputs of the nearest enclosing <form>. Otherwise, if it has a value attribute, it will be used in the body. When the default behavior is not enough, the hx-include and hx-params attributes allows you to control which values and which parameters to set, respectively. Otherwise, you can programmatically modify the body fields by listening to the htmx:configRequest event.

Result Content Handling
By default, HTMX replaces the inner HTML of the element firing the request with the HTML returned by the AJAX call. This means that HTMX-compliant AJAX endpoints should return HTML code.

To change the swap strategy, use the hx-swap attribute. That supports the following values:

innerHTML: Replace the inner HTML of the target element.
outerHTML: Replace the entire target element with the response.
beforebegin: Insert the response before the target element.
afterbegin: Insert the response before the first child of the target element.
beforeend: Insert the response after the last child of the target element.
afterend: Insert the response after the target element.
delete: Delete the target element regardless of the response.
none: Does not append the content from the response.

You can change the target element the swap logic refers to with the hx-target attribute, which accepts a CSS selector. Note that the attribute supports multiple triggers, each one separated by comma.

Focus now on the following snippet:

<button 
  hx-post="/api/v1/comments"
  hx-trigger="click" 
  hx-swap="afterend" 
  hx-target=".comments"
  >
Comment
</button>

This tells the browser:

“When a user clicks the <button>, perform a POST request to the URL ‘/api/v1/comments’ and add the resulting HTML to the .comments element”

HTMX in Action: Integration With ApostropheCMS

You now know what HTMX is, why it was created, and what it brings to the table. All that remains is to see it in action in a real-world example. What better way to do that than by integrating it with Apostrophe? If you are not familiar with this technology, ApostropheCMS is an open-source CMS and website builder built on top of modern technologies such as MongoDB and Node.js.

As ApostropheCMS is unopinionated on the frontend, it represents a natural fit for HTMX. Its data management and website building capabilities will make it easy and intuitive to dynamically retrieve and render HTML content via HTMX.

In this step-by-step section, you will look at how to integrate HTMX into an existing application. The starting point will be the blog application built in the “How to Build a Blog with the Apostrophe Blog Module” tutorial. You will learn how to add HTMX and use it to achieve the following dynamic interactions:

“Load More” functionality
Infinite scroll loading
Live content filtering

Let’s dive in!

Getting Started
First, make sure to meet ApostropheCMS's system requirements. Next, launch the command below to clone the GitHub repository of the blog application you will soon extend with HTMX:

git clone https://github.com/Tonel/apostrophe-blog

Install the project’s dependencies:

npm install

Then, fire the following command to build the ApostropheCMS UI and start up the blog:

npm run dev

Open https://localhost:3000 in the browser and you should see:

Follow the instructions, log in, and get familiar with the application. Play with the UI and populate the blog with several posts.

You can then find the blog's home page at http://localhost:3000/blog.

Great! If you want to learn more about how this application works and was built, take a look at our tutorial.

Integrating HTMX
As stated in the documentation, integrating HTMX into an application boils down to adding a <script> tag to the document <head>. No build tools or special configurations are required.

The fastest way to get going is to load the library via a CDN:

<script src="https://unpkg.com/htmx.org@1.9.6" integrity="sha384-FhXw7b6AlE/jyjlZH5

The goal of this section is to use HTMX to add dynamic interactions to the blog home page. So, you need to add the <script> instruction to the HTML document of that page.

To add HTMX to the blog home page, follow the /modules/@apostrophecms/blog-page/views/ path and open the index.html file. Paste the following line after the title block:

{% block extraHead %}
  <script src="https://unpkg.com/htmx.org@1.9.6" integrity="sha384-FhXw7b6AlE/jyjlZH5iHa/tTe9EpJ1Y55RjcgPbjeWMskSxZt1v9qkxLJWNJaGni" crossorigin="anonymous"></script>
{% endblock %}

extraHead is a block from the ApostropheCMS core layout template that allows you to add HTML elements at the end of the <head> tag.

If you instead want to have HTMX in all pages, you can add it to your project's dependencies with:

npm install htmx.org

Then, import it in the modules/asset/ui/src/index.js file:

import 'htmx.org';

export default () => {
  // your own project-level JS...
};

Open http://localhost:3000/blog in the browser and inspect its source code. You should see the following HTML:

<!DOCTYPE html>
<html lang="en" >
  <head>
    <link href="/apos-frontend/default/apos-bundle.css" rel="stylesheet" />
    <title>My Fantastic Blog </title>
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <script src="https://unpkg.com/htmx.org@1.9.6" integrity="sha384-FhXw7b6AlE/jyjlZH5iHa/tTe9EpJ1Y55RjcgPbjeWMskSxZt1v9qkxLJWNJaGni" crossorigin="anonymous"></script>
  </head>
<!-- Omitted for brevity... -->

Well done! The HTMX dependency script was added as required.

Adding a Load More Button With HTMX
Right now, when the blog has more than 10 posts, the home page shows a pagination element.

Click on one of these buttons, and you will be redirected to the selected page. For example, “2” brings you to /blog?page=2. What if you wanted to replace that interaction with a “Load More” button? Thanks to HTMX, that will take only a few lines of code!

When the “Load More” button is clicked, the page should perform an AJAX request to retrieve the HTML to render other blog post cards. You could think of using HTMX to make the button target the /blog?page=2 endpoint and swap the current content with the retrieved HTML. However, keep in mind that /blog?page=2 returns the entire HTML of a new page. Following this approach is not recommended, as you ideally want to replace only a small portion of the page not the all the page. Specifically, you want to swap the “Load More” button with the new blog post tabs.

To get close to the goal, you can take advantage of the aposRefresh=1 parameter. This query parameter instructs ApostropheCMS to return the rendered HTML of the inner template, excluding the wrapping markup.

For example, the /blog?page=2&aposRefresh=1 endpoint returns something like:

<div class="bg-container">
  <h1 class="bg-h1">My Fantastic Blog</h1>
  <h2>Filters</h2>
  <ul class="bg-filter-list">
    <li>
      <a href="/blog?year=2023">2023</a>
    </li>
    <li>
      <a href="/blog?year=2022">2022</a>
    </li>
    <li>
      <a href="/blog?year=2021">2021</a>
    </li>
    <li>
      <a class="is-active" href="/blog">All</a>
    </li>
  </ul>
  <h2>Blog post</h2>
  <div class="bg-preview-card">
    <div class="bg-preview-date">
      Released on September 4, 2022
    </div>
    <div class="bg-preview-title">
      <a href="/blog/lorem-ipsum-8">Lorem Ipsum 8</a>
    </div>
  </div>
  <div class="bg-preview-card">
    <div class="bg-preview-date">
      Released on August 2, 2022
    </div>
    <div class="bg-preview-title">
      <a href="/blog/lorem-ipsum-12">Lorem Ipsum 12</a>
    </div>
  </div>
  <!-- Omitted for brevity... -->
</div>

Much better! As you can see, this HTML involves only a partial section of the page. At the same time, it still includes the title and filter elements. To ignore them, you can change the index.html file so that it behaves differently based on the presence of a custom query parameter.

Achieve that by updating the rendering logic inside the main block of /modules/@apostrophecms/blog-page/views/index.html as follows:

{% block main %}
  {% if data.query.showOnlyList != "1" %}
    <div class="bg-container">
      <h1 class="bg-h1">{{ data.page.title }}</h1>
      <h2>{{ __t('aposBlog:filters') }}</h2>

      {% render filters.render({
           filters: data.piecesFilters,
           query: data.query,
           url: data.page._url
      }) %}

      <h2>{{ __t('aposBlog:pluralLabel') }}</h2>

      {{ renderBlogList() }}
    </div>
  {% else %}
    {{ renderBlogList() }}
  {% endif %}
{% endblock %}

Now, when the showOnlyList=1 query parameter is present, the endpoint for the blog home page will return only the list of blog posts. Otherwise, it will return the entire page as before.

You may be wondering what renderBlogList() is. This is a custom Nunjucks macro that renders the list of blog post cards and the “Load More” button:

{% set page = data.query.page | default(1) | int %}
  {% for piece in data.pieces %}
    <div class="bg-preview-card">
      <div class="bg-preview-date">
        {{ __t('aposBlog:releasedOn') }} {{ piece.publishedAt | date('MMMM D, YYYY') }}
      </div>
      <div class="bg-preview-title">
        <a href="{{ piece._url }}">{{ piece.title }}</a>
      </div>
    </div>
  {% endfor %}
  <div class="load-more-div">
    {% if page != data.totalPages %}
      <button
        hx-get="/blog?page={{page + 1}}&year={{data.query.year}}&showOnlyList=1&aposRefresh=1"
        hx-target=".load-more-div"
        hx-swap="outerHTML"
      >
        Load More
      </button>
    {% endif %}
  </div>
{% endmacro %}

Focus on the .load-more-div HTML element. That is where the HTMX magic happens!

page is a variable that stores the current page of the blog posts to render. If there are still some blogs to load, the “Load More” button is added to the page. When the user clicks it, the webpage makes an AJAX request to the endpoint specified in hx-get. This will return the rendered HTML with the list of the posts related to the next page, considering the optional year filter. HTMX will then replace the outer HTML of the .load-more-div element with that content.

Put it all together, and you will get:

<!-- /modules/@apostrophecms/blog-page/views/index.html -->

{% extends data.outerLayout %}

{% import "filters.html" as filters %}
{% import "@apostrophecms/pager:macros.html" as pager with context %}

{% block title %}{{ data.page.title }} {% endblock %}

{% block extraHead %}
  <script src="https://unpkg.com/htmx.org@1.9.6" integrity="sha384-FhXw7b6AlE/jyjlZH5iHa/tTe9EpJ1Y55RjcgPbjeWMskSxZt1v9qkxLJWNJaGni" crossorigin="anonymous"></script>
{% endblock %}

{% macro renderBlogList() %}
  {% set page = data.query.page | default(1) | int %}
  {% for piece in data.pieces %}
    <div class="bg-preview-card">
      <div class="bg-preview-date">
        {{ __t('aposBlog:releasedOn') }} {{ piece.publishedAt | date('MMMM D, YYYY') }}
      </div>
      <div class="bg-preview-title">
        <a href="{{ piece._url }}">{{ piece.title }}</a>
      </div>
    </div>
  {% endfor %}
  <div class="load-more-div">
    {% if page != data.totalPages %}
      <button
        hx-get="/blog?page={{page + 1}}&year={{data.query.year}}&showOnlyList=1&aposRefresh=1"
        hx-target=".load-more-div"
        hx-swap="outerHTML"
      >
        Load More
      </button>
    {% endif %}
  </div>
{% endmacro %}

{% block main %}
  {% if data.query.showOnlyList != "1" %}
    <div class="bg-container">
      <h1 class="bg-h1">{{ data.page.title }}</h1>
      <h2>{{ __t('aposBlog:filters') }}</h2>

      {% render filters.render({
           filters: data.piecesFilters,
           query: data.query,
           url: data.page._url
      }) %}

      <h2>{{ __t('aposBlog:pluralLabel') }}</h2>

      {{ renderBlogList() }}
    </div>
  {% else %}
    {{ renderBlogList() }}
  {% endif %}
{% endblock %}

Note that the pagination element has been removed by the template. You no longer need it.

Style the “Load More” button in /modules/asset/ui/src/scss/_blog.scss, and you are ready to test it. This is how your new http://localhost:3000/blog page behaves:

If you inspect the “Network” section of the browser's DevTools, you will notice that the “Load More” button triggers the following AJAX call:

This will return the HTML containing the new blog post cards to add to the page.

Congrats! You just used HTMX to add a click-to-load feature to your blog.

Note: You can find the entire code of this example in the htmx-load-more branch of the GitHub repository supporting the article.

Using HTMX to Implement Infinite Scrolling
Now that you have seen how to implement a “Load More” button with HTMX, achieving infinite scrolling is easy. All you have to do is change the renderBlogList() function as follows:

{% macro renderBlogList() %}
  {% set page = data.query.page | default(1) | int %}
  {% for piece in data.pieces %}
    <div class="bg-preview-card"
       {% if loop.last %}
           hx-get="/blog?page={{page + 1}}&year={{data.query.year}}&showOnlyList=1&aposRefresh=1"
           hx-trigger="revealed"
           hx-swap="afterend"
       {% endif %}
    >
      <div class="bg-preview-date">
        {{ __t('aposBlog:releasedOn') }} {{ piece.publishedAt | date('MMMM D, YYYY') }}
      </div>
      <div class="bg-preview-title">
        <a href="{{ piece._url }}">{{ piece.title }}</a>
      </div>
    </div>
  {% endfor %}
{% endmacro %}

The revealed HTMX event triggers when an element is scrolled into the viewport. By adding it to the last blog post card, you can implement infinite scroll loading behavior:

Awesome! Focus on the scrollbar to notice that the page adds dynamic content as the user scrolls down.

Note: You can find the complete code of this example in the htmx-infinite-scrolling branch.

Achieving Live Content Filtering Through HTMX
The goal here is to use HTMX to dynamically update the content of the page when clicking on a year filter button. In this case, you do not have to update the blog post list, but replace it entirely. Also, you need to override the HTML section that contains the filters to ensure that the correct button is enabled.

First, update filters.html to introduce the HTMX logic:

<!-- /modules/@apostrophecms/blog-page/views/filters.html -->

{%- macro here(url, changes) -%}
{{ url | build({
year: data.query.year
}, {
excludeContainer: 1,
aposRefresh: 1
}, changes) }}
{%- endmacro -%}

{% fragment render(data) %}
  <ul class="bg-filter-list">
    {% for year in data.filters.year %}
      <li>
          <button
            class="{{ 'is-active' if data.query.year == year.value }}"
            hx-get="{{ here(data.url, { year: year.value })}}"
            hx-target=".blog-page"
            hx-swap="outerHTML"
          >
            {{ __t(year.label) }}
          </button>
      </li>
    {% endfor %}
</ul>
{% endfragment %}

Note that the year filter elements are no longer links, but buttons that target a specific endpoint via HTMX. In particular, here() has been updated to produce the URL required to dynamically retrieve the desired HTML content. Keep in mind that build() accepts as many query parameter objects as you need.

The excludeContainer query parameter will control the rendering logic in the index.html file as below:

<!-- /modules/@apostrophecms/blog-page/views/filters.html -->

{% extends data.outerLayout %}

{% import "filters.html" as filters %}
{% import "@apostrophecms/pager:macros.html" as pager with context %}

{% block title %}{{ data.page.title }} {% endblock %}

{% block extraHead %}
  <script src="https://unpkg.com/htmx.org@1.9.6" integrity="sha384-FhXw7b6AlE/jyjlZH5iHa/tTe9EpJ1Y55RjcgPbjeWMskSxZt1v9qkxLJWNJaGni" crossorigin="anonymous"></script>
{% endblock %}

{% block main %}
  {% if data.query.excludeContainer != "1" %}
    <div class="bg-container">
      <h1 class="bg-h1">{{ data.page.title }}</h1>
  {% endif %}
     <div class="blog-page">
        <h2>{{ __t('aposBlog:filters') }}</h2>
        {% render filters.render({
             filters: data.piecesFilters,
             query: data.query,
             url: data.page._url
        }) %}
        <h2>{{ __t('aposBlog:pluralLabel') }}</h2>
        {% for piece in data.pieces %}
          <div class="bg-preview-card">
            <div class="bg-preview-date">
              {{ __t('aposBlog:releasedOn') }} {{ piece.publishedAt | date('MMMM D, YYYY') }}
            </div>
            <div class="bg-preview-title">
              <a href="{{ piece._url }}">{{ piece.title }}</a>
            </div>
          </div>
        {% endfor %}
        <div class="pagination">
          {{ pager.render({ page: data.currentPage, total: data.totalPages }, data.url | build({ excludeContainer: null })) }}
        </div>
      </div>
  {% if data.query.excludeContainer != "1" %}
    </div>
  {% endif %}
{% endblock %}

The home page of the blog will now have real-time filtering capabilities:

Awesome! You have just learned how HTMX simplifies the integration of dynamic interactions into an existing frontend application.

The next step is to add a loader through the hx-indicator attribute. Check out the docs to see all the other cool features HTMX has to offer!

Note: You can find the entire code of the example in the htmx-content-filtering branch.

Is HTMX the Future of Web Development?

HTMX is not here to replace React and similar frameworks. That should be clear. Instead, it presents a compelling solution for specific web development scenarios backed by its feature set.

To be specific, HTMX proves particularly well-suited for:

Efficient interactivity: It represents a lightweight solution compared to most JavaScript frameworks, making it an excellent choice to keep projects simple and lean.
Seamless integration: It natively supports integration with various technologies, such as ApostropheCMS, Django, and Flask.
Minimal overhead: It simplifies web development via custom HTML attributes, removing the complexity associated with modern JavaScript development.

In short, HTMX fills a niche where its capabilities shine, providing a valuable tool for web developers seeking efficient and seamless interactivity.

Conclusion

In this article, you explored HTMX, understanding what the library is, why it was born, what capabilities it provides, and why it is so popular. You learned how to get started with HTMX and how to use it to extend an existing ApostropheCMS application with dynamic interactions such as infinite scrolling. Once again, ApostropheCMS has proven to be a modern, solid, forward-looking technology that can support fresh libraries thanks to its unopinionated approach on the frontend. Try Apostrophe today!

How To Set Up the Template Library Pro Module in Apostrophe

Antonello Zanini — Thu, 02 Nov 2023 11:30:00 +0000

Code reuse is one of the fundamental pillars of programming. After spending time defining a UI component, procedure, or function, developers want to reuse what they have built as much as possible. But what about content creation? Editors also invest a lot of time in crafting quality content or devising original layouts. They, too, should have the opportunity to reuse what they create. This is where Apostrophe Template Library comes in!

This powerful Apostrophe Pro module transforms the way editors can approach content creation and design in the digital world. In detail, Template Library allows content creators to create and manage both layout and content templates directly in Apostrophe. The idea behind the module is to create content once and reuse it multiple times with just a few changes.

In this step-by-step tutorial, you will understand what Apostrophe Pro’s Template Library module is, how to set it up, and what it has to offer.

Let's dive in!

What Is the Apostrophe Template Library Module?

The Template Library module is an Apostrophe Pro extension. Its goal is to allow product managers to create and manage reusable templates. Specifically, each template must be related to an existing page type or piece type.

In other words, there are two types of templates supported by the Pro module:

Page templates: An existing page can become a reusable template that editors can apply to new pages to simplify the design process.
Piece templates: An existing piece instance can become a reusable template that editors can apply to new pieces to facilitate the creation of new content instances.

Note: @apostrophecms-pro/doc-template-library is the name of the npm package of the Template Library module.

Benefits of the Template Library Extension

The Template Library is a powerful tool that provides a lot of benefits to editors. Take a look at the three most important reasons why you should enable it in your Apostrophe application:

Enhanced Reusability: Promoting a culture of element reuse is what a templating library is all about. After spending a lot of time designing layouts and creating great content, editors can save them in templates with just a few clicks and reuse them whenever they wish. Just think, “design once and reuse many times!”
Improved Productivity: The module eliminates the need to start from scratch when defining content or designing new pages. This significantly boosts the productivity of content managers, allowing them to focus more on what matters the most.
Increased Consistency: Templates ensure that each new page or piece adheres to established style guidelines and design principles. This helps teams maintain a consistent look and feel, which is critical to building excellent user experiences.

Setting Up the Template Library Pro Module in Apostrophe

In this section, you will learn how to integrate Template Library into your Apostrophe project.

Since the Template Library is a Pro module, you first need to join Apostrophe Pro. Keep in mind that the module is also available in Apostrophe Assembly. Check our pricing page to compare our plans and find the solution that best suits you.

You will need an Apostrophe 3+ application to follow the tutorial below. If you do not already have one, read the setup guide in our documentation. Make sure you meet the requirements and then follow the instructions to create an Apostrophe 3+ project.

Time to set up the Template Library module!

Install the Template Library Module

After joining Apostrophe Pro, you will be added to the @apostrophecms-pro npm organization. However, if you npm install Pro modules in your projects directly, you will get the following 404 error: '@apostrophecms-pro/<pro_module_package_name>@*' is not in this registry.

The reason is that you must first authenticate your npm commands. In a development environment, the easiest way to do so is by running the following command: npm login

Press ENTER and the npm login page will automatically open in your browser. Type in your credentials and click the “Sign In” button.

Once logged in, go back to your project. You should see the success message below in your terminal: Logged in on https://registry.npmjs.org/

To keep the session alive, npm will create a global .npmrc configuration file for you containing the line below: //registry.npmjs.org/:_authToken=<YOUR_NPM_ACCESS_TOKEN>

Now, you can add the Template Library module to your project's dependencies with: npm install @apostrophecms-pro/doc-template-library

Behind the scenes, npm will use the authenticated URL seen earlier to download the private package and then install it.

In a production environment, you cannot rely on that approach. The problem is that the global configuration file exposes your npm access token, which should be treated as a secret. Instead, set up a granular token related to @apostrophecms-pro by following the official guide. Then, create a local .npmrc file in the root folder of your project and add the following line to it: //registry.npmjs.org/:_authToken=${NPM_TOKEN}

When running an npm command, the CLI will replace ${NPM_TOKEN} with the value read from the NPM_TOKEN environment variable. Thus, set the NPM_TOKEN env with the command below in the deployment server: export NPM_TOKEN="<YOUR_NPM_GRANULAR_TOKEN>"

Replace <YOUR_NPM_GRANULAR_TOKEN> with the value of your granular access token. The production environment is now allowed to install @apostrophecms-pro/doc-template-library.

Wonderful! It only remains to configure the doc-template-library module in your Apostrophe project.

Enable the Template Library Module in Your Project

As with any other Apostrophe module, you need to enable Template Library in the app.js file. To do so, make sure app.js contains the following lines:

// app.js

require('apostrophe')({
  // the name of your project
  shortName: 'apos-template-library-demo',
  modules: {
    // other modules...

    // enable the doc-template-library module
    '@apostrophecms-pro/doc-template-library': {},
  },
  // remaining configs...
});

Launch the development server, and you should now see a new button “Doc Template Library” in the upper right corner as below:

Congrats! You just set up the Template Library Pro module in Apostrophe.

Main Features of Apostrophe's Template Library

Let's explore the features and capabilities offered to editors by the Template Library module. For a more in-depth look, read our article “How to Use Apostrophe's Template Library to Improve Productivity.”

In the example below, we will assume that your Apostrophe application has:

A single piece type: “Article”
Three page types: “Default,” “Article index,” and “Home”

Explore Existing Templates

The “Doc Template Library” button opens the following modal:

Here, editors can see and manage all the page and piece templates available. Each template is represented by a card containing the image specified at creation time or a live preview automatically generated by Apostrophe.

Given a template, content managers can:

Edit: Change its settings or layout. This will only change the layout itself and not the pages or pieces based on it.
Archive: Remove the template from the library. This will not affect pages or pieces created using the template.
Duplicate: Generate a new template as a copy of the selected one.

Define a New Template

Editors can create a new template from scratch directly in the UI:

In the creation modal below, content managers need to:

Give the template a name
Add an optional overview image
Select the content type associated with the template

The content types available correspond to the list of page or piece types in the project.

After creating the template, Apostrophe will open a new page to define its content through the in-context editing feature.

For example, they could craft a template including instructions and tips for writing great articles:

Et voilà! Adding a new template takes only a few clicks. Keep in mind that editors also have the option of turning existing pages and pieces into templates.

Apply a Template

When adding a new piece instance or page, editors can now select one of the templates available from the “Template” tab. After applying one, the area field of the piece instance will contain the same content as the template:

Just see how this mechanism simplifies creating high-quality content by providing effective starting points!

Extra: Excluding a Piece Type From Templates

The ability to create templates based on existing pieces is great, but you may want to disable it for specific piece types. To do so, set the hasTemplates field to false in the modules option in app.js:

require('apostrophe')({
  shortName: 'apos-template-library-demo',
  modules: {
    // other modules...
    article: {
      options: {
        hasTemplates: false // <-- disable template for this piece type
      }
    }
  }
});

Wait for the app to refresh, and you will no longer be able to select the article piece type in the template creation modal. Also, the “Save as template…” option on the piece type will disappear.

Perfect, you just disabled the template features on the selected piece type to editors as desired. With Apostrophe, you are in control!

Conclusion

In this tutorial, we dug into the Apostrophe Pro’s Template Library module from a technical point of view. As seen here, it brings a lot of benefits to editors and adding it to an existing Apostrophe project only takes a couple of minutes.

After setting it up, editors and content managers on your team will have the ability to transform current content into reusable templates. The consequences in terms of productivity and consistency are huge and are only a few lines of code away!

Navigating the Generative AI Downpour

The Apostrophe Team — Wed, 04 Oct 2023 12:05:00 +0000

This year we have observed the flow of news around generative AI technologies go from a light trickle to a full on downpour. Today we are saturated, our inboxes full each morning with a deluge of new products, new funding rounds, new excitement about the power of generative AI and its immediate impact and future potential. It can be overwhelming (in both a positive and a negative sense) to observe this surging, turbulent flood of both opportunity and risk – and to try to figure out where to jump in and start swimming. At Apostrophe, we are letting our core principles guide us.

Like many other tech shops out there, our thinking about this started at the beginning of the year after seeing some of the earliest integrations coming from platforms like OpenAI. Thanks to the flexible architecture of Apostrophe, we were able to easily experiment with some simple integrations between generative AI and our content creation tools. We quickly open sourced our first module to demonstrate this potential and have since shared more in depth tutorials on the topic.

This first small release served as a foundation for our team to strategize about the future roadmap for Apostrophe and generative AI. With some internal strategy workshops and a hackathon, we explored everything from “create fully baked dynamic page layouts via a text prompt” to “enhance the experience of creating and searching developer documentation” to “provide suggestions to help editors create more SEO friendly sites” to “automatically translate text when localizing content”. We were lucky to share some of this process with some of our closest collaborators and the results have informed the future of our product roadmap.

As we consider these many possibilities, we look to our guiding principles and core values to help us prioritize the features that we think bring the strongest alignment and most significant value. Over all the years of evolution in our field, our focus has remained:

How can the tools we create help digital teams do their very best work?

This is why we created Apostrophe in the first place. It is what animates all of our decisions, particularly in a moment like this where there are new opportunities to consider and prioritize.

So what does that look like in practice? How do we apply a focus on helping digital teams do their best work? We think this means helping marketing and editorial teams produce content faster and more efficiently, but in a way that doesn’t risk degrading the quality of that content. It means enabling engineering and DevOps teams to focus more on innovation and less on setup and troubleshooting.

Ultimately, we think Apostrophe can provide the most value by applying generative AI to automate project scaffolding, rote content tasks, and other busywork, with the goal of facilitating the best possible application of our human creativity to create unique, delightful, and inspiring digital experiences.

So what’s next on our roadmap?

The first applications of our principles towards these features is taking the form of the following:

Automatic SEO and accessibility metadata generation: Generating a first draft of simple metadata like page descriptions and alt text for images is one way Apostrophe can streamline the work of content teams, especially teams that need to manage large volumes of documents and media.
Native translation support as part of our localization tools: Apostrophe has powerful localization workflows built into the core, but they currently require either manual translation or some integration with a third party translation platform like Smartling. Hooking our native localization workflow into a simple automated translation back end can help accelerate the work of managing a multilingual site when you don’t have the capacity to bring more translation resources to the project.

You can find more details about both of these in our public roadmap. Please share any feedback you like there, or submit additional ideas that could be considered for future features.

What about the far distant future?

As software engineers and digital creators, are we all just mowing the lawn while a tornado approaches in the background?

If you were to draw a straight line following the trajectory over just the first half of 2023, it was frighteningly easy to imagine a future where the entire creative economy has been replaced by some form of generative AI. But we know that the path ahead will not follow a straight line, and we know that there is no true replacement for the quality of human vision and creativity when it comes to doing great work.

As this technology makes its way through various technical and regulatory hurdles, and all of the other stops and starts and twists and turns influenced by the complex factors at play, we think it’s possible to guide it in a humane direction and make good choices as a society. As a company we’ll aim to do our part in that.

Let us know what you think!

Once again, please do share your feedback on our roadmap, or better yet join us in Discord and get involved by contributing directly to the project. If you’re a company working with Apostrophe and looking to collaborate more directly with us on any of these features, we love rolling up our sleeves in this way with our partners so definitely reach out.

There are so many more opportunities for what Apostrophe can do when paired with generative AI than we will ever be able to unlock just with our team alone - we look forward to hearing from you as we dive deeper into this work.

This post was written by Apostrophe's leading conversation starter, CEO, and staunch board game advocate. We also call him Alex.

Launch Faster with Apostrophe Starter Kits

The Apostrophe Team — Mon, 21 Aug 2023 12:25:00 +0000

Starter Kits offer the building blocks tailored to specific use cases, enabling developers to launch their websites faster and with enhanced functionality.

In today's digital landscape, teams are always looking for more efficient solutions to streamline their design and development processes. Apostrophe, the ultimate open source content management system and website builder, has introduced a suite of resources to kick start the upfront development work of new Apostrophe-powered projects. These pre-bundled Starter Kits offer the building blocks tailored to specific use cases, enabling developers to launch their websites faster and with enhanced functionality. In this blog post, we'll highlight the benefits of Apostrophe Starter Kits and how they can empower developers to build exceptional websites with ease.

Effortless Website Development

Building a website from scratch can be a time-consuming process, requiring digital teams to invest effort in both design and functionality. However, Apostrophe’s new Starter Kits simplify this upfront demand by providing pre-bundled projects designed for ecommerce, hospitality, and marketing sites, to go along with our existing minimalist Apostrophe 3 Essentials project. These Starter Kits act as a foundation, allowing developers to jumpstart their projects and reduce the time and effort required for initial setup.

Tailored to Specific Industries

Apostrophe Starter Kits are specifically designed to cater to the needs of various industries. The Apostrophe Essentials Kit provides a solid blank canvas for general-purpose websites, allowing developers to start their projects with a robust and flexible base. The Ecommerce Kit equips developers with the necessary components and features to set up an online store seamlessly. Whereas the Hospitality Kit offers specialized functionality for restaurants, hotels, resorts, and other leisure businesses. Lastly, the Marketing Kit empowers marketers with tools to create simple promotional websites that effectively showcase their products or services.

In releasing these Starter Kits as open source projects, we also hope to create new opportunities for the community to collaborate with us. And this is just the beginning! In partnership with our Partner Network, additional Starter Kits are planned for the Apostrophe Library. If you would like to contribute a Starter Kit, contact us today.

Accelerated Time-to-Market

By leveraging Apostrophe Starter Kits, developers can significantly reduce their time-to-market. The pre-built nature of the components in the kits eliminates the need to start from scratch, enabling developers to focus on customizing and fine-tuning the website to meet their specific requirements. With the Starter Kits' strong foundation and optimized workflows, developers can rapidly iterate and deploy websites, giving businesses a competitive edge in the ever-evolving digital landscape.

Unleash Your Creativity

Apostrophe Starter Kits not only offer efficiency but also provide developers with a platform to unleash their creativity. By streamlining the initial setup process, developers have more time and freedom to concentrate on implementing unique and innovative features that set their websites apart from the competition. Whether it's creating interactive elements, integrating third-party APIs, or designing a visually stunning user interface, Apostrophe Starter Kits empower developers to bring their ideas to life without being hindered by repetitive tasks.

Get Started with a Starter Kit Today

Apostrophe Starter Kits enhance efficiency and streamline the development process, allowing developers to invest more time and effort in the customization of the website. With the accelerated time-to-market and the ability to unleash creativity, developers can build exceptional websites that captivate users and deliver a seamless digital experience. Whether you're a developer or a business owner, Apostrophe Starter Kits provide the tools you need to begin your development journey on the Apostrophe platform.

To get started, simply navigate to the Starter Kit Library and choose the kit that aligns with your goals and objectives.

How to Integrate Generative AI Into Apostrophe

Antonello Zanini — Tue, 15 Aug 2023 12:05:00 +0000

As recently highlighted by Apostrophe's CTO, Tom Boutell, in a talk at Philly Tech Week, AI is transforming the CMS industry. At the same time, finding the right way to integrate AI into a CMS may not be easy. That is why the team behind Apostrophe built an AI Helper module to add text and image generation capabilities to the CMS and website builder with just a few lines of code.

Here you will learn what the Apostrophe AI helper is, how it works, and how it can be used to generate content with AI.

What Is the Apostrophe AI Helper Module?

The AI Helper module is one of Apostrophe’s many available extensions. As the name suggests, it is designed to facilitate the introduction of AI-based features in Apostrophe. In other words, AI Helper provides a simplified way to integrate OpenAI functionality into an Apostrophe project with just a few lines of code.

In detail, it relies on the OpenAI API to enhance Apostrophe with AI-driven helpers. Once integrated, the module currently offers:

An insert menu option to generate rich text from a prompt via GPT, the AI model behind ChatGPT.
A button to generate an image from a text prompt via DALL-E.

With these two features, editors can ask artificial intelligence to generate Apostrophe-ready content without having to leave the platform. This is a huge productivity boost.

As of this writing, the module is still in beta. The reasons are:

AI models are still not perfect, and they are prone to produce unreliable results.
The OpenAI API it depends on is subject to changes.
Generative AI is evolving so rapidly that the best way to integrate it into Apostrophe could change rapidly in terms of both UI and overall technical approach.

This does not mean that you cannot use it to experiment with generative AI in the content creation process. Quite the opposite!

Add AI to Apostrophe with the AI Helper Module

In this step-by-step tutorial, you will learn how to integrate the Apostrophe AI Helper module into your project. Follow the instructions below and start taking advantage of the power of generative AI!

Note: If you already have an Apostrophe app in place, you can skip the first two steps.

Prerequisites

Before jumping into this section, you need to meet the Apostrophe 3+ prerequisites:

To make the process of initializing an Apostrophe project easier, install the Apostrophe CLI:

npm install -g @apostrophecms/cli

You will now have access to the apos command, through which you can quickly set up and manage Apostrophe projects.

If you are a Windows user, you will also need to configure WSL (Windows Subsystem for Linux) as explained in the official docs.

Great! You are now ready to set up an Apostrophe 3+ project.

Initialize an Apostrophe Project

First, make sure that the MongoDB local server is running by following the official guide for your OS.

In the terminal, enter the folder where you want to create your Apostrophe project and launch:

apos create apos-ai-demo

This command will create an Apostrophe project called apos-ai-demo.

During the process, you will be asked to enter the password for the “admin” user. Type in a secure password and then store it in a safe place.

The apos-ai-demo folder should now contain an ApostropheCMS project. If this is your first Apostrophe project, you should spend some time familiarizing yourself with the Apostrophe file structure.

To start your application, enter the project folder:

cd apos-ai-demo

Then, run the development server with:

npm run dev

You will receive the following warning message:

WARNING: No session secret provided, please set the secret property of the session property of the @apostrophecms/express module in app.js

Do not worry, you can easily fix that as explained in the docs.

Open the http://localhost:3000/login page in your browser to make sure your Apostrophe starter project is running.

Fill out the form with "admin" as the username and the password set during the initialization process.

After successfully logging in, you will be redirected to the Apostrophe dashboard below:

Here, you have access to all the great features offered by ApostropheCMS, including website-building capabilities, an intuitive UI for content management, a drafting system, and in-context editing.

Perfect! You now have an Apostrophe project to extend through the OpenAI APIs.

Integrate the AI Helper Module

In the project folder, run the command below to install the AI Helper module:

npm install @apostrophecms/ai-helper

This will add the [@apostrophecms/ai-helper](https://www.npmjs.com/package/@apostrophecms/ai-helper) library to your project’s dependencies.

As with any other Apostrophe module, you must first enable it in the app.js file. To do so, make sure app.js contains the following lines:

// app.js

require('apostrophe')({
  // the name of your project
  shortName: 'apos-ia-demo',
  modules: {
    // other modules...

    // enable the ai-helper module
    '@apostrophecms/ai-helper': {},
  },
  // remaining configs...
});

If you run the application, it will now crash with the following error:

Error: APOS_OPENAI_KEY must be set in your environment

The reason is that the ai-helper module needs an OpenAI API key to function. If you do not have one, follow the procedure below to retrieve your free API key for limited usage:

Create an OpenAI account.
Follow the instructions and verify your account.
Sign in.
In the main dashboard, click the “API” card:

Click on your profile image in the upper right corner and select the “View API keys” option:

Click the “Create new secret key” button.

Call the new API key “Apostrophe” as below:

Click on the “Create secret key” button.

Copy the OpenAI API key and store it in a secret place:

Please keep in mind that when the trial ends, you will be subject to the OpenAI pricing.

You now have to set an APOS_OPENAI_KEY environment variable with the value of your OpenAI API key. On Linux, macOS, or Windows Subsystem for Linux (WSL) Windows with Git Bash, run the command below:

export APOS_OPENAI_KEY=<YOUR_OPENAI_API_KEY>

On Windows with PowerShell, run:

$Env:APOS_OPENAI_KEY = "<YOUR_OPENAI_API_KEY>"

Replace <YOUR_OPENAI_API_KEY> with the value of the secret API key retrieved above.

That command will configure the required env in the terminal session. In the same terminal window, re-launch the project again:

npm run dev

This time, Apostrophe should load with no error.

You are ready to add OpenAI-based AI features to any page that supports the [rich-text widget] (https://v3.docs.apostrophecms.org/guide/core-widgets.html#rich-text-widget). To achieve that, update the '@apostrophecms/rich-text' module configuration by adding the ai option to the insert property:

insert: [
    // other values...
    'ai'
],

If you then want to ask GPT to generate text with subheadings, you will also need to make sure that styles contains:

styles: [
  {
    tag: 'p',
    label: 'Paragraph (P)'
  },
  {
    tag: 'h2',
    label: 'Heading 2 (H2)'
  },
  {
    tag: 'h3',
    label: 'Heading 3 (H3)'
  },
  {
    tag: 'h4',
    label: 'Heading 4 (H4)'
  }
  // other styles...
],

If you are using the Apostrophe Security Headers plugin, you will also need to add the following config to security-headers/index.js inside modules/@apostrophecms:

// modules/@apostrophecms/security-headers/index.js

module.exports = {
  options: {
    policies: {
      ai: {
        'img-src': '*.blob.core.windows.net'
      }
    }
  }
};

This policy allows you to deal with OpenAI images for editing purposes.

Now, suppose you want to add AI content generation capabilities to the Apostrophe default page module. This is what default-page/index.js inside modules would look like:

// modules/default-page/index.js

module.exports = {
  extend: '@apostrophecms/page-type',
  options: {
    label: 'Default Page'
  },
  fields: {
    add: {
      main: {
        type: 'area',
        options: {
          widgets: {
            '@apostrophecms/rich-text': {
              toolbar: [
                'styles',
                '|',
                'bold',
                'italic',
                'strike',
                'link',
                '|',
                'bulletList',
                'orderedList'
              ],
              styles: [
                {
                  tag: 'p',
                  label: 'Paragraph (P)'
                },
                {
                  tag: 'h2',
                  label: 'Heading 2 (H2)'
                },
                {
                  tag: 'h3',
                  label: 'Heading 3 (H3)'
                },
                {
                  tag: 'h4',
                  label: 'Heading 4 (H4)'
                }
              ],
              insert: [
                'table',
                'image',
                'ai' // add the AI features
              ]
            },
            '@apostrophecms/image': {},
            '@apostrophecms/video': {}
          }
        }
      }
    },
    group: {
      basics: {
        label: 'Basics',
        fields: [
          'title',
          'main'
        ]
      }
    }
  }
};

Great! Add a new ”Default” page to your site to see the artificial intelligence features in action.

Get Ready to Unleash the Power of AI

In the Apostrophe dashboard, click “Pages,” and then “New Page.” This will open the modal below:

Give your new page a title, select “Default” as page type, and click “Publish.”

A new record will now appear in the “Manage Pages” section:

Click the dots on the right and select “Preview” to open the new page:

Well done! This blank page is about to get filled with some AI-generated content.

AI Rich Text Generation

Now that your page is ready to host some AI-generated content, hit the “Edit” button:

Click “Add Content” and select the “Rich Text” option.

Type “/” in the empty rich text widget to access the element menu and select “Generate Text.”

This will open an input area where you can write your prompt for the AI model:

For example, type:

“100 words about why AI is the future, in the style of Ernest Hemingway, with subheadings” To write a good prompt, it is also a good idea to specify a word count. Also, do not forget that you can ask GPT to include headings and links.

Click “Generate” and wait for the AI magic to happen.

💥 Boom! Your page will now contain AI-generated formatted text:

Note that AI could produce surprising or inappropriate results.

See the entire process in action in the video below:

How AI Helper Rich Text Generation Works

If you are wondering how this works, take a look at the ai-helper-rich-text-widget/index.js file on GitHub. In detail, focus on:

const marked = require('marked');

// ...

prompt = `
  Generate text in markdown format, based on the following prompt:

  ${prompt}
`;
const body = {
  prompt,
  model: aiHelper.options.textModel,
  max_tokens: aiHelper.options.textMaxTokens,
  n: 1
};
const result = await self.apos.http.post('https://api.openai.com/v1/completions', {
    headers: {
      Authorization: `Bearer ${process.env.APOS_OPENAI_KEY}`
    },
    body
});

if (!result?.choices?.[0]?.text) {
  throw self.apos.error('error');
}
let markdown = result.choices[0].text;

// Remap headings to levels actually available in this widget
markdown = markdown.replace(/(^|\n)(#+) /g, (all, before, hashes) => {
  if (!headingLevels.length) {
    return '';
  }
  const level = headingLevels[hashes.length - 1];
  return before + (level ? (before + '#'.repeat(level) + ' ') : '');
});

const html = marked.parse(markdown);
return {
  html
};

What this code snippet does is:

Tweak the prompt behind the scenes to ask GPT to return a response in Markdown format.
Perform the API call to the OpenAI server using the APOS_OPENAI_KEY env for authentication.
Convert the Markdown string returned by the API to HTML.

This is how the Apostrophe AI Helper extension manages to turn an AI prompt into a structured page with links and subheadings.

If you want to override this default behavior, create a file index.js under modules/@apostrophe/ai-helper-rich-text-widget and initialize it with your custom AI rich text generation logic.

AI Image Generation

Your current page has some interesting content but lacks an eye-catching image. Again, you can use artificial intelligence to generate one.

Click the “Add Content” button, and select “Image:”

Apostrophe will add a sample image for you. Click on it and select the “Edit Widget” icon:

Click “Browse Image” and hit the “🤖" (robot) button in the upper right corner.

This will open an input area where you can type your DALL-E prompt:

For example, write:

“An image of a futuristic city”

Click “Generate Image,” wait for OpenAI to do its magic, and you should be seeing something as follows:

Keep in mind that AI image helper generates 1024x1024 images, which is the maximum size supported by OpenAI. At the time of writing, smaller images are not recommended as they are not much cheaper and are unlikely to look good on a website.

Click on an AI-generated image to open it in a modal:

Since DALL-E may produce low-quality results, having the possibility to inspect each image before adding it to the multimedia library is an essential tool. If you are not convinced by the result, click "Delete" to remove the image forever. Otherwise, it will be cached for around one hour before disappearing from the selection section.

In some cases, you may want to ask DALL-E to generate images similar to the current one. This is what the "Variations" button is all about. As you can see in the video below, that will produce four more images:

Once you found the image you like the most, click “Select” to add it to the article. Here is what the final page looks like:

Watch the video below to better understand how easy the entire AI image generation process is:

Just as seen before, you can overwrite the default logic by properly defining a modules/@apostrophe/ai-helper-image/index.js file.

Congrats! You just integrated generative AI into Apostrophe!

Conclusion

In this article, you learned what the Apostrophe AI Helper module is and how it can provide generative AI to your editors. In detail, this extension offers a quick and easy way to integrate OpenAI features into your Apostrophe site. Thanks to Apostrophe's extensibility, you can also easily customize the AI content generation logic.

Keep in mind that Apostrophe has just begun dipping its first toes into the AI space. Now that the team has this foundation and a deeper understanding of what is possible, they are excited introduce other features that leverage these powerful generative tools. Keep an eye on the Apostrophe product roadmap!

By following this step-by-step tutorial, you saw how to initialize an Apostrophe project, integrate the AI Helper module, and take advantage of it to reach your content goals. Thanks to AI, writing great content so quickly has never been easier!