**Quick Introduction**

In this quick intro guide I will cover the following things

• How to create a Shopify App project using ExicoShopifyFramework
• How to install the app in an actual Shopify store
• Walk over few built-in features of the ExicoShopifyFramework

So let's start covering these above topics step-by-step.

1. Install the project template

The easiest way to create a Shopify app using ExicoShopifyFramework is to use the ExicoShopifyApp project template. Open up the command prompt and type in the following command

dotnet new -i ExicoShopifyApp

Now type in

dotnet new 

And you should see that new dotnet core project template has been added to your system called ExicoShopifyApp

Now lets create a new Shopify app project using the template we just installed. Type

dotnet new ExicoShopifyApp

The result would be something like this (I created the project inside an empty folder called demo; so my project name is demo.csproj)

Now lets open the project in Visual studio 2017 (you can use any editor) and have a look at the structure of the project

2. Making minimum changes to the appsettings

Now open up the appsettings.Development.json file (because we intent to run the app in development environment) and find the section called SettingsSeed

The minimum requirement to be able to install this newly created app of ours into any Shopify store is to modify the SettingsSeed section. Out of the box the that section would look something like this

  "SettingsSeed": {
    "SECRET_KEY": "shopify-app-secret-key", 
    "API_KEY": "shopify-app-api-key", 
    "PRIVILEGED_IPS": "127.0.0.1", 
    "SEND_GRID_API_KEY": "sendgrid-api-key", 
    "APP_BASE_URL": "https://localhost:44300", 
    "APP_VERSION": "1.0.0",
    "SHOPIFY_EMAILS_FROM_ADDRESS": "an_email_address",
    "SHOPIFY_EVENT_EMAIL_SUBSCRIBERS": "email_addresses_comma_seperated",
    "APP_NAME": "My Shopify App",
    "APP_SUPPORT_EMAIL_ADDRESS": "aupport_email_address"
  },

Now the item names are pretty self explanatory. A detail description of all settings are discussed in the Settings wiki page.

This guide is to quickly enable you to get the framework up and running without doing too much work.So We are not interested in seeing any web hooks in action right now.Partly because Shopify won't accept localhost as a part of the URL; even though technically we can make it working using ngrok or something similar like that. But I am going to skip it in this quick introduction.Also I am using visual studio because it will create self signed certificate and let me use it in my local machine with IIS express; I don't need to do any configuration.If you wish to use kestrel you are more than welcome to do that. But in that case you have to do some configuration and make the kestrel running on https using a self signed certificate on your local box.

Now the only items that we will be changing in that section are

• SECRET_KEY (get it from the app setup page within the Shopify partner dashboard)
• API_KEY (get it from the app setup page within the Shopify partner dashboard)

• SEND_GRID_API_KEY (SendGrid)
• APP_BASE_URL (if you wish to run the app on different port on local machine)
• SHOPIFY_EMAILS_FROM_ADDRESS
• SHOPIFY_EVENT_EMAIL_SUBSCRIBERS
• APP_SUPPORT_EMAIL_ADDRESS

ExicoShopifyFramework uses SendGrid to send emails. SendGrid offers free plan (40k emails first 30 days then 100 emails/day) which is perfect for me especially for development phase. I use their paid plan for other projects in production. However ExicoShopifyFramework is flexible enough and it allows you to write your own email sender (may be you want to use SMTP) and hook it up with the core engine. You implement a simple interface and register that as your email service and you are done.I will write a tutorial on how to implement custom emailer and hook it up with the framework in a blog/wiki page soon.

Finally use same or different email addresses for the last three settings of the above list. It a quick start demo so using same email is better in my opinion. And again purpose of these settings along with all other framework settings are discussed in the Settings wiki page.

Now one last thing, ExicoShopifyFramework uses a database and for my case the default connection string in the appsettings.Developer.json file is just perfect. If you need to change the connection string then change it; it is the very first setting of the appsettings.Development.json file.

  "ConnectionStrings": {
    "DefaultConnection": "Server=localhost\\SQLEXPRESS;Database=MyShopifyApp-DEVELOPMENT;MultipleActiveResultSets=true;Trusted_Connection=True"
  }

3. Build and run the app and create database

Before we build the app, lets just check whether our project has the latest Exico.Shopify.Web.Core NuGet package. Open up the package manager console and execute the following command

Update-Package Exico.Shopify.Web.Core

Now lets build the project and it should compile without error. Run the app and you should see something similar to this

Once the app runs it also creates the database in the background. If you connect to your database server then you should see the database is indeed created

4. App settings in the Shopify partner dashboard

Now we have everything set up. Lets try installing our app into a development store. Assuming that you already created an app using Shopify partner dashboard. If you do not have an app created using the partner dashboard yet, then it time now.

For this demo I created one called Exico Shopify Test App - Local Machine

I will now go to the setup of the application and walk you over my settings (you should have similar settings for for yours)

Our local app is running on https://localhost:44300/ so my settings look like this

In this above settings you can see that all these requests are going to be handled by Shopify controller. It is a built in controller provided by the framework. Details about this and other built in controllers can be found in the Built in Controllers page.

As for the mandatory controller settings leave them blank for now.

