Forem: ExpressionEngine

ExpressionEngine and Headless

ExpressionEngine — Mon, 27 Jun 2022 14:11:00 +0000

Headless is all the rage, and for good reason. People and devices consume content in a variety of ways that have needed a different approach to the CMS as a single platform to handle both the managing of content and displaying the content. The idea of a headless CMS focuses the responsibility of the CMS to only administrating content, while the presentation of content is left to a different stack of tools. The presentation can also benefit from static CDN caching for scaling, and increased security. We are not talking about just blog posts, but also data like the current temperature outside, rocket launch times, and infection rates.

In the world of headless, ExpressionEngine is considered a hybrid CMS. It is able to deliver on many headless concepts, so the final answer depends on which part of the definition is the most useful for your case. Let’s first cover what ExpressionEngine does well around the scope of headless out of the box.

What ExpressionEngine Can Do

ExpressionEngine excels at content management through user-defined custom fields that are grouped into channels of content. Said another way, content can be broken into highly structured fields that fit the needs of the site. It has robust roles & permission management for users, and a template engine able to output text in most formats, from JSON to HTML and XML. ExpressionEngine can also be wildly extended by add-on modules. All of this is managed by an intuitive control panel.

What ExpressionEngine is Not

ExpressionEngine is not offered as a SaaS, or built with microservices, and is not currently offered as a fully maintained cloud option. ExpressionEngine is a traditional monolithic PHP application that must be downloaded and installed on a LAMP-like stack. Like most CMS’s in this category, the core can be auto-updated with a single click. It also does not have GraphQL, and editing entries through the API takes a little bit of extra work.

Out of the Box

Most APIs for a headless CMS are typically going to return JSON, and this is absolutely possible in ExpressionEngine! To create a JSON-formatted template, simply create a new template, select the type of javascript, and create a tag loop to output entry data. Since templates are independent of each other, it is also possible to run both a standard HTML website alongside various API endpoints in the same ExpressionEngine install.

Limitations

No rate limits

Since these behave like normal web pages, there is not a way to limit page requests per API key.

Lack of access control with something like tokens

API keys and tokens in the header of a request to control access or enforce limits are not supported.

GET is the only request type

Requests that modify data such as POST, PATCH, and DELETE would not be supported out of the box. See further down the article for more information.

`GET` Example

To display a list of upcoming events at, say, a conference center, first create a channel to hold the event information such as the title, event date…etc. Conference rooms in the facility would have their own channel and contain information like hall capacity, name, and photos and then be related to the event. This structure can then be outputted in templates:

Example of an HTML template at `/events/item/my-event`

{exp:channel:entries channel="events"}

  <!-- Event Info -->
  <h1>{title}</h1>
  <time>{entry_date format="%m/%d/%Y"}</time>
  <p>{description_custom_field}</p>

  <!--- Room Relationship -->
  {conference_room}
    <h3>Room: {conference_room:title}</h3>
    <p>Capacity: {conference_room:size}</p>
  {conference_room}

{/exp:channel:entries}

Example of the same data in JSON at `/api/events/my-event`

{exp:http_header content_type="application/json"}
[
  {exp:channel:entries channel="events" backspace=’1’}
  {
    // Event Info:
    ‘title’ : ‘{title}’,
    ‘entry_id’ : {entry_id},
    ‘description’ : ‘{description_custom_field}’,

    // Room Relationship:
    ‘conference_room’ : [
      {conference_room backspace='1'}
      {
        'room_title' : ‘{conference_room:title}’,
        ‘size’ : ‘{conference_room:size}’
      },{/conference_room}
    ]

  },{/exp:channel:entries}
]

Creating Better Queries

The vanilla channel entries loop is a bit cumbersome to fine-tune queries using the URL like a typical REST API. To get more control, URL query parameters can be used through the first-party add-on Low Search. They can be any of the standard fields such as date, status, or title plus all custom fields, and relationships.

The most common use for this approach is updating a page with search results using asynchronous javascript (AJAX). Andy McCormick wrote a series on this. While in Andy’s series the templates returned HTML, it can be easily changed to JSON:

Entries Template /group/entries

{exp:http_header content_type="application/json"}
[
  {exp:low_search:results query="{segment_3}" backspace="1"}
    {
      ‘title’ : ‘{title}’,
      ‘entry_id’ : {entry_id},
      ‘custom_field_1’ : ‘{custom_field_1}’,

    },{/exp:low_search:results}
]

Static HTML File:

const request_url = '/group/entries?status=open&channel=events&limit=10';

const entries = await fetch(request_url).then(response => response.json());

entries.forEach( entry => {

  console.log(entry.title);
  console.log(entry.entry_id);
  console.log(entry.custom_field_1);

});

Extending with Add-ons

ExpressionEngine can be extended with Add-ons written by 3rd party developers through the ExpressionEngine Store, or can be custom-written per-project. Here are just a few to check out:

Bones by TripleNERDScore

https://expressionengine.com/add-ons/bones

Bones combines both the Low Search query URL feature, plus gives a full output of entry data in a predictable format. This skips a lot of custom template authoring. Data can be returned as JSON through an action URL (see below), or template. Bones also provides the ability to require an API key in order to access data, adding to security. Like the Low Search approach, data queries are made through the URL parameter. Bones also helps with counting objects, and better error handling than a standard template.

Webservice by Reinos

https://expressionengine.com/add-ons/reinos-webservice

This add-on provides a highly customized web service for ExpressionEngine that includes GET and POST processes.

Custom Add-ons

If none of these options suit your needs, you can create your own custom add-on. Add-ons can tap into control panel events such as when entries are updated, or someone logs in, to have their own custom logic and endpoints for data.

When building an ExpressionEngine module there is a service called Action ID, or “ACT”. A module method can be run when a specific URL is requested. This can be the start of your API and can accept GET as well as POST and other requests to update ExpressionEngine. For example, by visiting the URL below, the function act_action would be called.

