Ch2 : Play New Project

[Introduce]

新專案建立,我們可以使用兩種方式來建立新專案,一個是使用activator ui來啟動activator的網頁介面來建立專案,但是我這邊介紹是以最基本的指令模式來建立專案,一開始可能不太習慣,我想多敲一點點指令也是不錯的。

請你開啟命令與提字元,按照以下步驟來建立一個基本的Play專案。而本身Play支援ScalaJava語言,我們將會建立PlayJava專案來繼續往下練習。

PlayFramework 2.5.4 所使用的Java版本建議是Java8以上,若使用Java7版本會有一些相容性問題,建議還是使用Java8版本的JDK,來撰寫Play專案,以及專案所有可編輯的檔案,預設需要是UTF8編碼,否則後續可能會有編譯錯誤問題。


Oh! it's time to let you upset and practice.


step 1 : 首先我們回到我們Play的安裝的相關目錄下。我們來建立一個目錄叫作project,方便以後我們要找專案放在那裡。
EX PATH :C:\playFramework\project

step 2 : 接下來用命令來切換到我們新建立的project目錄下,來創立新專案。
CMD : cd C:\playFramework\project (意旨切換目錄到C:\playFramework\project下的意思)

step 3 : 這個指令,是我們學習的第一個指令。用來建立新專案。
activator new [project-name] [template-name]
這指令意思是請Play幫我創立一個專案,要叫什麼名字,要用使用什麼的樣版。因為我們要創一個Java專案名字叫做myFirstApp,後面樣版選擇是play-java,接下來請再畫面輸入以下指令,來建立專案。
activator new myFirstApp play-java

step 4 : 新專案產生完畢後,我們編譯這個新專案之前,我們必須用Notepad++來去編輯build.sbt,來新增以下指令,來編譯我們的Play專案。主要官方提到因為是Play本身支援Scala,如果沒去設定的話,會導致Eclipse無法辨認views或routesScala程式,所以我們需要編譯出純.class檔案,好讓Eclipse知道相關Scala程式該怎樣使用。

// Compile the project before generating Eclipse files, so that .class files for views and routes are present
EclipseKeys.preTasks := Seq(compile in Compile)

// Java project. Don't expect Scala IDE
EclipseKeys.projectFlavor := EclipseProjectFlavor.Java

// Use .class files instead of generated .scala files for views and routes
EclipseKeys.createSrc := EclipseCreateSrc.ValueSet(EclipseCreateSrc.ManagedClasses, EclipseCreateSrc.ManagedResources)

step 5 : 因為是剛建立的新專案,我們需要去編譯它,主要這個專案已經寫好這個專案需要的jar、js等等還需要ㄧ些前置步驟才能讓網站啟用,以及後續的Eclipse的專案匯入。請切換到我們新專案下,再輸入編譯指令來去建置專案,這個步驟會耗費許多時間,因為需要網路來去下載相關檔案,請耐心等候,泡個咖啡等ㄧ下吧!!
cd C:\playFramework\project\myFirstApp
activator compile

註:如果發生編譯錯誤,跳出以下這個錯誤訊息的話,主要原因是,新版的Play預設是以Java8所編譯的,所以要用舊版的話,要再修正project/plugins.sbt的內容,才能順利編譯過新專案,不過還是建議使用Java8版本來撰寫Play專案,減少類似情形發生。

java.lang.UnsupportedClassVersionError: com/typesafe/config/ConfigException : Unsupported major.minor version 52.0
    at java.lang.ClassLoader.defineClass1(Native Method)
    at java.lang.ClassLoader.defineClass(ClassLoader.java:800)
    at java.security.SecureClassLoader.defineClass(SecureClassLoader.java:142)
    at java.net.URLClassLoader.defineClass(URLClassLoader.java:449)
    at java.net.URLClassLoader.access$100(URLClassLoader.java:71)
    at java.net.URLClassLoader$1.run(URLClassLoader.java:361)
    at java.net.URLClassLoader$1.run(URLClassLoader.java:355)

修改project/plugins.sbt,就可以在舊的Java7版本所編譯。

