Friday, 4 May 2018

Create JSS Basic App for Sitecore step by Step

JSS is a complete SDK for JavaScript developers allowing to build full-fledged solutions using Sitecore and modern JavaScript UI libraries and frameworks (React.js and Angular). You can develop by being completely disconnected from Sitecore and get started without a Sitecore install. And deploy apps in physically decoupled way ("headless") to any platform and virtually to any cloud with full Sitecore Experience Platform capability preserved, including Experience Editor, Personalization, MV testing and Tracking / Analytics.

Requirements

JSS server functionality requires active subscription license.
To check if your license can use JSS, open your license.xml in a text editor and search for Sitecore.Visit - if it's found, you're ready to use JSS
  1. Sitecore XP 9.0 (Update-1 highly recommended). You can download it here.
  2. node.js v6.9 or later (Command: node --version)
  3. yarn, or npm v5.7 or later (Command: npm --version)
Create your JSS App

npm install -g @sitecore-jss/sitecore-jss-cli
jss create my-first-jss-app basic-sample-react
cd my-first-jss-app jss start

  • To start the app in disconnected mode which uses locally defined content, run jss start

Configuring the Sitecore connection


To setup the Sitecore connection, run jss setup at a command line within your JSS app, and follow the prompts. You will be asked for several pieces of information:
  • The Sitecore "Website" folder: This is the root physical path to the Sitecore instance to connect to. This is used by jss deploy config, jss deploy files, and jss deploy:watch. If you're connecting to a remote Sitecore instance that does not have a local physical path, leave this blank. You will need to use jss deploy packageto deploy your application in this scenario, and manually deploy the app's Sitecore config file.
  • The Sitecore host. This is the root URL to the Sitecore instance to connect to. This is used by jss deploy package and connected mode. If you do not plan to use those, this can be left blank.
  • The Sitecore API key. When setting up the JSS server components an API key is issued to enable connections to the Sitecore server. This is required if the Sitecore host is set.
jss setup will help you generate the scjssconfig.json file that contains your local instance-specific settings. If you prefer, you may also manually create the scjssconfig.json file in your app's root (a peer of package.json). Here is a sample of the file:

JSS install for Sitecore

The JSS server packages downloaded from dev.sitecore.net:
  • Sitecore JavaScript Services Tech Preview Server 9.0.1 rev. 180412.zip
  • Sitecore JavaScript Services Tech Preview Infrastructure 9.0.1 rev. 180412.zip

Installation

  1. Install both .zip packages using Installation Wizard from Sitecore Desktop.
  2. Make the following changes in Web.config.
    1. Add the following element to the bottom of the system.webServer/handlers section  <addverb="*"path="sitecorejss_media.ashx"type="Sitecore.JavaScriptServices.Media.MediaRequestHandler, Sitecore.JavaScriptServices.Media"name="Sitecore.JavaScriptServices.Media.MediaRequestHandler"/>
    2. If you installed the Infrastructure package, add the following element inside the system.webServer/modules section  <addname="Sitecore.JavaScriptServices.Ship.ShipFilter"type="Sitecore.JavaScriptServices.Ship.ShipFilter, Sitecore.JavaScriptServices.Ship"/>

Sitecore configuration

Step 1. Configure your host names

This step is optional and only needed if you want to associate JSS apps with a separate site with a designated host name. If you don't want this, you will have to modify the site definition for your sample app and remove the hostNameattribute. The config file can be found under sitecore/config:
On Windows the hosts file will typically be found at C:\Windows\System32\drivers\etc\hosts:
  127.0.0.1    JssBasicAppReactWeb
After adding the host name entries, add them to as bindings on the IIS instance:

Step 2. API Key