https://example.com/index.php?ACT=23&action=get_entries

// On install, ExpressionEngine can
// create a new ACT ID to the method name of your choice.
function act_action()
{

  if (ee()->input->post('action') === 'get_entries')
  {

    $entries = ee('Model')->get('ChannelEntry')->all();

    return json_encode($entries);

  }

}

Modifying Entries

Creating and updating entries in ExpressionEngine will take a little bit of work, and require building a Module add-on.

When installing an add-on’s ACT action, setting the csrf_exempt to 1 will disable the token check as shown below. At this point any data can be submitted to your method, so be careful how this is used.

Also to note, updating Grid and Fluid fields take additional steps to be updated and are beyond the scope of this writeup.

Within the add-ons’s upd.myaddon.php file:

$data = array(
    'class' => 'MyClass' ,
    'method' => 'my_act_method',
    'csrf_exempt' => 1 // Important, use with care.
);
ee()->db->insert('actions', $data);

From here, the my_method function can alter data in ExpressionEngine. For example, to update the title of an entry we could do something like the following:

POST Request:

curl -d 'title=NewTitle!&entry_id=5' -X POST https://example.com/index.php?ACT=23

mod.myaddon.php :

function my_act_method()
{

    // Get fields from POST using sanitized methods:
    $entry_id = ee()->input->post('entry_id');
    $new_title = ee()->input->post('title');

    // Use ExpressionEngine models to get an entry.
    $entry = ee('Model')->get('ChannelEntry', $entry_id)->first(); 
    $entry->title = $new_title; // Change the title.
    $entry->save(); // Save changes.

}

Final Thoughts

Using ExpressionEngine to power a headless application is absolutely possible, with some limitations. ExpressionEngine excels at content management while providing the possibility for a hybrid of standard HTML and API templates in the same open-source system. It can deliver that data in numerous ways. ExpressionEngine can also be extended with existing or custom add-ons to build more functionality where the native options are limited. Where ExpressionEngine may not fit is if you are looking for a fully-hosted and maintained CMS on a monthly or annual fee with a little extendability, or if a lot of data is being updated outside of the ExpressionEngine control panel.

Originally published by Blair Liikala at u.expressionengine.com

Building an E-commerce Website With ExpressionEngine, Part 4

ExpressionEngine — Mon, 13 Jun 2022 10:04:00 +0000

Part 4: Notifications and Order management

4a) Notifications

We have most of the puzzle pieces of a working store in place. Next we’ll quickly review Notification setup and Order Management within CartThrob. Navigate to the Notifications tab.

Starting at the top of the page with the Log email? setting; I typically don’t log email unless it’s a troubleshooting situation. When enabled, it writes debug info to a CartThrob database table.

We are going to setup two email notifications. The first notification is intended for the customer, while the second is intended for the store owner.

In the CartThrob settings, the first block is what we’ll use for the Customer notification. CartThrob likely created a few of these email configuration blocks by default.

Everything is pretty self-explanatory here. The To email address is dynamically assigned from the order itself using the ExpressionEngine variable.

Next, the Email template needs to point to a standard ExpressionEngine template, in our case a fairly basic HTML table template geared for email delivery.

The Event setting is used to match a CartThrob event that must be triggered to send this email. In this case, a successful transaction.

We are ready to move on to the next email block for the store owner. The setup is nearly identical, only differing in subject line, recipient, and email template. The Event setting remains as “Successful Transaction,” which means two emails are sent by CartThrob for each successful order. Marked in yellow, below, are the subtle differences in the owner email compared to customer

On the frontend, we’re ready to submit a test order to test the notifications. I’ll add a couple of items to my cart, even specifying an order note. Here is what the email notification looks like to the customer:

4b) Order Management

Where does CartThrob store all this?

Order entries

If you remember when we used that installation function within the CartThrob Installation Tab, it created the Coupon Codes and the Orders Channels.

The Orders Channel looks like a standard ExpressionEngine channel with the title being the order number, and then the statuses that we have assigned to the channel.

If I look through a sample Order entry, it’s pretty standard; just a lot of custom fields. In this case, the actual line items for the order appear on the order items CartThrob field.

The expected order and customer data is found in the entry fields. Note the layout tabs that capture the billing, shipping payment. It’s all here in the ExpressionEngine Entry!

Order Manager

The CartThrob order manager is a separate Add-On; you can add both to your ExpressionEngine control panel menu manager as you see fit.

Within Order Manager, you’ll have basic reports around order totals by month, product reports, etc.

Within Order Manager, the Orders menu appears above the Reports. I’m just going to look at a single order I just made. It looks like an ExpressionEngine channel entries interface but it is slightly different, supplementing with some CartThrob-specific functionality.

Click on a test entry and you’ll see the contents of this order, with functions for deleting the order, re-sending the order notification, or issuing a tracking number.

This concludes our tutorial of the CartThrob setup and frontend review. On to our final installment to cover Templates!

Have questions or comments about this course? Be sure to join the discussion and post in the ExpressionEngine Forums!

Originally published by Paul Larson at u.expressionengine.com

Building an E-commerce Website With ExpressionEngine, Part 3

ExpressionEngine — Fri, 10 Jun 2022 10:04:00 +0000

Part 3: Shipping / Tax / Payments

3a) Shipping

Within CartThrob, navigate to Shipping. There’s several plugins to choose from; for this example I’m using By weight - Threshold. The settings are self-explanatory. The shipping plugin uses a tiered system so any order weight total of up to 5 lbs will match the first row, resulting in a shipping charge of $8, and so on.

For the last row I have a really high threshold of 500, so anything after 15 lbs will just cost $500.

Click Submit to save the plugin selection and its values.

On the frontend we’ll test the Yoda Bowling Ball. The cart tallies shipping as $13, because the By Weight - Threshold plugin matches the order total of 10 lbs. (Totals up to and matching 10 lbs will match the $13 calculation.)