// The Play plugin
// addSbtPlugin("com.typesafe.play" % "sbt-plugin" % "2.5.4")
addSbtPlugin("com.typesafe.play" % "sbt-plugin" % "2.3.9")  <--- 換成舊版的*Java7*版本編譯*Play*程式


step 6 : 編譯完之後,基本上,它就是一個可以執行網頁服務的Play專案,啟動Play網頁後預設Port是9000,讓我們看看結果吧!!若要停止,在命令與提示字元下,使用快捷鍵ctrl + D,來去中斷Play的網頁服務執行。
activator run
網址 : http://127.0.0.1:9000

step 7 : 接下來,我們要讓Eclipse匯入Play專案還需要一點調整,主要早期Play專案原本預設可輸入eclipse來去建置專案,現在已經沒有內建支援了,需要我們用Notepad++來去編輯plugins.sbt這個檔案,來把額外的套件加回去。
PATH : C:\playFramework\project\myFirstApp\project , 一個檔名叫做plugins.sbt的檔案。
新增以下擴充套件,可以讓Play專案可以支援eclipses這個指令。
addSbtPlugin("com.typesafe.sbteclipse" % "sbteclipse-plugin" % "4.0.0")

step 8 : 一樣在命令與提示字元模式下,切換到原本專案的目錄,我們要讓專案可以支援Eclipse來去匯入這個Play專案。
cd C:\playFramework\project\myFirstApp
activator eclipse

step 9 : Eclipse左上角依序點選,File/Import/General/Existing project,就可以順利匯入專案了。基本上Play的專案建立與匯入還有啟用,到這邊告一段落了。


[Play目錄架構介紹]

接下來我們介紹Play專案目錄架構。Play本身就支援主流MVC架構,所以不同功能的程式或檔案,它們應該的擺放位置,基本上已經固定下來了。以下這段文字目錄介紹,我擷取至Play 2.5.Xdocument,我就直接拿來使用了。我會仿官方流程來翻譯與介紹下來,跟額外補充。這邊的話,先有個大致印象即可,之後要新增相關程式或檔案時,再返回參考即可。

app                      → Application sources
 └ assets                → Compiled asset sources
    └ stylesheets        → Typically LESS CSS sources
    └ javascripts        → Typically CoffeeScript sources
 └ controllers           → Application controllers
 └ models                → Application business layer
 └ views                 → Templates
build.sbt                → Application build script
conf                     → Configurations files and other non-compiled resources (on classpath)
 └ application.conf      → Main configuration file
 └ routes                → Routes definition
dist                     → Arbitrary files to be included in your projects distribution
public                   → Public assets
 └ stylesheets           → CSS files
 └ javascripts           → Javascript files
 └ images                → Image files
project                  → sbt configuration files
 └ build.properties      → Marker for sbt project
 └ plugins.sbt           → sbt plugins including the declaration for Play itself
lib                      → Unmanaged libraries dependencies
logs                     → Logs folder
 └ application.log       → Default log file
target                   → Generated stuff
 └ resolution-cache      → Info about dependencies
 └ scala-2.11
    └ api                → Generated API docs
    └ classes            → Compiled class files
    └ routes             → Sources generated from routes
    └ twirl              → Sources generated from templates
 └ universal             → Application packaging
 └ web                   → Compiled web assets
test                     → source folder for unit or functional tests



app目錄 : 我們很清楚就看見已經分好MVC的目錄結構。你也可以在app底下放自己想要的程式,在app新增package,也是可以的,ex : app/utils。在app/assets目錄下,你可以擺放你常用的LESS、CSS檔案,或是CoffeeScript

-app/controllers   
(它的主要用途是當我們發動一個事件時,會先根據play的routes設定,去找尋要呼叫的controllers,應該要回傳的資料或資訊。) 
-app/models   
(controllers進來後,它可以選擇要呼叫的models程式,這邊通常負責商業邏輯部份,來去運算最後的結果,回傳給controllers。)
-app/views   
(程式運算完畢後,我們會把結果給使用者看到,而views大多用來擺放網頁,來把資料塞入頁面後,呈現出使用者想要知道的結果。請特別注意,不要在views裡新增scala的package,可能會導致編譯錯誤。)