The services used by JSS (including the Layout Service, the Content Service, and the Dictionary Service) utilize the API Keymechanism provided by Sitecore Services Client (SSC). You'll need to create an API Key and note its Item ID for use in setting up the sample apps.
  1. Log into Sitecore (e.g. http://your-host-name/sitecore) and open the Desktop application.
  1. Using the database icon in the lower right, switch to the core database.From the start menu / Sitecore icon, open the Content Editor application.
  2. Navigate to /sitecore/system/Settings/Services/API Keys in the content tree, and via right-click or the Home ribbon, insert a new API Key item.
  3. Give the item any name you like, though in practice the name should reflect where the key will be used (e.g. the name of your app).
  4. At the minimum, specify * as value in AllowedControllers:
  1. It is recommended to specify the Impersonation User explicitly. The impersonation user is a Sitecore user whose security context is used for requests from the JSS app. If no impersonation user is specified, it will default to the sitecore\ServiceAPIuser and some APIs may not work correctly. For example, when using the Dictionary Service without dictionary domains, the Impersonation User will need to access the items under /sitecore/system. By default, the sitecore\ServiceAPI user doesn't have read access to that content area. To address this, you will have to specify a new account there with appropriate permissions or simply put standardextranet\anonymous in there.
    Do not ever use sitecore\admin or any other privileged user as the impersonation user. A serious security breach will result. Use only extranet\anonymous or a dedicated specific user for impersonation.
  2. Save the item and make note of its Item ID.

Step 3. Config deployment

Config deployment can be done in two ways:

Automatic config deployment

Automatic deployment deploys the config patches directly from the JSS app using the JSS CLI. The JSS app must be connected to Sitecore for this to work.
  1. Ensure that scjssconfig.json exists in the JSS app root; if it does not, run jss setup to set up the connection to Sitecore
  2. Run jss deploy config.
    Make sure you execute the command under proper privileges, as UAC in Windows may block you from writing into the Sitecore folder.
    This will take the Sitecore config patch file under sitecore/config and copy it to the Sitecore App_Config/Include/zzz folder. You may also copy this file manually; jss deploy config is just for convenience.This configures the app, creates a site for it and enables live mode among other handy things. A Sitecore developer should review the patch file carefully to ensure that all the settings are as they should be; in production, for example, live mode is undesirable.

Step 4. (Optional step) Sitecore Ship configuration

Only required if you are deploying to a remote Sitecore instance via the npm deploy scripts. This is not required if your Sitecore instance you are deploying to is installed on the same machine where you deploy from.
  1. Open /ship/web.config on your Sitecore server
  2. Set allowRemote to true
  3. Add your IP to the whitelist:
         <packageInstallation enabled="true" allowRemote="true" allowPackageStreaming="false" recordInstallationHistory="false"> <Whitelist> <add name="local loopback" IP="127.0.0.1" /> <add name="Added ip" IP="your-dev-machine-IP-goes-here" /> </Whitelist> </packageInstallation>
Important: Ensure that the Ship files and configurations are not deployed to production content delivery servers (or are disabled), that IP whitelists are as tight as possible, and use SSL to avoid security issues.

App deployment

Deployment

  1. Open a command prompt/terminal within your JSS app
  2. jss deploy package --includeContent --includeDictionary
This will:
  • Run the production build of your app (by default the build package script)
  • Generate the app manifest, which defines the Sitecore structure needed to power the app
  • Generate a Sitecore update package with the manifest and production bundle
  • Install the package over HTTP on your Sitecore instance.
There are many available options for jss deploy package, which are all set to sensible defaults if unspecified. You can see all of the options for it using jss deploy package --help.

Verification

1. Content shows up in Content Tree

To test, log into your Sitecore instance using the selected app host http://JssBasicApp/sitecore/ and open Content Editor. You should see JSSBasicApp item under /sitecore/content:
You should now be able to see the same app you saw in dev if you open http://jssbasicapp/. It looks quite similar to the default Sitecore welcome page, but the whole output is coming from your JS application. Notice the title changed to "Sitecore Experience Platform + JSS"?
If the app does not work on content delivery, ensure that it has been published and is in a workflow state that allows publishing. See content workflows for more about how workflow operates in JSS apps.
Try launching the /Home page in Experience Editor, your app is now fully editable:
Posted by at
Labels: ,

No comments:

Post a Comment

Thanks for your comment

Subscribe to: Post Comments (Atom)