3b) Taxes

Within CartThrob, navigate to Taxes. I’ll leave “Calculate taxes using shipping address” as No , since I want to calculate by billing address.

For the Tax Plugin, we’ll use “Tax by Location - Percentage”. Each row represents a tax rate, region, and zip. CartThrob will use these values to match to the customer’s billing address to tally the proper tax rate. For this example, I’ll use 7.7%.

Like shipping, I added a second row with a high value to catch all other situations. Anything that doesn’t match the first row would be match by this global rule which is 20%. We could put in more rows and more zip codes and regions, but we’ll leave this simple for now!

Click Submit. Taxes are done! Add an item to your cart on the frontend and give it a try!

3c) Payments

Now that our shipping and tax are behaving, I’ll look at the payment gateways. Within CartThrob, navigate to Payments , and focus on the first menu, Choose your primary payment gateway. I’m using the Stripe plugin developer mode. (Stripe and Authorize are the gateways I use the most. I prefer Stripe because it’s just easier to test compared to Authorize or Paypal)

You can choose the various gateways that CartThrob has available. The first select menu is showing you what gateway is chosen, the second is giving you the chance to edit that gateway’s settings. (the settings will appear below, without a page reload, upon making this selection)

Below is where I have my test modes selected, and I have my Test Mode API key (secret), and Test Mode API key (publishable) that I configured within my Stripe account.

Everything else I can leave as-is. Click Submit to save the changes.

3d) Submit an order on the frontend

Now we can actually complete an order! At the bottom of my checkout page, I’m using the default Stripe test number, 4242 4242 4242 4242, providing any CVV code and a valid expiration date.

Our test order was hopefully successful! Head over to Stripe (or your gateway), and view the appropriate Dashboard for test orders to confirm.

Have questions or comments about this course? Be sure to join the discussion and post in the ExpressionEngine Forums!

Originally published by Paul Larson at u.expressionengine.com

Building an E-commerce Website With ExpressionEngine, Part 2

ExpressionEngine — Wed, 08 Jun 2022 10:04:00 +0000

Part 2: Channel installation and Discounts

2a) Orders/Discount Channel Installation

Back in the ExpressionEngine backend, go to the CartThrob add-on, and then the “Installation” tab. (We’re not going to Orders Tab which would be the logical next step)

Of these available installation options, we actually skip most of them because we’re starting with pretty basic templates that we’ve created. Our store is not really complicated enough for Packages or Discounts channels. Instead, we will only choose Store - Orders and then Store - Coupon Codes channels. (Remember, our FakeBowling.shop ExpressionEngine site already had a Products channel) If you’re curious, Store - Purchased items would be used to if you want to show “Customers Also Bought..” on a product page, which is a cool feature.

We are not installing any templates, as we already have those completed.

Click Install Templates & Channels.

Navigate to the Channels menu, and you’ll hopefully see that the two new channels were created.

Now, head back to CartThrob, navigate to the Orders tab, and this one’s sort of settle. You have to first click your order channel, Store - Orders , and then be sure to select “Yes” for “Save completed orders to a channel?”

Upon submitting these changes, we should see statuses that need to be assigned. Scroll down to the Order Status section and map each status accordingly.

We’ll follow suit with Order Data Fields. (this one takes a while!)

Now CartThrob knows about our Orders channel and its Status and Data fields.

2b) Coupon Code (Discounts)

Next, we’re going to make some fields to store coupon codes. In the Fields menu, there’s now a field group called Coupon Codes with a default field {coupon_code_type}. We’re going to supplement this with two more fields of our own.

Add a text input field, we’ll call it just “Coupon Code”, shortname {coupon_code}. This will be the field that we put the actual code the customer would type in on the cart page, e.g. “Black Friday” coupon.

Follow up by creating another text field as the {coupon_description}. This field would be for a frontend display, such as, “You now have a 10% off your order” to display in the cart.

With the discount fields created, it’s back CartThrob settings and then the Discounts tab. Our fields haven’t yet been assigned to the new channel, so we’ll add that setting and click Submit.

Now we are ready to make a coupon code entry within the Store - Coupon Codes channel. Our title is “Ten Percent Off EE CONF Special,” a Type of “Percentage Off,” and Percentage Off value of 10. And finally, a Coupon Code of “abc123” and a Coupon Description.

We’re done! These coupon codes can be tested on the frontend.

Have questions or comments about this course? Be sure to join the discussion and post in the ExpressionEngine Forums!

Originally published by Paul Larson at u.expressionengine.com

Building an E-commerce Website With ExpressionEngine, Part 1

ExpressionEngine — Tue, 07 Jun 2022 10:04:00 +0000

This is a five-part series on how to build an ecommerce website in ExpressionEngine from scratch using the CartThrob add-on.

This walkthrough will be in 5 parts, covering the following:

Part 1: Setting the stage: product field creation
Part 2: Channel installation and Discounts
Part 3: Shipping / Tax / Payments
Part 4: Notifications and Order management
Part 5: Template setup and tag overview

Throughout this series I'm joined on video by Greg Crane, a developer at Creative Arc, for each key segment of the walkthrough. Greg created all the templates, too, which are available for download.

Have questions or comments about this course? Be sure to join the discussion and post in the ExpressionEngine Forums!

Part 1: Setting the stage

CartThrob is an ecommerce add-on we’ve used for many years, building sophisticated stores that integrate with ERPs, event ticketing sites, or even basic invoice payment forms. This series provides a foundation for building a CartThrob commerce website from scratch, covering field creation, channel configuration and assignment, payments, shipping, taxes and order notifications. A high-level overview of template tags is found in Part 5 of the walkthrough, along with a zip archive of the full example templates.

Disclaimer: This is a way to build a CartThrob store, not the way. The power of CartThrob is in how it extends ExpressionEngine. You can bring your ExpressionEngine skills to bear and simply extend into commerce.