The framework does come with handlers that can handle the mandatory webhooks. But since we are running our app locally Shopify won't Accept the URLs because they will have localhost in the URL. Unacceptable by Shopify but technically correct values for these above settings , in our case, are :

NOTE: MandatoryWebHooks is a built in controller.

Now lets do one more thing, let's just disable Shopify Embedded App Sdk for now.

The framework can run as embedded app as well. But the default behavior is not-embedded model. To enable your app (built with Exico Shopify Framework ) to run in embedded mode, you need to enable the option in two places. One that is enabled by default in Shopify partners dashboard (app extension section) and the other place is your app's appsettings; setting name is UsesEmbededSdk

4. Let's install the app

In this step you need to create a development store if you do not have one already. I already created one called https://dev-3-store.myshopify.com (owner email is [email protected])

Our goal is to install our demo app in this store. Now our app is running locally and it is not listed in the app store yet. So we need to install this manually. To install it manually on a development store do the following steps from the app setup page More Actions->Install on development store

Then choose the development store (in this case the store is https://dev-3-store.myshopify.com)

Hitting install app on store will start the installation process and the framework will take over and handle the rest of the process (assuming our demo app is still running on local machine).

These are the following steps that will occur one after another as a part of the installation process and all of these steps will be handled by the Exico Shopify Framework ; you do not write a single line of code !

First screen that will appear is this

The two permissions that are listed above are coming from our appsettings.Development.json file's following section.

  "Permissions": [
    "read_inventory",
    "write_inventory"       
  ]

Add remove permissions according to your need.

Now click on the Install unlisted app you will see this screen

This Test plan is also coming from appsettings.Development.json file's following section.

  "PlansSeed": [
    {
      "Name": "Test",
      "TrialDays": 5,
      "IsTest": true,
      "DisplayOrder": 1,
      "Price": 0.01,
      "Description": "This is a test plan",
      "Footer": "Test footer.",
      "Active": true,
      "IsDev": false,
      "IsPopular": true,
      "PlanDefinitions": [
        {
          "OptionName": "Feature1",
          "OptionValue": "Value1",
          "Description": "Enables feature1"
        }
      ]
    }
  ]

When we started our app the app created this plan inside the database using this setting, in the Plans and PlanDefinitions table in the database and now it is being loaded from database (after first read it is cached in memory though).

Now if you click in the subscribe button . Framework will handle your request and redirect you back to a new screen within the store admin to confirm the subscription charge

Now if you decline the charge the framework will handle it and take appropriate action. But for our demo we will click Approve charge to complete with the installation.

And that will be handled by the framework as well and will grant you immediate access to the app's dashboard.

5. Checkout few built in features that ship with the ExicoShopifyFramework

And now that we have successfully installed our demo app running on our local machine in the development store!!! Let's checkout some features of the framework.To do that go to the Apps section in your development store. You will find that our app is listed as installed app :-). Click on the app name and it will take you to the app dashboard page.

Now back to the app. Once you are in the app dashboard please click on the MyProfile and you will see that the framework provides a nice profile page that is built into it.

Now click on the Support button and you will see the build in support page

Note that all (razor cshtml) views rendered by the framework are overridable. You can replace the default look and feel with your own custom views. How to replace these default pages with your own view are discussed in Customizing views wiki page.

Now during this installation in the background the framework has already produced three emails and sent to the appropiate recipients. There are total three emails that are sent during the installation process

1. An email to the app developer saying that some shop (in our case dev-3-store) has installed our app.

1. A welcome message to the store owner with default welcome message (you can customize the message according to your need, we will see the details in the settings wiki page).

1. An error event email.

Because we did not specify the uninstall or any webhook definitions in the appsettings.Development.json file,

     "WebHooks": [
       /*{
         "Topic": "orders/create",
         "Callback": "callback-url"
       } */
     ],

So the framework auto generated the uninstall webhook for us and it was using the app base URL setting from the database (that was seeded from the appsettings.Development.json file)

     "SettingsSeed": {
       ....
       "APP_BASE_URL": "https://localhost:44300",
       ....
     }

So the URL it generated was something like below

   https://localhost:44300/AppUninstall/AppUninstalled?userId=[some-guid]

and the creation of the hook failed because the URL contains localhost and Shopify will not allow any URL that contains localhost as a part call back URL for any webhooks. As a result Shopify API threw an exception and the framework caught it and notified us about this exception via email.

AppUninstalled is a built in controller. We will talk about built in controllers in the Built in Controllers wiki page.

---

Whats Next ?

So far we have seen an example Shopify App project that is using Exico Shopify Framework.But it doesn't do anything.That's because we haven't written anything yet. At this point the possibilities are endless. You can create any kind of app using this base project. If you do not need to override any default functionalities/views then the next step would be to create a controller that extends the ABaseSubscriberController and start writing your app specific code!!

Conclusion

So, in summary, you get all of these pages,functionalities and many more features right out of the box when you use Exico Shopify Framework. This framework is extremely customizable and extensible , almost anything can be replaced with a few lines of codes by your custom implementation.

You also get built in controllers , attributes,subscription based access control, view helpers,email helper, logging helper, API helpers and many other handy tools that you can leverage so that spend your time concentrating on the app specific code rather than thinking and wasting time on generic and routine stuffs.

Please browse other wiki pages and learn more!