public目錄 : 在這目錄下,可以已經有三個分類,stylesheets、javascripts、images,我們可以依據這些功能性目錄,來擺放樣式、js檔案、圖片等等。我們一樣可以新增ㄧ些需要公開的檔案放在這目錄下。請注意就是,這個目錄下的檔案,在您網頁伺服器啟動後,網址會對應到assets的路徑下,其它使用者將可以使用到你所公開的相關檔案。
EX URL : http://127.0.0.1:9000/assets/stylesheets/main.css。

conf目錄 : 如果當你需要ㄧ些設定檔,這邊是很好的選擇擺放位置,這裡預設有application.conf、以及routes,給Play專案使用中。

-conf/application.conf   
這個檔案是Play啟動時,主要的設定檔案,裡面有ㄧ些設定,需要特別設定時,可以修改與使用。   
-conf/routes   
這個檔案用來定義我們網站相關的網址或服務。實際啟動後,當使用者使用相關服務時,會依據routes所設定,來去呼叫controllersn的方法,來回覆使用者的請求。



lib目錄 : 當你有想要使用的jar檔案,可以丟到這目錄,給您的專案使用。請注意,這邊擺放的jar並不受專案控制,版本將會是您人工所控管與使用。

build.sbt : Play專案建置時,會根據build.sbt來去建置。這邊可以設定我們Play專案版本是多少,還有專案所需要的ㄧ些相依性jar檔要使用幾版。在建置完後,Play產出的專案jar檔案存放在哪些目錄下,都可以在這裡去設定。

project目錄 : 這裡是sbt建置額外的設定與版本。

-project/plugins.sbt   
sbt建置時可以擴充的套件,來協助我們來建置專案。   
-project/build.properties   
sbt建置時,這個設定檔可以告訴*Play*專案,要使用*sbt*幾版來建置專案。


target目錄 : 專案建置完,Play會產出相關的.class檔案或.scala檔案在這目錄裡。只介紹比較主要的部分。

target/scala-2.11/classes   
包含所有編譯完的Java、Scala的檔案。
target/scala-2.11/classes_managed   
這邊不同的是,這邊所編譯出來檔案,這些檔案會是framework所管理相關檔案。像routes等等。


.gitignore : 現在主流的版控系統是GIT,而專案已經先寫好,那些目錄是不需要接受GIT控管的,通常不受控管的程式大多是編譯過檔案,而不需要上傳上去的檔案。


[補充說明]
因為Play本身編碼一律要使用UTF-8格式,如果在activator compile遇到類似這種錯誤,可以這樣解決!!。
以下錯誤的原因是app/routes下有寫入中文,而本身預設編碼還是UTF8,還是錯誤,比較快速的解決方法是,先把中文說明部份都移除後,確認compile正常後,再復原回去。

為了確保之後,不會遇到類似這問題,我們需要做ㄧ些環境設定。

step1 : 我要先在Windows裡新增環境變數,JAVA_OPTS,讓編譯的程式輸出一律都是"UTF8"。

JAVA_OPTS
-Dfile.encoding=UTF-8

step2 : 確認你的檔案是UTF8的格式,再重新編譯一次,就可以完成了。


[Final]
到這邊,基本的Play專案介紹與目錄結構就OK了,而Play目錄結構介紹,部份說明我並沒有寫入,有興趣的朋友,可以再看看Play官方的介紹。

下一章還尚未進入Play程式撰寫,我還需要讓您知道Play專案的常用指令,你需要先好好閱讀過,才會讓程式順利寫下去。而後半段的部署,是需要等到要把上線的時刻,才需要閱讀,若覺得還沒到那個階段,可以往後跳到第四章 : Let's Play !!,開始實際了解Play程式與撰寫,等需要到部署服務時,再返回第三章後半部參考即可。


[Reference]

1.Creating a new application.
https://www.playframework.com/documentation/2.5.x/NewApplication

2.Anatomy of a Play application.
https://www.playframework.com/documentation/2.5.x/Anatomy

3.Eclipse unresolved symbol with Play Framework
http://stackoverflow.com/questions/18575375/eclipse-unresolved-symbol-with-play-framework

results matching ""

    No results matching ""