Acknowledgements : These example templates, and the general configuration covered in this walkthrough are developed by Greg Crane from store builds for our clients.

Introducing our demo store, FakeBowling.shop!

As you might have guessed, our chosen demonstration store is one that sells bowling accessories. Such a store would likely have Simple Products such as a bowling ball, or Optioned Products such as a shirt with size options, or Virtual Products such as League dues where shipping and weight don’t apply.

This is a speed run starting from an existing ExpressionEngine website; our journey begins just after the CartThrob add-on has been installed but none of the configuration has been completed. Two basic channels exist in our ExpressionEngine site for this example: {simple_products} and {optioned_products}.

Let’s get started!

1a) Simple Products: field creation and entry configuration

We’re going to create our simple product fields and then review how those appear on the front end, then configure CartThrob so it knows about that simple product channel. Within the Fields menu, you’ll see we already created field groups for our Simple and Optioned products, but for now we’re going to focus on the Simple Product Field group.

The first field we need to add is the price. Create a new field within this field group; use the field type “CartThrob - Simple”. I’ll call this Simple Product Price , {simple_product_price}, making it required.

The next field is the Quantity, or the Inventory Tracking field, and this can just be text input with “Integer” as the Allowed Content setting. In our case we used {simple_product_inventory}.

The third field to create is a Text input field, named {simple_product_weight} with Number set for Allowed Content.

We have three demo products in our store (two bowling balls and one accessory). Note that Products within CartThrob are simply ExpressionEngine channel entries: everything you’re accustomed to from a standard ExpressionEngine website applies; we are simply introducing CartThrob field types.

Let’s look at one test product entry as an example (8-pound Hello Kitty ball). We already have the photo and the body and the SKU in there, but I’ll just give this a price of $53 and a quantity of 98 in stock.

Following suit, the Yoda ball is $103 with a Inventory of 5, followed by the Bag Roller product, priced at $80 and a quantity of 60.

A quick peek at one of these items on the frontend:

Now, we can go to the CartThrob add-on within the ExpressionEngine backend, which at the moment doesn’t know this channel exists. From the Products tab, we’ll assign the channel Simple Products. Our Price Field name is the Simple Product Price , the weight field name is Simple Product Weight and the quantity field is Simple Product Inventory.

So now CartThrob knows that products are coming from that channel, and it knows which fields to use for the pricing and for the shipping/weight calculations. On to Optioned Products!

1b) Optioned Products

So we have the basics of the simple product configured and populated. Now we have our more complicated Optioned products that are in a different channel, and just as we did for the Simple products, we have to make some fields, populate the products, and then configure CartThrob to use the appropriate channel and fields. As a reminder, Optioned products refer to T-shirt with sizes of small, medium, and large, for example.

The CartThrob price modifier field

Returning to the Fields menu, navigate to the Optioned Product Field Group. Create a new field of type CartThrob price modifier. The name of my field is simply “Options,” with a Short name of {optioned_product_options}. Note: On the frontend, the name of the field (Options) is what’s going to display next to the dropdown with the options, shirt sizes and colors, for example.

Next, we’ll make a basic Text input field {optioned_product_weight} with Number as the Allowed Content setting.

Add Product Options to Entry

Go to “Edit” menu and bring up our Optioned Product channel. We’ll use our Shirt product (The Andy) as an example.

As we scroll down that product entry page, we’ll see our blank CartThrob Price Modifier field with default columns of Option Short Name, Option Label, and Price.

Next, a detail that is easy to miss the first time you do it: we can add additional columns; in our case, Inventory and SKU. (We’re making the assumption that the option prices here are what the customer will see on the frontend. Another option is to have a separate base price for which the price modifiers would add or subtract the prices from that base price). For this example, though, there is no base price, and the Option price is what the customer will see in their cart.

Sizes (Options) have been added: Small, Medium, and Large with their associated price, inventory, and SKU.

Note: Within the Options (CartThrob Price Modifier field), the “Save” action is for the Preset, you’ll need to save the Entry afterwards. The preset makes data entry easier as you add more products.

Setup Optioned Product Channel within CartThrob

CartThrob doesn’t know this “Optioned Products” channel exists yet, so we’ll head back to the CartThrob add-on, “Products” tab. You’ll see our simple products are still there but we’re going to add another channel (click “ Add Another Channel ”). We’ll choose Optioned Products with the settings below:

So far so good! Now we have to save by clicking Submit at the bottom of the page. We should be ready to move on.

1c) Frontend Add to Cart Demo

We now have our products created, both the simple and the optioned products. Upon adding the Yoda bowling ball to the cart, it’s good to see it has the proper line-item cost and then a subtotal cost. Updating the cart to a quantity of 2, for example, properly adjusts the subtotal and listed quantity.

Next, we add the Andy product, size Medium, to the cart.

Both simple and optioned products are together in the same cart with a proper subtotal, all responding to quantity changes by clicking “Update Cart.”

We have the basics of the cart working in terms of the product information and calculations. Next, we’ll continue and configure CartThrob to handle the orders.

Have questions or comments about this course? Be sure to join the discussion and post in the ExpressionEngine Forums!

Originally published by Paul Larson at u.expressionengine.com

Headless ExpressionEngine: Using Bones to Create a Static Site

ExpressionEngine — Mon, 06 Jun 2022 10:34:00 +0000

ExpressionEngine is so powerful under the hood when it comes to managing content. In this example, we’ll use Bones to use the data from our EE site to build out a static site, using a static site generator called Jigsaw. We’ll explore a bit of API safety, as well as managing data coming from EE.

If you haven’t, watch the first part of our series on Bones here: Using ExpressionEngine To Power Your JavaScript Frontend Using Bones

YouTube:

Bones is a super simple way to utilize ExpressionEngine as a headless content management system for use in javascript frontends, static site builders, and more!

Bones Hello World: https://github.com/dougblackjr/bones-hello-world

Originally published by Doug Black at u.expressionengine.com

Using ExpressionEngine To Power Your JavaScript Frontend Using Bones

ExpressionEngine — Mon, 17 Jan 2022 14:26:00 +0000

Let’s take a look at building a Vue.js frontend powered by headless ExpressionEngine using the Bones add-on.

Bones is a super simple way to utilize ExpressionEngine as a headless content management system for use in javascript frontends, static site builders, and more!

YouTube:

Find more information here:

Bones Hello World: https://github.com/dougblackjr/bones-hello-world

Originally published by Doug Black at u.expressionengine.com

A Primer On Simple Conditionals

ExpressionEngine — Tue, 11 May 2021 14:55:00 +0000

This article is intended as a gentle introduction to ExpressionEngine conditionals to give the reader an idea of how they work using real-world examples.

What is a “conditional”?

They allow you to compare or evaluate one piece of information against another and optionally show a response based on the result.

Conditionals generally work on the result being true or false - in essence, you’re asking a question to get an answer.

What can you compare/evaluate?

You can compare any variable or value available in ExpressionEngine, including global variables, channel entry fields, member fields, and your own custom values.

Here’s a non-exhaustive list of things you can evaluate either singly or one versus the other:

numbers
dates
URL segments
entry fields, title, custom fields
files, filename, extension
statuses
trigger words (like yes/no, on/off)
logged in status, name, email, etc.
member group, name, ID, etc.
your own values, hard coded or generated programmatically

When to use a conditional

There are near infinite uses, but some common ones are:

checking if a visitor is logged in or not
display alternative content based on the value of other content
display different content based on part(s) of a URL
changing HTML or other code based on the value of something
adding opening and closing HTML tags like <div></div>
checking if something exists or not
checking the value of something

Conditional tag syntax

Conditional tags are always wrapped in {if}{/if} tags - just like regular HTML tags. You add values you want to evaluate and provide the answer based on the result.

Here are a few very simplistic examples showing you how evaluation logic works:

{if sky}Yes the sky exists!{/if}
{if sky is blue}It's day time{/if}
{if sky is black}It's night time{/if}
{if sky is NOT blue}It's night time{/if}
{if sky is NOT black}It's day time{/if}

See how we’re comparing the sky and its color then providing an answer for each variation? Note how there’s more than one way to provide the same answer (“is” and “is NOT”). The actual answer can be anything you want, even no answer at all.

Let’s start with a basic example

{if logged_in}
  Hello customer
{/if}

What this does is check if the visitor has logged in to your site.

if logged in, they will see the “Hello customer” message
if not logged in, they will see nothing

Let’s expand that a bit more…

{if logged_in}
  Hello customer
{if:else}
  Please login
{/if}

What we’re now doing is getting two possible values.

if logged in, they will see the “Hello customer” message
if not logged in, they will see the “Please login” message

So “if” the first value is true do that, “else” do the other.

Evaluating entry content

Your entries are made up of several custom and core fields such as Title, Entry date, Status, and so on. You can evaluate any of these in a conditional, some are a little more complicated than others, but the logic is the same.

Let’s say you have a field for a blog excerpt contained in a div element. Your template code may look like this:

<div class="row">
  {blog_excerpt}
</div>

The only problem here; if the excerpt field is blank, the page will have an empty div element in it; you won’t want that!

To solve this, you can use a conditional to only show the div if the excerpt exists:

{if blog_excerpt}
<div class="row">
  {blog_excerpt}
</div>
{/if}

So “if” the excerpt exists, then show it, otherwise do nothing. In other words, the div elements will only show if the excerpt exists.

Let’s expand that by providing a fallback message:

{if blog_excerpt}
  <div class="row">
    {blog_excerpt}
  </div>
{if:else}
  The author hasn't written an excerpt
{/if}

So “if” the excerpt exists, show it, “else” show the message.

Comparing a date

Date variables in ExpressionEngine allow you to format a display date however you need.

In this example, I’m using the 3 letter code for day of the week, Mon, Tue, Wed, etc. referenced by the %D format value. The current_time tag outputs, you can probably guess, the current time, as in right now.

The idea here is to show a message on a specific day, in this case, a Sunday:

{if "{current_time format='%D'}" == "Sun"}
 Sorry we're closed today
{/if}

What this does is compare the current day of the week {current_time format="%D"} to a target day value of “Sun”(day). If the answer is true (if today is Sunday) show the message, otherwise do nothing. The == value is shorthand for “is equal to.”

Note that here we have to wrap the current_time tag in double quotes because it’s a tag inside another tag.

Testing against a URL segment

Conditionally do something based on part of a URL

Say you have a URL like https://example.com/blog/post/my-blog-post, then “blog” is segment 1, “post” is segment 2, and “my-blog-post” is segment 3 (See the docs for more on URL Segments ).

Here’s a couple of examples:

{if segment_1 == "blog"}This is the blog.{/if}


{if segment_2 == "post"}You're reading a blog post.{/if}


{if segment_1 == "about-us"}Why not read our blog?{/if}


{if segment_1 == ""}This must the home page.{/if}

Using a conditional to show a confirmation message

Say you have a contact form page at https://example.com/contact and your success page is at https://example.com/contact/thanks - you can run a conditional on segment_2 (thanks) to show a success message in the same template:

{if segment_2 == "thanks"}
Thanks for getting in touch!
{/if}

<form>
...contact form fields
</form>

Using a conditional to insert a CSS class name

Let’s say you wanted to add a class to an element but only in the /blog section. You could do something like this:

<body{if segment_1 == "blog"} class="blog"{/if}>

Would output as this (if the segment matched):

<body class="blog">

You could also append a new class name to an existing one like this:

<body class="body{if segment_1 == 'blog'} blog{/if}">

The result:

<body class="body blog">

Counting first and last

You can use conditionals to do simple calculations based on numbers. ExpressionEngine entries make available variables for:

count (a running count of the entries being displayed, so the first entry will be “1”, the third entry would be “3”)
total_results (the total number of entries being displayed)

You want to mark the first or second item:

{if count == 1}
This is the first one
{/if}

{if count == 2}
This is the second one
{/if}

You want to mark the last item:

{if count == total_results}
This is the last one
{/if}

You can combine these when you need to output some HTML before and after your content:

{if count == 1}

<div class="row">
{/if}

  Content...

{if count == total_results}
</div>

{/if}

Using operators

These allow you to compare things but in different ways. You can test for things that exist or don’t exist, less than or more than, and even look for specific words or phrases.

So far I’ve only used the == operator (equal to) in my examples. Here are a few more ways to compare values:

Check if something is not empty/blank

{if blog_exerpt != ""}The excerpt is not empty{/if}

Where != “” is asking if the field is not empty - not equals blank.

Check if something is empty/blank

{if blog_exerpt == ""}The excerpt is empty{/if}

Where == “” is asking if the field is empty - equals blank.

Check for a word or phrase in text

{if blog_exerpt *= "Tom"}The excerpt mentions Tom{/if}

Where *= is asking if the text contains the word “Tom.”

Check if something is less than x

{if product_stock < 10}Low stock{/if}

Where < is asking if the value is less than 10.

Check if something is more than x

{if product_stock > 10}We have loads in stock{/if}

Where > is asking if the value is more than 10.

There are many operators available for you to use. A full list is available in the documentation.

Troubleshooting conditionals

If your conditional tag doesn’t work, here are a few things to check:

is the syntax correct?
have you missed the trailing {/if} ?
check spelling, missing or extra spaces
is your tag in the right place in the template?

If you still have problems, it’s always worth posting on the EECMS Slack channel or the ExpressionEngine forums. An experienced eye will usually help you solve it.

Summing up

Conditionals can be hard to get your head around at first but stick with it. As soon as it clicks, you’ll find they can be incredibly powerful tools to help you create dynamic site content.

Originally published by Rob Allen at u.expressionengine.com

Contributing to ExpressionEngine Documentation

ExpressionEngine — Fri, 16 Apr 2021 15:24:00 +0000

Contributing to the ExpressionEngine Documentation

Good documentation is the foundation of good software and your contributions can help make good documentation great.

If you’re an ExpressionEngine user, then you have something to add. There is always room for more examples, clarifications, corrections, and updates. Jump in and make a pull request or give us a heads up by reporting an issue. Since the docs are all in markdown formatting and updates should be pretty straightforward.

Understanding the Workflow.

Contributing to the docs requires a basic understanding of Git. Here’s an overview of the workflow

Fork the GitHub repository: https://github.com/ExpressionEngine/ExpressionEngine-User-Guide . Read more about creating a fork of and working with a public repository here: https://docs.github.com/en/github/getting-started-with-github/fork-a-repo#fork-an-example-repository
Create a branch (see Branches below).
Update your branch
Submit a Pull Request, requesting merging your branch into the 6.dev branch of the ExpressionEngine public repository.

Contributing to the Documentation

All of the source files exist under docs/ and is where you will add new documentation or modify existing documentation. We recommend working from feature branches and making pull requests to the #.dev branch of this repo (See Branches below).

Suggesting a change is easy and there is no way you’ll mess up the public repo.

Start by forking the repository, the new branch you create is the one you’ll do your work in.

Once you have your new branch, confirm you’re actually in it! If you haven’t already, make sure you’ve read though the style guide. Then make your changes inside of your feature branch.

Push your changes to your fork of the repository, and when you’re done, send us a pull request.

We’ll take a look at your pull request, make sure everything looks alright, ask for any needed changes, and then merge it into the main code.

Branches

| Branch | Purpose |
| ------ | ------- |
| #.x | Currently released and published version.
| #.dev | Updates for the next version of ExpressionEngine (current version is the default branch). Does not exist for previous versions. |
** replace `#` with the current version of ExpressionEngine or version you wish to target.

Recommended branch names are namespaced and unique, e.g.:

feature/my-feature-slug
bug/bug-description-slug

Building and Reviewing the Docs Locally

While some updates are easy and can just be done in markdown without much review, others require a review of what the updates will actually look like when published to the docs. To review changes, you’ll need to build the docs locally. This requires a little bit of setup but is not overly complicated if you’re already familiar with front-end build tools.

Prerequisites

Building the docs requires Node and npm.

In the root of the repository, install all the dependencies: npm install

Building the Docs

To build the docs: npm run build

To dynamically rebuild on any file changes: npm run watch

Building theme assets

The documentation css and js files are located under theme/assets-src.

To build the theme assets, run npm run buildAssets. You can also dynamically rebuild the assets when a file changes: npm run watchAssets.

As with anything else, if you have any trouble building the docs let us know and we’d be happy to help.

Style Guide

Please read the style guide for samples and convention standards used in the ExpressionEngine user guide.

Reporting Issues

Want to help but a little daunted by the idea of making a pull request? We still want to hear from you. You can report errors in the documentation as issues in the github repo. Just remember, the more detailed the report, the more likely someone will be able to make improvements.

Thanks!

Most importantly, THANK YOU! Thank you for caring about the community and wanting to help. ExpressionEngine is open source and has always been successful because of our community. Let us know if you have any problems with the docs or anything else and we’ll be happy to help.

Originally published by Andy McCormick at u.expressionengine.com

Using Mailgun to Send Emails from your Website

ExpressionEngine — Tue, 13 Apr 2021 22:26:00 +0000

Mailgun’s SMTP Relay service is a quick an easy way to have ExpressionEngine transactional emails handled through a dedicated email provider. There’s just one tiny glitch you need to be aware of. The line ending setting needs to be changed from the default \n to \r\n. That’s it. Everything else is self-evident. But in case it’s not…

In your Mailgun account, go to the Overview for your domain. In my case, I just have their default sandbox domain. You’re going to select ‘SMTP’ as your mail option and the required settings, including username and password, will be revealed.

Go to your ‘Settings- Outgoing Email’ settings in your ExpressionEngine control panel and enter your Mailgun settings

Setting	Value
Protocal	SMTP
Newline Character	\r\n
Server Address	smtp.mailgun.org
Server Port	587
Connection Type	STARTTLS

Save your settings and send a few test emails from the Communicate page.

Originally published by Robin Sowell at u.expressionengine.com

Add commenting to your articles

ExpressionEngine — Thu, 28 Jan 2021 22:10:00 +0000

Summary

Adding a comment section to your articles and posts gives your reader a chance to add value to what you’ve written – or draw your attention to a necessary correction or update. If you’ve struggled with integrating comments to your site content, we’re here to help!

This tutorial assumes that you already have a basic site set up, with both single-entry article pages and some sort of index page that lists all of your articles. If you run into trouble with this tutorial, the Expression Engine documentation is likely a great resource.

Enable the Comments Module

The first thing you need to do is enable the Comments module; it’s not with the other add-ons where you think it might be.

Head to the Expression Engine system settings page, and click on Comment Settings, at the following URL: /admin.php/cp/settings/comments

Flip the “Enable comment module?” toggle to on and hit save.

Enable Commenting on the Channel

Next, you’ll need to enable commenting for the specific Channel you want to have comments on. Head to the Channel Manager. /admin.php?/cp/channels Inside the Channel Manager, click on the Settings tab for the Channel where you wish to allow commenting, and look for the Commenting section shown in the screenshot below. You’ll find it way down near the bottom of the page.

Flip “Allow Comments?” to the “On” position, and keep in mind that you’ll need to do this for every Channel for which you want comments enabled.

There are a few other helpful settings here which we’ll go over, but if you just want the basics you can skip to the next section.

Other Channel Commenting Settings

Allow comments default - Each individual entry can have comments turned on or off. This option determines if new entries in this channel will have commenting turned on. Require Email - This does what it sounds like. If enabled, anyone submitting a comment must be either logged in or provide an email address. Important note: If this is turned on, you must have an email field in your comment submission form! Require Membership - A stricter version of Require Email. With this option, users must be registered members of the site to comment. Render URLs and Email addresses as links? - When members submit comments with URLs or email addresses, this setting controls if those appear as clickable links. You may wish to disable this, depending on your particular usability requirements.

Enable Commenting by Member Roles

Next up, check to ensure you’ve given appropriate member roles permission to comment. Super Admins automatically have all permissions, so testing is sometimes confusing. It’s a good idea to create a test user for yourself in a standard Member or Editor role to verify your permissions are working correctly.

Member Roles can be found by clicking on the Members menu item and the Member Groups submenu, or at this URL: /admin.php?/cp/members/roles

EE5 Note:

If you’re following this guide for Expression Engine v5, you will follow essentially the same steps, but the permission is found under the Member Groups settings, rather than Member Roles. The control panel URL you will want for EE5 is: /admin.php?/cp/members/groups

For each Member Role that you want commenting enabled, look for the Commenting section under the Website Access tab. Flip the toggle on for “Submit Comments.”

If you want Guests (users who are not logged in) to be able to comment, be sure to enable this for the Guest member role – that’s the default anyway.

If you have a special Member Role who should be immune to comment moderation, you can give them the “Bypass moderation” permission. This is also where you can allow specific Member Roles to edit or delete their own comments, or the comments of others if you wish.

Important note: Enabling the “Edit comments by others” setting doesn’t automatically make the interface to allow this appear on the front end – this is just granting permissions.

CAPTCHA or no CAPTCHA?

Another comment-related setting you can optionally enable is CAPTCHA, the test to try and make sure someone is a human and not a spambot.

The settings for CAPTCHA can be found on the System Settings page, under the CAPTCHA submenu at this URL: /admin.php?/cp/settings/captcha

Keep in mind that enabling CAPTCHA here will enable it for all front-end forms, not just for comments. I like to enable it, but then I disable “Require CAPTCHA while logged in.” We assume that registered members can be trusted at least at this level, and this way only Guests will face the CAPTCHA.

Display Comments with an Article

That’s it for the set up work! Stretch your fingers, grab a tea, and now we can move on to the template work!

In the template for your single-entry article page, you’ll need to enter template code to display comments. This tag pair is dynamic by nature, and by default will fetch the correct entry automatically based on the current URL.

Important note: This code must be placed OUTSIDE of any exp:channel:entries loop, because it uses some of the same variables, including {count}. If you do need to put it inside the loop, you must use an embed.

At its most basic, the comment entries loop looks like this:

{exp:comment:entries sort="asc" limit="20"}
  {comment}
  <p>By {author} on {comment_date format="%Y %m %d"}</p>
{/exp:comment:entries}

We won’t go into a full description of the ways you can output and format comments – it’s quite robust.

The Comment Submission Form

The most important piece of the puzzle is the submission form. After all, there’s no point in displaying comments if no one can submit them.

Place the following code directly beneath the comment:entries loop we posted above.

{exp:comment:form channel="news"}

  {if logged_out}
    <label for="name">Name:</label> <input type="text" name="name" value="{name}" size="50" /><br />
    <label for="email">Email:</label> <input type="text" name="email" value="{email}" size="50" /><br />
  {/if}

  <label for="comment">Comment:</label><br />
  <textarea name="comment" cols="70" rows="10">{comment}</textarea>

  {if captcha}
    <label for="captcha">Please enter the word you see in the image below:</label><br />
    <p>{captcha}<br />
    <input type="text" name="captcha" value="{captcha_word}" maxlength="20" /></p>
  {/if}

  <input type="submit" name="submit" value="Submit" />

{/exp:comment:form}

There are a few specific things to watch for in the comment submission code.

First, be sure to change the channel parameter to the name of your Channel.

Second, notice that we are asking for an Email address if the user is not logged in, but skipping it if they are. This is linked back to the earlier point about the “Require Email” and “Require Membership” options found under Channel Settings.

The third thing to notice here is the {if captcha} line. If CAPTCHA is turned on, and the user is not exempt from CAPTCHA, a standard CAPTCHA will appear in this area of the form. You can find out more about how to customize CAPTCHA in the Expression Engine documentation.

Once this is in place, you should see your comment form on the front end, and be able to submit new comments. Hurray!

Lastly, if for any reason the person viewing the page does not have commenting permission (either because of member, entry, or channel settings), the form will simply not display. You can use {if comments_disabled} to display alternate instructions if there will be some entries in each status.

The display of existing comments is possible whether comments are enabled or not – once an entry has comments, disabling comments will only disable the form, not the comments you’ve already collected.

Editing Comments

ExpressionEngine does a decent job of trying to let you edit existing comments via Javascript. We recommend following the instructions in the documentation. However, because each site is unique, it may require some tweaking to their JavaScript. The important thing to note is that before you spend too much time digging into the javascript and templates, save yourself some time and check to make sure your permissions are set properly.

--
Originally published by Michael Kant at u.expressionengine.com

Custom Global Variables Using the Config File

ExpressionEngine — Mon, 03 Jun 2019 15:13:00 +0000

One thing I like to do is take advantage of global_vars in template tags. I’m a big fan of keeping configuration in the site’s config.php file. That way, values can be changed depending on the environment either by using something like Ansible to provision and configure your site, or by using PHP’s getenv() functions. For additional reading on environment based configuration check out The Twelve-Factor App.

Here is an example of what is included in nearly all of my ExpressionEngine site’s config.php files. Each variable is prefixed with global:, similar to how we prefix the pre: variables in my previous article.

$default_global_vars = [
    'global:disabled_params' => 'disable="trackbacks|pagination|member_data"',
    'global:disabled_params_all' => 'disable="trackbacks|pagination|member_data|category_fields|categories|custom_fields"',
    'global:disabled_params_strict' => 'disable="trackbacks|pagination|member_data|category_fields|categories"',
    'global:blog_category_groups' => '2|3|5|6',
    'global:some_api_key' => '98ufahaskdfnasd312',
];

if (!isset($assign_to_config['global_vars'])) {
    $assign_to_config['global_vars'] = [];
}

$assign_to_config['global_vars'] = array_merge(
    $default_global_vars,
    $assign_to_config['global_vars']
);

Now in my templates I can shorten my tags, and globally update every entries tag on the site with a single change in the config.php file.

{exp:channel:entries {global:disabled_params}}
    ...
{/exp:channel:entries}

Some people like to prefix everything. I’ve seen custom fields prefixed with cf_, thus their templates are filled with {cf_body}, {cf_summary}, or {cf_related_entries}. I’ve personally never been a fan of prefixing field variables unless it is a prefix which helps indicate what channel it belongs to, such as {person_first_name}. {cf_person_first_name} feels redundant to me, but again, that is personal preference.

Prefixing or no prefixing, find what works for you, just pick a pattern and be consistent 😊

--
Originally published by Brian Litzinger at u.expressionengine.com

Forem: ExpressionEngine

ExpressionEngine and Headless

What ExpressionEngine Can Do

What ExpressionEngine is Not

Out of the Box

Limitations

No rate limits

Lack of access control with something like tokens

GET is the only request type

GET Example

Example of an HTML template at /events/item/my-event

Example of the same data in JSON at /api/events/my-event

Creating Better Queries

Extending with Add-ons

Bones by TripleNERDScore

Webservice by Reinos

Custom Add-ons

Modifying Entries

Final Thoughts

Building an E-commerce Website With ExpressionEngine, Part 4

Part 4: Notifications and Order management

4a) Notifications

4b) Order Management

Order entries

Order Manager

Building an E-commerce Website With ExpressionEngine, Part 3

Part 3: Shipping / Tax / Payments

3a) Shipping

3b) Taxes

3c) Payments

3d) Submit an order on the frontend

Building an E-commerce Website With ExpressionEngine, Part 2

Part 2: Channel installation and Discounts

2a) Orders/Discount Channel Installation

2b) Coupon Code (Discounts)

Building an E-commerce Website With ExpressionEngine, Part 1

Part 1: Setting the stage

1a) Simple Products: field creation and entry configuration

1b) Optioned Products

1c) Frontend Add to Cart Demo

Headless ExpressionEngine: Using Bones to Create a Static Site

Using ExpressionEngine To Power Your JavaScript Frontend Using Bones

A Primer On Simple Conditionals

What is a “conditional”?

What can you compare/evaluate?

When to use a conditional

Conditional tag syntax

Let’s start with a basic example

Evaluating entry content

Comparing a date

Testing against a URL segment

Conditionally do something based on part of a URL

Using a conditional to show a confirmation message

Using a conditional to insert a CSS class name

Counting first and last

Using operators

Check if something is not empty/blank

Check if something is empty/blank

Check for a word or phrase in text

Check if something is less than x

Check if something is more than x

Troubleshooting conditionals

Summing up

Contributing to ExpressionEngine Documentation

Contributing to the ExpressionEngine Documentation

Understanding the Workflow.

Contributing to the Documentation

Branches

Building and Reviewing the Docs Locally

Prerequisites

Building the Docs

Building theme assets

Style Guide

Reporting Issues

Thanks!

Using Mailgun to Send Emails from your Website

Add commenting to your articles

Summary

Enable the Comments Module

Enable Commenting on the Channel

`GET` Example

Example of an HTML template at `/events/item/my-event`

Example of the same data in JSON at `/api/events/my-event`